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.

Dans le HEAD de la page, il faut ajouter la librairie JavaScript dans une balise <script>.

<head>
 ...
 <script src="https://static.scelliuspaiement.labanquepostale.fr/static/js/authenticate-client/V1.0/kr-authenticate.umd.js"></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 des champs dans notre playground.

Exemple de requête

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

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

https://api.scelliuspaiement.labanquepostale.fr/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 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":"LBP",
  "metadata":null,
  "status":"SUCCESS",
  "mode":"TEST",
  "serverUrl":"https://api.scelliuspaiement.labanquepostale.fr",
  "_type":"V4/WebService/Response",
  "answer":{
    "operationSessionId":"30641640cba14eab8e6766094fd201da",
    "operationUrl":"https://api.scelliuspaiement.labanquepostale.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.scelliuspaiement.labanquepostale.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("42229744:testpublickey_tPXxrUVsoGkggk9LuO8o0PBRdWg8jWUhWmYMURwCbc8ap");

Avec l'élément DOM:

  const krAuthenticate = new KrAuthenticate("42229744:testpublickey_tPXxrUVsoGkggk9LuO8o0PBRdWg8jWUhWmYMURwCbc8ap", {
 element: document.getElementById("id-challenge-element")
  });

Dans cet exemple, l' id 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 fournie dans la réponse du Service V4.1/PCI/Charge/CreatePayment dans l'objet answer/AuthenticationSessionResponse#operationUrl.	Oui

Exemple :

operationUrl : "https://api.scelliuspaiement.labanquepostale.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='https://static.scelliuspaiement.labanquepostale.fr/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('42229744:testpublickey_tPXxrUVsoGkggk9LuO8o0PBRdWg8jWUhWmYMURwCbc8ap');

    // 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();
        krAuthenticate.authenticate("https://theUrlFromThePciCall", 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

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

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 de code avec la classe `KrAuthenticate`et la méthode `KrAuthenticate.authenticate`

4. Exécution de la librairie JavaScript

5. Analyse du résultat du paiement

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 de code avec la classe KrAuthenticateet la méthode KrAuthenticate.authenticate

4. Exécution de la librairie JavaScript

5. Analyse du résultat du paiement

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`

3. Exemple de code avec la classe `KrAuthenticate`et la méthode `KrAuthenticate.authenticate`