3D Secure (3DS)

3D Secure (3DS) is an authentication protocol that lets the card issuer verify the cardholder's identity before a card payment is authorized.

In Revup, 3DS applies to Customer-Initiated Transactions (CIT): any payment where the customer is present and starts the payment can require 3DS authentication. This includes:

• One-off payments
• The initial payment of token-based payments
• The initial payment of subscriptions
• Subsequent CIT payments with a token (paymentDetails.type: consumer_initiated)

note

Although the customer does not enter their card details again, a CIT payment with a token can still require 3DS authentication if the card issuer decides so. Your integration must be ready to handle the waiting_user_interaction status and the 3DS challenge in this flow too.

Merchant-Initiated Transactions (MIT) are not authenticated with 3DS because the customer is not present. For more information, see CIT and MIT.

info

Adding 3DS fields to an order does not guarantee that the payment will undergo a 3DS process. Whether 3DS is applied depends on the payment provider and the card issuer, not on Revup. According to PSD2 regulations, all payments made in the European Economic Area and the United Kingdom need authentication configuration.

3DS payment flow

Frictionless vs challenge authentication

Depending on the risk assessment made by the card issuer, a 3DS payment can follow one of two flows:

• Frictionless — the issuer authenticates the cardholder using the transaction and device information, without any action from the customer. The payment continues to its result directly.
• Challenge — the issuer requires the customer to verify their identity, for example with a one-time code or a confirmation in their banking app.

When the transaction is returned with the waiting_user_interaction status and an action object, the customer must be redirected to action.url. This does not always mean the customer will have to interact: depending on the payment provider and the card issuer, the page loaded can show a challenge, or it can complete automatically, for example after collecting device information or when the issuer finally applies a frictionless authentication. Your integration must handle both cases in the same way.

Providing the threeDSDetails fields in the order gives the issuer more information for its risk assessment and can increase the chance of a frictionless authentication.

1. Configure the order

The following order fields are related to 3DS:

Field	Description
threeDSSupport	Interest level in processing the payment through 3DS: no_3ds, indifferent, preferred_3ds or required_3ds.
redirectUrl.threeDSChallengeResult	URL where the customer is redirected at the end of the 3DS challenge. A default value can also be configured for the merchant.
threeDSDetails	Additional 3DS v2.0 information about the cardholder account, merchant risk indicators and prior authentications. Providing it can increase the chance of a frictionless authentication.

Stripe

For payments processed through Stripe, Revup integrates 3DS in Stripe's automatic mode. In this mode, Stripe determines whether 3DS authentication is required for each payment, based on the card issuer and regulatory requirements. When a challenge is required, your integration handles it in the same way as for any other provider.

For a complete request example, see Create single payment order with 3DS. For the full list of fields, see Order fields.

2. Handle the 3DS challenge

3DS payments are always managed asynchronously. The first status reported for the transaction will be in_process or waiting_user_interaction.

When the payment requires a 3DS challenge, Revup returns the transaction with:

• transactionStatus set to waiting_user_interaction.
• An action object with the information required to load the 3DS challenge.

The behavior is the same whether you receive the transaction in the Revup SDK response or in the callback to the redirect URL.

The action object

Field	Type	Description
action.url	String	URL of the 3DS challenge, provided by the access control server.
action.method	String	HTTP method to use with action.url: GET or POST.
action.parameters	Array (Object)	Optional. Key and value pairs of parameters to send to action.url. Usually present when action.method is POST.

The method and data required for the challenge depend entirely on the payment provider, not on Revup. For more information, see Notification fields.

Example with GET

{
  "transactionId": "cb6dea98-57ea-4cc6-9ead-7df499d08f8a",
  "transactionStatus": "waiting_user_interaction",
  "action": {
    "url": "https://www.acsserver.com/redirect",
    "method": "GET"
  }
}

Example with POST

{
  "transactionId": "433296ec-a1cd-47b3-bf3a-db87d5926262",
  "transactionStatus": "waiting_user_interaction",
  "message": "The payment is being processed",
  "action": {
    "url": "https://www.redirect-url-domain.es",
    "method": "POST",
    "parameters": [
      {
        "key": "connector",
        "value": "THREEDSECURE"
      },
      {
        "key": "PaReq",
        "value": "XXXXYYYYZZZZZ"
      }
    ]
  }
}

Load the 3DS challenge

Use action.method to decide how to send the customer to action.url:

• GET — redirect the customer to action.url.
• POST — submit a POST request to action.url from the customer's browser, sending each item in action.parameters as a form field.

function loadThreeDSChallenge(action) {
  const { url, method, parameters = [] } = action;

  if (method === 'POST') {
    const form = document.createElement('form');
    form.method = 'POST';
    form.action = url;

    for (const { key, value } of parameters) {
      const input = document.createElement('input');
      input.type = 'hidden';
      input.name = key;
      input.value = value;
      form.appendChild(input);
    }

    document.body.appendChild(form);
    form.submit();
  } else {
    window.location.href = url;
  }
}

This loads the 3DS challenge. Once the customer completes it, they are redirected to the redirectUrl.threeDSChallengeResult URL of the order, or to the default URL configured for the merchant.

note

The page loaded from action.url does not always require customer interaction. It can complete automatically and redirect the customer without showing a challenge. In all cases, confirm the final result of the payment with the callback or the notifications, as described in Handle the result.

tip

The customer leaves your page to complete the challenge. Persist any information you need, such as the orderId and transactionId, before redirecting them.

For the SDK-specific events, see the payment.action_required event in Revup Unified SDK 1.3.

3. Handle the result

When the 3DS challenge is completed, the customer is redirected with an HTTP 301 redirect to the redirectUrl.threeDSChallengeResult URL sent in the order, or to the default URL configured for the merchant.

The final status of the payment is also sent to the notificationUrl of the order through a notification. Use the notification to update the payment in your backend, as the customer may not always reach the threeDSChallengeResult page, for example if they close the browser during the challenge.

Do not rely on the initial payment response to determine the result of a 3DS payment. Use the redirect callback, notifications or the Transaction API to obtain the final status.

The transaction information includes 3DS-related fields such as:

Field	Description
is3ds	Whether the transaction passed through the 3DS process.
authorizationInfo.eci	Electronic Commerce Indicator returned by the card scheme with the outcome of the authentication.
liabilityShift	Whether the liability for fraudulent chargebacks shifts to the card issuer after a successful 3DS authentication.

For more information, see Handle the payment result and Payment fields.

3DS errors

Code	Description
0120	Authentication Failed - 3D Secure Not Supported
0121	Authentication Failed - 3D Secure
0122	Authentication Failed - Card is not enrolled for 3D Secure V2
0123	Authentication Failed - Merchant is Not Enrolled in 3D Secure
0124	Authentication Failed - Invalid 3D Secure Code
0125	Authentication Failed - Issuer is Not Enrolled for 3D Secure V2
0126	Authentication Failed - Provider is Not Enrolled for 3D Secure
0702	3D Secure Configuration Error

For the complete list of errors, see Error appendix.

Testing 3DS

The Mock Acquirer provides test cards to simulate different 3DS results:

Card number	3DS result
5577000055770004	APPROVED (frictionless)
5555555555554444	PENDING
5555444433331111	FAILED. Error 0121 - Authentication Failed - 3D Secure
4000160000000004	PENDING with custom failed

For all test cards and codes, see Testing.