INTEGRATION

Getting Started

TRANSACTION ASSURANCE

3D-Secure

INTEGRATION

3D-Secure

3 Domain Secure, also known as 3DS is an authentication protocol. 3DS adds an additional layer of security to online payments. The fundamental concept behind 3DS is to authenticate the identity of the cardholder during an online transaction. The 3 domains refer to the issuer, acquirer and the interoperability domain, the latter being the infrastructure provided by the card networks for 3DS authentications.

The first version was 3DS1 created by Visa in early 2000s, and it was later adopted by other payment schemes under there own brand names. Although 3DS1 was a first step towards improving online payment security, there were a couple of challenges such as poor user experience, high checkout abandonment, and limited support for modern devices.

Later on 3DS2, a newer version was created that also addressed some of the challenges of 3DS1. Also the ownership of the protocol was transferred to EMVco. 3DS2 was also aligned with the regulation of the revised Payment Services Directive (PSD2), which came into full effect on September 14, 2019 (see here for the directive). PSD2 states the requirements for strong customer authentication (SCA), and the method of card authentication that meet SCA requirements.

SCA comprises of three pivotal elements: something you know, something you own, and something you are. This was defined under PDS2 in the Regulatory Technical Standards (RTS). To comply with these SCA requirements for payment authentication, 3DS emerges as the go-to solution. Upon successful 3DS authentication, the liability for fraudulent chargebacks transitions from the merchant to the card issuer, a phenomenon known as liability shift.

Silverflow has its own 3DS solution, which can service its agents in 3DS Authentications.

Frictionless Flow

A 3DS authentication knows 2 flows; either frictionless or a challenge flow. The frictionless flow consists of the least number of steps for the cardholder. This means SCA is not necessary and thus the challenge flow is bypassed entirely.

The starting point is sending an authentication request by calling POST /3ds. When the issuer does not require a challenge (for example, when sufficient data points lead to a positive risk-based assessment) it will respond with a 3DS result of "authenticated".

The result signifies that the shopper seamlessly navigated the process, concluding the authentication. To increase the likelihood of achieving a frictionless flow, set the property called challengeIndicator to "no-challenge" of your 3DS authentication request when calling POST /3ds. Another way to increase the likelihood of the cardholder going through a frictionless flow is to request an exemption.

Note that the acquirer usually will be liable for fraud when using exemptions. See Exemptions section below for more information about exemptions and liability shifts.

Challenge Flow

The challenge flow also starts with an authentication request by calling  POST /3ds. As opposed to the frictionless flow, the issuer now decides that the cardholder needs to take an extra step to authenticate themselves, also known as strong customer authentication (SCA). Therefore in the response, the result property will be challenge. As explained in the section above, there are ways to try to get the cardholder through a frictionless flow. Ultimately, the issuer decides whether that is honored or a challenge is required.

There could be use cases where SCA is required, for example, in the first transaction of a recurring sequence. In this case, the property challengeIndicator when calling  POST /3ds needs to be set to challenge-mandated, to indicate to the issuer that a challenge flow must take place. 

Exemptions

In light of PSD2, it's important to differentiate between exempted and out-of-scope transactions. Exemptions are designed to facilitate a frictionless flow for specific payment scenarios, aiming to streamline the process for cardholders by skipping the challenge flow. Out-of-scope transactions are not subject to the PSD2 mandate, and therefore, Strong Customer Authentication (SCA) is not required. In this section, we will go over the possible exemptions.

SCA exemptions - PSD2 mandates Strong Customer Authentication (SCA) for electronic payments to enhance security, but it also allows for specific exemptions to avoid excessive friction.

Low-risk transactions - Transaction Risk Analysis (TRA) Low-risk transactions refer to transactions processed by issuers or acquirers that fall below-specified thresholds related to a certain amount, as stated here below: 

  • 0.13% for amounts between €0 to €100 EUR

  • 0.06% for amounts between €100 to €250 EUR

  • 0.01% for amounts between €250 to €500 EUR

