Checkout icon

API reference

Learn about parameters that you can use in your 3D Secure request.

To support 3D Secure 2 authentication, use v41 or later of the following endpoints:

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

3D Secure 2 additional parameters

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 objects are mandatory for some issuers and card schemes, and not providing them in your payment request can result in a failed authentication. Click the object names to see all the parameter descriptions for that object.

Object name Required Description
accountInfo -x- Shopper account information for 3D Secure 2.
billingAddress -x- We strongly recommend that you include this in your request. Card schemes require this for channel web, iOS, and Android implementations.
browserInfo -white_check_mark-
Required for all channels for 3D Secure 1		 Full object required for channel web.

The userAgent and acceptHeader fields are required for mobile integrations (channel iOS and Android) if you want to support 3D Secure 2 redirect authentication.
deliveryAddress -x- The address where the purchased goods should be delivered. Include this in your request whenever available.
installments -x- Include in your request when you want to split the payments into installments.
merchantRiskIndicator -x- Additional risk fields for 3D Secure 2. Include this in your request whenever available.
mpiData -x- Use this object to authorise a payment with Adyen if you have 3D Secure 2 authentication data from another 3D Secure 2 provider.
paymentMethod.holderName Required for Visa The cardholder's name.
shopperEmail Required for Visa We strongly recommend that you include this in your request. Card schemes require this for channel web, iOS, and Android implementations.
shopperIP Required for Visa We strongly recommend that you include the shopper's IP address for channel web.
socialSecurityNumber -x- The shopper's CPF or CNPJ number. We strongly recommend that you include this for shoppers in Brazil. Supported from v50 and later of our API.
threeDS2RequestData -x- Include this in your request when specifically required in your integration. For example, in a 3D Secure 2 authentication-only implementation.
threeDS2requestData.homePhone,
threeDS2RequestData.workPhone or
threeDS2RequestData.mobilePhone		 Required for Visa A phone number for the shopper. shopperEmail or a phone number is required for Visa.

Payload structure

FieldTypeDescription

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

3D Secure indicators

The following parameters indicate your readiness to support 3D Secure 2 natively and your preference to perform 3D Secure authentication on a transaction. Include the following parameters in the /payments request, if applicable.

Object name Required Description
authenticationData.attemptAuthentication -x- Indicates if you want to perform 3D Secure authentication for a transaction. Allowed values:
  • always – Perform 3D Secure authentication.
  • never - Do not perform 3D Secure authentication. If PSD2 SCA regulations require that you must perform authentication, the transaction gets declined.
Alternatively, you can use Dynamic 3D Secure to configure rules for applying 3D Secure.
authenticationData.authenticationOnly -x- If set to true, you will only do the 3D Secure 2 authentication, and not the payment authorisation.
authenticationData.threeDSRequestData.nativeThreeDS -x- Including this doesn't mean every transaction will use 3D Secure 2. Adyen still selects the version of 3D Secure based on configuration to optimize authorisation rates and improve the shopper's experience.

This parameter only indicates your readiness to support 3D Secure 2 natively on Drop-in or Components. To specify that you want to perform 3D Secure on a transaction, use Dynamic 3D Secure or send the authenticationData.attemptAuthentication parameter.
scaExemption -x- Indicates the exemption type that you want to request for the particular transaction. If a value is specified, this will override our exemption logic. Possible values:
  • lowValue
  • secureCorporate
  • trustedBeneficiary
  • transactionRiskAnalysis

accountInfo

FieldTypeRequiredDescription

accountAgeIndicator

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

Allowed values:

  • notApplicable

  • thisTransaction

  • lessThan30Days

  • from30To60Days

  • moreThan60Days

accountChangeDate

String
-x-
 Date when the shopper's account was last changed.

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

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

accountChangeIndicator

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

Allowed values:

  • thisTransaction

  • lessThan30Days

  • from30To60Days

  • moreThan60Days

accountCreationDate

String
-x-
 Date when the shopper's account was created.

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

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

You can also use this field to include the account creation date in your payment request. This information can then be used for the Shopper account age risk check when you select the creation date option.

passwordChangeDate

String
-x-
 Date when the shopper last changed their password.

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

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

passwordChangeIndicator

String
-x-
 Indicator for when the shopper's account was last changed.Allowed values:

  • thisTransaction

  • lessThan30Days

  • from30To60Days

  • moreThan60Days

