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.

1.1. Authentication

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 (messageCategory)

Payment

Used for the normal payment authentication flow. The message value is 01.

Non-Payment

Used for e.g. cardholder account verification. The message value is 02.

Device channels (deviceChannel)

APP

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 01.

BRW

Authentications performed using a browser, similar to 3-D Secure version 1. The message value is 02.

3RI

Authentications performed without cardholder involvement, used for e.g. getting 3-D Secure values for subsequent recurring transactions. The message value is 03.

1.2. URL Endpoints

There are 3 API endpoints for this service, refer to Reference for parameter definition. Brief descriptions are:

/preauth

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.

/auth

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.

/postauth

Used when the /auth did 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:

Authentication

The following describes the individual points in the diagram:

  1. 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.

  2. The /preauth response (ref. 2.1.0, 2.2.0) 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.

  3. The cardholder browser invokes the received threeDSMethodURL, to allow the ACS to fingerprint the browser. See the 3DS Method invocation guide.

  4. The Requestor uses the /auth endpoint to send the information needed for the 3-D Secure Server. The Server assembles a AReq message and transmits it to the Directory Server.

  5. The Authentication response (ref. 2.1.0, 2.2.0) is an ARes, as defined by the specification.

    This ARes contains either:

    • The authentication result (frictionless flow)

    • Information about how to proceed with the challenge (challenge flow)

    • Information stating why the challenge cannot continue

  6. The cardholder completes the challenge on the their device. See the Challenge flow guide.

  7. The ACS informs the Requestor about the challenge result through a callback.

  8. The /postauth endpoint is used to fetch the results of the authentication.

  9. Nominally a RReq is returned to the Requestor. Parameters are detailed in the /postauth response (ref. 2.1.0, 2.1.0) 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 own implementation, so discrepancies with ACS implementations are unavoidable.

Warning

  1. Under no circumstances may real card numbers or other cardholder information be sent to the sandbox.

  2. The production endpoint is to be used only for production requests.