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.

3DS authentication is only available for instruction.method = card and will return a validation error response if used with others.

threeDS object example

To understand which values improve authentication rates see "Additional values to used by the assessment".

"instruction": {
  ....
  "threeDS": {
    "type": "integrated",
    "mode": "always",
    "challenge": {
      "returnUrl": "http://payment.example.com",
    },
    "deviceData": {
      "acceptHeader": "text/html",
      "userAgentHeader": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)",
      "browserLanguage": "en-GB",
      "browserScreenHeight": 1200,
      "browserScreenWidth": 900,
      "browserJavaEnabled": true,
      "browserColorDepth": "32",
      "timeZone": "300",
      "browserJavascriptEnabled": true,
      "channel": "browser"
    }
  }
}

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 (native)

API integration with a native client side SDK.

React Native

Using React Native with WebView

threeDS object schema

typestringrequired

Value"integrated"

modestringrequired

Value"always"

challengeobject(Challenge)required

An object containing 3DS challenge preferences and configuration.

challenge.returnUrlstringrequired

Once the customer completes the challenge page the issuer redirects/posts to the returnUrl in order for you to resume the session. It must be the full URL path.

challenge.windowSizestring

Specify the challenge window size (width x height) that the issuer should use. This is to better tailor the experience to the customers device. Default is 390x400.

Default "390x400"

Enum"250x400""390x400""600x400""500x600""fullPage"

challenge.preferencestring

Set a preference for how the Issuer decides on a 3DS challenge. challengeMandated will be automatically set by Payments API for the first CIT payment in an MIT series or when storing cards (token creation).

Enum"noPreference""noChallengeRequested""challengeRequested""challengeMandated"

deviceDataobject(DeviceData)required

An object containing device data for 3DS & Fraud assessment.

deviceData.acceptHeaderstring[ 1 .. 2048 ] charactersrequired

Used by the issuer to check if the customer's browser is compatible with the issuer 3DS challenge display.

deviceData.userAgentHeaderstring[ 1 .. 2048 ] charactersrequired

Used by issuers as part of risk analysis and correctly displaying the challenge. Must conform to RFC 7321.

deviceData.browserLanguagestring[ 1 .. 8 ] characters

Your customer's browser language that can be used by the issuer in risk analysis. Must conform to the language tags defined by IETF. E.g. en-GB, fr-FR.

deviceData.browserJavaEnabledboolean

Defines whether Java is enabled on your customers browser.

deviceData.browserColorDepthstring

The color depth of your customers browser

Enum"1""4""8""15""16""24""32""48"

deviceData.browserScreenHeightinteger(int32)

Defines the pixel height of the customers browser.

deviceData.browserScreenWidthinteger(int32)

Defines the pixel width of the customers browser.

deviceData.timeZonestring^[+-]?\d{1,4}$

Time zone offset in minutes between UTC and your customer's browser local time.
Example time zone offset values in minutes:
If UTC -5 hours:
300
+300
If UTC +5 hours:
-300

deviceData.browserJavascriptEnabledboolean

Defines whether Javascript is enabled on your customers browser.

deviceData.channelstring

Determines the channel that the transaction came through.

Enum"browser""native"

previousSuspiciousActivityboolean

Has the account been flagged for suspicious activity.

userTypestring

Enum"guestUser""registeredUser""federatedAccount""issuerCredentials""thirdPartyAuthentication""fidoAuthenticator"

accountHistoryobject(AccountHistory)

Customer account history.

accountHistory.createdAtstring

Date the customer account was created.

accountHistory.modifiedAtstring

Date the customer account was last modified.

accountHistory.passwordModifiedAtstring

Date the password for the customer account was last modified.

accountHistory.paymentAccountEnrolledAtstring

Date the payment account was added to the cardholder account.

reorderboolean

Repeat of a previous order.

preOrderDatestring

Expected date that a pre-ordered purchase will be available.

transactionHistoryobject(TransactionHistory)

Object containing details of the last transaction.

transactionHistory.attemptsLastDayinteger(int32)

Number of transactions (successful or abandoned) for this cardholder account within the last 24 hours.

transactionHistory.attemptsLastYearinteger(int32)

Number of transactions (successful or abandoned) for this cardholder account within the last year.

transactionHistory.completedLastSixMonthsinteger(int32)

Number of purchases with this customer account during the previous six months.

transactionHistory.addCardsLastDayinteger(int32)

Number of attempts to add a card in the last 24hrs.

transactionHistory.shippingAddressFirstUsedAtstring

When the shipping address used for the transaction was first used.

giftCardsPurchaseobject(PaymentsGiftCardsPurchase)

If the order is being used to purchase a gift card.

giftCardsPurchase.totalValueobject(Value)

giftCardsPurchase.quantityinteger(int32)

The number of gift cards being purchased.

Warning

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

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

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

² Provide for web/browser integration only

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

EMVco recommended values

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 payments 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 ¹
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 ¹

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

Next steps

SCA Exemptions
Testing (3DS tab) for scenario details and magic test values