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 lorsque l'authentification du porteur est gérée par notre serveur d'authentification pendant le paiement.

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 *.lyra.com;connect-src *.lyra.com *.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 d'authentification du porteur

Appelez le Web Service V4.1/PCI/Charge/CreatePayment en utilisant les champs ci-dessous :

NIVEAU	NOM	DESCRIPTION	REQUIS
1	amount	Montant du paiement dans la plus petite unité de la devise.	Oui
1	currency	Code (ISO 4217 alpha3) de la devise du paiement.	Oui
1	orderId	Référence de la commande (récommandé).	Non
1	formAction	Permet d'indiquer si vous souhaitez enregistrer la carte. Valeurs possibles : PAYMENT REGISTER_PAY	Non
1	customer	Objet contenant les données de l'acheteur.	Non
2	email	Adresse e-mail de l'acheteur (récommandé).	Non
1	paymentForms	Objet contenant les données de la carte.	Oui
2	paymentMethodType	Type du moyen de paiement. Doit être valorisé à CARD.	Oui
2	cardHolderName	Nom et prénom du porteur de la carte (récommandé).	Non
2	pan	Numéro de carte.	Oui
2	expiryMonth	Mois d'expiration de la carte.	Oui
2	expiryYear	Année d'expiration de la carte.	Oui
2	securityCode	Code de sécurité de la carte (CVV ou 4DBC).	Non
1	ipnTargetUrl	Url pour notifier de la fin d'authentification	Non

D'autres champs facultatifs sont disponibles. Retrouvez la description et l'intégralité des champs dans notre playground.

Exemple de requête

/fr/rest/V4.0/api/kb/authentication.html

https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.php#L9-L44

https://api.lyra.com/api-payment/V4.1/PCI/Charge/CreatePayment

{  
  "amount": "990",
  "currency": "EUR",
  "paymentForms": [
      {
        "cardHolderName": "John Doe",
        "pan": "4970110000001003",
        "expiryMonth": 11,
        "expiryYear": 23,
        "securityCode": "123",
        "paymentMethodType": "CARD"
      }
    ],
    "customer": {
      "email": "sample@example.com"
    },
    "ipnTargetUrl": "https://merchant.ipn.com"
  }

/**
 * I initialize the PHP SDK
 */
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/keys.php';
require_once __DIR__ . '/helpers.php';

/** 
 * Initialize the SDK 
 * see keys.php
 */
$client = new Lyra\Client();

/**
 * I create a formToken
 */
$store = array("amount" => 250, 
"currency" => "EUR", 
"orderId" => uniqid("MyOrderId"),
"customer" => array(
  "email" => "sample@example.com"
));
$response = $client->post("V4/Charge/CreatePayment", $store);

/* I check if there are some errors */
if ($response['status'] != 'SUCCESS') {
    /* an error occurs, I throw an exception */
    display_error($response);
    $error = $response['answer'];
    throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage'] );
}

/* everything is fine, I extract the formToken */
$formToken = $response["answer"]["formToken"];

?>

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 et l'intégralité des champs dans notre playground.

Exemple de réponse

{
  "webService":"PCI/Charge/CreatePayment",
  "version":"V4",
  "applicationVersion":"6.0.0",
  "serverDate":"2023-04-16T11:11:21+00:00",
  "ticket":"839ecda45f6449a8869747a80c26b2d2",
  "applicationProvider":"LYRA",
  "metadata":null,
  "status":"SUCCESS",
  "mode":"TEST",
  "serverUrl":"https://api.lyra.com",
  "_type":"V4/WebService/Response",
  "answer":{
    "operationSessionId":"30641640cba14eab8e6766094fd201da",
    "operationUrl":"https://api.lyra.com/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.lyra.com/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("69876357:testpublickey_DEMOPUBLICKEY95me92597fd28tGD4r5");

Avec l'élément DOM :

const krAuthenticate = new KrAuthenticate("69876357:testpublickey_DEMOPUBLICKEY95me92597fd28tGD4r5", {
 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.lyra.com/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('69876357:testpublickey_DEMOPUBLICKEY95me92597fd28tGD4r5');

  // 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 Frictionless, sans 3DS Method	L'authentification se déroule sans aucune interraction du porteur.	3DS2 - Authentification Frictionless, sans 3DS Method
3DS2 Frictionless, avec 3DS Method	Un script (3DS Method) est exécuté en amont de l'authentification qui se déroule ensuite sans interraction du porteur.	3DS2 - Authentification Frictionless, avec 3DS Method
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

Consultez la section Tests et cas d'utilisation pour avoir d'autres exemples.

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 d'authentification du porteur

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 d'authentification du porteur

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`