English
API ReferenceSign In

Dynamic 3DS

Last updated 03/22/2021

Introduction

3DS increases the security of online payments because this it helps to verify buyer's identity. This process usually requires an additional step such as a One-Time-Password, or app login. Naturally, this increases friction for your customers during payment process.

Having 3DS activated may also cause certain payments to fail. Reasons for this include:

  • An issuing bank may be less likely to decline payments when 3DS is not activated
  • A card may not be enrolled in 3DS because it is not activated for e-commerce, in which the transaction will not go through anyway even if 3DS is optional
  • Some businesses (e.g. tourism) charge their foreign customer's card on behalf of the customer, in which the issuing bank would not allow 3DS to go through

How Can Dynamic 3DS Help?

Xendit Dynamic 3DS reviews online card payments made by your customers, to see if these payments would be more likely to succeed if 3DS is skipped.

Every card has a Bank Identification Number (BIN), which is the first 6 digits of the card.

When your customer makes an online card payment through Xendit, and Dynamic 3DS is activated, we will assess the acceptance rates of cards that have the same BIN when 3DS is activated or skipped. This checks if cards that have this BIN have a higher failure rate if 3DS is activated. This assessment uses data across all the transactions we process for all our merchants.

The result of the assessment is simple:

  • If that card is assessed to likely have a higher acceptance rate with 3DS activated, then we will recommend that 3DS be activated. If you're using XenInvoice, 3DS will automatically be initiated in this case. The recommendation will look like this:
{
    "should_3ds": true,
    "bin_number": "466160"
}
  • If that card is assessed to likely have a higher acceptance rate without 3DS activated, then 3DS will not be initiated for that transaction.
{
    "should_3ds": false,
    "bin_number": "420080"
}

Note:

  • Activating Dynamic 3DS does not deactivate 3DS across all your card payments. For card payments where Dynamic 3DS recommends not to skip 3DS, then 3DS will still be initiated.
  • For multiple-use tokens, where Dynamic 3DS is activated and 3DS is set to optional, you can choose to not authenticate even when Dynamic 3DS recommends not to skip 3DS.

Benefits of Dynamic 3DS

You can expect to see an increase in acceptance rates for your card transactions, meaning higher volumes and revenue and better payment experience for your customers.

Contact your Xendit Account Manager after you have activated Dynamic 3DS if you would like us to perform a review of its impact on your payments. This should ideally be done after a few months at least so that there is enough data to do a comparative analysis.

What You Should Watch Out For

On transactions where 3DS is skipped, there is no liability shift for a fraudulent chargeback. Thus, if a transaction turns out to be fraudulent and the actual cardholder raises a chargeback, there is a risk that you will lose the chargeback and have to return the funds received from that payment.

As 3DS is a fraud prevention tool, skipping 3DS leads to increased fraud risk. Our Xendit Fraud Guard can help you keep the risk of such fraud under control.

How You Can Activate Dynamic 3DS

Please contact your Xendit Account Manager directly if you wish to activate Dynamic 3DS. We will respond to your request shortly thereafter and process it together with you from there.

Do note that not every merchant is eligible for Dynamic 3DS since skipping 3DS entails an amount of risk which Xendit has to ascertain for each individual merchant, based on your industry and individual business circumstances.

Setting Up Dynamic 3DS for Use

Here we set out instructions on how you can use Dynamic 3DS depending on your integration with Xendit.

Direct Integration With Xendit.JS

Xendit.JS is automatically updated when we add features to it. If you integrated with us directly using JavaScript (e.g. on a HTML checkout page), as long as you continue to load Xendit.JS from the CDN, it will contain the Dynamic 3DS function.

The relevant code in Xendit.JS that performs the Dynamic 3DS function is:

Xendit.card.threeDSRecommendation = function (requestData, callback)

For transactions using single-use tokens, as Xendit.JS bundles tokenization and 3DS together, the Dynamic 3DS and authentication process is automatic. No additional step is necessary on your end to use Dynamic 3DS once it is activated.

For multiple-use tokens, you will have to write a function that will call:

Xendit.card.threeDSRecommendation = function (requestData, callback)

With the request:

// if using token ID</code></strong>
var requestData = {
token_id: '5ddb78581341a42969aac5de'
}
// "token_id" is the Xendit-generated ID of the multiple-use token you created during tokenisation</code>

// if using BIN</code></strong>
var requestData = {
bin_number: '123456'
}
// "bin_number" is the BIN of the card that is transacting

You will need to write a function to handle the callback function:

callback = function (err, recommendation)

This callback function accepts two arguments:

  • err is an error object that has information about failures
  • recommendation contains the 3DS recommendation used to trigger 3DS or skip 3DS

The result of the recommendation will be passed to the callback function and will look like this:

{
    "should_3ds": true,
    "token_id": '5ddb78581341a42969aac5de',
    "bin_number": '123456'
}
// if Dynamic 3DS recommends that 3DS should be skipped, "should_3ds" will return "false"
// if you used "bin_number" to send the request, you will not see "token_id" in the recommendation

Based on the 3DS recommendation, you can then configure your system to call our Authentication API endpoint:

  • If "should_3ds": true, then initiate authentication and continue with charge
  • If "should_3ds": false, then skip authentication and go straight to authorization and then charge

Invoices

On Xendit Invoices through the Invoice UI, once Dynamic 3DS is activated, it will work automatically. The 3DS recommendation will be generated in the back-end and the payment will proceed to, or skip, 3DS based on that recommendation. You will not need to perform any additional step to enable this.

SDKs

If you are using Xendit SDKs for integration, please refer to our Dynamic 3DS - SDK docs for implementation.

Testing Dynamic 3DS

We have a test page where you can send test Dynamic 3DS requests and see sample responses. Under "API Configuration", you should paste the Public Key which you can get from your Xendit Settings (Settings > Developers > API Keys) in your Xendit Dashboard.

You can try out the test page even if Dynamic 3DS has not been activated for you yet.

Testing Guide

Below are credit card BINs that you can use to simulate true or false responses from the Dynamic 3DS test page.

ScenarioBIN
Dynamic 3DS recommendation returns true520000
Dynamic 3DS recommendation returns false411111

As mentioned above, you should trigger an authentication (3DS) request if the recommendation is true. If the recommendation is false, skip authentication and proceed to send a charge request if you wish to process the payment immediately.

Note: You can use the default public API key (already filled on the form) in our dynamic 3DS test page, if you want to use yours, you need to activate the feature (dynamic 3DS) first through your dashboard Settings > Payment Method > Cards > Cards Settings.