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.
1. Add the JavaScript library to your site
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-sogecommerce.societegenerale.eu/static/js/authenticate-client/V1.0/kr-authenticate.umd.js"></script>
...
</head>
2. Initiating a request for cardholder authentication
Appelez le Web Service V4.1/PCI/Charge/CreatePayment en utilisant les champs ci-dessous :
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:
| 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 set toCard. | 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
{ "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":"SOGECOM",
"metadata":null,
"status":"SUCCESS",
"mode":"TEST",
"serverUrl":"https://api-sogecommerce.societegenerale.eu",
"_type":"V4/WebService/Response",
"answer":{
"operationSessionId":"30641640cba14eab8e6766094fd201da",
"operationUrl":"https://api-sogecommerce.societegenerale.eu/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-sogecommerce.societegenerale.eu/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("61881992:testpublickey_k7sM5cu1WTzkCCqU966agj3Ia3b04Pcsw4dZoeLVVUbc3");
- With the DOM element:
const krAuthenticate = new KrAuthenticate("61881992:testpublickey_k7sM5cu1WTzkCCqU966agj3Ia3b04Pcsw4dZoeLVVUbc3", {
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-sogecommerce.societegenerale.eu/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-sogecommerce.societegenerale.eu/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('61881992:testpublickey_k7sM5cu1WTzkCCqU966agj3Ia3b04Pcsw4dZoeLVVUbc3');
// 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
La durée de la session de paiement est fixée à 10 minutes. Au bout de ce délai, si l'IPN n'a pas été configurée par le marchand, il est recommandé de faire un appel au Web Service Order/Get pour obtenir le résultat du paiement.