API reference

To support 3D Secure 2 authentication on your Classic integration, use v40 or later of the following endpoints:

• /authorise
• /authorise3ds2
• get3dsAvailability

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 might be mandatory for the issuer and the card scheme, and not providing them in your payment request might result in a failed authentication. Click the object names to see all the parameter descriptions for that object.

Object name	Required	Description
accountInfo		Shopper account information for 3D Secure 2.
billingAddress		We strongly recommend that you include this object in your request. Card schemes require this for deviceChannel browser or app implementations.
browserInfo	Required for all channels for 3D Secure 1	Full object required for deviceChannel browser. The userAgent and acceptHeader fields are required for mobile integrations (deviceChannel app) if you want to support 3D Secure 1 redirect authentication in case the transaction is routed to 3D Secure 1.
deliveryAddress		The address where the purchased goods should be delivered. Include this in your request whenever available.
installments		Include in your request when you want to split the payments into installments.
merchantRiskIndicator		Additional risk fields for 3D Secure 2. Include this in your request whenever available.
mpiData		Use this object to authorise a payment with Adyen if you have 3D Secure 2 authentication data from another 3D Secure 2 provider.
recurring		Use this object when you want to enable recurring payments, with additional optional fields for 3D Secure 2 transactions.
shopperEmail		We strongly recommend that you include this object in your request. Card schemes require this for deviceChannel browser or app implementations. We recommend that you include this object in your request.
shopperIP		We strongly recommend that you include the shopper's IP address for deviceChannel browser.
socialSecurityNumber		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		Include this in your request when required. For example, in an authentication-only implementation.
authenticationData.authenticationOnly		If set to true, you will only do the 3D Secure 2 authentication, and not the payment authorisation.

accountInfo

Field	Type	Required	Description
accountAgeIndicator	String		Indicator for the length of time since this shopper account was created. Possible values: notApplicable thisTransaction lessThan30Days from30To60Days moreThan60Days
accountChangeDate	String		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		Indicator for when the shopper's account was last changed. Possible values: thisTransaction lessThan30Days from30To60Days moreThan60Days
accountCreationDate	String		Date when the shopper's account was created. Format: ISO 8601 YYYY-MM-DDThh:mm:ssTZD Example: 2017-07-17T13:42:40+01:00
accountType	String		The type of the shopper's account. For example, for a multi-account card product. Possible values: notApplicable credit debit
addCardAttemptsDay	Integer		Number of attempts the shopper made to add a card to their account in the last day. Maximum value: 999
passwordChangeDate	String		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		Indicator for when the shopper's account password was last changed. Possible values: thisTransaction lessThan30Days from30To60Days moreThan60Days
purchasesLast6Months	Integer		Number of purchases in the last 6 months. Maximum value: 9999
pastTransactionsDay	Integer		Number of transactions from this shopper in the past 24 hours. Maximum value: 999
pastTransactionsYear	Integer		Number of transactions from this shopper in the past year. Maximum value: 999
paymentAccountAge	String		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		Indicator for the length of time since this payment method was added to the shopper's account. Possible values: notApplicable thisTransaction lessThan30Days from30To60Days moreThan60Days
deliveryAddressUsageDate	String		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		Indicator for when this delivery address was first used with the 3DS Requestor. Possible values: thisTransaction lessThan30Days from30To60Days moreThan60Days
suspiciousActivity	Boolean		Whether suspicious activity was recorded on this account.
homePhone Deprecated in Checkout API v68	String		Use threeDSRequestData.homePhone instead. Shopper's home phone number, including the country code.
mobilePhone Deprecated in Checkout API v68	String		Use threeDSRequestData.mobilePhone instead. Shopper's mobile phone number, including the country code.
workPhone Deprecated in Checkout API v68	String		Use threeDSRequestData.workPhone instead. Shopper's work phone number, including the country code.

Mapping Adyen parameters to EMVCo fields

The Adyen accountInfo parameters map to the EMVCo specifications as follows.

billingAddress

We strongly recommend that you include this in your request. Card schemes require this for deviceChannel browser or app implementations. If you include this object in your request, provide the following fields.

