1. Getting Started¶
This page is intented to familiarize you with superficial 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 flow for the cardholder.
Authentications 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 mobile device, utilizing a dedicated 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 flow where the cardholder is not challenged.
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.
The Output contains:
Information that might be usable in determining whether to fall back to 3-D Secure v1.
An optional threeDSMethodURL that 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 Securer Server to assemble a
The Auth Output is an
ARes, as defined by the specification.
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.
RReqis returned to the Requestor. Parameters are detailed in the postauth response section.
1.4. Sandbox environment¶
A sandbox environment is included as a service for initial and continuous integration, and for live tests. This is our 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.