Merchant/PSP Initiated 3DS Integration Guide

On this page:

This guide explains how to perform a merchant/PSP initiated 3D Secure authentication.

This is also known as a 3DS Requestor Initiated (3RI) authentication.

This type of authentication is performed without the cardholder present.

This can be used for recurring payments or payments made in installments, when the cardholder has previously set up the payment.

Merchant/PSP Initiated 3D Secure Flow Diagram

The merchant/PSP initiated 3D Secure flow is shown below:

%%{ init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#ececff' } } }%% sequenceDiagram participant BACKEND as Client Back-End participant 3DS_SERVER as Ravelin 3D Secure BACKEND ->> 3DS_SERVER: Authenticate Request 3DS_SERVER ->> BACKEND: Authenticate Response 3DS_SERVER --> BACKEND: If a challenge is required (transStatus = D) 3DS_SERVER ->> BACKEND: Decoupled challenge completion notification BACKEND ->> 3DS_SERVER: Result Request 3DS_SERVER ->> BACKEND: Result Response

Authenticate Request

To prepare an Authenticate Request your back-end must gather the required customer and transaction data.

See our 3D Secure API reference for full details of the Authenticate Request.

A merchant/PSP initiated authentication is identified by setting the deviceChannel field to 03.

Once Ravelin receives the Authenticate Request we will proceed with the 3D Secure process. The authentication request is sent to the ACS which decides the outcome of the authentication.

Merchant/PSP-initiated authentications cannot use a browser or in-app 3D Secure challenge since the cardholder is not present. If the issuer ACS determines that a challenge is required, it will utilise a decoupled challenge to authenticate the transaction.

We recommend that you set threeDSRequestorPriorAuthenticationInfo with the details of the authentication that was completed during payment set up to improve the likelihood of achieving a frictionless authentication.

The Authenticate Response will be returned to your back-end. An example of a successful frictionless Authenticate Response is shown below:

{
  "status": 200,
  "timestamp": 1600081748,
  "cardScheme": "Visa",
  "data": {
    "messageVersion": "2.2.0",
    "threeDSServerTransID": "bfc44ca7-0373-423e-8f55-e57e6523a149",
    "acsTransID": "161d6b82-0d47-4e4b-b617-20cf6ba75754",
    "dsTransID": "7f2774c2-3b6b-43b3-b121-5179f64075b2",
    "acsReferenceNumber": "example-acs-reference-number",
    "dsReferenceNumber": "example-ds-reference-number",
    "transStatus": "Y",
    "eci": "05",
    "authenticationValue": "bG9va2l0c2FuZWFzdGVyZWdnIQo="
  }
}

See our 3D Secure API reference for full details of the Authenticate Response.

The Authenticate Response transStatus field describes the next action you need to take.

Transaction Status	Description	Next Action
`Y`	Authentication Successful	The transaction achieved a Frictionless authentication. Continue to authorisation using the `authenticationValue` from the Authenticate Response.
`A`	Authentication Attempted	The cardholder was not authenticated, but proof of the authentication being attempted has been provided. Continue to authorisation using the `authenticationValue` from the Authenticate Response.
`D`	Decoupled Challenge Required	Decoupled authentication will be performed by the issuer. Make a Result Request to learn the final outcome.
`N`	Authentication Failed	See the `transStatusReason` field for more detail. Only proceed to authorisation if authentication is not required, and this is within your risk appetite.
`U`	Authentication Unavailable	See the `transStatusReason` field for more detail. Only proceed to authorisation if authentication is not required, and this is within your risk appetite.
`R`	Authentication Rejected	See the `transStatusReason` field for more detail. The issuer rejected the authentication attempt and requests that authorisation is not attempted.
`I`	Informational Only	Authentication was not requested. The data was sent to the ACS for informational purposes only.

Decoupled Challenge

Decoupled challenges are most commonly used during merchant/PSP-initiated (3RI) authentications. They can also be used instead of browser or in-app challenges in cases where the customer’s device is not supported or the merchant/PSP requested it by setting the threeDSRequestorDecReqInd in the Authenticate Request.

Decoupled challenge happens outside the scope of the EMVCo 3D Secure specification and therefore neither the merchant/PSP-backend nor the 3DS Server are involved in its completion. Once the challenge is completed the ACS sends the results to the 3DS Server after which the results can be retrieved by the merchant/PSP by making a Result Request. The maximum time allowed for the completion of a decoupled challenge by the EMVCo 3D Secure specification is 7 days. This can be reduced by setting threeDSRequestorDecMaxTime in the Authenticate Request.

Ravelin’s 3DS Server can notify the merchant/PSP backend when the results are available. The results can then be retrieved by making the Result Request. In order to set up the notification the merchant/PSP would need to provide us with a Decoupled Challenge Notification URL during integration to which the 3DS Server will send a POST request with the threeDSServerTransID for the authentication in the request body. If required, please also provide us with a way to authenticate the request, for example basic authentication or bearer token. If you successfully receive the notification you should respond with a 200 OK response. An example request is shown below:

POST https://example-merchant.com/3ds/decoupled-challenge-notification HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
  "threeDSServerTransID": "bfc44ca7-0373-423e-8f55-e57e6523a149"
}

Result Request

If the transaction status in the Authenticate Response was D, the ACS will have performed a decoupled authentication.

When your backend receives a request to your Decoupled Challenge Notification URL you must send a Result Request to obtain the Authentication Value. The Authentication Value is used to authorise the transaction with your payment gateway.

The handler for your Decoupled Challenge Notification URL may make the Result Request.

An example Result Request is shown below:

POST https://pci.ravelin.com/3ds/result HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
  "threeDSServerTransID": "bfc44ca7-0373-423e-8f55-e57e6523a149"
}

See our 3D Secure API reference for full details of the Result Request.

If the authentication was successful, the response will contain the Authentication Value.

An example successful Result Response is shown below:

{
  "status": 200,
  "timestamp": 1600081748,
  "cardScheme": "Visa",
  "data": {
    "threeDSServerTransID": "bfc44ca7-0373-423e-8f55-e57e6523a149",
    "messageVersion": "2.2.0",
    "transStatus": "Y",
    "eci": "05",
    "authenticationValue": "dGVzdHltY3Rlc3QsaGV5dGhlcmUK"
  }
}

See our 3D Secure API reference for full details of the Result Response.

The Result Response transStatus field describes the next action you need to take.

Transaction Status	Description	Next Action
`Y`	Authentication Successful	Continue to authorisation using the `authenticationValue` from the Result Response.
`A`	Authentication Attempted	The cardholder was not authenticated, but proof of the authentication being attempted has been provided. Continue to authorisation using the `authenticationValue` from the Result Response.
`N`	Authentication Failed	See the `transStatusReason` field for more detail. Only proceed to authorisation if authentication is not required, and this is within your risk appetite.
`U`	Authentication Unavailable	See the `transStatusReason` field for more detail. Only proceed to authorisation if authentication is not required, and this is within your risk appetite.
`R`	Authentication Rejected	See the `transStatusReason` field for more detail. The issuer rejected the authentication attempt and requests that authorisation is not attempted.

This completes the Merchant/PSP Initiated 3DS Flow.

Next steps

Test your 3DS integration with our test cards

Feedback

Was this page helpful?