Applications Web monopages
L'utilisation d'une application web monopage (en anglais single-page-application ou SPA) a pour avantage :
- de réduire le temps de chargement.
- de consommer moins de ressources.
Étapes d'intégration
- Charger le formulaire de paiement
- Initialiser le formulaire de paiement
- Afficher le formulaire de paiement
- Analyser le résultat du paiement
Frameworks
Charger le formulaire de paiement
Dans le HEAD
:
Chargez notre librairie JavaScript : src="https://static.scelliuspaiement.labanquepostale.fr/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js"
Intégrez obligatoirement la clé publique dans le paramètre
kr-public-key
(3 ème clé du tableau des clés API REST ).Appliquez un thème (lien : Thèmes).
Dans le BODY
:
- Masquez le formulaire de paiement, dans une
<div>
.
Exemple de code
<head> <!-- Javascript library. Should be loaded in head section --> <script type="text/javascript" src="https://static.scelliuspaiement.labanquepostale.fr/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js" kr-public-key="42229744:testpublickey_tPXxrUVsoGkggk9LuO8o0PBRdWg8jWUhWmYMURwCbc8ap:testpublickey_DEMOPUBLICKEY95me92597fd28tGD4r5"> </script> <!-- theme and plugins. should be loaded in the HEAD section --> <link rel="stylesheet" href="https://static.scelliuspaiement.labanquepostale.fr/static/js/krypton-client/V4.0/ext/classic-reset.min.css"> <script type="text/javascript" src="https://static.scelliuspaiement.labanquepostale.fr/static/js/krypton-client/V4.0/ext/classic.js"></script> </head> <body> ... <!--Hidden payment form --> <div id="paymentForm" class="kr-smart-form" style="display:none"> <!-- payment form fields --> <div class="kr-pan"></div> <div class="kr-expiry"></div> <div class="kr-security-code"></div> <!-- payment form submit button --> <button class="kr-payment-button"></button> <!-- error zone --> <div class="kr-form-error"></div> </div> ... </body>
Initialiser le formulaire de paiement
Lorsque l'acheteur décide de payer, créez un formToken en envoyant une requête vers le Web Service Charge/CreatePayment :
- Toujours depuis votre serveur marchand, car vos données sensibles sont protégées.
- Jamais depuis votre navigateur, car certaines données sensibles sont vulnérables, comme vos identifiants. Pour sécuriser vos données, nous bloquons la requête et affichons des erreurs CORS.
Exemple de code
/**
* Called on 'checkout' click
*/
function onCheckout(){
// Create the order, based on your cart
var order = {
"amount": 990,
"currency": "EUR",
"orderId": "myOrderId-999999",
"customer": {
"email": "sample@example.com"
}
};
// Call merchant server to get form token and then display payment form
getFormToken(order, displayPaymentForm, alert);
}
/**
* Get form token from merchant server
* @param order
* @param resolve
* @param reject
*/
function getFormToken(order, resolve, reject){
var request = new XMLHttpRequest();
// Open a new connection, using the POST request on the URL endpoint
request.open('POST', 'YOUR_SERVER/payment/init', true);
request.setRequestHeader('Content-Type', 'application/json');
request.onload = function (){
if (request.status >= 200 && request.status < 400) {
resolve(this.response);
}
else
{
reject("Invalid server response. Code " + request.status);
}
};
request.onerror = function (error){
reject(error);
};
// Send request
request.send(JSON.stringify(order));
}
- Appelez votre serveur marchand pour valider le panier (contrôle et gestion des stocks, montant du panier, etc).
Exemple de code en Node JS :
/* Init payment form */
router.post('/init', function(req, res, next){
var order = req.body;
// TO DO: check that order is valid
// Call CreatePayment web service to create the form token
request.post({
url: "https://api.scelliuspaiement.labanquepostale.fr/api-payment/V4/Charge/CreatePayment",
headers: {
'Authorization': 'Basic Njk4NzYzNTc6dGVzdHBhc3N3b3JkX0RFTU9QUklWQVRFS0VZMjNHNDQ3NXpYWlEyVUE1eDdN',
'Content-Type': 'application/json'
},
json: order
}, function(error, response, body){
if (body.status === 'SUCCESS')
{
// Send back the form token to the client side
res.send(body.answer.formToken);
}
else
{
// Do your own error handling
console.error(body);
res.status(500).send('error');
}
});
});
Afficher le formulaire de paiement
Une fois le formToken généré :
- Affichez le formulaire, par défaut masqué.
- Associez-le au formulaire : KR.setFormToken.
- Intégrez la fonction KR.onSubmit pour recevoir la notification lors du retour à la boutique.
Exemple de code
/**
* Display the payment form with the argument form token
* @param formToken
*/
function displayPaymentForm(formToken){
// Show the payment form
document.getElementById('paymentForm').style.display = 'block';
// Set form token
KR.setFormToken(formToken);
// Add listener for submit event
KR.onSubmit(onPaid);
}
Analyser le résultat du paiement
A la fin du paiement, analysez le résultat du paiement :
Depuis l'IPN (Instant Payment Notification), lors d'un appel de serveur à serveur. Plus d'infos: Analyse de l'IPN (URL de notification).
Depuis le retour à la boutique grâce à la méthode KR.onSubmit.
- Utilisez une fonction personnalisée
onPaid
pour afficher un message selon le statut de la transaction.
- Utilisez une fonction personnalisée
Exemple de code
/**
* Called when payment is finished
* @param event
*/
function onPaid(event){
if (event.clientAnswer.orderStatus === "PAID") {
// Remove the payment form
KR.removeForms();
// Show success message
document.getElementById("paymentSuccessful").style.display = "block";
} else {
// Show error message to the user
alert("Payment failed !");
}
}
Intégration avec Vue / React / Angular
L'intégration avec des frameworks JavaScript compilés (type Vuee, React ou Angular) nécessite l'utilisation de la librairie embedded-form-glue.
Avantages
- Préchargement de la librairie pour permettre un affichage plus rapide pour les réseaux lents.
- Gestion de la configuration lorsque l'application n'est pas encore chargée.
- Permet d'ajouter, de supprimer, et d'afficher à nouveau le formulaire facilement.
Travailler dans un environnement asynchrone
Dans un environnement asynchrone, tous les événements et méthodes retournent des promesses. La méthode then()
contient deux propriétés:
KR
: la référence de librairie JavaScript est toujours retournée permettant de chaîner les promesses.result
: le résultat de l'opération, peut être non défini ou absent de l'objet si aucun résultat n'est renvoyé.
Exemple de code
KR.validateForm().then( ({KR, result}) => { /* there is no error */ /* result == null */ } ) .catch( ({KR, result}) => { /* Get the error message */ var code = result.errorCode; var message = result.errorMessage; var myMessage = code + ": " + message; console.log(myMessage); /* if you have defined a callback using */ /* result.onError(), you can trigger it calling: */ return result.doOnError(); } );
Exemples
Framework | Description |
---|---|
Angular | exemple d'intégration pour Angular |
Ember | exemple d'intégration pour Ember |
Ionic | exemple d'intégration pour Ionic |
Next | exemple d'intégration pour Next |
React | exemple d'intégration pour React |
Server | exemple d'intégration pour Server |
Svelte | exemple d'intégration pour Svelte |
Vue | exemple d'intégration pour Vue |
require.js | exemple d'intégration avec RequireJS |