For currencies other than the euro, the transaction amount thresholds are converted using the daily exchange rate published by the European Central Bank (ECB).

Once the above requirements are met, through our API, this exemption can be requested when initiating your 3DS authentication request by setting the challengeIndicator to no-challenge-tra and using our charges endpoint by setting the scaExemptionRequest to "tra". If the issuer approves the exemption, the cardholder will undergo a frictionless flow. It's important to note that the party requesting the exemption (either the acquirer or issuer) will assume liability for fraud.

Low-value Transactions - Transactions below €30,- are considered low value and are exempt from SCA. However, only five consecutive low-value payments on the same card can be exempted or when the cumulative sum of the previous low-value payments on the same card is under €100,-. 

After five consecutive transactions or when the cumulative sum goes over 100,-, SCA is required again. The issuer is responsible to keep track of the cumulative sum and consecutive count

As with other exemptions, the party requesting the exemption will carry the fraud liability. On our API you can request this exemption when sending your 3DS authentication request by setting the challengeIndicator to no-challenge-low-value and/or using our charges endpoint by setting the scaExemptionRequest to"low-value". When the issuer honors the exemption the cardholder will go through a frictionless flow.

Secure Corporate payments - The Secure Corporate Payments exemption applies to payments made through a dedicated corporate payments process or protocol. This includes payments made through central travel accounts (CTA), lodged corporate/commercial cards, virtual cards dedicated to corporate expenses, and secure corporate cards. For example a corporate procurement system that can accessed by authorized employees through a secure log-in process or protocol initiated by businesses that is not available to consumers.

Similar to other exemptions, you can request this exemption by setting the challengeIndicator to "no-challenge-scp" when calling POST /3ds and/or using our charges endpoint by setting the scaExemptionRequest to "scp". If the issuer honors the exemption, the cardholder will proceed through a frictionless flow.

Recurring transactions - Recurring transactions that are exempted from SCA are a series of transactions that consist of the same amount and are made to the same payee. 

Only the initial transaction of a recurring series requires SCA. The best practice here is to set the challengeIndicator to "challenge-mandated" in the authentication request.

However, if there is any change in the transaction amount, SCA authentication will be required again. Alternatively, these transactions can be treated similarly to Merchant Initiated Transactions (MITs), offering a degree of flexibility, particularly in instances where the transaction amount varies.

With recurring transactions, the first transaction requires SCA, and when authenticated successfully the liability shifts to the issuer. However, for the subsequent transactions of the recurring sequence, the liability does not shift and remains with the acquirer. This does not apply when 3RI flow is used for the subsequent transactions, see here for more information on 3DS 3RI.

Applying Exemptions

The card networks recommend requesting the same exemptions during authentication and authorization. This means that the first exemption request will be when you call POST /3ds, and the second will be when doing a charge request by calling POST /charges . At Silverflow, we provide both options. We do recommend sending the exemption request at least in the 3DS authentication request because when not granted this will result in a challenge flow, where the cardholder will need to undergo SCA and can still complete the payment. However, whenever an exemption request in authorization is not granted, it will result in a soft decline, and the charge request is declined. The cardholder would need to start the payment initiation again in this case.

Exemptions & fraud liability - As described above it is possible to request an exemption during the 3DS flow. When honored by the issuer it will result in a frictionless flow for the cardholder. However, keep in mind that when the merchant or acquirer requests the exemption the liability does not shift and remains at the merchant/acquirer.

When setting up a 3DS strategy it is advised to consider frictionless flows through exemptions versus the liability that remains at the merchant/acquirer and based on that trade-off, set your 3DS rules according to your risk appetite. 

The above guidance on liability shift are provided as a reference only. We recommend relying on the official guidance provided by the card schemes. 

3DS result and fraud liability

When calling our 3DS endpoints the 3DS result will indicate if there was a liability shift or not. There are 4 different 3DS results possible: 

Authenticated - This result indicates that the cardholder was successfully authenticated. Both the frictionless and the challenge flow, can have authenticated as a 3DS result. The liability shifts to the issuer. 

