3DS App Integration Guide

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

App Flow Diagram

The 3D Secure app flow is shown below:

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).

Version Request

The Version Request determines whether the customer’s card supports 3DS 2, and which 3DS 2 version it supports.

To prepare for this request your mobile app must send the customer’s selected payment card to your back-end so that you can make the Version Request. You may decide the format of this request.

This request can be performed asynchronously as soon as the customer has selected the payment card or synchronously when the customer submits their order.

Your back-end can then get the PAN for the selected card to make the Version Request. An example Version Request is shown below:

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

{
  "transactionId": "123-abc-XYZ",
  "pan": "4111111111111111"
}

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

An example Version Response, when the payment card supports 3D Secure 2, is shown below:

{
  "status": 200,
  "timestamp": 1600081748,
  "cardScheme": "Visa",
  "data": {
    "transactionId": "123-abc-XYZ",
    "threeDSServerTransID": "bfc44ca7-0373-423e-8f55-e57e6523a149",
    "availableVersions": ["2.1.0", "2.2.0"],
    "versionRecommendation": "2.2.0",
    "acsStartProtocolVersion": "2.1.0",
    "acsEndProtocolVersion": "2.2.0",
    "dsStartProtocolVersion": "2.1.0",
    "dsEndProtocolVersion": "2.2.0",
    "threeDSMethodURL": "https://www.example-acs.com/method",
    "acsInfoInd": ["01", "02"]
  }
}

The Version Response will contain the supported 3D Secure protocol versions. You should use the version provided in versionRecommendation in Create Transaction and Authenticate Request.

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

Create Transaction

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

You should pass the versionRecommendation returned in the Version Response to the createTransaction method.

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.

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.

The messageVersion field is optional and will default to the versionRecommendation returned in the Version Response.

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,
  "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.

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.

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.

If you are interested in why a challenge was unsuccessful, your back-end can still call the Result Request endpoint to receive the transStatusReason.

An example Result Request is shown below:

POST https://3ds.live.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.

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

Next steps

Test your 3DS integration with our test cards

Integrate 3D Secure into your website

Feedback

Was this page helpful?

Thanks for the feedback. If you'd like to provide more detail, please email support@ravelin.com.