When using our Drop-in/Components, the billing address is returned in an event. For example, on web integrations, this is the state.data.billingAddress object from the onSubmit event.

Field	Type	Required	Description
city	String		The name of the city.
country	String		The country code. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).
houseNumberOrName	String		The number or name of the house.
postalCode	String		The postal code consisting of 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		Use case: required for addresses in the US and Canada. The state or province code of the billing address as defined in ISO 3166-2. Example: CA in US, or ON in Canada.
street	String		The name of the street.

browserInfo

The full object is required for deviceChannel browser.

For mobile integrations (deviceChannel app), the userAgent and acceptHeader fields are required if you want to support 3D Secure 1 redirect authentication in case the transaction is routed to 3D Secure 1

Field	Type	Required	Description
acceptHeader	String		The accept header value of the shopper's browser.
colorDepth	Int		Use case: web integrations. 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		Use case: web integrations. Boolean value indicating if the shopper's browser is able to execute Java.
javaScriptEnabled	Boolean		Boolean value indicating if the shopper's browser is able to execute JavaScript. If not present, the default value is true.
language	String		Use case: web integrations. 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		Use case: web integrations. The pixel height of the shopper's screen.
screenWidth	Int		Use case: web integrations. The pixel width of the shopper's screen.
timeZoneOffset	String		Use case: web integrations. Time difference between UTC time and the shopper's browser local time, in minutes. Example: -120
userAgent	String		The user agent value of the shopper's browser.

card

Field	Type	Required	Description
number	String		Cardholder Account Number
expiryMonth	String		Card/Token Expiry Month
expiryYear	String		Card/Token Expiry Year
cvc	String		Card Security Code
holderName	String		Name of the cardholder

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.

When using our Drop-in/Components, the billing address is returned in an event. For example, on web integrations, this is the state.data.billingAddress object from the onSubmit event.

Field	Type	Required	Description
city	String		The name of the city.
country	String		The country code. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).
houseNumberOrName	String		The number or name of the house.
postalCode	String		The postal code consisting of 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		Use case: required for addresses in the US and Canada. The state or province code of the billing address as defined in ISO 3166-2. Example: CA in US, or ON in Canada.
street	String		The name of the street.

installments

Include the installments object in your request when you want to split the payment into installments. If you include this object in your request, some sub-fields are required.

Field	Type	Required	Description
value	Integer		The number of installments. For Mexico, the value can be 0, for other countries, the value must be greater than zero. See installment options in supported countries/regions for possible values. 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.
extra	Integer		The bonus percentage, refund percentage, or if the transaction is completed with a Buy Now Pay Later payment method for transactions processed in Mexico.
plan	String		Use case: required for installments in Japan, and Mexico. The installment plan. Possible values: regular revolving bonus The default value is regular.

merchantRiskIndicator

Field	Type	Required	Description
addressMatch	Boolean		Whether the chosen delivery address is identical to the billing address.
deliveryEmail Deprecated in Checkout API v68	String		Use deliveryEmailAddress instead. The delivery email address (for digital goods).
deliveryEmailAddress	String		The delivery email address (for digital goods).
deliveryTimeframe	String		The estimated delivery time for the shopper to receive the goods. Possible values: electronicDelivery sameDayShipping overnightShipping twoOrMoreDaysShipping
giftCardAmount	Integer		For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s).
giftCardCurr	Integer		For prepaid or gift card purchase, ISO 4217 three-digit currency code of the gift card, other than those listed in Table A.5 of the EMVCo 3D Secure Protocol and Core Functions Specification.
giftCardCount	String		For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.
preOrderDate	String		For pre-order purchases, the expected date this product will be available to the shopper. Format: ISO 8601 YYYY-MM-DDThh:mm:ssTZD Example: 2017-07-17T13:42:40+01:00
preOrderPurchase	Boolean		Whether this transaction is for pre-ordering a product.
preOrderPurchaseInd	String		Indicates if this transaction is for placing an order for merchandise with a future availability or release date.
reorderItems	Boolean		Whether the shopper has already purchased the same items in the past.
reorderItemsInd	Boolean		Indicates if the he cardholder is reordering previously purchased merchandise.
deliveryAddressIndicator	String		Indicator regarding the delivery address. Possible values: shipToBillingAddress shipToVerifiedAddress shipToNewAddress shipToStore digitalGoods goodsNotShipped other
shipIndicator	String		Indicates the shipping method for the purchase.

