The 3DS Requestor performs three processes during an authentication:
Initialise Authentication - the 3DS Requestor sends a request to ActiveServer to initialise the authentication, preparing ActiveServer for the authentication.
Execute Authentication - ActiveServer executes the authentication. There are two main authentication flows in 3DS2, frictionless flow and challenge flow, which are described in the Process Flows section.
Get Authentication Result - the authentication result is returned to the 3DS Requestor.
Process 1: Initialise Authentication¶
In this step the 3DS web adapter collects the information that the cardholder has entered at the front end and passes it to the 3DS Requestor at the back end. The 3DS Requestor then passes all the information required by 3DS2 to ActiveServer to start the authentication.
Using our example in the integration overview, when the customer selects Continue to checkout, the 3DS web adapter sends an
initialise authentication message to the 3DS Requestor which contains the cardholder's information plus required transaction data.
The 3DS Requestor receives the
initialise authentication message, formats it according to the ActiveServer API, and generates and adds a unique 3DS Requestor transaction ID (
threeDSRequestorTransID) to the message. Once the message is populated, it will be sent to ActiveServer by calling:
/authindicates the request is an authentication request.
/brwindicates the request is from a browser. ActiveServer also accepts requests from mobile applications via
/initindicates the request is to initialise the authentication.
When ActiveServer receives the
/api/v1/auth/brw/init/ message it will return the callback URLs, i.e.
threeDSServerCallbackUrl for the 3DS Requestor to setup page forwarding mechanisms on the checkout page (hidden iframes are used for current implementation of the callbacks in
3ds Web Adapter). Once the iframes are setup, ActiveServer will be able to start the browser information collecting process and be ready for the authentication process.
ActiveServer and the ACS automatically collect the browser information, and this process is NOT part of the 3DS Requestor.
The only thing that may be related to this process in the 3DS Requestor environment is that the
3DS web adapter sets up the required hidden iframes automatically in the checkout page in order for the callback pages to be executed.
Process 2: Execute Authentication¶
Once the browser information collection is complete, authentication can be executed by the merchant by calling
/api/v1/auth/brw. This will trigger ActiveServer to initiate the 3DS2 messaging process.
What if browser information collection failed?
It is not uncommon that the browser information collection process may fail or not be started at all. In this scenario, to improve user experience, ActiveServer will return an
InitAuthTimedOut event (15 seconds after
InitAuth request is called and no
brw call thereafter) to the
3ds web adapter to indicate that Process 1 has failed. The checkout page can then handle this error accordingly.
Without this timeout mechanism, the checkout process could be stuck in the middle of processing as there won't be any callbacks sent by ActiveServer.
There are two main authentication flows in 3DS2, frictionless flow and challenge flow.
- Frictionless flow - initiates a 3D Secure authentication flow, which consists of the AReq/ARes authentication messages. If the ACS determines the transaction is low risk based on the information provided, authentication is approved immediately.
- Challenge flow - if the ACS determines that the transaction is high risk, above certain thresholds, or subject to regulatory mandates which requires further Cardholder interaction, the frictionless flow transitions into the challenge flow. In addition to the AReq and ARes messages that comprise frictionless flow, the challenge flow consists of the CReq/CRes challenge messages and the RReq/RRes result messages.
The dotted lines indicate messaging outside the scope of the 3DS2 protocol, including communication between the Client/3DS Requestor and Authorisation
Process 3: Get Authentication Result¶
Once the 3DS2 process is complete, the merchant calls
/api/v1/auth/brw/result to get the authentication result. The authentication result (from the ARes or RRes depending on challenge status) contains information such as as the ECI, Authentication Value (e.g. CAVV) and final Transaction Status.
Note that the authentication result is also available in the response of the
/api/v1/auth/brw call if the authentication process is frictionless. However, the merchant site can always get the authentication result by calling the
Get Authentication Result API.
Select Next in the footer below to learn more about the Authentication sequence.