View authentication messages

Use cases

The aim of 3D Secure is to protect e-merchants against the risk of fraud, and more specifically against cardholder disputes.

Visa Secure (replaces "Verified by Visa") is the 3D Secure program from Visa.
Mastercard Identity check (replaces "Mastercard Secure Code" ) is the 3D Secure program from Mastercard.
Safekey is the 3D Secure program from American Express.

CB Paiement sécurisé est le programme 3D Secure de CB

ProtectBuy is the 3D Secure program from Diners and Discover.

This WebService is used to retrieve messages exchanged as part of the authentication process.

In the event of a dispute, this data is essential to protect the merchant with proof of the cardholder's authentication.

Request

The authentication messages can be retrieved via the unique authentication identifier. It comes from the authenticationResponse.id field present in the final result of calls to the PCI/Authentication/CreateSession , PCI/Charge/CreatePayment Web Services received via the IPN or IAN. Or as a response from the PCI/Authentication/GetSession , Transaction/Get , Order/Get Web Services.

Here's an example in the authentication result (received in the IAN following the call to PCI/Authentication/CreateSession).

TheAuthenticationResponseData:
path :answer.id

{
  (...)
  "answer": {
    "id": "cb3cb538-1959-47c0-ba8d-2be52e535d81",
    "protocol": {
      (...)
      "_type": "V4/Charge/Authenticate/Protocol"
    },
    "value": {
      "authenticationType": "FRICTIONLESS",
      "authenticationId": {
        (...)
        "_type": "V4/Charge/Authenticate/AuthenticationId"
      },
      "authenticationValue": {
        (...)
        "_type": "V4/Charge/Authenticate/AuthenticationValue"
      },
      "status": "SUCCESS",
      "commerceIndicator": "05",
      "extension": {
        (...)
        "_type": "V4/Charge/Authenticate/AuthenticationResultExtensionThreedsV2"
      },
      "reason": {
        "_type": "V4/Charge/Authenticate/AuthenticationResultReason"
      },
      "_type": "V4/Charge/Authenticate/AuthenticationResult"
    },
    "_type": "V4/AuthenticationResponseData"
  }
}

In the example :

id: "cb3cb538-1959-47c0-ba8d-2be52e535d81" (link :Playground)

Here is an example in the payment result (via the IPN or the return to shop)

ThePayment:
path :transactions.transactionDetails.cardDetails.authenticationResponse.id

Example of a response: object `Payment`

{
    "transactions": [
    {
      "shopId": "73239078",
      (...)
      "transactionDetails": {
        (...)
        "cardDetails": {
          
          },
          "authenticationResponse": {
            "id": "fa73d948-2e96-45fb-a701-75812d19f7bb",
            "operationSessionId": "56a80c1f94f64f549a1eb00048d56d35",
            "protocol": {
              (...)
            },
            (...)
              },
              "_type": "V4/Charge/Authenticate/AuthenticationResult"
            },
            "_type": "V4/AuthenticationResponseData"
          },
      "_type": "V4/PaymentTransaction"
    }
  ]
}

In the example :

id: "fa73d948-2e96-45fb-a701-75812d19f7bb" (link :Playground)

Link to Web Services returning an authentication id :

Call the WebService PCI/Authentication/GetMessages with the unique authentication identifier.

PARAMETER	required	Description
id	YES	Unique identifier of the authentication, in UUID format.

Response

The AuthenticationMessagesResponse object will contain the parameters below:

PARAMETER	Description
id	Unique identifier of the authentication, in UUID format.
messages.date	Date of authentication message sent or received.
messages.message	Authentication message.
messages.messageType	Type of authentication message (see table below ).

Values table `messages.messageType`

Values	Full name	Description
AREQ	Authentication Request	Message used to request and initiate authentication.
ARES	Authentication Response	DS response indicating authentication status and whether strong authentication is required.
CReq	Challenge Resquest	Message initiating strong cardholder authentication.
RREQ	Results Request	Message containing the final authentication result sent by the DS.
RRES	Results Response	Acknowledgement of receipt of RReq message.
CRES	Challenge Response	ACS response indicating the end of strong authentication.
Erro	Error message	Error message received or sent.

See all the fields in our playground :

AuthenticationMessagesResponse

Example of request and response

Call to Web Service PCI/Authentication/GetMessages with the unique identifier of a transaction authentication.

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/GetMessages

{
"id": "fa73d948-2e96-45fb-a701-75812d19f7bb"
}