Mapping Adyen parameters to EMVCo fields

The Adyen merchantRiskIndicator parameters map to the EMVCo specifications as follows.

mpiData

Field	Type	Required	Description
authenticationResponse	String		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		The cardholder authentication value (base64 encoded, 20 bytes in a decoded form). This is the authenticationValue returned in the Authentication Response (ARes) for the frictionless flow, or the RReq for the challenge flow.
challengeCancel	String		Indicator informing the Access Control Server (ACS) and the Directory Server (DS) that the authentication has been cancelled. See possible values.
directoryResponse	String		The result of the initial authentication response. This is the transStatus from the ARes.
dsTransID	String		The unique transaction identifier assigned by the Directory Server to identify a single transaction.
eci	String		The electronic commerce indicator (ECI). This is a scheme specific indicator of the authentication result.
riskScore	String		Use case: required for Cartes Bancaires transactions. Risk score calculated by Directory Server (DS).
threeDSVersion	String		The version of 3D Secure 2 used. Possible values: 2.1.0 2.2.0
transStatusReason	String		Provides information on why the transStatus field has the specified value. See possible values.
tokenAuthenticationVerificationValue	String		The network token authentication verification value (TAVV). This is the network token cryptogram.

Possible challengeCancel values

MPI data combinations

When you are using authentication data from a third party to authorize payments with Adyen, you send multiple values you receive to Adyen. You must make sure that the combination of the values you send are aligned with what Adyen expects.

The possible combinations differ for each authentication flow. Cartes Bancaires does not use the ECI value, but it may be returned in some cases.

Mapping Adyen parameters to EMVCo fields

The Adyen mpiData parameters map to the EMVCo specifications as follows.

recurring

Field	Type	Required	Description
recurringFrequency	String		Use this in 3D Secure 2 transactions to specify minimum number of days between authorisations.
recurringExpiry	String		Use this in 3D Secure 2 transactions to specify a date after which no further authorisations shall be performed.

scaExemption

If you want to request an exemption for a transaction, include this object in the additionalData of your request.

Field	Type	Required	Description
scaExemption	String		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

shopperEmail

We strongly recommend that you include this object in your request. Card schemes require this for deviceChannel browser or app implementations.

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

shopperIP

We strongly recommend that you include the shopper's IP address for deviceChannel browser.

socialSecurityNumber

threeDS2RequestData

The threeDS2RequestData object contains additional request fields that are required for certain types of 3D Secure 2 integrations.

