3DS 2.x API
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
.
If the Requestor doesn't want to receive the ThreeDSServerResultsResponse
with a push from the 3DS Server side to the Results Response Notification URL, there is a possibility
to disable this behavior and instead enable a pull mechanism so the Requestor can pull the data from an endpoint.
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 if the push mechanism is enabled
For details about the 3DS Results data sent from the 3DS Server to the Requestor, refer to 3DS Results. For details about the pull mechanism behavior, refer to 3DS Results Response Data.
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.
OpenAPI Definition
OpenAPI definition documents are separated in two groups, inbound and outbound files. The inbound files contain the definition for 3DS Server APIs and the models used as request and response body. The outbound files contain the schema for the models which the 3DS Server sends to the Requestor e.g 3DS Result Response. Files are available in json and yaml formats.
Files are available in json and yaml formats.
Links for downloading:
Release Notes
1.1
- Highlighted the required fields of the ThreeDSVersioningResponse V4 Model.