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.

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.

Pour autoriser l'accès aux ressources de notre librairie JS depuis votre site, ajoutez une balise meta dans le HEAD de la page, avec les directives CSP suivantes :

<head>
 ...
 <meta http-equiv="Content-Security-Policy" content="script-src *.systempay.fr;connect-src *.systempay.fr *.payzen.eu">
 ...
</head>

<p>La valeur <no-translate><code>https://*.payzen.eu</code></no-translate> de la directive <no-translate>CSP</no-translate> <no-translate><code>connect-src</code></no-translate> n'est utile que pour le mode test. Vous pouvez la supprimer sur votre environnement de production.</p>

Ajoutez la librairie JavaScript dans une balise script.

Implémentez le SRI et ajoutez l'attribut integrity dans la balise script. Voir Intégrer l'intégrité des sous-ressources (SRI).

Exemple avec le hash sha384-m2TqTgecvuLe1k+/eCJg3(...)TsYGcJfc5RMWYa/ :

<head>
 ...
 <script src="/static/js/authenticate-client/V1.0/kr-authenticate.umd.js"
    integrity="ssha384-m2TqTgecvuLe1k+/eCJg3(...)TsYGcJfc5RMWYa/"
    crossorigin="anonymous"></script>
 ...
</head>

2. Initier une demande de vérification de carte

Appelez le service V4.1/PCI/Charge/VerifyPaymentMethod en utilisant les champs ci-dessous :

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

Retrouvez la description des champs dans notre playground.

Exemple de requête

/doc/fr-FR/rest/V4.0/api/kb/authentication.html

https://api.systempay.fr/api-payment/V4.1/PCI/Charge/VerifyPaymentMethod

  {
    "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 JavaScript puis appeler la méthode authenticate. Il est recommandé 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	Élé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 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.

6. 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.

Catégories

Tags

Guide d'intégration

1. Ajouter la librairie JavaScript à votre site

2. Initier une demande de vérification de carte

Exemple de requête

Exemple de réponse

3. Initialiser le script d'authentification

1. Paramètres d'initialisation de la classe `KrAuthenticate`

2. Paramètres de la méthode d'exécution de l'authentification `KrAuthenticate.authenticate`

3. Exemple d'intégration exploitant bootstrap, JQuery et la librairie

4. Exécution de la librairie JavaScript

5. Analyse du résultat du paiement

6. Gestion du timeout

Catégories

Tags

Guide d'intégration

1. Ajouter la librairie JavaScript à votre site

2. Initier une demande de vérification de carte

Exemple de requête

Exemple de réponse

3. Initialiser le script d'authentification

1. Paramètres d'initialisation de la classe KrAuthenticate

2. Paramètres de la méthode d'exécution de l'authentification KrAuthenticate.authenticate

3. Exemple d'intégration exploitant bootstrap, JQuery et la librairie

4. Exécution de la librairie JavaScript

5. Analyse du résultat du paiement

6. Gestion du timeout

1. Paramètres d'initialisation de la classe `KrAuthenticate`

2. Paramètres de la méthode d'exécution de l'authentification `KrAuthenticate.authenticate`