Field	Type	Required	Description
acctInfo	Object		Additional information about the shopper's account.
acctType	String		The type of account. Possible values: 01: not applicable 02: credit 03: debit
acquirerBIN	String		Use case: required if you enrolled for 3D Secure 2 through a different acquirer or PSP and are performing the authentication-only flow. The acquiring BIN enrolled for 3D Secure 2. This string should match the value that you will use in the authorization.
acquirerMerchantID	String		Use case: required if you enrolled for 3D Secure 2 through a different acquirer or PSP and are performing the authentication-only flow. The authorisation merchant ID enrolled for 3D Secure 2. This string should match the value that you will use in the authorization.
addrMatch	String		Indicates if the shipping address and billing address of the shopper match. Possible values: Y: the addresses match. N: the addresses do not match.
challengeIndicator Deprecated in Checkout API v68	String		Use case: required to manually request exemptions to the challenge through the API request, or for Cartes Bancaires transactions. The preference for receiving a challenge from the issuer. Possible values: noPreference requestNoChallenge requestChallenge requestChallengeAsMandate On Checkout API v68 or later, use threeDSRequestorChallengeInd instead.
deviceRenderOptions.sdkInterface	String		Only for app-based integrations. The supported SDK interface types. Defaults to native. Possible values: native html both
deviceRenderOptions.sdkUiType	Array		Only for app-based integrations. The string array of UI types supported for displaying specific challenges. Defaults to all values. Possible values: text singleSelect multiSelect outOfBand otherHtml
mcc	String		Use case: required if you enrolled for 3D Secure 2 through a different acquirer or PSP and are performing the authentication-only flow. The four-digit code with which the acquirerMerchantID is registered at the scheme.
merchantName	String		Use case: required if you enrolled for 3D Secure 2 through a different acquirer or PSP and are performing the authentication-only flow, or if you are enrolled with Adyen, and want to override the merchant name configured on your account. The merchant name that the issuer presents to the shopper if they get a challenge. We recommend to use the same value that you will use in the authorization. Format: Maximum length: 40 characters
messageVersion	String		The 3D Secure 2 protocol version.
notificationURL	String		Use case: required for deviceChannel browser or if you built your own implementation with channel Web. The URL where the Challenge Response value will be sent.
sdkAppID	String		Use case: required for deviceChannel app. The sdkAppID value as received from the 3D Secure 2 SDK.
sdkEncData	String		Use case: required for deviceChannel app. The sdkEncData value as received from the 3D Secure 2 SDK.
sdkEphemPubKey	Object		Use case: required for deviceChannel app. The sdkEphemPubKey value as received from the 3D Secure 2 SDK. This object includes the crv, kty, x, and y.
sdkMaxTimeout	Integer		Only for app-based integrations. The maximum amount of time in minutes for the 3D Secure 2 authentication process. Defaults to 60 minutes.
sdkReferenceNumber	String		Use case: required for app-based integrations. The sdkReferenceNumber value as received from the 3D Secure 2 SDK.
sdkTransID	String		Use case: required for app-based integrations. The sdkTransID value as received from the 3D Secure 2 SDK.
threeDSCompInd	String		The completion indicator for the threeDSMethodUrl fingerprinting.
threeDSRequestorChallengeInd	String		Use case: required if you want to manually request exemptions to the challenge through the API request, or for Cartes Bancaires transactions. Indicates whether a challenge is requested for this transaction. Possible values: 01: no preference 02: no challenge requested 03: challenge requested by the 3D Secure requestor 04: challenge requested due to a mandate 05: no challenge requested due to a performed risk analysis. 06: Data-only flow.
threeDSRequestorID	String		Use case: required for Visa payments if you enrolled for 3D Secure 2 through a different acquirer or PSP and are performing the authentication-only flow. The unique requestor ID assigned by the Directory Server when you enrol for 3D Secure 2.
threeDSRequestorName	String		Use case: required for Visa payments if you enrolled for 3D Secure 2 through a different acquirer or PSP and are performing the authentication-only flow. The unique requestor name assigned by the Directory Server when you enrol for 3D Secure 2.
threeDSRequestorURL	String		The 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		The type of transaction being authenticated. Highly recommended for Brazil. Possible values: goodsOrServicePurchase checkAcceptance accountFunding quasiCashTransaction prepaidActivationAndLoad Supported from v50 and later of Checkout API.
homePhone, workPhone or mobilePhone	String		Use case: required for Visa and JCB payments if you did not include the shopperEmail parameter, and did not provide the phone number in telephoneNumber. A phone number for the shopper. Format: The phone number must include a plus sign (+) and a country code (1-3 digits), followed by the number (4-15 digits). Example: +4912345678901 If the value you provide does not follow the guidelines, we drop the value and do not submit it for authentication.

threeDS2Result

Send the property below within the threeDS2Result object to submit the results of the challenge flow. Refer to the web, iOS, or Android integration pages for the values that you should use.

Field	Type	Required	Description
transStatus	String		Indicates whether a transaction was authenticated.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.

additionalData.threeDS2Result

If you perform an authentication-only transaction, the following properties are returned in the additionalData object in an /authorise3ds2 response.

Possible 'transStatusReason' values

authenticationData.authenticationOnly

Field	Type	Required	Description
authenticationData.authenticationOnly	String		If set to true, you will only do the 3D Secure 2 authentication, and not the payment authorisation.