Implementation guide

This section describes how to implement the exchanges between the browser, the merchant server and the payment gateway when the cardholder authentication is handled by our authentication server during the payment.

To facilitate integration of the solution, our JavaScript library collects data from the customer's equipment and browser, communicates directly with the 3DS Server and manages the cardholder's interaction during the challenge.

In the ,HEAD, of the page, add the JavaScript library to a <script>.

<head>
 ...
 <script src="https://static.systempay.fr/static/js/authenticate-client/V1.0/kr-authenticate.umd.js"></script>
 ...
</head>

2. Initiating a request for cardholder authentication

Call the Web ServiceV4.1/PCI/Charge/CreatePayment using the fields below:

LEVEL	name	Description	required
1	amount	Amount expressed in the smallest currency unit.	YES
1	currency	Code (ISO 4217 alpha3) of the payment currency.	YES
1	orderId	Order reference ( recommended ).	No
1	formAction	Allows to indicate if you want to save the card details. Possible values: PAYMENT REGISTER_PAY	No
1	customer	Object containing buyer's data.	No
1	paymentForms	Object containing the card data.	YES
2	paymentMethodType	Type of payment method.Must be valued at CARD.	YES
2	pan	Card number.	YES
2	expiryMonth	Card expiration month.	YES
2	expiryYear	Card expiration year.	YES
2	securityCode	Card security code (CVV or 4DBC).	No
1	ipnTargetUrl	Url to notify end of authentication	No

Other optional fields are available. Find field descriptions in our playground.

Sample query

/doc/en-EN/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.1/PCI/Authentication/CreatePayment

{  
  "amount": "990",
  "currency": "EUR",
  "paymentForms": [
      {
        "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"];

?>

In the AuthenticationSessionResponse, you will find the following fields:

answer.operationSessionId: authentication session identifier (to keep)
answer.operationUrl: url to be sent to the JavaScript library

Field descriptions can be found on our playground.

Example of a response

{
  "webService":"PCI/Charge/CreatePayment",
  "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/Payment/Session/30641640cba14eab8e6766094fd201da;JSESSIONID=7A4beEA2d5fdbFeA7389F3B91a7bDBaBc8DA9df5.default-hostname",
    "_type":"V4/PCI/Authentication/AuthenticationSessionResponse"
  }
}

In the example :

answer.operationSessionId: "30641640cba14eab8e6766094fd201da"
answer.operationUrl: "https://api.systempay.fr/api-payment/V4/Charge/Public/Authenticate/Payment/Session/30641640cba14eab8e6766094fd201da;JSESSIONID=7A4beEA2d5fdbFeA7389F3B91a7bDBaBc8DA9df5.default-hostname"

3. Initialize authentication script

Once the authentication session has been created, you need to initialize the JavaScript authentication library and call the authenticate method. It is advisable to add a visual loading indicator to this call.

// définition de la class javascript
class KrAuthenticate{
  constructor(publicKey,options)
  authenticate(operationUrl)
}

1. Class initialization parameters `KrAuthenticate`

name	Description	required
publicKey	Public TEST or PRODUCTION key for the store. More info: 3 rd key in the table of REST API keys.	YES
options	DOM element in which the authentication window will be displayed (optional).	No

You can also make the authentication window appear in another DOM element using the element attribute of the optional options parameter.

Without DOM element ( advised ):

  const krAuthenticate = new KrAuthenticate("73239078:testpublickey_Zr3fXIKKx0mLY9YNBQEan42ano2QsdrLuyb2W54QWmUJQ");

With the DOM element:

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

In this example, the DOM element id is : id-challenge-element.

2. Authentication execution method parameters `KrAuthenticate.authenticate`

Use the operationUrl field generated during session creation (step 2).

name	Description	required
operationUrl	Authentication initialization URL provided in the V4.1/PCI/Charge/CreatePayment service response in the answer/AuthenticationSessionResponse#operationUrl object.	YES

Example: .

operationUrl: "https://api.systempay.fr/api-payment/V4/Charge/Public/Authenticate/Payment/Session/30641640cba14eab8e6766094fd201da;JSESSIONID=7A4beEA2d5fdbFeA7389F3B91a7bDBaBc8DA9df5.default-hostname"

3. Code example with class ,`KrAuthenticate`,and method `KrAuthenticate.authenticate`

Example of integration using bootstrap, JQuery and the library:

<!-- import JS -->
    [...]
    <script src='https://static.systempay.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('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 authenticatePayment(){
        document.querySelector('#submitButton').disabled = true;
        buildOverlay();
        krAuthenticate.authenticate("https://theUrlFromThePciCall", myCallback);
    }</script>

4. Executing the JavaScript library

The JavaScript library performs all the actions required for authentication.

Authentication cases	Description	Test
3DS2 Frictionless, sans 3DS Method	Authentication takes place without any interference from the wearer.	3DS2 - Frictionless Authentication, without the 3DS Method
3DS2 Frictionless, avec 3DS Method	A script (3DS Method) is executed upstream of authentication, which then takes place without any interference from the bearer.	3DS2 - Frictionless authentication, with the3DS Method
3DS2 Challenge, sans 3DS Method	Authentication requires action on the part of the bearer.	3DS2 - Challenge authentication, without3DS Method
3DS2 Challenge, avec 3DS Method	A script (3DS Method) is executed upstream of the bearer's authentication actions.	3DS2 - Challenge authentication, with the3DS Method

See Tests and use cases for more examples.

5. Analysis of payment results

At the end of the authentication and authorization request, the platform returns a Payment object in the IPN. It describes the payment details (payment status, result of authorization request, result of cardholder authentication, etc.).

More info: Payment.

Managing timeouts

The payment session duration is set to 10 minutes . After this time, if the IPN has not been configured by the merchant, it is recommended to make a call to the Web ServiceOrder/Get to get the payment result.

Categories

Tags

Implementation guide

1. Add the JavaScript library to your site

2. Initiating a request for cardholder authentication

Sample query

Example of a response

3. Initialize authentication script

1. Class initialization parameters `KrAuthenticate`

2. Authentication execution method parameters `KrAuthenticate.authenticate`

3. Code example with class ,`KrAuthenticate`,and method `KrAuthenticate.authenticate`

4. Executing the JavaScript library

5. Analysis of payment results

Managing timeouts

Categories

Tags

Implementation guide

1. Add the JavaScript library to your site

2. Initiating a request for cardholder authentication

Sample query

Example of a response

3. Initialize authentication script

1. Class initialization parameters KrAuthenticate

2. Authentication execution method parameters KrAuthenticate.authenticate

3. Code example with class ,KrAuthenticate,and method KrAuthenticate.authenticate

4. Executing the JavaScript library

5. Analysis of payment results

Managing timeouts

1. Class initialization parameters `KrAuthenticate`

2. Authentication execution method parameters `KrAuthenticate.authenticate`

3. Code example with class ,`KrAuthenticate`,and method `KrAuthenticate.authenticate`