Non-authenticated - This result indicates that the cardholder is non-authenticated. This can be the result after the cardholder completed the challenge flow or did not complete the challenge flow. The liability remains at the merchant/ acquirer. 

Attempt - This result indicates that the merchant attempted to use 3DS, but the issuer was unable to complete the authentication process. The liability shifts to the issuer. 

Challenge - This result indicates that the cardholder still has to complete the challenge flow. The 3DS authentication is still ongoing. It is advised to wait with authorization processing until an authenticated, attempt or non-authenticated result is returned when doing a GET/3ds/{threedsKey}. 

3DS result

Explanation

Liability shift

Authenticated

This result indicates that the cardholder was successfully authenticated. Both the frictionless and the challenge flow, can have authenticated as a 3DS result.

The liability shifts to the issuer.

Non-authenticated

This result indicates that the cardholder is non-authenticated. This can be the result after the cardholder completed the challenge flow or did not complete the challenge flow. 

The liability remains at the merchant/ acquirer.

Attempt

This result indicates that the merchant attempted to use 3DS, but the issuer was unable to complete the authentication process.

The liability shifts to the issuer.

Challenge 

This result indicates that the cardholder still has to complete the challenge flow. The 3DS authentication is still ongoing. It is advised to wait with authorization processing until an authenticated, attempt or non-authenticated result is returned when doing a GET/3ds/{threedsKey}.

There is none, at this stage.

Out-of-Scope of SCA transactions

Out of scope transactions are not covered by the PSD2 mandate and don’t require SCA.

Merchant Initiated Transactions (MITs) - Merchant-initiated transactions (MITs) are transaction types where the cardholder is not directly involved at the time of the transaction (is not in session). These transactions occur based on an initial charge, for which payment details were previously stored with the customer's consent for future use. The initial payment in a series of MITs must undergo Strong Customer Authentication (SCA), but subsequent payments can bypass SCA if the charge request specifies it as an MIT. 

MOTO transactions - Mail Order and Telephone Orders (MOTO) charges are out of scope from PDS2 and therefore from SCA requirements. These transactions, which involve orders placed via mail or telephone, are not classified as online payments and thus do not require SCA authentication.

Inter-regional (One-Leg) Transactions - Inter-regional transactions, also known as one-leg transactions, occur when either the issuer or the acquirer is not based in the European Economic Area (EEA), Monaco, or the UK. These transactions are considered out-of-scope, as per the PSD2 directive, and are out of scope from SCA requirements. For instance, transactions involving US cardholders shopping at European merchants or vice versa are not subject to SCA authentication.

Anonymous prepaid cards - Due to the anonymous nature of these type of cards, cardholders do not need to complete SCA when such a payment method is used to complete the transaction.

For further details and a comprehensive list of exemptions, you can refer to the official documentation here provided by the European Banking Authority. Additionally, it's worth noting that countries outside of Europe, such as Australia, Brazil, Malaysia, and India, may also have authentication requirements for specific payment transactions.

3RI Flow

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.

3DS Challenge Flow Integration

The 3DS challenge flow facilitates strong customer authentication, complying with the PSD2 directive. The challenge flow requires the cardholder to take extra steps to validate their identity. The 3DS protocol is designed to do this in a secure way with a native look and feel, therefore the cardholder will interact with their issuing bank directly while undergoing the challenge. This requires some extra technical infrastructure.

3dsChallengeTemp

On a high level, the following happens:

  • The cardholder checks out and the 3DS authentication is initiated (step 1 and 2).

  • The issuer determines that the cardholder needs to be challenged (step 5).

  • The cardholder browser sets up a communication channel directly with the issuer (step 9). The issuer endpoint is in the acsURL of the rres property in the 3DS entity.

  • A challenge window is rendered in the cardholder browser. This challenge window is owned by the issuer. All interactions within this window are between the cardholder browser and the issuer. There are no other parties in between (step 10). Because other parties, including Silverflow, cannot know what happens during this interaction, they get notified later with the result.

  • The cardholder performs the challenge and the issuer receives and evaluates the result (step 11 and 12).

  • The issuer reports the result to the card network (DS Server) and the acquirer (3DS Server) (step 13 to 16).

  • The 3DS requestor is being notified that the challenge has been finished. This is the trigger to close the challenge window. Note that this does not contain the actual result of the challenge (step 17).

  • The 3DS requester retrieves the result of the challenge from the 3DS server (step 18).

