3DS App Integration Guide

This guide explains how to use Ravelin’s 3DS Server to perform 3D Secure authentication in a mobile app.

Steps


App Flow Diagram

The 3D Secure app flow is shown below:

%%{ init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#ececff' } } }%% sequenceDiagram participant APP as Client App participant 3DS_SDK as Ravelin 3DS SDK participant BACKEND as Client Back-End participant 3DS_SERVER as Ravelin 3D Secure APP ->> 3DS_SDK: Initialisation APP ->> 3DS_SDK: Create Transaction APP ->> BACKEND: Start Authentication BACKEND ->> 3DS_SERVER: Authenticate Request 3DS_SERVER ->> BACKEND: Authenticate Response APP --> 3DS_SERVER: If a challenge is required BACKEND ->> APP: Challenge Details APP ->> 3DS_SDK: Start Challenge 3DS_SDK ->> APP: Challenge Complete APP ->> BACKEND: Challenge Complete BACKEND ->> 3DS_SERVER: Result Request 3DS_SERVER ->> BACKEND: Result Response

In the app flow all communication with the Issuer ACS is handled by the Ravelin 3DS SDK.


Initialisation

Before performing 3D Secure authentication, the Ravelin 3DS SDK needs to be initialised. This can be done when your app starts or when 3D Secure authentication is started.

Initialisation must only take place once during a single app session.

Initialisation performs various security checks to ensure that the 3DS SDK is running on a secure device which has not been tampered with.

This uses the initialize method. For details of this method see our 3DS SDK docs (iOS, Android).


Create Transaction

Call the createTransaction and getAuthenticationRequestParameters methods. For details of these methods see our 3DS SDK docs (iOS, Android).

This creates a transaction with a unique sdkTransID and gathers the device data.

Send the following device and transaction data from your app to your back-end for use in the Authenticate Request.

Name Authenticate request field Acquired from
SDK Transaction ID sdkTransID getSDKTransactionID() method
SDK App ID sdkAppID getSDKAppID() function
Device Data sdkEncData getDeviceData() method
SDK Ephemeral Public Key sdkEphemPubKey getSDKEphemeralPublicKey() function

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.

Ensure you send all the required fields, and as many optional fields as you can. The more optional fields you provide, the greater the chance of the transaction achieving a Frictionless authentication.

The Ravelin 3DS Server proceeds with the 3D Secure process. The authentication request is sent to the ACS which decides whether a challenge is required.

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 Action to take
Y Authentication Successful The transaction achieved a Frictionless authentication, continue to authorisation using the authenticationValue from the Authenticate Response.
A Authentication Attempted 3DS was attempted but was not possible. However the card scheme granted a successful authentication on the issuer’s behalf.
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.
C Challenge Required A challenge is required, make a Challenge Request.
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.


Challenge Request

To make a challenge request, your app must call the doChallenge method. One of the arguments to this function is challengeStatusReceiver, this contains callback methods which are called after the challenge has taken place. For further details of this method see our 3DS SDK docs (iOS, Android).

After calling the doChallenge method the 3DS SDK handles the whole challenge process:

  • The 3DS SDK prepares and sends a Challenge Request (CReq) to the ACS.
  • The ACS responds with the Challenge Response (CRes), and the 3DS SDK displays the challenge form to the cardholder.
  • The cardholder enters their authentication data (for example, a one time password sent via SMS).
  • The cardholder submits the challenge form, and their authentication data is sent to the ACS.
  • The ACS evaluates the authentication data to determine whether the customer successfully authenticated themselves.
  • The ACS responds to the 3DS SDK with a CRes.
  • The 3DS SDK examines the CRes and a callback method is called on challengeStatusReceiver depending on the outcome of the challenge.

If the completed callback method is called, the authentication was successful. The completed method will receive a CompletionEvent object containing the sdkTransactionID and transactionStatus values.

The transactionStatus field describes the next action you need to take.

Transaction Status Description Action to take
Y Authentication successful The challenge was successful, make a Result Request to obtain the authentication value.
N Authentication failed The authentication failed, stop processing the transaction.

If one of the other callback methods (cancelled, timedOut, protocolError, runtimeError) are called, the authentication was not successful. For details on how to proceed see our 3DS SDK docs (iOS, Android).

You must call the close and cleanup methods at the end of the 3D Secure authentication. For details of these methods see our 3DS SDK docs (iOS, Android).


Result Request

If the transaction status received by the completed callback method was Y, your back-end must send a Result Request to obtain the Authentication Value. The Authentication Value is used to authorise the transaction with your payment gateway.

An example Result Request is shown below:

{
    "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,
    "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 Action to take
Y Authentication Successful The authentication was successful, continue to authorisation using the authenticationValue from the Result Response.
A Authentication Attempted 3DS was attempted but was not possible. However the card scheme granted a successful authentication on the issuer’s behalf.
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.

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