purchasesLast6Months

Integer
-x-

Number of purchases in the last 6 months.Maximum value: 9999

addCardAttemptsDay

Integer
-x-

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

pastTransactionsDay

Integer
-x-

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

Maximum value: 999

pastTransactionsYear

Integer
-x-

Number of transactions from this shopper in the past year.Maximum value: 999

paymentAccountAge

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

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

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

paymentAccountIndicator

String
-x-
 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
-x-

Date when the selected delivery address was first used with the 3DS Requestor.

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

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

deliveryAddressUsageIndicator

String
-x-
 Indicator for when this delivery address was first used with the 3DS Requestor.

  • thisTransaction

  • lessThan30Days

  • from30To60Days

  • moreThan60Days

suspiciousActivity

Boolean
-x-

Whether suspicious activity was recorded on this account.

homePhone

String
-x-

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

mobilePhone

String
-x-

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

workPhone

String
-x-

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

Mapping Adyen parameters to EMVCo fields

Below is a reference to map Adyen accountInfo parameters to EMVCo specifications.

Adyen parameter EMVCo parameter
accountAgeIndicator chAccAgeInd
accountChangeDate chAccDate
accountChangeIndicator chAccChangeInd
accountCreationDate chAccDate
passwordChangeDate chAccPwChange
passwordChangeIndicator chAccPwChangeInd
purchasesLast6Months nbPurchaseAccount
addCardAttemptsDay provisionAttemptsDay
pastTransactionsDay txnActivityDay
pastTransactionsYear txnActivityYear
paymentAccAge paymentAccountAge
paymentAccountIndicator paymentAccInd
deliveryAddressUsageDate shipAddressUsage
deliveryAddressUsageIndicator shipAddressUsageInd

billingAddress

We strongly recommend that you include this in your request. Card schemes require this for channel web, iOS, and Android implementations. If you include this object in your request, provide the following fields.

Field Type Required Description
city String -white_check_mark- The name of the city.
country String -white_check_mark- The two-character country code as defined in ISO-3166-1 alpha-2. For example, US.
houseNumberOrName String -white_check_mark- The number or name of the house.
postalCode String -white_check_mark- A maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries/regions.
stateOrProvince String -x- State or province codes as defined in ISO 3166-2. Required for the US and Canada. For example, CA in US or ON for Canada.
street String -white_check_mark- The name of the street.

browserInfo

The full object is required for channel web.

For mobile integrations, the userAgent and acceptHeader fields are required if you want to support 3D Secure 2 redirect authentication.

Field Type Required Description

acceptHeader

String
-white_check_mark-

The accept header value of the shopper's browser.

colorDepth

Int
-white_check_mark-

The color depth of the shopper's browser in bits per pixel. Use the browser's screen.colorDepth property to obtain the value. Accepted values: 1, 4, 8, 15, 16, 24, 32, or 48 bit.

javaEnabled

Boolean
-white_check_mark-

Boolean value indicating if the shopper's browser is able to execute Java.

javaScriptEnabled

Boolean
-x-

Boolean value indicating if the shopper's browser is able to execute JavaScript. A default 'true' value is assumed if the field is not present.

language

String
-white_check_mark-

The name of the browser language used by the shopper. This is the navigator.language value of the shopper's browser as defined in IETF BCP 47.Examples:nl-NL,fr-FR,en-US.

screenHeight

Int
-white_check_mark-

The pixel height of the shopper's screen.

screenWidth

Int
-white_check_mark-

The pixel width of the shopper's screen.

timeZoneOffset

String
-white_check_mark-

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

userAgent

String
-white_check_mark-

The user agent value of the shopper's browser.

deliveryAddress

Include this object in your request if you want to submit the shopper's delivery address. If you include this object in your request, provide the following fields.

Field Type Required Description
city String -white_check_mark- The name of the city.
country String -white_check_mark- The two-character country code as defined in ISO-3166-1 alpha-2. For example, US.
houseNumberOrName String -white_check_mark- The number or name of the house.
postalCode String -white_check_mark- A maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries/regions.
stateOrProvince String -x- State or province codes as defined in ISO 3166-2. Required for the US and Canada. For example, CA in US or ON for Canada.
street String -white_check_mark- The name of the street.

installments

Include this object in your request when you want to split the payment into installments. If you include this object in your request, provide the following field.

