Skip to content
APIs/Payments/
/3DS Authentication

3DS Authentication

Steps in summary

  1. Add the threeDS object to the payments request to enable 3DS.
  2. A response outcome of 3dsDeviceDataRequired will provide details to perform the issuers Device Data Collection on the customer's browser.
  3. Resume the payment using the supply3dsDeviceData action from the response. If frictionless the payment will proceed and authorize.
  4. If the outcome is 3dsChallenged details will be provided to display the issuer's challenge page.
  5. Resume the payment using the complete3dsChallenge action from the response to proceed with the payment.

Integration options

Web integration

API integration with a browser based client side.

iOS/Android integration (native)

API integration with a native client side SDK.

React Native

Using React Native with WebView.

How much data to provide

The issuer uses device data and certain values in the Payments API request to decide if the transaction is likely to be fraudulent.
How this data is interpreted varies by issuer. Supplying more data increases the chances of the outcome being frictionless (without a challenge).
Some issuers may fail the authentication entirely without the recommended fields.

Below is our latest guide on what to include.

Objects used for 3DS authentication:

  • cardNumber, billingAddress - core payment details
  • instruction.threeDS - for 3DS specific data, some are mandatory
  • instruction.customer - firstName, lastName, email, phone, dateOfBirth, ipAddress

EMVco required values

  • instruction.paymentInstrument.cardHolderName
  • instruction.customer.email 1
  • instruction.customer.firstName 2
  • instruction.customer.lastName 2
  • instruction.customer.phoneNumber 1

1 Either customer.email or customer.phoneNumber are required.

2 Only required if instruction.paymentInstrument.cardHolderName is not provided.


The following are considered mandatory by EMVco and are already part of Device Data Collection. We recommend providing these in the API request along with other device values to maximize authentication rates if Device Data Collection fails.

  • instruction.threeDS.deviceData.browserScreenWidth 1
  • instruction.threeDS.deviceData.browserScreenHeight 1
  • instruction.customer.ipAddress

1 Provide for web/browser integration only.

  • instruction.paymentInstrument.billingAddress.city
  • instruction.paymentInstrument.billingAddress.country
  • instruction.paymentInstrument.billingAddress.address1
  • instruction.paymentInstrument.billingAddress.postalCode
  • instruction.paymentInstrument.billingAddress.state

Device Data Collection failure

In the event the device data collection fails to run (browser/native), additionally provide the following in the payment request to maintain healthy authentication rates and reduce issuer challenges:

Providing the data below directly in the API request should not be viewed as an alternative to running the Device Data Collection form. It is a fallback only.

  • instruction.customer.ipAddress 1
  • instruction.threeDS.deviceData.browserLanguage
  • instruction.threeDS.deviceData.browserScreenHeight
  • instruction.threeDS.deviceData.browserScreenWidth
  • instruction.threeDS.deviceData.browserJavaEnabled
  • instruction.threeDS.deviceData.browserColorDepth
  • instruction.threeDS.deviceData.timeZone
  • instruction.threeDS.deviceData.browserJavascriptEnabled
  • instruction.threeDS.deviceData.channel 1

1 Only these values apply to (iOS/Android), the others are not applicable.

How to enable authentication outage exemptions

Authentication outage exemptions are currently not part of the default merchant setup. Please speak to your Implementation Manager to enable this feature.

Once enabled, you can set threeDS.exemptionOnOutage as true in the request.

...
"threeDS": {
  "exemptionOnOutage": true
}
...

The exemption increases the likelihood of receiving a successful authorization but transactions are not eligible for liability shift.

The response body will contain the following if you use an authentication outage exemption.

...
"threeDS": {
  "outcome": "authenticationOutage"
}
...

See our testing guide for how to reproduce the response on the Try environment.

Next steps