Guide d'intégration
Cette section décrit la manière d'implémenter les échanges entre le navigateur, le serveur marchand et la plateforme de paiement pendant la vérification de la carte.
1. Ajouter la librairie JavaScript à votre site
Afin de faciliter l'intégration de la solution, notre librairie JavaScript collecte les données de l'équipement et du navigateur du client, communique directement avec le 3DS Server et gère l'interaction du porteur de carte pendant le challenge.
Dans le HEAD de la page, il faut ajouter la librairie JavaScript dans une balise script.
<head>
...
<script src="https://static.systempay.fr/static/js/authenticate-client/V1.0/kr-authenticate.umd.js"></script>
...
</head>Si pour des raisons de sécurité (contraintes PCI-DSS) vous devez implémenter le SRI, consultez la page : Intégrer l'intégrité des sous-ressources (SRI).
2. Initier une demande de vérification de carte
Appelez le service V4.1/PCI/Charge/VerifyPaymentMethod en utilisant les champs ci-dessous :
Champs attendus
| Nom | Description | Requis |
|---|---|---|
| amount | Montant à payer, exprimé dans sa plus petite unité monétaire (le centime pour l'euro) | Oui |
| currency | Devise du paiement. Code ISO 4217 alpha-3. Ex: "EUR" pour l'euro. | Oui |
| customer.email | Adresse e-mail de l'acheteur. | Non |
| paymentMethodType | Type du moyen de paiement. Valeur obligatoire: CARD. | Oui |
| pan | Numéro de carte. | Oui |
| expiryMonth | Mois d'expiration de la carte. | Oui |
| expiryYear | Année d'expiration de la carte. | Oui |
| securityCode | Code de sécurité de la carte (CVV ou 4DBC). | Non |
| ipnTargetUrl | Url pour notifier du résultat du paiement | Non |
| orderId | Référence de la commande | Non |
L'intégralité et la description des champs sont disponibles dans le playground : V4.1/PCI/Charge/VerifyPaymentMethod.
Exemple de requête
{
"amount": "990",
"currency": "EUR",
"customer": {
"email": "sample@example.com"
},
"ipnTargetUrl": "https://my.site/my-ipn",
"orderId": "myOrderId-1234",
"paymentForms": [
{
"paymentMethodType": "CARD",
"pan": "4970110000001003",
"expiryMonth": 11,
"expiryYear": 25,
"securityCode": 123
}
]
}Lors de la réponse AuthenticationSessionResponse, vous trouverez les champs suivants :
answer.operationSessionId: l'identifiant de la session d’authentification (à conserver)answer.operationUrl: url à transmettre à la librairie JavaScript
Retrouvez la description des champs dans notre playground.
Exemple de réponse
{
"webService":"PCI/Charge/VerifyPaymentMethod",
"version":"V4.1",
(...)
"ticket":"839ecda45f6449a8869747a80c26b2d2",
"applicationProvider":"NPS",
"metadata":null,
"status":"SUCCESS",
"mode":"TEST",
"serverUrl":"https://api.systempay.fr",
"_type":"V4/WebService/Response",
"answer":{
"operationSessionId":"30641640cba14eab8e6766094fd201da",
"operationUrl":"https://api.systempay.fr/api-payment/V4/Charge/Public/Authenticate/Payment/Session/30641640cba14eab8e6766094fd201da;JSESSIONID=7A4beEA2d5fdbFeA7389F3B91a7bDBaBc8DA9df5.default-hostname",
"_type":"V4/PCI/Authentication/AuthenticationSessionResponse"
}
}Dans l'exemple :
answer.operationSessionId: "30641640cba14eab8e6766094fd201da"answer.operationUrl: "https://api.systempay.fr/api-payment/V4/Charge/Public/Authenticate/Payment/Session/30641640cba14eab8e6766094fd201da;JSESSIONID=7A4beEA2d5fdbFeA7389F3B91a7bDBaBc8DA9df5.default-hostname"
3. Initialiser le script d'authentification
Une fois la session d'authentification créée, vous devez initialiser la librairie d'authentification JavaScript puis appeler la méthode authenticate. Il est conseillé de rajouter un indicateur visuel de chargement lors de cet appel.
// définition de la class javascript
class KrAuthenticate {
constructor(publicKey,options)
authenticate(operationUrl)
}1. Paramètres d'initialisation de la classe KrAuthenticate
| NOM | DESCRIPTION | REQUIS |
|---|---|---|
| publicKey | Clé publique de TEST ou de PRODUCTION de la boutique. Plus d'infos : **3 ème clé** du tableau des clés d'API REST. | Oui |
| options | Elément du DOM dans lequel sera affichée la fenêtre d'authentification (facultatif). | Non |
Vous pouvez aussi faire apparaitre la fenêtre d'authentification dans un autre élément du DOM grâce à l'attribut element du paramètre facultatif options.
- Sans élément DOM (conseillé) :
const krAuthenticate = new KrAuthenticate("73239078:testpublickey_Zr3fXIKKx0mLY9YNBQEan42ano2QsdrLuyb2W54QWmUJQ"); - Avec l'élément DOM :
const krAuthenticate = new KrAuthenticate("73239078:testpublickey_Zr3fXIKKx0mLY9YNBQEan42ano2QsdrLuyb2W54QWmUJQ", { element: document.getElementById("id-challenge-element") });
Dans cet exemple, l' identifiant de l'élement du DOM est : id-challenge-element.
2. Paramètres de la méthode d'exécution de l'authentification KrAuthenticate.authenticate
Utilisez le champ operationUrl généré lors de la création de la session (étape 2).
| NOM | DESCRIPTION | REQUIS |
|---|---|---|
| operationUrl | URL d'initialisation de l'authentification lors de la réponse dans l'objet answer/AuthenticationSessionResponse#operationUrl. | Oui |
Exemple :
operationUrl: "https://api.systempay.fr/api-payment/V4/Charge/Public/Authenticate/Payment/Session/30641640cba14eab8e6766094fd201da;JSESSIONID=7A4beEA2d5fdbFeA7389F3B91a7bDBaBc8DA9df5.default-hostname"
3. Exemple de code avec la classe KrAuthenticate et la méthode KrAuthenticate.authenticate
Exemple d'intégration exploitant bootstrap, JQuery et la librairie:
<!-- import JS -->
[...]
<script src='/static/js/authenticate-client/V1.0/kr-authenticate.umd.js'></script>
[...]
<form action='javascript:authenticatePayment()'>
<button id='submitButton' type='submit' class='btn btn-primary'>Authenticate</button>
</form>
[...]
<script>
// instantiate library
const krAuthenticate = new KrAuthenticate('73239078:testpublickey_Zr3fXIKKx0mLY9YNBQEan42ano2QsdrLuyb2W54QWmUJQ');
// Callback removing the overlay
function myCallback(data) {
document.getElementById('overlay').remove();
}
// this is an example of overlay with a bootstrap spinner
function buildOverlay() {
let overlay = document.createElement('div');
overlay.setAttribute('id', 'overlay');
overlay.style.backgroundColor = '#D3D3D3';
overlay.style.height = '100%';
overlay.style.position = 'absolute';
overlay.style.top = '0';
overlay.style.opacity = '0.90';
overlay.style.width = '100%'
overlay.classList.add('d-flex', 'justify-content-center', 'flex-column', 'align-items-center');
overlay.innerHTML = `
<div class="spinner-border" role="status">
<span class="sr-only">Loading...</span>
</div>
`;
document.body.appendChild(overlay);
}
// Main function triggered by button
function authenticatePayment() {
document.querySelector('#submitButton').disabled = true;
buildOverlay();
// add the operationUrl in the object answer/AuthenticationSessionResponse#operationUrl
krAuthenticate.authenticate("operationUrl", myCallback);
}
</script>4. Exécution de la librairie JavaScript
La librairie JavaScript se charge d'exécuter toutes les actions nécessaires à l'authentification.
| Cas d'authentification | Description | Test |
|---|---|---|
| 3DS2 Challenge, sans 3DS Method | L'authentification nécessite des actions de la part du porteur. | 3DS2 - Authentification Challenge, sans 3DS Method |
| 3DS2 Challenge, avec 3DS Method | Un script (3DS Method) est exécuté en amont des actions d'authentification du porteur. | 3DS2 - Authentification Challenge, avec 3DS Method |
5. Analyse du résultat du paiement
À la fin de l'authentification et de la demande d'autorisation, la plateforme retourne un objet Payment dans l'IPN. Il décrit le détail du paiement (statut du paiement, résultat de la demande d'autorisation, résultat de l'authentification du porteur, etc...).
- Plus d'infos : Payment.
Gestion du timeout
La durée de la session de paiement est fixée à 10 minutes. Au bout de ce délai, si l'IPN n'a pas été configurée par le marchand, il est recommandé de faire un appel au Web Service Order/Get pour obtenir le résultat du paiement.