The majority of the complexity is found in in managing the challenge window and setting up communication with the issuer. This following paragraph explains how this can be set up.

Initiating the Challenge Flow by Sending a Challenge Request

The cardholder browser needs to send a message called the Challenge Request (CReq) to the issuer (step 9). The goal of this CReq is to set up the channel of communication between the cardholder and the issuer.

The response of the CReq is the HTML that the issuer generates. This HTML represents the challenge window and needs to be rendered in such a way that the cardholder can see it, for example in an HTML iframe or a new browser window.

Creating the Challenge Request

The CReq contains information for the issuer to identify the transaction and contains the JSON fields as described in the table below.

Property Name

Description

Type

threeDSServerTransID

Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.

The value can be retrieved from ares.threeDSServerTransID.

36 character string

acsTransID

Universally unique transaction identifier assigned by the ACS to identify a single transaction.

The value can be retrieved from ares.acsTransID.

36 character string

messageType

The value is always CReq

4 character string

messageVersion

2.1.0 or 2.2.0

6 digit string

challengeWindowSize

Values accepted: 

01 (250 x 400)

02 (390 x 400)

03 (500 x 600)

04 (600 x 400)

05 (Full screen) 

2 digit string

See the example below for a correctly formatted CReq:

Sending the Challenge Request

Once the CReq has been created, it must be sent from the cardholder browser to the issuer. This needs to be done in a particular way:

  • The HTTP method must be POST

  • The Content-Type header needs to be application/x-www-form-urlencoded. This means that in the request the keys and values are encoded in key-value tuples separated by &.

  • The CReq needs is sent as a key-value pair in the request. The key is creq.

  • The value of the creq key is the CReq. However, the CReq JSON structure must be base64url encoded. Note that base64url is different than normal base64.

  • The request needs to be sent to the URL received in the ares.acsURL, for example https://acsUrl.com/challenge.

Session Management

Optionally, you can add custom data to the CReq HTTP request which will be returned to you on the CRes HTTP response unchanged (note that this is not part of the CReq and CRes JSON itself). This can be used to accommodate for custom session handling. You can use the field threeDSSessionData for this, which also needs to be base64url encoded. Let’s assume this is your threeDSSessionData in JSON:

The final HTTP request should look something like this, including the optional threeDSSessionData after the creq (note that your actual HTTP request might look more complete, this is just a general example):

Completing the Challenge Flow

Once the cardholder has completed the challenge flow, the 3DS requester receives a notification (step 17). This notification is called the Challenge Response (CRes).

The CRes contains the field described in the table below.

Property Name

Description

Type

threeDSServerTransID

Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.

The value can be retrieved from ares.threeDSServerTransID.

36 character string

acsTransID

Universally unique transaction identifier assigned by the ACS to identify a single transaction.

The value can be retrieved from ares.acsTransID.

36 character string

messageType

The value is always CRes

4 character string

messageVersion

2.1.0 or 2.2.0

6 digit string

transStatus

Indicates the result of the transaction. It can only contain the following values in the CRes:

Y (Authentication Verification Successful)

N (Not Authenticated /Account Not Verified; Transaction denied.)

1 character string

See the example below for a correctly formatted CRes:

Receiving the Challenge Response

The CRes is sent to the notificationUrl provided in the initial 3DS request. The CRes is sent from the challenge window in the cardholder browser (not from the server of the issuer directly). This is possible because at this stage the challenge window is still open and controlled by the issuer; the issuer is capable of executing its own Javascript in there.