Field Type Required Description
value Int -white_check_mark- Required only when you want to split the payment into installments. The number of installments, value needs to be greater than zero. Usually, the acquirer sets the maximum allowed number of installments. For example, it may not be possible to split a payment in more than 24 installments.

merchantRiskIndicator

FieldTypeRequiredDescription

addressMatch

Boolean
-x-

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

deliveryEmail

String
-x-

The delivery email address (for digital goods).

deliveryTimeframe

String
-x-
 The estimated delivery time for the shopper to receive the goods.

Allowed values:

  • electronicDelivery

  • sameDayShipping

  • overnightShipping

  • twoOrMoreDaysShipping

giftCardAmount

Integer
-x-

For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s).

giftCardCount

String
-x-

For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.

preOrderDate

String
-x-
 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
-x-

Whether this transaction is for pre-ordering a product.

reorderItems

Boolean
-x-

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

deliveryAddressIndicator

String
-x-
 Indicator regarding the delivery address.

Allowed values:

  • shipToBillingAddress

  • shipToVerifiedAddress

  • shipToNewAddress

  • shipToStore

  • digitalGoods

  • goodsNotShipped

  • other

Mapping Adyen parameters to EMVCo fields

Below is a reference to map Adyen merchantRiskIndicator parameters to EMVCo specifications:

Adyen parameter EMVCo parameter
deliveryEmail deliveryEmailAddress
deliveryTimeframe deliveryTimeframe
giftCardAmount giftCardAmount
giftCardCount giftCardCount
preOrderDate preOrderDate
preOrderPurchase preOrderPurchaseInd
reorderItems reorderItemsInd

mpiData

You can only use the 3D Secure 1 parameters and values on this page if you are in one of the territories where 3D Secure 1 is still supported.

To authorise payments with Adyen using 3D Secure authenticated data, send a /payments request with an mpiData object containing the following parameters. Get the values from the authentication data produced by a 3D Secure 1 MPI (Mastercard SecureCode or Visa Secure) or a 3D Secure 2 provider.

Field Type Required Description
authenticationResponse String -x- In 3D Secure 1, this is the authentication response if a shopper was redirected.
In 3D Secure 2, this is the transStatus from the last CRes (Challenge Response) message or in the RReq (Results Request) sent after the shopper completes the challenge. If the transaction was frictionless there is no RReq, so omit this parameter.
cavv String -x- This is the cardholder authentication value (base64 encoded, 20 bytes in a decoded form). In 3DS2 this is the authenticationValue returned in the ARes (if frictionless) or the RReq (if a challenge flow).
cavvAlgorithm String -x- Include this only for 3D Secure 1. The CAVV algorithm used.
challengeCancel String -x- Indicator informing the Access Control Server (ACS) and the Directory Server (DS) that the authentication has been cancelled. See possible values.
directoryResponse String -x- The enrollment response from the directory server. In 3D Secure 1, this is the enrollment response from the VERes message from the directory server.
In 3D Secure 2, this is the transStatus from the ARes (Authentication Response).
dsTransID String -x- Supported for 3D Secure 2. The unique transaction identifier assigned by the Directory Server to identify a single transaction.
eci String -x- The electronic commerce indicator.
xid String -x- Supported for 3D Secure 1. The transaction identifier assigned by directory server (base64 encoded, 20 bytes in a decoded form).
threeDSVersion String -x- Include this only for 3D Secure 2. The version of 3D Secure 2 used: 2.1.0 or 2.2.0.
transStatusReason String -x- Provides information on why the transStatus field has the specified value. See possible values.

Possible challengeCancel values

Value Description
00 Data element is absent or value has been sent back with the key challengeCancel.
01 Cardholder selected Cancel.
02 3DS Requestor cancelled Authentication.
03 Transaction abandoned.
04 Transaction timed out at ACS — other timeouts.
05 Transaction timed out at ACS — first CReq not received by ACS.
06 Transaction error.
07 Unknown.
08 Transaction timed out at SDK.

Possible directoryResponse values for 3D Secure 1

Raw Response Description
Y Enrolled
N Not enrolled (the card is not enrolled for 3D Secure)
U Authentication unavailable

Possible authenticationResponse values for 3D Secure 1

Raw Response Description
Y Authenticated
N Authentication failed

Mapping Adyen parameters to EMVCo fields

Below is a reference to map Adyen mpiData parameters to EMVCo specifications:

