1. Getting Started
This page is intented to familiarize you with parts of the 3-D Secure v2, and to provide you with some understanding of a 3-D Secure v2 authentication flow.
In 3-D Secure v2, cardholder authentication might not necessarily involve the cardholder.
An authentication flow not involving the cardholder, is called a frictionless flow, whereas a flow involving the cardholder is called a challenge flow. The frictionless flow utilizes device fingerprinting to verify cardholder authenticity, providing a smoother transaction for the cardholder.
The structure of an authentication transaction can be described broadly by the two variables below, which are included in every transaction.
Message categories (
Used for the normal payment authentication flow. The message value is
Used for e.g. cardholder account verification. The message value is
Device channels (
Authentications initiated on a e.g. a mobile phone, utilizing a dedicated native 3-D Secure SDK for the specific device. The message value is
Authentications performed using a browser, similar to 3-D Secure version 1. The message value is
Authentications performed without cardholder involvement, used for e.g. getting 3-D Secure values for subsequent recurring transactions. The message value is
1.2. URL Endpoints
There are 3 API endpoints for this service, refer to Reference for parameter definition. Brief descriptions are:
This is used when performing transactions from a browser (as opposed to using an SDK). It will return an optional 3-D Secure Method URL, which is used for browser fingerprinting. This can support risk-based analysis and assist in ensuring a frictionless flow where the cardholder is not directly involved.
While in the transition period between 3-D Secure v1 and v2, this endpoint can help determine if v1 should be used instead. This is documented in the 3-D Secure version determination guide.
The primary API method to provide authentication data to the issuer. Under certain circumstances, the authentication flow will end successfully here, this is called a frictionless flow.
Used when the
/authdid not result in a frictionless flow, this endpoint returns the result of the challenge performed by the cardholder. In this case the flow is called a challenge flow. Read more about this in Challenge flow.
1.3. Overview of Authentication Flow
This figure illustrates the authentication flow from a requestor point of view:
The following describes the individual points in the diagram:
A call to the /preauth endpoint is performed if the request originator is a cardholder using a browser. This is opposed to using a SDK or the authentication being Requestor initiated.
Information that might be usable in determining whether to fall back to 3-D Secure v1.
threeDSMethodURLthat is invoked in the user browser.
The cardholder browser invokes the received
threeDSMethodURL, to allow the ACS to fingerprint the browser. See the 3DS Method invocation guide.
The Requestor uses the /auth endpoint to send the information needed for the 3-D Secure Server. The Server assembles a
AReqmessage and transmits it to the Directory Server.
The authentication result (frictionless flow)
Information about how to proceed with the challenge (challenge flow)
Information stating why the challenge cannot continue
The cardholder completes the challenge on the their device. See the Challenge flow guide.
The ACS informs the Requestor about the challenge result through a callback.
The /postauth endpoint is used to fetch the results of the authentication.
1.4. Sandbox environment
A sandbox environment is included as a service for initial and continuous integration, and for live tests. This is our own implementation, so discrepancies with ACS implementations are unavoidable.
Under no circumstances may real card numbers or other cardholder information be sent to the sandbox.
The production endpoint is to be used only for production requests.