Response

   {
   "id": "fa73d948-2e96-45fb-a701-75812d19f7bb",
    "messages": [
        {
            "date": "2023-06-07T09:13:20Z",
            "messageType": "AREQ",
            "message": "{\"threeDSServerTransID\":\"4302c1cb-188a-46ac-a6c2-9677ddf1405c\",\"messageExtension\":[{\"criticalityIndicator\":false,\"data\":\"<MESSAGE_EXTENSION_DATA_ELEMENT>\",\"id\":\"A000000042_CB-EXEMPTACQ\",\"name\":\"CB-EXEMPTACQ\"},{\"criticalityIndicator\":false,\"data\":\"<MESSAGE_EXTENSION_DATA_ELEMENT>\",\"id\":\"A000000042_CB-USECASE\",\"name\":\"CB-USECASE\"}],\"messageType\":\"AReq\",\"messageVersion\":\"2.2.0\",\"deviceChannel\":\"02\",\"threeDSServerRefNumber\":\"3DS_LOA_SER_LYNE_020100_00098\",\"threeDSServerOperatorID\":\"batmanEnSlip\",\"threeDSCompInd\":\"Y\",\"threeDSRequestorAuthenticationInd\":\"01\",\"threeDSRequestorChallengeInd\":\"05\",\"threeDSRequestorID\":\"45251785700028\",\"threeDSRequestorName\":\"Lyra SMS\",\"threeDSRequestorURL\":\"http://www.lyra-sms.com\",\"threeDSServerURL\":\"http://localhost:8080/protected/v1/3dsv2/notify/rreq?network=CB&messageVersion=2.2.0&deviceChannel=BROWSER&challengeInd=NO_CHALLENGE_REQUESTED_TRA&authenticateId=4302c1cb-188a-46ac-a6c2-9677ddf1405c\",\"acctType\":\"02\",\"acquirerBIN\":\"00000017807\",\"acquirerMerchantID\":\"05785350       -08121902\",\"addrMatch\":\"N\",\"browserAcceptHeader\":\"text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7\",\"browserIP\":\"10.33.168.125\",\"browserJavaEnabled\":true,\"browserJavascriptEnabled\":true,\"browserLanguage\":\"fr\",\"browserColorDepth\":\"24\",\"browserScreenHeight\":\"969\",\"browserScreenWidth\":\"1920\",\"browserTZ\":\"-120\",\"browserUserAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36\",\"cardExpiryDate\":\"2406\",\"acctInfo\":{\"shipNameIndicator\":\"01\"},\"acctNumber\":\"5100********0106\",\"billAddrCity\":\"toulouse\",\"billAddrCountry\":\"250\",\"billAddrLine1\":\"2 rue de test\",\"billAddrPostCode\":\"31000\",\"email\":\"parayreludovic@gmail.com\",\"homePhone\":{\"cc\":\"33\",\"subscriber\":\"670011400\"},\"mobilePhone\":{\"cc\":\"33\",\"subscriber\":\"670011492\"},\"shipAddrCity\":\"Labège\",\"shipAddrCountry\":\"250\",\"shipAddrLine1\":\"innovation\",\"shipAddrPostCode\":\"31670\",\"mcc\":\"5965\",\"merchantCountryCode\":\"250\",\"merchantName\":\"Lyra SMS\",\"messageCategory\":\"01\",\"notificationURL\":\"https://pass-inte01.lyra-labs.fr/public/v1/3dsv2/notify/cres/4302c1cb-188a-46ac-a6c2-9677ddf1405c/CB\",\"purchaseAmount\":\"20000\",\"purchaseCurrency\":\"978\",\"purchaseExponent\":\"2\",\"purchaseDate\":\"20230607091320\",\"transType\":\"01\"}"
        },
        {
            "date": "2023-06-07T09:13:20Z",
            "messageType": "ARES",
            "message": "{\"threeDSServerTransID\":\"4302c1cb-188a-46ac-a6c2-9677ddf1405c\",\"messageExtension\":[{\"criticalityIndicator\":false,\"data\":\"<MESSAGE_EXTENSION_DATA_ELEMENT>\",\"id\":\"A000000042_CB-EXEMPTACQ\",\"name\":\"CB-EXEMPTACQ\"},{\"criticalityIndicator\":false,\"data\":\"<MESSAGE_EXTENSION_DATA_ELEMENT>\",\"id\":\"A000000042_CB-USECASE\",\"name\":\"CB-USECASE\"}],\"messageType\":\"ARes\",\"messageVersion\":\"2.2.0\",\"acsTransID\":\"286bf72c-dc87-4785-9fb0-82266849c320\",\"dsTransID\":\"d610d3a1-1a1c-402b-a4d1-34d1ab92165f\",\"acsChallengeMandated\":\"Y\",\"acsReferenceNumber\":\"3DS_LOA_ACS_PPFU_020100_00009\",\"acsURL\":\"https://acs-inte01.lyra-labs.fr/acs/v2/creq\",\"authenticationType\":\"02\",\"dsReferenceNumber\":\"DS_LOA_DIS_PPFU_020100_00010\",\"transStatus\":\"C\"}"
        },
        {
            "date": "2023-06-07T09:13:20Z",
            "messageType": "CREQ",
            "message": "{\"threeDSServerTransID\":\"4302c1cb-188a-46ac-a6c2-9677ddf1405c\",\"messageExtension\":[{\"criticalityIndicator\":false,\"data\":\"<MESSAGE_EXTENSION_DATA_ELEMENT>\",\"id\":\"A000000042_CB-USECASE\",\"name\":\"CB-USECASE\"},{\"criticalityIndicator\":false,\"data\":\"<MESSAGE_EXTENSION_DATA_ELEMENT>\",\"id\":\"SIMULATION-AREQ\",\"name\":\"SIMULATION-AREQ\"}],\"messageType\":\"CReq\",\"messageVersion\":\"2.2.0\",\"acsTransID\":\"286bf72c-dc87-4785-9fb0-82266849c320\",\"challengeWindowSize\":\"03\"}"
        },
        {
            "date": "2023-06-07T09:13:23Z",
            "messageType": "RREQ",
            "message": "{\"threeDSServerTransID\":\"4302c1cb-188a-46ac-a6c2-9677ddf1405c\",\"messageExtension\":[{\"criticalityIndicator\":false,\"data\":\"<MESSAGE_EXTENSION_DATA_ELEMENT>\",\"id\":\"A000000042_CB-AVALGO\",\"name\":\"CB-AVALGO\"}],\"messageType\":\"RReq\",\"messageVersion\":\"2.2.0\",\"acsTransID\":\"7fd8019a-c7b1-457b-9811-e3a763e789d2\",\"dsTransID\":\"a1959823-b9ff-429f-8d6e-3739ca3cf96a\",\"authenticationType\":\"01\",\"authenticationValue\":\"v**************************=\",\"eci\":\"05\",\"interactionCounter\":\"02\",\"messageCategory\":\"01\",\"transStatus\":\"Y\"}"
        },
        {
            "date": "2023-06-07T09:13:23Z",
            "messageType": "RRES",
            "message": "{\"threeDSServerTransID\":\"4302c1cb-188a-46ac-a6c2-9677ddf1405c\",\"messageType\":\"RRes\",\"messageVersion\":\"2.2.0\",\"acsTransID\":\"7fd8019a-c7b1-457b-9811-e3a763e789d2\",\"dsTransID\":\"a1959823-b9ff-429f-8d6e-3739ca3cf96a\",\"resultsStatus\":\"01\"}"
        },
        {
            "date": "2023-06-07T09:13:23Z",
            "messageType": "CRES",
            "message": "{\"threeDSServerTransID\":\"4302c1cb-188a-46ac-a6c2-9677ddf1405c\",\"messageType\":\"CRes\",\"messageVersion\":\"2.2.0\",\"acsTransID\":\"0b96eccc-4d1a-4d62-b1da-7d4bc97acf16\",\"dsTransID\":\"9bd29fdc-9487-4343-8710-2fdd5909734e\",\"challengeSelectInfo\":[],\"transStatus\":\"Y\"}"
        }
    ],
    "_type": "V4/Authentication/AuthenticationMessagesResponse"
}

Categories

Tags

View authentication messages

Use cases

Request

Here's an example in the authentication result (received in the IAN following the call to PCI/Authentication/CreateSession).

Here is an example in the payment result (via the IPN or the return to shop)

Example of a response: object `Payment`

Response

Values table `messages.messageType`

Example of request and response

Request

Response

Categories

Tags

View authentication messages

Use cases

Request

Here's an example in the authentication result (received in the IAN following the call to PCI/Authentication/CreateSession).

Here is an example in the payment result (via the IPN or the return to shop)

Example of a response: object Payment

Response

Values table messages.messageType

Example of request and response

Request

Response

Example of a response: object `Payment`

Values table `messages.messageType`