Merchant/PSP Initiated 3DS Integration Guide

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,
    "data": {
        "threeDSServerTransID": "bfc44ca7-0373-423e-8f55-e57e6523a149",
        "acsTransID": "161d6b82-0d47-4e4b-b617-20cf6ba75754",
        "messageVersion": "2.2.0",
        "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 Continue to authorisation using the authenticationValue from the Authenticate Response.
A Authentication Attempted 3DS was attempted, but was not possible. However, proof of the authentication attempt was generated. Continue to authorisation using the authenticationValue from the Authenticate Response.
N Authentication Failed The authentication failed, stop processing the transaction.
U Authentication Unavailable Authentication could not be performed. You may attempt to proceed to authorisation without an authenticationValue.
R Authentication Rejected The issuer rejected the authentication attempt and requests that authorisation is not attempted. Stop processing the transaction.
D Decoupled Challenge Required Decoupled authentication will be performed by the issuer. Make a Result Request to learn the final outcome.
I Informational Only Authentication for the transaction was not requested. The data was sent to the ACS for informational purposes only.

For all transStatus values, see the transStatusReason field for more detail.