Adyen parameter EMVCo parameter
authenticationValue authenticationValue
dsTransID dsTransID
eci eci
messageVersion messageVersion
threeDSServerTransID threeDSServerTransID
authenticationResponse threeDAuthenticatedResponse
directoryResponse threeDOfferedResponse
challengeCancel challengeCancel

paymentMethod

The following fields are required in the paymentMethod object. If you are fully PCI compliant you can pass the parameters for raw card data instead.

Field Type Required Description
type String -white_check_mark- Set this to scheme.
encryptedCardNumber String -white_check_mark- Encrypted card number.
encryptedExpiryMonth String -white_check_mark- Encrypted card expiry month.
encryptedExpiryYear String -white_check_mark- Encrypted card expiry year.
encryptedSecurityCode String -white_check_mark- Encrypted card verification code.
holderName String -white_check_mark- Name of the cardholder.
threeDS2SdkVersion String -white_check_mark- Required for mobile integrations.

shopperEmail

We strongly recommend that you include this in your request. Card schemes require this for channel web, iOS, and Android implementations.

Field Type Required Description
shopperEmail String -x- The cardholder's email address.

shopperIP

We strongly recommend that you include the shopper's IP address for channel web.

Field Type Required Description
shopperIP String -x- The shopper's IP address.

socialSecurityNumber

Field Type Required Description
socialSecurityNumber String -x- The shopper's CPF or CNPJ number. We strongly recommend that you include this for shoppers in Brazil. Supported from v50 and later of our API.

threeDS2RequestData

Field Type Required Description
acquirerBIN String
-x-
 The acquiring BIN enrolled for 3D Secure 2. Required if you enrolled for 3D Secure 2 through a different acquirer or PSP and are performing an authentication-only integration. This string should match the value that you will use in the authorization.
acquirerMerchantID String
-x-
 The authorisation MID enrolled for 3D Secure 2. Required if you enrolled for 3D Secure 2 through a different acquirer or PSP and are performing an authentication-only integration. This string should match the value that you will use in the authorization.
challengeIndicator String
-x-
 Possibility to specify a preference for receiving a challenge from the issuer.

Allowed values:

  • noPreference

  • requestNoChallenge

  • requestChallenge

  • requestChallengeAsMandate
deviceChannel String
-white_check_mark-
 Use this only for Classic integration. The environment of the shopper.

Allowed values:

  • app

  • browser
deviceRenderOptions Object
-x-
 Optional and only for deviceChannel app. Display options for the 3DS2 SDK.
  sdkInterface String
-x-
 Supported SDK interface types. Defaults to native.

Allowed values:

  • native

  • html

  • both
 sdkUiType Array
-x-
 String array of UI types supported for displaying specific challenges. Defaults to all values.

Allowed values:

  • text

  • singleSelect

  • multiSelect

  • outOfBand

  • otherHtml
merchantName String
-x-
 The merchant name that the issuer presents to the shopper if they get a challenge. Required if you enrolled for 3D Secure 2 through a different acquirer or PSP and are performing an authentication-only integration. We recommend to use the same value that you will use in the authorization. Maximum length is 40 characters.

Optional for a full 3D Secure 2 integration. Use this field if you are enrolled with us and want to override the merchant name already configured on your account.
notificationURL String
-x-
 Required for deviceChannel browser or if you built your own implementation with channel web. URL where the Challenge Response value will be sent.

sdkAppID

 String
-x-
 Required for deviceChannel app. The sdkAppID value as received from the 3D Secure 2 SDK.
sdkEncData String
-x-
 Required for deviceChannel app. The sdkEncData value as received from the 3D Secure 2 SDK.

sdkEphemPubKey

 Object
-x-
 Required for deviceChannel app. The sdkEphemPubKey value as received from the 3D Secure 2 SDK.
  crv String
-x-
 The crv value as received from the 3D Secure 2 SDK.
  kty String
-x-
 The kty value as received from the 3D Secure 2 SDK.
  x String
-x-
 The x value as received from the 3D Secure 2 SDK.
  y String
-x-
 The y value as received from the 3D Secure 2 SDK.
sdkMaxTimeout Integer
-x-
 Optional and used only for deviceChannel set to app. The maximum amount of time in minutes for the 3D Secure 2 authentication process. Defaults to 60 minutes.
sdkReferenceNumber String
-x-
 Required for deviceChannel set to app. The sdkReferenceNumber value as received from the 3D Secure 2 SDK.
