API Reference

Learn about our 3D Secure 2 payload structure and the objects and parameters you can pass in the payment request.

This page describes payload structures and objects for /payments API. If you are using a classic integration, see 3D Secure 2 classic integration.

The following endpoints support 3D Secure 2 authentication:

In addition to the regular parameters you provide on your payment request, we recommend that you provide all available information to increase the likelihood of achieving a frictionless flow and a higher authorisation rate. 

Some of these fields might be mandatory for the issuer, and not providing them in your payment request might result in a failed authentication.

Payload structure

Field Type Description
threeds2.fingerprintToken Base64url encoded string

Required to initialize the device fingerprinting process. This contains the following parameters:

  • threeDSMethodNotificationURL
  • threeDSMethodUrl
  • threeDSServerTransID
threeds2.challengeToken Base64url encoded string Required to initialize the challenge flow. This contains the following parameters:
  • acsReferenceNumber
  • acsTransID
  • acsURL
  • messageVersion
  • threeDSNotificationURL
  • threeDSServerTransID
threeds2.fingerprint Base64 encoded string

Returned by the Component after the challenge flow. This contains the following parameters:

  • threeDSCompInd
threeds2.challengeResult Base64 encoded string

Returned by the Component after the challenge flow. This contains the following parameters:

  • transStatus

accountInfo 

Field Type Required Description

accountAgeIndicator

String (error)

Indicator for the length of time since this shopper account was created.

Allowed values:

  • notApplicable

  • thisTransaction
  • lessThan30Days
  • from30To60Days
  • moreThan60Days

accountChangeDate

String (error)

Date when the shopper's account was last changed.

Format: ISO 8601 YYYY-MM-DDThh:mm:ssTZD

Sample: 2017-07-17T13:42:40+01:00

accountChangeIndicator

String (error)

Indicator for when the shopper's account was last changed.

Allowed values:

  • thisTransaction

  • lessThan30Days
  • from30To60Days
  • moreThan60Days

accountCreationDate

String (error)

Date when the shopper's account was created.

Format: ISO 8601 YYYY-MM-DDThh:mm:ssTZD

Sample: 2017-07-17T13:42:40+01:00

passwordChangeDate

String (error)

Date when the shopper last changed their password.

Format: ISO 8601 YYYY-MM-DDThh:mm:ssTZD

Sample: 2017-07-17T13:42:40+01:00

passwordChangeDateIndicator

String (error)

Indicator for when the shopper's account was last changed.

Allowed values:

  • thisTransaction
  • lessThan30Days
  • from30To60Days
  • moreThan60Days

purchasesLast6Months

Integer (error)

Number of purchases in the last 6 months.

addCardAttemptsDay

Integer (error)

Number of attempts the shopper tried to add a card to their account in the last day.

pastTransactionsDay

Integer (error)

Number of transactions from this shopper in the past 24 hours.

pastTransactionsYear

Integer (error)

Number of transactions from this shopper in the past year.

paymentAccountAge

String (error)

Date this payment method was added to the shopper's account.

Format: ISO 8601 YYYY-MM-DDThh:mm:ssTZD

Sample: 2017-07-17T13:42:40+01:00

paymentAccountIndicator

String (error)

Indicator for the length of time since this payment method was added to the shopper's account.

Allowed values:

  • notApplicable

  • thisTransaction
  • lessThan30Days
  • from30To60Days
  • moreThan60Days

deliveryAddressUsageDate

String (error)

Date the selected delivery address was last used.

Format: ISO 8601 YYYY-MM-DDThh:mm:ssTZD

Sample: 2017-07-17T13:42:40+01:00

deliveryAddressUsageIndicator

String (error)

Indicator for when this delivery address was last used.

  • thisTransaction
  • lessThan30Days
  • from30To60Days
  • moreThan60Days

suspiciousAccActivity

Boolean (error) Whether suspicious activity was recorded on this account.

homePhone

String (error)

