View authentication session results

Presentation

This section details the use of the PCI/Authentication/GetSession Web Service to obtain the authentication result and proceed with the authorization request.

Use cases

Le Web Service PCI/Authentication/CreateSession a pour but d'authentifier le porteur de la carte de paiement. Le résultat de l'authentification contient les données nécessaires à la demande d'autorisation tel que le CAVV (pour plus d'infos : Guide d'intégration (mode simple)).

The authentication result is retrieved by the merchant:

automaticallyfrom the IAN, entered when the request is made to the Web Service :PCI/Authentication/CreateSession( fieldianTargetUrl).

If there is no response from the IAN, use the Web Service PCI/Authentication/GetSession, after the authentication session has expired (10 minutes) to retrieve the authentication result.

Request

Use the fieldoperationSessionId, present in the authentication result. This field can be found in the Web Service responsePCI/Authentication/CreateSession.

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"

Call the WebServicePCI/Authentication/GetSessionwith the fieldoperationSessionId.

PARAMETER	required	Description
operationSessionId	YES	Unique identifier for the authentication session.

Response

The AuthenticationResponseData object is the WebService response PCI/Authentication/GetSession and contains the parameters below:

PARAMETER	Description
id	Unique identifier of the authentication, in UUID format.
operationSessionId	Unique identifier for the authentication session.
value.authenticationType	Type of authentication that has been applied.
value.authenticationId.authenticationIdType	The field originates from the dsTransId field of the v2 3DS protocol.
value.authenticationId.value	Value of the authentication transaction identifier known to the banking network.
value.authenticationValue.authenticationValueType	Type of authentication value.
value.authenticationValue.value	Final authentication value (depending on the DS this value can be called CAVV, AEVV or AAV). Character string encoded in base64 with a size of 28 characters.
value.status	Authentication status, i.e. the positive/negative outcome of the authentication.
value.commerceIndicator	Commerce Indicator, or ECI (Electronic Commerce Indicator) for the 3DS protocol. Indicator returned by the ACS to report the results of cardholder’s authentication attempt.
value.reason.code	Additional code explaining the result. E.g.: DS_TIMEOUT.
value.reason.message	Additional message explaining the result.
protocol.name	Name of the protocol used by the cardholder authentication services.
protocol.version	Version of the protocol used by the cardholder authentication services.
protocol.network	Network where the payment method was authenticated.
protocol.challengePreference	Indicates whether or not the merchant has requested a challenge.
protocol.simulation	Boolean indicating if the authentication must be carried out in simulation mode.

See all the fields in our playground :

AuthenticationResponseData of type AuthenticationResult

Example of request and response

Call to the PCI/Authentication/CreateSession Web Service.

Request

/doc/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"];

?>

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"

Call to Web Service PCI/Authentication/GetSession.

Request

/doc/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/GetSession

{
"operationSessionId": "30641640cba14eab8e6766094fd201da"
}

Response


{
  "webService":"PCI/Authentication/GetSession",
  "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":{
        "id": "e1180f84-ed34-4511-b160-bd2a79c5823a",
        "protocol": {
            "name": "THREEDS",
            "version": "2.2.0",
            "network": "VISA",
            "challengePreference": "NO_PREFERENCE",
            "simulation": true,
            "_type": "V4/Charge/Authenticate/Protocol"
        },
        "value": {
            "authenticationType": "CHALLENGE",
            "authenticationId": {
                "authenticationIdType": "dsTransId",
                "value": "64305551-aaf8-4ed8-87f0-93edc79298fc",
                "_type": "V4/Charge/Authenticate/AuthenticationId"
            },
            "authenticationValue": {
                "authenticationValueType": "CAVV",
                "value": "F2lYFh91NAcDOD+I3OTQSjdMDA4=",
                "_type": "V4/Charge/Authenticate/AuthenticationValue"
            },
            "status": "SUCCESS",
            "commerceIndicator": "05",
            "extension": {
                "authenticationType": "THREEDS_V2",
                "threeDSServerTransID": "e1180f84-ed34-4511-b160-bd2a79c5823a",
                "dsTransID": "64305551-aaf8-4ed8-87f0-93edc79298fc",
                "acsTransID": "06729a8f-083e-4e77-8167-b9781797f778",
                "requestorName": "Lyra SMS",
                "_type": "V4/Charge/Authenticate/AuthenticationResultExtensionThreedsV2"
            },
            "reason": {
                "_type": "V4/Charge/Authenticate/AuthenticationResultReason"
            },
            "_type": "V4/Charge/Authenticate/AuthenticationResult"
        },
        "_type": "V4/AuthenticationResponseData"
    }
}

3. Authentication result analysis

The authentication process is complete. The response contains the data needed to proceed with the authorization request, such as the CAVV.

Categories

Tags

View authentication session results

Presentation

Use cases

Request

Example of a response

Response

Example of request and response

Request

Response

Request

Response

3. Authentication result analysis