The CRes is sent in the following way:

  • The HTTP method is POST.

  • The Content-Type is application/x-www-form-urlencoded. This means that in the request the keys and values are encoded in key-value tuples separated by &.

  • The CRes needs is sent as a key-value pair in the request. The key is cres.

  • The value of the cres key is the CRes JSON structure in a base64url encoded format. Note base64url is different than normal base64.

  • The CRes is sent to the notificationUrl provided in the initial request.

  • If the threeDSSessionData has been provided in the CReq, this field is returned unchanged in the CRes with key threeDSSessionData.

Continuing the Flow to Authorization

The received CRes does not contain the authenticationValue that is required for authorization. The authenticationValue is the proof of authentication and will represent the authentication outcome. This can either be positive (fully authenticated) but also negative (in case of authentication attempts). The authenticationValue can be retrieved from the 3DS Server, in this case Silverflow.

Retrieving the 3DS Entity

To get the authenticationValue, do an HTTP GET request to the 3DS endpoint using the 3DS key received in the initial response. The result of the challenge has now been appended to the existing 3DS entity.

The result can be found in the added rreq property, which is the RReq we have received directly from the issuer. The rreq property will only be there after receiving the CRes on the notificationUrl. This implies that you have to wait to receive the CRes before retrieving the challenge result. Receiving the CRes should be the trigger to GET the result; you do not need to poll the API. Note that if you do the GET before receiving the CReq, the rreq property might not be there yet!

Once you’ve done the GET to /3ds/tds-<your-key>, you’ll receive an entity looking like this:

Note that the flow has a value of challenge and the result is now authenticated. The relevant fields for authorization are rreq.authenticationValue and rreq.dsTransID. Once you’ve been able to retrieve those fields, the 3DS flow is finished.

The rreq.authenticationValue and rreq.dsTransID need to be provided in the threeDsAuthenticationResult when creating a charge. This links the authorization to the corresponding 3DS authentication.

3DS Method Integration

The 3DS Method URL flow is an optional flow prior to the 3DS authentication that allows the issuer to gather more data of the cardholder environment to perform more accurate fingerprinting. This ultimately makes it easier to determine whether a challenge flow is necessary or not, resulting in less challenge flows. The 3DS Method URL flow requires some additional infrastructure.

3dsMethodTemp

On a high level, the following happens:

  • Silverflow maintains a cache that contains 3DS enrollment information. This cache gets updated daily with information from the card networks.

  • The 3DS requestor checks if there is a 3DS Method URL associated to the issuer of the card. This indicates whether the issuer supports the 3DS Method flow (step 1).

  • The 3DS requestor will use the cardholder browser to make a call directly to the issuer. This request is sent to the 3DS Method URL and includes the generated threeDSServerTransID. Usually this call is made inside a hidden HTML iframe (step 3 and 4).

  • The issuer is now able to execute JavaScript inside the hidden iframe. This is leveraged by the issuer to gather additional data (step 5).

  • Once the issuer is finished, the 3DS requestor is informed through a callback from the issuer. Now the normal 3DS authentication can start (step 6).

Checking if the 3DS Method Flow is Supported

Because the 3DS Method Flow is optional, not all issuers support it. To check if an issuer supports the 3DS Method flow, you can call the /3ds/cardRanges endpoint as documented on the API documentation. The response of this endpoint contains 3DS enrollment information for the provided card number (step 1).

Consider the following example response of the /3ds/cardRanges endpoint:

The relevant parts for executing the 3DS Method Flow are:

  • threeDSMethodURL: If this is present, the issuer supports the 3DS Method flow.

  • threeDSServerTransID: If threeDSMethodURL is present, Silverflow will generate the threeDSServerTransID on behalf of you and return it. This value must be used in the 3DS Method Flow and in the 3DS authentication.

Preparing the 3DS Method Flow

The cardholder browser needs to send a field called threeDSMethodDatato the earlier obtained threeDSMethodURL. The threeDSMethodDatais a JSON object with the following structure:

Property Name

Description

Type

threeDSServerTransID

Universally unique transaction identifier generated by Silverflow to identify a single transaction. This ID is returned in the /3ds/cardRangesresponse.

36 character string

threeDSMethodNotificationURL

