Formulaire embarqué: Tester rapidement

Cette page donne un exemple d'intégration rapide d'un formulaire de paiement sécurisé en simplement 3 actions.

Pour un guide d'intégration plus complet (ou pour une intégration depuis un site en JavaScript), rendez-vous ici : Démarrer: Paiement simple

1. Initialiser le formulaire

Lorsqu'un acheteur finalise son achat sur votre site, vous devez valider sa transaction sur votre serveur marchand, en vérifiant notamment le montant, la devise, le contenu du panier, etc...

Une fois ces vérifications effectuées, votre serveur marchand doit appeler le Web Service Charge/CreatePayment afin d'initialiser la transaction.

En réponse, votre serveur marchand récupère un formToken, un objet encrypté permettant d'initialiser le formulaire embarqué avec les informations de la transaction et celles correspondant à votre configuration de boutique.

{
    "amount":   990,
    "currency": "EUR",
    "orderId":  "myOrderId-999999",
    "customer": {
        "email": "sample@example.com"
    }
}

{
    "amount":   1500,
    "currency": "PEN",
    "orderId":  "myOrderId-999999",
    "more": "parameters",
    "customer": {
        "email": "sample@example.com"
    }
}

{
    "amount":   20000,
    "currency": "ARS",
    "orderId":  "myOrderId-999999",
    "more": "parameters",
    "customer": {
        "email": "sample@example.com"
    }
}

{
    "amount":   100000,
    "currency": "COP",
    "orderId":  "myOrderId-999999",
    "more": "parameters",
    "customer": {
        "email": "sample@example.com"
    }
}

