• France
status page
demonstrations
assistance
FAQContact support
Search
Categories
Tags
English
French
English
Homepage
Use cases
Create a payment
Create an installment payment
Create a multi-card (split) payment
Create a payment by Alias (Token)
Create a payment link
Create a recurring payment
Manage subscriptions
Manage your transactions (refund, cancel...)
Analyze your reports
API docs
Embedded Form
REST API
Hosted payment
Mobile payment
File exchange
Snippets
Payment methods
Plugins
Guides
Merchant Back Office
Functional guides

View authentication messages

  • Use cases
  • Request
  • Response

The activation of these features is subject to prior approval by Sogecommerce.

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 fromVisa
  • Mastercard Identity check(replaces"Mastercard Secure Code") is the 3D Secure program fromMastercard
  • Safekeyis the 3D Secure program fromAmerican Express
  • CB Paiement sécuriséis the 3D Secure program fromCB
  • ProtectBuyis the 3D Secure program fromDinersandDiscover

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": "61881992",
      (...)
      "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 :

  • Transaction/Get
  • Transaction/Order
  • PCI/Authentication/GetSession
  • PCI/Authentication/CreateSession (from IAN)
  • PCI/Charge/CreatePayment (via the IPN)
  1. 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-EN/rest/V4.0/api/kb/authentication.html
https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.php#L9-L44
https://api-sogecommerce.societegenerale.eu/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"
}
© 2024 {'|'} All rights reserved to Sogecommerce
2.91.0-doc-1.11