APIs
/
Payments
/
Additional Features
/
3DS Authentication

3DS Authentication

Steps in Summary

  1. Add the threeDS object to the payments api request to enable 3DS
  2. A response outcome of 3dsDeviceDataRequired will provide details to perform the issuers device data collection on the customers 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 issuers 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 Payment 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

Next steps