{
    "amount":   2500,
    "currency": "BRL",
    "orderId":  "myOrderId-999999",
    "more": "parameters",
    "customer": {
        "email": "sample@example.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"];

?>

/**
 * 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"];

?>

Plus de détails sur l'authentification des appels au web service REST sont disponibles ici: Phase d'authentification.

La réponse sera :

{
    "status": "SUCCESS",
    "_type": "V4/WebService/Response",
    "webService": "Charge/CreatePayment",
    "applicationProvider": "PAYZEN",
    "version": "V4",
    "applicationVersion": "4.1.0",
    "answer": {
        "formToken": "DEMO-TOKEN-TO-BE-REPLACED",
        "_type": "V4/Charge/PaymentForm"
    }
}

2. Afficher le formulaire

Une fois le formToken en votre possession, vous pouvez afficher le formulaire de paiement.

Pour cela, vous devez :

inclure dans le header de votre page de paiement la librairie JavaScript du formulaire de paiement (kr-payment-form.min.js), en passant en argument votre clé d'accès (voir ici pour savoir comment la récupérer), ainsi que les feuilles de styles associées,
inclure un élément de type DIV avec comme arguments:
- la classe kr-embedded
- l'attribut kr-form-token dans lequel vous aurez reporté le formToken récupéré à l'étape précédente.

C'est dans cette DIV que sera affiché le formulaire de paiement.

Il est impératif que la librairie principale soit chargée très tôt, bien avant les autres librairies JS utilisées sur votre page.

<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" 
   content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" />  

  <!-- Javascript library. Should be loaded in head section -->
  <script 
   src="https://api.lyra.com/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js" 
   kr-public-key="69876357:testpublickey_DEMOPUBLICKEY95me92597fd28tGD4r5" 
   kr-post-url-success="paid.html">
  </script>

  <!-- theme and plugins. should be loaded after the javascript library -->
  <!-- not mandatory but helps to have a nice payment form out of the box -->
  <link rel="stylesheet" 
  href="https://api.lyra.com/static/js/krypton-client/V4.0/ext/classic-reset.css">
 <script 
  src="https://api.lyra.com/static/js/krypton-client/V4.0/ext/classic.js">
 </script> 
</head>
<body>
  <!-- payment form -->
  <div class="kr-embedded"  kr-form-token="DEMO-TOKEN-TO-BE-REPLACED">

    <!-- payment form fields -->
    <div class="kr-pan"></div>
    <div class="kr-expiry"></div>
    <div class="kr-security-code"></div>

    <!-- payment form submit button -->
    <button class="kr-payment-button"></button>

    <!-- error zone -->
    <div class="kr-form-error"></div>
  </div>
</body>
</html>

<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" 
   content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" /> 

  <!-- Javascript library. Should be loaded in head section -->
  <script 
   src="<?php echo $client->getClientEndpoint();?>/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js"
   kr-public-key="<?php echo $client->getPublicKey();?>"
   kr-post-url-success="paid.php">
  </script>

  <!-- theme and plugins. should be loaded after the javascript library -->
  <!-- not mandatory but helps to have a nice payment form out of the box -->
  <link rel="stylesheet" 
   href="<?php echo $client->getClientEndpoint();?>/static/js/krypton-client/V4.0/ext/classic-reset.css">
  <script 
   src="<?php echo $client->getClientEndpoint();?>/static/js/krypton-client/V4.0/ext/classic.js">
  </script>
</head>
<body style="padding-top:20px">
  <!-- payment form -->
  <div class="kr-embedded" kr-form-token="<?php echo $formToken;?>">

    <!-- payment form fields -->
    <div class="kr-pan"></div>
    <div class="kr-expiry"></div>
    <div class="kr-security-code"></div>  

    <!-- payment form submit button -->
    <button class="kr-payment-button"></button>

    <!-- error zone -->
    <div class="kr-form-error"></div>
  </div>  
</body>
</html>

Le client JavaScript utilise des éléments DIV spéciaux pour insérer les champs du formulaire. Ces conteneurs sont identifiés à partir des classes suivantes :

Class	Description
kr-pan	Numéro de la carte
kr-expiry	Date d'expiration
kr-security-code	Code de sécurité (CVV)
kr-form-error	Zone d'affichage des erreurs
kr-first-installment-delay	Nombre de mois de différé à appliquer sur la première échéance
kr-identity-document-type	Type de document d'identité
kr-identity-document-number	Numéro de la pièce d'identité
kr-card-holder-name	Nom du porteur de la carte
kr-card-holder-mail	Adresse e-mail du porteur de la carte

Exemple de formulaire de paiement :

Lorsque l'acheteur valide le formulaire, la transaction est soumise par le formulaire directement à notre plateforme de paiement pour validation.

Si la transaction est validée, l'acheteur est redirigé vers la page mentionnée dans l'attribut kr-post-url-success de la balise <script>
Si la transaction est refusée, une erreur apparaît, l'acheteur reste sur la page de paiement.

3. Vérifier le statut de la transaction

Durant le processus de paiement, les 2 actions suivantes ont lieu séquentiellement:

Une notification instantannée (Instant Payment Notification, ou IPN) est envoyée avec toutes les informations de la transaction, que celle-ci soit acceptée ou refusée. L'URL de notification de votre serveur doit être configurée dans la boutique sur votre Back Office.

Notification instantanée (IPN)
Le navigateur reçoit également les mêmes informations de transaction à la fin du processus de paiement.

Retour navigateur

Vous ne devez traiter qu'un seul de ces 2 messages (ils sont identiques). Ils vous servent à valider votre panier, et à enclencher la suite du votre processus d'achat.

Exemple d'informations envoyées :

kr-hash=c3c0323c748fdb7c2d24bd39ada99663526236828efa795193bebfdea022fe58
kr-hash-algorithm=sha256_hmac
kr-hash-key=sha256_hmac
kr-answer={"orderStatus":"PAID", (...)

La première étape consiste à valider l'intégrité du message, en vérifiant que la signature (kr-hash) correspond bien à l'ensemble du message.

Une fois l'intégrité du message validée, vous pouvez traiter la transaction (dont le statut est stocké dans la propriété kr-answer).