Shopper's home phone number (including the country code).

mobilePhone

String (error)

Shopper's mobile phone number (including the country code).

workPhone

String (error)

Shopper's work phone number (including the country code).

billingAddress

This object is required by schemes for both browser-based and app-based implementations.

Field Type Required Description

city

String

(tick)

Cardholder Billing Address City

country String
(tick)

Cardholder Billing Address Country

houseNumberOrName

String
(tick)

Cardholder Billing Address Line 1

postalCode

String
(tick)

Cardholder Billing Address Postal Code

stateOrProvince

String
(tick)

Cardholder Billing Address State

street

String
(tick)

Cardholder Billing Address Line 1

browserInfo

This object is required for deviceChannel browser.

Field Type Required Description
acceptHeader String

The accept header value of the shopper's browser.
colorDepth Int

The color depth of the shopper's browser.
javaEnabled Boolean

Whether the shopper's browser has Java enabled.
language String

The name of the browser language used by the shopper. Usually a two letter country code.

Examples: NL, FR, US.

screenHeight Int

The pixel height of the shopper's screen.
screenWidth Int

The pixel width of the shopper's screen.
timeZoneOffset String

Time difference between UTC time and the shopper's browser local
time, in minutes. Example: "-120"

userAgent String

(tick)

The user agent value of the shopper's browser.

card

Field Type Required Description

number

String

(tick)

Cardholder Account Number

expiryMonth String (tick) Card/Token Expiry Month
expiryYear String (tick) Card/Token Expiry Year

holderName

String (tick)

Cardholder Name

installments

Field Type Required Description

value

Int

(tick)

Installment Payment Data

merchantRiskIndicator

Field Type Required Description
addressMatch Boolean (error)

Whether the chosen delivery address is identical to the billing address.

deliveryEmail String (error)

The delivery email address (for digital goods).

deliveryTimeframe String (error)

The estimated delivery time for the shopper to receive the goods.

Allowed values:

  • electronicDelivery
  • sameDayShipping
  • overnightShipping
  • twoOrMoreDaysShipping
giftCardAmount Integer (error)

The amount purchased with a prepaid or gift card.

giftCardCount String (error)

Number of individual prepaid or gift cards used for this purchase.

preOrderDate String (error)

For pre-order purchases, the expected date this product will be available to the shopper.

Format: ISO 8601 YYYY-MM-DDThh:mm:ssTZD

Sample: 2017-07-17T13:42:40+01:00

preOrderPurchase Boolean (error)

Whether this transaction is for pre-ordering a product.

reorderItems Boolean (error)

Whether the shopper has already purchased the same items in the past.

deliveryAddressIndicator String (error)

Indicator regarding the delivery address.

Allowed values:

  • shipToBillingAddress
  • shipToVerifiedAddress
  • shipToNewAddress
  • shipToStore
  • digitalGoods
  • goodsNotShipped
  • other

recurring

Field Type Required Description

recurringFrequency

String

(error)

Recurring Frequency

recurringExpiry

String (error)

Recurring Expiry

shippingAddress

Field Type Required Description

city

String

(error)

Cardholder Shipping Address City

country String (error)

Cardholder Shipping Address Country

houseNumberOrName

String (error)

Cardholder Shipping Address Line 1

street

String (error)

Cardholder Shipping Address Line 1

postalCode

String (error)

Cardholder Shipping Address Postal Code

stateOrProvince

String (error)

Cardholder Shipping Address State

shopperEmail

Cardholder Email Address. This object is required by schemes for both browser-based and app-based implementations.

threeDS2RequestData

Field Type Required Description
authenticationOnly Boolean (error)

If set to true, you will only do the 3D Secure 2 authentication, not the payment authorisation.

challengeIndicator String (error)

Possibility to specify a preference for receiving a challenge from the issuer.

Allowed values:

  • noPreference
  • requestNoChallenge
  • requestChallenge
deviceChannel String