sdkTransID String
-x-
 Required for deviceChannel set to app. The sdkTransID value as received from the 3D Secure 2 SDK.
threeDSCompInd String
-x-
 Completion indicator for the threeDSMethodUrl fingerprinting.
threeDSRequestorID String
-x-
 Unique requestor ID assigned by the Directory Server when you enrol for 3D Secure 2. Required if you enrolled for 3D Secure 2 for Visa through a different acquirer or PSP and are performing an authentication-only integration
threeDSRequestorName String
-x-
 Unique requestor name assigned by the Directory Server when you enrol for 3D Secure 2. Required if you enrolled for 3D Secure 2 for Visa through a different acquirer or PSP and are performing an authentication-only integration
threeDSRequestorURL String
-x-
 URL of the (customer service) website that will be shown to the shopper in case of technical errors during the 3D Secure 2 process.
transactionType String
-x-
 The type of transaction being authenticated. Highly recommended for Brazil.

Allowed values:

  • goodsOrServicePurchase

  • checkAcceptance

  • accountFunding

  • quasiCashTransaction

  • prepaidActivationAndLoad

Supported from v50 and later of our API.

threeDS2Result

This object is returned in the response when you perform an authentication-only integration.

Field Type Description

authenticationValue

String

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

Example: AQIDBAUGBwgJCgsMDQ4PEBESExQ=
dsTransID

String

The unique transaction identifier assigned by the Directory Server to identify a single transaction.
challengeIndicator

String

 Specifies a preference for receiving a challenge from the issuer.
Possible values:

  • noPreference

  • requestNoChallenge

  • requestChallenge

  • requestChallengeAsMandate

eci

String

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

Example: 02
exemptionIndicator

String

 Indicates the exemption type that was applied by the issuer to the authentication, if exemption applied.
Possible values:

  • lowValue

  • secureCorporate

  • trustedBeneficiary

  • transactionRiskAnalysis

threeDSServerTransID

String

The unique identifier assigned by the 3D Secure 2 Server.

transStatus

String

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

Possible values:

  • Y: Authentication / Account verification successful.

  • I: Authentication / Exemption granted by Issuer.

  • 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.

This field is called 3DS challenged in your Customer Area.

transStatusReason

String

 Provides information on why the transStatus field has the specified value. See possible values.

Possible 'transStatusReason' values

Value Scheme Description
01 All Card authentication failed.
02 All Unknown device.
03 All Unsupported device.
04 All Exceeds authentication frequency limit.
05 All Expired card.
06 All Invalid card number.
07 All Invalid transaction.
08 All No card record.
09 All Security failure.
10 All Stolen card.
11 All Suspected fraud.
12 All Transaction not permitted for cardholder.
13 All Cardholder not enrolled in service.
14 All Transaction timed out at ACS.
15 All Low confidence.
16 All Medium confidence.
17 All High confidence.
18 All Very high confidence.
19 All Exceeds ACS maximum challenges.
20 All Non-payment transaction not supported.
21 All 3RI transaction not supported.
22 All ACS technical issue.
23 All Decoupled Authentication required by ACS but not requested by 3DS Requestor.
24 All 3DS Requestor decoupled max expiry time exceeded.
25 All Decoupled Authentication was provided insufficient time to authenticate cardholder. ACS will not make attempt.
26 All Authentication attempted but not performed by the cardholder.
80 Visa Error connecting to ACS.
80 Mastercard Returned on all Data Only authentications.
80 American Express Safekey is not available for this type of card.
81 Visa ACS timed out.
81 Mastercard Challenge exemption accepted.
82 Visa Invalid response from ACS.
82 Mastercard Challenge Mandate requested but could not be performed.
83 Mastercard, Visa System Error response from ACS.
84 Visa VMID not eligible for requested program.
85 Visa VMID not eligible for requested program.
86 Visa Protocol version not supported by ACS
87 Visa Transaction is excluded from Attempts Processing (includes non- reloadable pre-paid cards and non-payments (NPA)).
88 Visa Requested program not supported by ACS.

Mapping Adyen parameters to EMVCo fields

Below is a reference to map Adyen threeDS2Result parameters to EMVCo specifications:

Adyen parameter EMVCo parameter
authenticationValue authenticationValue
dsTransID dsTransID
eci eci
threeDSServerTransID threeDSServerTransID
transStatus transStatus