Pop-in: Rapid testing

This page provides a quick overview of how to insert a secured payment form into a pop-in by following only 3 steps.

For a more detailed integration guide, go to: Start: Single payment

The pop-in and embedded forms are integrated in the same way. All you need to do is add a directivekr-popinto the div<div class="kr-embedded">:<div class="kr-embedded" kr-popin>.

1. Create a formToken

When a buyer finalizes a purchase on your website, you must validate their transaction on your merchant server and verify the amount, the currency, the contents of the cart, etc.

Once these checks have been completed, your merchant server must call the Charge/CreatePayment Web Service in order to initialize the transaction.

In response, your merchant server retrieves a formToken, an encrypted object allowing to initialize the embedded form with the transaction details and the details corresponding to your shop configuration.

{
"amount":   990,
"currency": "EUR",
"orderId":  "myOrderId-999999",
"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"];

?>

You can find more information on the authentication of calls to the REST web service here: Authentication phase.

The response will be:

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

The generated formToken isDEMO-TOKEN-TO-BE-REPLACED

2. Display a form

Once you have the formToken, you can display the payment form.

For this, you must:

  • include the JavaScript library of the payment form (kr-payment-form.min.js) in your payment page, passing your access key as an argument (go here to learn how to retrieve it), as well as the associated CSS files,
  • include a DIV element with the arguments: kr-embedded class and kr-form-token attribute used for transferring the formToken retrieved in the previous step. This DIV will display the payment form.
  <!-- payment form -->
  <div class="kr-embedded"
   kr-popin
   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>

<!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.systempay.fr/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js"
      kr-public-key="73239078:testpublickey_Zr3fXIKKx0mLY9YNBQEan42ano2QsdrLuyb2W54QWmUJQ"
      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.systempay.fr/static/js/krypton-client/V4.0/ext/classic-reset.css"
    />
    <script src="https://api.systempay.fr/static/js/krypton-client/V4.0/ext/classic.js"></script>
  </head>
  <body>
    <!-- payment form -->
    <div class="kr-embedded" kr-popin 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>

The JavaScript client uses special DIV elements to insert form fields. These containers are identified by the following classes:

Class Description
kr-pan Card number
kr-expiry Expiry date
kr-security-code Security code (CVV)
kr-form-error Error display area

The form fields defined via<div class="kr-pan"></div>are optional. The JavaScript client will automatically add the fields required by the payment method or delete the unused fields.

Example of a payment form:

The form is functional, you can make a fictitious payment using test cards from the debug sidebar (in the left bottom corner of the window).

When the buyer validates the form, the transaction is submitted via the form directly to our payment gateway for validation.

  • If the transaction is validated, the buyer is redirected to the page specified in the attributekr-post-url-successof the tag
  • If the transaction is rejected, a error appears and the buyer stays on the payment page.

3. Verify the transaction status

During the payment process, the 2 following actions occur sequentially:

  • An instant notification (Instant Payment Notification, or IPN) is sent with all the transaction details, and must be accepted or rejected. The notification URL of your server must be configured in the shop via your Back Office.
  • The browser also receives the same transaction details and the end of the payment process.

You must process only one of these 2 messages (they are identical). They allow you to validate your cart and to pursue your purchase process.

Example of sent information:

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

The first step consists in validating the integrity of the message by verifying that the signature (kr-hash) corresponds to the entire message.

Once the integrity of the message has been validated, you can process the transaction (whose status is stored in the kr-answer property).