3D-Secure

Silverflow's API for 3DS authentications (3D-Secure 2.x) is designed with simplicity in mind. It provides a straightforward abstraction over the 3DS protocol while exposing all the necessary data from the card network. By delivering the correct type of transaction, along with other mandatory data such as the amount and card number, Silverflow handles the construction of the 3DS protocol messages and the interaction with the card network, making the process seamless for developers.

The 3DS protocol offers developers two distinct flows: the frictionless flow and the challenge flow. The frictionless flow is triggered when the issuer deems the transaction to have a low risk of fraud, such as for low amounts. In cases where the transaction carries a higher risk of fraud, the challenge flow, requiring additional cardholder interaction, is initiated. Developers have the control to manage these flows based on their specific needs. The result of the 3DS process is an authentication value, which must be provided to the issuer through the card networks during authorization. PIN, CVC, and AVS authentication are performed during the authorization process, giving developers the power to ensure secure transactions.

The 3DS frictionless flow is the most straightforward 3DS flow. A 3DS call is made, and if the flow property is frictionless and the result property is authenticated, the authentication is completed.

The ares.authenticationValue and ares.dsTransID can be used for authorization; the values of these properties need to be passed in threeDsAuthenticationResult.authenticationValue and threeDsAuthenticationResult.directoryServerTransId of the charge request, respectively.

The challenge flow is more involved. A challenge flow is observed when the flow and result properties contain a challenge. The initial call succeeded, but the cardholder must still perform a challenge. A cardholder challenge can be initiated by creating a CReq and filling it in with the data received in the 3DS response:

This CReq must be encoded using the base64 URL and sent to the area.acsURL through the cardholder browser. The HTTP method must be POST, and the Content-Type must be application/x-www-form-urlencoded.

Note that the CReq must be encoded by base64 URL, not base64 encoded. Some issuers might return an error if this requirement is not satisfied. For more information, please look at the EMV 3-D Secure Protocol and Core Functions Specification (2018), section A.5.4 (Browser CReq and CRes POST).

If the result in the first call is a 3DS attempt or non-authenticated, the flow property will be none, and the result property will be attempt or non-authenticated.

3DS requester-initiated authentications (3RI), also known as merchant-initiated authentications, allow merchants to authenticate a transaction without the direct involvement of the cardholder. 3RI is a 3DS authentication message enabling merchants to submit data to the issuer to assess and authorize a payment when the buyer is absent.

The merchant must store the cardholder's information from a previous transaction to generate the authentication data necessary for authorization.

To allow an issuer to gather additional browser information before the regular 3DS authentication flow, Silverflow provides the possibility of using the 3DS Method URL to facilitate this risk assessment.

Using the 3DS Method is optional, and not all account ranges support 3DS and the Method URL. To assess whether a 3DS Method URL is available, a POST call can be made to the /3ds/cardRanges endpoint, returning, among other things, the threeDSMethodURL.

After obtaining the information on the Method URL, a hidden iFrame can be generated on the checkout page. Through this, a POST call to the threeDSMethodURL should be made, which includes the threeDSMethodNotificationURL and the threeDSServerTransID generated by the 3DS Requestor.

When the issuer is finished, the 3DS Requestor will receive a notification on the threeDSMethodNotificationURL that was provided, and the normal 3DS authentication flow can be completed.

According to the Mastercard Rules, a UCAF/AAV cryptogram has a specific validity limit, and the Visa 3D Secure guides make no mention of this, but generally, it is advised to use a UCAF/AAV within the first 90 days.

After this point, an issuer might still approve an authorization request with the provided UCAF/AAV. An authorization can still be attempted without the AAV or UCAF data, but the merchant becomes liable in case of fraud (loss of liability shift).

3DS transaction status and reason codes can be found in the response of a 3DS authentication request, ares.transStatusReason and ares.transStatus. It provides information, in the form of a letter, on the transStatus and the reason, in the form of a number, why the particular transStatus has been returned.

The table below maps the transStatus to the actual reason written out in plaintext.

The table below maps the transStatusReason number to the actual reason written out in plaintext.