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

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 3D Secure challenge since the cardholder is not present.

The Authenticate Response will be returned to your back-end. An example of a successful 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.

Next steps

Test your 3DS integration with our test cards

Feedback

Was this page helpful?