(tick)

The environment of the shopper. Allowed values:

  • app
  • browser
deviceRenderOptions Object (error)

Display options for the 3DS2.0 SDK. Required for deviceChannel app.

  sdkInterface String (error)

Supported SDK interface types.

Allowed values:

  • Native
  • Html
  • both
  sdkUiType Array (error)

String array of UI types supported for displaying specific challenges.

Allowed values:

  • text
  • singleSelect
  • multiSelect
  • outOfBand
  • otherHtml
notificationURL String (error) URL where the Challenge Response value will be sent. Required for deviceChannel browser.

sdkAppID

String (error)

The sdkAppID value as received from the 3DS 2.0 SDK. Required for deviceChannel app.

sdkEncData String (error) The sdkEncData value as received from the 3DS 2.0 SDK. Required for deviceChannel app.

sdkEphemPubKey

Object (error) The sdkEphemPubKey value as received from the 3DS 2.0 SDK. Required for deviceChannel app.
  crv String (error) The crv value as received from the 3D Secure 2.0 SDK.
  kty String (error) The kty value as received from the 3D Secure 2.0 SDK.
  x String (error) The x value as received from the 3D Secure 2.0 SDK.
  y String (error) The y value as received from the 3D Secure 2.0 SDK.
sdkMaxTimeout Integer (error) The maximum amount of time in minutes for the 3DS 2.0 authentication process. Only for deviceChannel set to app.
sdkReferenceNumber String (error) The sdkReferenceNumber value as received from the 3DS 2.0 SDK. Only for deviceChannel set to app.
sdkTransID String (error) The sdkTransID value as received from the 3DS 2.0 SDK. Only for deviceChannel set to app.
threeDSCompInd String (error) Completion indicator for the threeDSMethodUrl fingerprinting.
threeDSRequestorURL String (error) URL of the (customer service) website that will be shown to the shopper in case of technical errors during the 3DS2.0 process

threeDS2Result

Field Type Required Description
authenticationValue String

(tick)

The value for the 3D Secure 2.0 authentication session. The returned value is a Base64-encoded 20-byte array.

Example: AQIDBAUGBwgJCgsMDQ4PEBESExQ=

eci String

(tick)

The Electronic Commerce Indicator returned from the schemes for the 3D Secure 2.0 payment session.

Example: 02

threeDSServerTransID String

(tick)

The unique identifier assigned to the transaction by the 3D Secure 2.0 Server.

timestamp String

(tick)

The date and time of the cardholder authentication, in UTC.

Format = YYYYMMDDHHMM

transStatus String

(tick)

Indicates whether a transaction was authenticated, or whether additional verification is required.

Possible values:

  • Y = Authentication / Account verification successful.
  • N = Not Authenticated / account not verified. Transaction denied.
  • U = Authentication / account verification could not be performed.
  • A = Authentication / verification was attempted but could not be verified.
  • C = Challenge Required. Additional authentication is required using a Challenge.
  • R = Authentication / account verification rejected by the Issuer.
transStatusReason String

(tick)

Provides information on why the transStatus field has the specified value.

Possible values:

  • 01 = Card authentication failed.
  • 02 = Unknown device.
  • 03 = Unsupported device.

  • 04 = Exceeds authentication frequency limit.

  • 05 = Expired card.

  • 06 = Invalid card number.

  • 07 = Invalid transaction.

  • 08 = No Card record.

  • 09 = Security failure.

  • 10 = Stolen card.

  • 11 = Suspected fraud.

  • 12 = Transaction not permitted to cardholder.

  • 13 = Cardholder not enrolled in service.

  • 14 = Transaction timed out at the ACS.

  • 15 = Low confidence.

  • 16 = Medium confidence.

  • 17 = High confidence.
  • 18 = Very high confidence.
  • 19 = Exceeds ACS maximum challenges.
  • 20 = Non-Payment transaction not supported.
  • 21 = 3RI transaction not supported.