• France
lyra.com
Search
Categories
Tags
Europe (English)
France
Spain
Europe (English)
India
Home
Implementation
Embedded form (cards)
REST payment API
REST PCI-DSS payment API
REST SEPA API
Hosted payment
Data collection form
File exchange
Mobile payment
Snippets
Plugins
Marketplace
Back Office
Merchant Back Office
Expert Back Office
Guides
Help
FAQ
Video tutorials
Support

Embedded form: rapid testing

This page provides a quick overview of how to integrate a secured payment form in only 3 steps.

For a more detailed integration guide (or for integration via a website in JavaScript), go to: Getting started: single payment.

1. Initializing the form

When a Buyer finalizes their purchase on your website, you must validate their transaction on your merchant server, making sure to check the amount, currency, cart contents, etc.

Once these verification has 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.

/en/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/Charge/CreatePayment
{
    "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"];

?>

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": "PAYZEN",
    "version": "V4",
    "applicationVersion": "4.1.0",
    "answer": {
        "formToken": "DEMO-TOKEN-TO-BE-REPLACED",
        "_type": "V4/Charge/PaymentForm"
    }
}

The generated formToken is: Processing...

2. Displaying the form

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

For the different labels to be displayed correctly, you must define the character encoding on your page.

To do this, use an HTML <meta> tag containing the value "UTF-8". For example:

  <head>
    ... 
    <meta charset="UTF-8">
    ...
  </head>

Next, you must:

  • In the header of your payment page, include the JavaScript library of the payment form ( kr-payment-form.min.js), passing your access key as an argument (see how to retrieve it here), as well as the associated style sheets.
  • Include an element of type DIV with the following arguments:
    • kr-embedded class
    • kr-form-token attribute with the posted formToken that was retrieved in the previous step.

The payment form will be displayed in this DIV.

It is imperative for the main library to be loaded very early on, well before the other JS libraries used on your page:.

/en/rest/V4.0/api/kb/authentication.html
https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.php#L45-L85
https://api.lyra.com/api-payment/V4/Charge/CreatePayment
<!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://static.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://static.lyra.com/static/js/krypton-client/V4.0/ext/classic-reset.css">
 <script 
  src="https://static.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>

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
kr-first-installment-delay Number of months of deferral to be applied to the first payment
kr-identity-document-type ID type
kr-identity-document-number ID number
kr-card-holder-name Cardholder name
kr-card-holder-mail Cardholder's e-mail address

eb045d78d273107348b0300c01d29b7552d622abbc6faf81b3ec55359aa9950c.

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 mentioned in the kr-post-url-success attribute of the <script> tag.
  • If the transaction is rejected, a error appears and the Buyer stays on the payment page.

3. Checking the transaction status

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

  • An Instant Payment Notification (IPN) is sent with all the information about the transaction, whether it is accepted or refused. The notification URL of your server must be configured in the shop in your Back Office.

    Instant Payment Notification (IPN)

  • The browser also receives the same transaction details and the end of the payment process.

    Browser return

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

Recruitment

Head Office :

LYRA NETWORK
109, rue de l’innovation
31670 Labège
FRANCE

2.17.0-doc-1.8