1. Getting Started¶
1.1. Sandbox environment¶
A sandbox environment is included to ease integration. It is provided as a service for continuous integration and for live tests. This is our own implementation so there will be some discrepancies with the production endpoint. The production endpoint is to be used only for production requests.
Under no circumstances may real card numbers or other cardholder information be sent to the sandbox.
1.2. Authentication scenarios¶
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.3. 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), where 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.
A single call to receive all the data that is needed for authentication, except for the 3-D Secure Method URL used for fingerprinting when performing an authentication through a browser. Under certain circumstances, the authentication flow will end successfully here, this is called 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.4. 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.