Integration guide (simple mode)

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

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

LEVEL	name	Description	required
1	customer	Object containing buyer's data.	No
1	paymentForm	Object containing the card data.	YES
2	pan	Card number.	YES
2	expiryMonth	Card expiration month.	YES
2	expiryYear	Card expiration year.	YES
2	networkPreference	Name of the preferred network recommended by the merchant.	YES
1	merchant	Object containing the merchant contract number.	YES
2	mid	Merchant ID number.	YES
1	protocolRequest	Object describing the desired authentication mode.	YES
2	Name	Name of the authentication protocol.	YES
2	Version	Version of the authentication protocol.	No
1	merchant	Object containing information about the contract.	YES
1	productType	Product type for which the transaction is made.	YES
1	transactionCategory	Populated with PAYMENT.	YES
1	amount	Amount for which authentication is requested.	YES
1	ianTargetUrl	Url required for end-of-authentication notification	YES

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/PCI/Authentication/CreateSession

{
  "amount": 1230,
  "currency": "EUR",
  "transactionCategory": "PAYMENT",
  "productType": "GOODS_OR_SERVICE_PURCHASE",
  "merchant": {
    "mid": "1234567"
  },
  "paymentForm":{
    "pan": "4970110000000013",
    "expiryMonth": "02",
    "expiryYear": "24",
    "networkPreference": "VISA"
  },
  "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"];

?>

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/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"
  }
}

In the example :

answer.operationSessionId: "30641640cba14eab8e6766094fd201da"
answer.operationUrl: "https://api.systempay.fr/api-payment/V4/Charge/Public/Authenticate/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 REST API keys table.	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`

Utilisez le champ operationUrl généré lors de l' appel PCI/Authentication/CreateSession (étape 2).

name	Description	required
operationUrl	Authentication initialization URL provided in Web Service response PCI/Authentication/CreateSession in object answer/AuthenticationSessionResponse#operationUrl.	YES

Example: .

answer.operationUrl: "https://api.systempay.fr/api-payment/V4/Charge/Public/Authenticate/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: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. Perform authentication

The JavaScript library takes care of executing all the actions required for authentication. Below is a list of possible scenarios.

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 the 3DS Method
3DS2 Challenge, sans 3DS Method	Authentication requires action on the part of the bearer.	3DS2 - Challenge authentication, without the 3DS Method
3DS2 Challenge, avec 3DS Method	A script (3DS Method) is executed upstream of the bearer's authentication actions.	3DS2 - Challenge authentication, with the 3DS Method

See Tests and use cases for more examples.

5. Authentication result analysis

The authentication result will be automatically posted to the URL, valued in the field:ianTargetUrlduring the authentication request initialization.
This result contains the data required for the authorization application, such as theCAVV.

Managing timeouts

The authentication session lasts 10 minutes.
At the end of this period, it isRecommendedcall the Web ServicePCI/Authentication/GetSessionto obtain the authentication result.

Categories

Tags

Integration guide (simple mode)

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. Perform authentication

5. Authentication result analysis

Managing timeouts

Categories

Tags

Integration guide (simple mode)

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. Perform authentication

5. Authentication result analysis

Managing timeouts

1. Class initialization parameters `KrAuthenticate`

2. Authentication execution method parameters `KrAuthenticate.authenticate`

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