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

By not providing certain information it is highly likely to impact your authentication success rates. Below is our latest guide on what to include.

Data 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

By providing these, the issuer can make a more accurate assessment and will reduce challenge outcomes in favor of frictionless.

EMVco required values

If certain values are not provided, you risk increased 3dsChallenged outcomes and even 3dsAuthenticationFailed. Card issuers use the below values to help decide if a transaction is fraudulent. We strongly recommend you provide this data, so your authentication rates remain high.

  • instruction.paymentInstrument.cardHolderName
  • instruction.customer.ipAddress
  • instruction.customer.email 1
  • instruction.customer.firstName 3
  • instruction.customer.lastName 3
  • instruction.customer.phoneNumber 1
  • instruction.threeDS.browserLanguage 2
  • instruction.threeDS.deviceData.browserScreenWidth 2
  • instruction.threeDS.deviceData.browserScreenHeight 2

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

2 Provide for web/browser integration only

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

  • 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