Guide d'intégration (mode simple)

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>

2. Initier une demande d'authentification du porteur

Appelez le service PCI/Authentication/CreateSession en utilisant les champs ci-dessous :

NIVEAU	NOM	DESCRIPTION	REQUIS
1	customer	Objet contenant les données de l'acheteur.	Non
2	email	Adresse e-mail de l'acheteur (récommandé).	Non
1	paymentForm	Objet contenant les données de la carte.	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	networkPreference	Nom du réseau préférenciel préconisé par le marchand.	Oui
1	merchant	Objet contenant le numéro de contrat marchand.	Oui
2	mid	Numéro de contrat du marchand.	Oui
1	protocolRequest	Objet décrivant le mode d'authentification souhaité.	Oui
2	name	Nom du protocole d'authentification.	Oui
2	version	Version du protocole d'authentification.	Non
1	merchant	Objet contenant les informations sur le contrat.	Oui
1	productType	Type de produit concerné par la transaction.	Oui
1	transactionCategory	Valorisé à PAYMENT.	Oui
1	amount	Montant pour lequel l'authentification est demandée.	Oui
1	ianTargetUrl	Url requise pour la notification de fin d'authentification	Oui

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.systempay.fr/api-payment/V4/PCI/Authentication/CreateSession

{
  "amount": 1230,
  "currency": "EUR",
  "transactionCategory": "PAYMENT",
  "productType": "GOODS_OR_SERVICE_PURCHASE",
  "merchant": {
    "mid": "1234567"
  },
  "paymentForm":{
    "cardHolderName": "John Doe",
    "pan": "4970110000000013",
    "expiryMonth": "02",
    "expiryYear": "24",
    "networkPreference": "VISA"
  },
  "customer": {
    "email": "sample@example.com"
  },
  "protocolRequest": {
    "name": "THREEDS",
    "version": "2",
    "challengePreference": "NO_PREFERENCE"
  },
  "ianTargetUrl": "https://myiantargeturl.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/Authentication/CreateSession",
  "version":"V4",
  "applicationVersion":"6.0.0",
  "serverDate":"2023-04-16T11:11:21+00:00",
  "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/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/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 apparaître 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' 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 l' appel PCI/Authentication/CreateSession (étape 2).

NOM	DESCRIPTION	REQUIS
operationUrl	URL d'initialisation de l'authentification fournie dans la réponse du Web Service PCI/Authentication/CreateSession dans l'objet answer/AuthenticationSessionResponse#operationUrl.	Oui

Exemple :

answer.operationUrl : "https://api.systempay.fr/api-payment/V4/Charge/Public/Authenticate/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.systempay.fr/static/js/authenticate-client/V1.0/kr-authenticate.umd.js"></script>
    [...]
    
    <form action='javascript:authenticateSession()'>
      <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 authenticateSession(){
        document.querySelector('#submitButton').disabled = true;
        buildOverlay();
        krAuthenticate.authenticate("https://theUrlFromThePciCall", myCallback);
    }</script>

4. Exécution de l'authentification

La librairie JavaScript se charge d'exécuter toutes les actions nécessaires à l'authentification. Ci-dessous une liste de scénarios possibles.

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

5. Analyse du résultat de l'authentification

Les résultat de l'authentification sera automatiquement posté vers l'URL, valorisée dans le champianTargetUrl lors la requête d'initialisation de demande d'authentification.
Ce résultat contient les données nécessaires à la demande d'autorisation comme dans l'exemple avec le CAVV.

Gestion du timeout

La durée de la session d'authentification est fixée à 10 minutes.
Au bout de ce délai, il est conseillé de faire un appel au Web Service PCI/Authentication/GetSession pour obtenir le résultat de l'authentification.

Catégories

Tags

Guide d'intégration (mode simple)

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 l'authentification

5. Analyse du résultat de l'authentification

Gestion du timeout

Catégories

Tags

Guide d'intégration (mode simple)

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 l'authentification

5. Analyse du résultat de l'authentification

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`