API reference

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

Adyen is no longer developing the Classic API integration

This page is for the Classic API (/authorise) integration, which we no longer accept new integrations with.

We strongly recommend switching to the newer 3D Secure on Checkout API integration.

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

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	Description
`accountAgeIndicator`	String	Indicator for the length of time since this shopper account was created. Allowed 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. Allowed 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` 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	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 was last changed.Allowed values: thisTransaction lessThan30Days from30To60Days moreThan60Days
`purchasesLast6Months`	Integer	Number of purchases in the last 6 months.Maximum value: 9999
`addCardAttemptsDay`	Integer	Number of attempts the shopper tried to add a card to their account in the last day.Maximum value: 999
`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. Allowed 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. thisTransaction lessThan30Days from30To60Days moreThan60Days
`suspiciousActivity`	Boolean	Whether suspicious activity was recorded on this account.
`homePhone`	String	Shopper's home phone number (including the country code).
`mobilePhone`	String	Shopper's mobile phone number (including the country code).
`workPhone`	String	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 deviceChannel browser or app implementations. If you include this object in your request, provide the following fields.

Field	Type	Description
`city`	String	The name of the city.
`country`	String	The two-character country code as defined in ISO-3166-1 alpha-2. For example, US.
`houseNumberOrName`	String	The number or name of the house.
`postalCode`	String	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	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	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	Description
`acceptHeader`	String	The accept header value of the shopper's browser.
`colorDepth`	Int	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	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. A default 'true' value is assumed if the field is not present.
`language`	String	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	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	The user agent value of the shopper's browser.

card

Field	Type	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.

Field	Type	Description
`city`	String	The name of the city.
`country`	String	The two-character country code as defined in ISO-3166-1 alpha-2. For example, US.
`houseNumberOrName`	String	The number or name of the house.
`postalCode`	String	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	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	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		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

Field	Type	Description
`addressMatch`	Boolean	Whether the chosen delivery address is identical to the billing address.
`deliveryEmail`	String	The delivery email address (for digital goods).
`deliveryTimeframe`	String	The estimated delivery time for the shopper to receive the goods. Allowed values: electronicDelivery sameDayShipping overnightShipping twoOrMoreDaysShipping
`giftCardAmount`	Integer	For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s).
`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 Sample: 2017-07-17T13:42:40+01:00
`preOrderPurchase`	Boolean	Whether this transaction is for pre-ordering a product.
`reorderItems`	Boolean	Whether the shopper has already purchased the same items in the past.
`deliveryAddressIndicator`	String	Indicator regarding the delivery address. Allowed values: shipToBillingAddress shipToVerifiedAddress shipToNewAddress shipToStore digitalGoods goodsNotShipped other

mpiData

Field	Type	Description
`authenticationResponse`	String	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	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	Include this only for 3D Secure 1. The CAVV algorithm used.
`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 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	Supported for 3D Secure 2. The unique transaction identifier assigned by the Directory Server to identify a single transaction.
`eci`	String	The electronic commerce indicator.
`xid`	String	Supported for 3D Secure 1. The transaction identifier assigned by directory server (base64 encoded, 20 bytes in a decoded form).
`threeDSVersion`	String	Include this only for 3D Secure 2. The version of 3D Secure 2 used: 2.1.0 or 2.2.0.
`transStatusReason`	String	Provides information on why the transStatus field has the specified value. See possible values.

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.

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

socialSecurityNumber

Field	Type	Required	Description
`socialSecurityNumber`	String		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	Description
`acquirerBIN`		String	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	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	Possibility to specify a preference for receiving a challenge from the issuer. Allowed values: noPreference requestNoChallenge requestChallenge requestChallengeAsMandate
`deviceChannel`		String	Use this only for Classic integration. The environment of the shopper. Allowed values: app browser
`deviceRenderOptions`		Object	Optional and only for `deviceChannel` app. Display options for the 3DS2 SDK.
	`sdkInterface`	String	Supported SDK interface types. Defaults to native. Allowed values: native html both
	`sdkUiType`	Array	String array of UI types supported for displaying specific challenges. Defaults to all values. Allowed values: text singleSelect multiSelect outOfBand otherHtml
`merchantName`		String	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	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	Required for `deviceChannel` app. The `sdkAppID` value as received from the 3D Secure 2 SDK.
`sdkEncData`		String	Required for `deviceChannel` app. The `sdkEncData` value as received from the 3D Secure 2 SDK.
`sdkEphemPubKey`		Object	Required for `deviceChannel` app. The `sdkEphemPubKey` value as received from the 3D Secure 2 SDK.
	`crv`	String	The `crv` value as received from the 3D Secure 2 SDK.
	`kty`	String	The `kty` value as received from the 3D Secure 2 SDK.
	`x`	String	The `x` value as received from the 3D Secure 2 SDK.
	`y`	String	The `y` value as received from the 3D Secure 2 SDK.
`sdkMaxTimeout`		Integer	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	Required for `deviceChannel` set to app. The `sdkReferenceNumber` value as received from the 3D Secure 2 SDK.
`sdkTransID`		String	Required for `deviceChannel` set to app. The `sdkTransID` value as received from the 3D Secure 2 SDK.
`threeDSCompInd`		String	Completion indicator for the `threeDSMethodUrl` fingerprinting.
`threeDSRequestorID`		String	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	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	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. Allowed values: goodsOrServicePurchase checkAcceptance accountFunding quasiCashTransaction prepaidActivationAndLoad Supported from v50 and later of our API.

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.

Field	Type	Description
`threeds2.threeDS2Result.authenticationValue`	String	The value for the 3D Secure 2 authentication session. The returned value is a Base64-encoded 20-byte array.Example: `AQIDBAUGBwgJCgsMDQ4PEBESExQ=`
`threeds2.threeDS2Result.dsTransID`	String	The unique transaction identifier assigned by the Directory Server to identify a single transaction.
`threeds2.threeDS2Result.eci`	String	The Electronic Commerce Indicator returned from the schemes for the 3D Secure 2 payment session.Example: `02`
`threeds2.threeDS2Result.threeDSServerTransID`	String	The unique identifier assigned to the transaction by the 3D Secure 2 Server.
`threeds2.threeDS2Result.transStatus`	String	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.
`threeds2.threeDS2Result.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.

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.