3DS 2.x API

Overview

Browser Authentication Flow

3DS Versioning

The 3DS Versioning Method provides information about the ACS and DS supported protocols and the 3DS Method URL, if existing. When the device channel is Browser, the 3DS Versioning Method needs to be invoked before the authentication request.

The 3DS Server will:

  • generate a threeDSServerTransID
  • obtain the versioning data (ACS and DS supported protocol versions and the 3DS Method URL)
  • if present 3DS Method URL, generate a threeDSMethodDataForm

If the supported protocol version is 2.0, the obtained threeDSServerTransID should be sent in the following authentication request.

3DS versioning data could also be requested without further initiating an authentication request.

For details about the 3DS Versioning request/response models and samples, refer to 3DS Versioning.

3DS Authentication

When a 3DS Authentication is initiated, the 3DS Server will:

  • ensure the availability of the necessary information for the AReq message
  • determine which DS the authentication transaction needs to be sent
  • establish a secure link with the DS
  • send the AReq message to the DS using the secured link established

For Browser channel, when initiating authentication request, use threeDSServerTransID from previously invoked 3DS versioning.

Once a response from the DS is received, the 3DS Server will:

  • for an authenticated transaction, format and send a ThreeDSServerAuthenticationResponse indicating a successful authentication
  • for a transaction with a challenge, format a CReq message and send a ThreeDSServerAuthenticationResponse including the CReq, indicating that further Cardholder interaction is required to complete the authentication
  • for a transaction not authenticated, format a ThreeDSServerAuthenticationResponse indicating a not successful authentication

For details about the 3DS Authentication request/response models and samples, refer to 3DS Authentication.

Handle Challenge Cancelled

The 3DS Server provides an endpoint for a notification about a challenge cancellation in case the challenge was requested in the authentication response, but there was a decision from the 3DS Requestor to opt out of the challenge.

In order to notify the 3DS Server about a challenge cancelled for a specific transaction, post the 3DS Server Transaction ID to the challenge-cancelled endpoint.

For details about the challenge cancelled request sample, refer to Challenge cancelled.

3DS Results

The Results Request (RReq) Message contains information of the result of the authentication. The message is sent by the ACS through the DS to the 3DS Server. There is only one Results Request message per authentication. This message is present only when the authentication requires Cardholder challenge.

As a response the 3DS Server creates a Results Response (RRes) message and sends it to the DS. Additionally, the 3DS Server sends ThreeDSServerResultsResponse message to the Requestor via the ResultsResponseNotificationUrl.

When a RReq message is received from the DS, the 3DS Server will:

  • validate the received RReq data
  • log the received message
  • generate a RRes message
  • send the RRes message to the DS using the established secured link
  • send the ThreeDSServerResultsResponse message to the Requestor

For details about the 3DS Results data sent from the 3DS Server to the Requestor, refer to 3DS Results.

3DS Challenge

The final Challenge Response (CRes) Message contains information of the result of the challenge flow. The final Challenge Response message is sent from the ACS to the Requestor environment via an HTTP POST through the browser to the Notification URL that was sent in the initial AReq message. The final Challenge Response Message is present only for BROWSER flow when the Challenge cycle is finished. This message is a base64-encoded string.

The 3DS Server has an endpoint where the Requestor can send an HTTP POST JSON message of type ThreeDSServerFinalCResRequest containing the base64-encoded CRes message and returns a ThreeDSServerChallengeResponse message. This message will contain the decoded challenge response and should some errors occur during message processing or validation, it will include them as well.

When a CRes message is received, the 3DS Server will:

  • decode and validate the received CRes data
  • log the received message
  • return the ThreeDSServerChallengeResponse message back to the Requestor

For details about the 3DS Challenge data sent from the 3DS Server to the Requestor, refer to 3DS Challenge.