3DS Authentication

How to enable

Using the instruction.threeDS object and setting the type value to integrated will enable a 3DS authentication to run as part of the payment request.

ThreeDS object (Required)

"instruction": {
  "threeDS": {
      "type": "integrated",
      "mode": "always",
      "challenge": {
        "returnUrl": ""
        "acceptHeader": ""
        "userAgentHeader": ""

Full schema

any (ThreeDS)

If 3DS authentication is not available/applicable (e.g. subsequent recurring (MIT), Apple Pay) a validation error message will be returned.

Additional Values used by the assessment

As well as core payment details such as the cardNumber, billingAddress and any key:values in the instruction.threeDS object, the following key:values are used as part of the 3DS authentication. By providing these, the issuer can make a more accurate assessment and will reduce challenge outcomes in favor of frictionless.

instruction.customerfirstName, lastName, email, phone, dateOfBirth, ipAddress

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.cardHoldeName
  • customer.ipAddress
  • customer.email 1
  • customer.firstName
  • customer.lastName
  • customer.phoneNumber 1
  • instruction.threeDS.browserLanguage
  • threeDS.deviceData.browserScreenWidth
  • threeDS.deviceData.browserScreenHeight

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

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

Additional Requests & Responses

When 3DS is enabled there are up to two extra steps:

  • Device Data Collection - Issuer run device data collection, used as part of the issuers risk assessment.
  • Challenge - As an additional level of fraud prevention the issuer prompts for an identity check.

placeholder image

Web Integration

API integration with a browser based client side.

placeholder image

iOS/Android Integration

API integration with a native client side SDK.