The URL that will receive the notification of the completion of the 3DS Method from the ACS.

Variable length string with a maximum of 256 characters

See the example below for a correctly formatted threeDSMethodData:


Sending the 3DS Method Request

Once the threeDSMethodData has been created, it must be sent from the cardholder browser to the issuer. This needs to be done in a particular way:

  • The request is usually sent through a hidden iframe in the browser (step 3).

  • The HTTP method must be POST

  • The Content-Type header needs to be application/x-www-form-urlencoded. This means that in the request the keys and values are encoded in key-value tuples separated by &.

  • The threeDSMethodData is sent as a key-value pair in the request. The key is threeDSMethodData.

  • The value of the threeDSMethodData is the JSON structure above. However, the threeDSMethodData must be base64url encoded. Note that base64url is different than normal base64.

  • The request needs to be sent to the threeDSMethodURL obtained from the /3ds/cardRanges endpoint.

The final HTTP request should look something like this (note that your actual HTTP request might look more complete, this is just a general example):

Once this request has been sent (step 4), the issuer will respond with its script to gather additional data (step 5). How this is done exactly, is issuer specific.

Note that the 3DS Method Flow has to be finished within 10 seconds.

Finishing

the 3DS Method Flow

When the issuer is finished executing its script, it will send a request to the threeDSMethodNotificationURL. The request is sent through the browser window controlled by the issuer (step 6). The issuer will echo back the threeDSMethodData just containing the threeDSServerTransID.

The structure is described in the table below:

Property Name

Description

Type

threeDSServerTransID

Universally unique transaction identifier assigned by Silverflow to identify a single transaction.

This ID is provided in the /3ds/cardRanges response.

36 character string

See an example below:

The notification is sent in the following way:

  • The HTTP method is POST.

  • The Content-Type is application/x-www-form-urlencoded. This means that in the request the keys and values are encoded in key-value tuples separated by &.

  • The Content-Type header needs to be application/x-www-form-urlencoded.

  • The threeDSMethodData is sent as a key-value pair in the request. The key is threeDSMethodData.

  • The value of the threeDSMethodData is the JSON structure above. However, the threeDSMethodData must be base64url encoded. Note that base64url is different than normal base64.

  • The request is sent to the threeDSMethodNotificationURL provided in the initial request to the issuer to initiate the 3DS Method Flow.

Continuing to 3DS Authentication

When calling /v1/3ds to initiate a 3DS authentication, you must provide the same threeDSServerTransID that was returned by Silverflow in the /3ds/cardRanges response (step 7).

Once the notification has been received, the 3DS Method Flow is finished. Now the 3DS authentication can start.

When calling /v1/3ds to initiate a 3DS authentication, you must provide the same threeDSServerTransID that was returned by Silverflow in the /3ds/cardRanges response (step 7). This is used by the issuer to link the authentication with the execution of the 3DS Method Flow. Because the issuer had the opportunity to gather more data, the chances of getting challenged are reduced.

Trans Status Reason Code Descriptions

ares.transStatusReason

Transaction Status Reason Description

1

Card authentication failed

2

Unknown Device

3

Unsupported Device

4

Exceeds authentication frequency limit

5

Expired card

6

Invalid card number

7

Invalid transaction

8

No Card record

9

Security failure

10

Stolen card

11

Suspected fraud

12

Transaction not permitted to cardholder

13

Cardholder not enrolled in service

14

Transaction timed out at the ACS

15

Low confidence

16

Medium confidence

17

High confidence

18

Very High confidence

19

Exceeds ACS maximum challenges

20

Non-Payment transaction not supported

21

3RI transaction not supported

22

ACS technical issue

23

Decoupled Authentication required by ACS but not requested by 3DS Requestor

24

3DS Requestor Decoupled Max Expiry Time exceeded

25

Decoupled Authentication was provided insufficient time to authenticate cardholder. ACS will not make attempt

26

Authentication attempted but not performed by the cardholder

27–79

Reserved for EMVCo future use (values invalid until defined by EMVCo)

80–99

Reserved for DS use