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": ""
      }
      "deviceData": 
        "acceptHeader": ""
        "userAgentHeader": ""
  }
}

Full schema

type required	string Value: "integrated"
mode required	string Value: "always"
required	object (Challenge) An object containing 3DS challenge preferences and configuration.
required	object (DeviceData) An object containing device dat`a for 3DS & Fraud assessment.
previousSuspiciousActivity	boolean Has the account been flagged for suspicious activity.
userType	string Enum: "guestUser" "registeredUser" "federatedAccount" "issuerCredentials" "thirdPartyAuthentication" "fidoAuthenticator"
	object (AccountHistory) Customer account history.
reorder	boolean Repeat of a previous order.
preOrderDate	string Expected date that a pre-ordered purchase will be available.
	object (TransactionHistory) Object containing details of the last transaction.
	object (GiftCardsPurchase) If the order is being used to purchase a gift card.

Attention

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.customer`	firstName, lastName, email, phone, dateOfBirth, ipAddress
`instruction.shipping`	address

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 ¹
customer.firstName
customer.lastName
customer.phoneNumber ¹
instruction.threeDS.browserLanguage
threeDS.deviceData.browserScreenWidth
threeDS.deviceData.browserScreenHeight

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

EMVco Recommended values

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.

Web Integration

API integration with a browser based client side.

iOS/Android Integration

API integration with a native client side SDK.