--- title: "3D Secure 2 API reference" description: "Learn about parameters that you can use in your 3D Secure 2 request." url: "https://docs.adyen.com/online-payments/3d-secure/api-reference" source_url: "https://docs.adyen.com/online-payments/3d-secure/api-reference.md" canonical: "https://docs.adyen.com/online-payments/3d-secure/api-reference" last_modified: "2023-07-12T14:00:00+02:00" language: "en" --- # 3D Secure 2 API reference Learn about parameters that you can use in your 3D Secure 2 request. [View source](/online-payments/3d-secure/api-reference.md) For 3D Secure 2, you include additional parameters in your payment requests that provide additional information to authenticate your shoppers. You include these parameters when you make a request to one of the following endpoints: * [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) * [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) * [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) This page describes payload structures and objects for [Checkout API](https://docs.adyen.com/api-explorer/Checkout/latest/overview) **v41** or later. If you are using a classic integration, see [3D Secure 2 classic integration](/online-payments/classic-integrations/classic-api-integration/3d-secure-authentication/native-3ds2/api-reference-3d-secure-2). ### Parameter types There are various parameters you can include in your requests for 3D Secure 2 authentication. The tables on this page specify the parameters that are required, conditionally required, recommended, and optional to include in your requests. | Icon | Type | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------- | | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Required | Parameters that are required to complete 3D Secure 2 authentication. | | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | Conditionally required | Parameters that are required for particular setups, or issuers and card schemes. | | ![Recommended](/user/pages/reuse/image-library/01.icons/recommended/recommended.svg?decoding=auto\&fetchpriority=auto) | Recommended | Parameters that are not required to send in your requests, but including them may increase the authentication performance. | | | Optional | Parameters that map to a field in the EMVCo Authentication Response (`Areq`), but are optional to include in your requests. | ## 3D Secure 2 objects In addition to the regular fields you provide in your payment requests, 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. Some fields have sub-fields where you can, or need to, provide more information. | Object | Required | Description | | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [accountInfo](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-accountInfo) | ![Recommended](/user/pages/reuse/image-library/01.icons/recommended/recommended.svg?decoding=auto\&fetchpriority=auto) | Shopper account information for 3D Secure 2. See [the reference](#accountinfo) to learn its sub-fields. | | [authenticationData](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-authenticationData) | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for certain 3D Secure 2 setups. The data for the 3D secure 2 authentication. See [the reference](#authenticationdata) to learn its sub-fields. | | [billingAddress](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-billingAddress) | ![Recommended](/user/pages/reuse/image-library/01.icons/recommended/recommended.svg?decoding=auto\&fetchpriority=auto) | The address where to send the invoice. We recommend to include it in your requests when available to improve authentication performance See [the reference](#billingaddress) to learn its required sub-fields. | | [browserInfo](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-browserInfo) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The shopper's browser information. See [the reference](#browserinfo) to learn its sub-fields and the requirements depending on your integration type. | | [channel](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-channel) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The platform where a payment transaction takes place. Possible values:- **Web** - **iOS** - **Android** | | [deliveryAddress](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-deliveryAddress) | ![Recommended](/user/pages/reuse/image-library/01.icons/recommended/recommended.svg?decoding=auto\&fetchpriority=auto) | The address where the purchased goods must be delivered. Include this in your request whenever available. See [the reference](#deliveryaddress) to learn about its required sub-fields. | | [installments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-installments) | | If you want to split the payment into [installments](/payment-methods/cards/credit-card-installments/), include this object to specify the installment settings. See [the reference](#installments) to learn about its required sub-fields. | | [merchantRiskIndicator](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-merchantRiskIndicator) | ![Recommended](/user/pages/reuse/image-library/01.icons/recommended/recommended.svg?decoding=auto\&fetchpriority=auto) | Additional risk fields for 3D Secure 2. Include this in your request whenever available. See [the reference](#merchantriskindicator) to learn about its sub-fields. | | [mpiData](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-mpiData) | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required if you are making a request to authorize a payment using [third-party authentication data](/online-payments/3d-secure/authorize-mpidata) from another 3D Secure 2 provider. This is the authentication data produced by a merchant plug-in (MPI). See [the reference](#mpidata) to learn its required sub-fields. | | [origin](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-origin) | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for browser-based (`channel`: **Web**) transactions. The origin URL of the page where you are rendering the Drop-in/Component. When this field is not set, or set incorrectly, the 3D Secure 2 action can not be handled correctly. **Format**:- Maximum characters: 80 - Do not include subdirectories and a trailing slash.**Example**: If you are rendering on `https://your-company.example.com/checkout/payment`, set to `https://your-company.example.com`. | | [paymentMethod](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The type and required details for a card payment method. See [the reference](#paymentMethod) to learn about its required sub-fields. | | [telephoneNumber](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-telephoneNumber) | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions if you did not include the `shopperEmail` field. The shopper's phone number. To be more specific, you can use the `mobilePhone`, `homePhone`, and `workPhone` fields in the `threeDS2RequestData` object. **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. | | [returnUrl](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-returnUrl) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The URL where the shopper is redirected back to after completing authentication to support cases where the payment is routed to the [3D Secure 2 redirect flow](/online-payments/3d-secure/redirect-3ds2/). See our [integration guides](/online-payments/3d-secure/native-3ds2) to learn how to set this URL depending on your platform. | | [scaExemption](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-additionalData-listOfValues-scaExemption) | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required if you want to request exemptions through the API request, or when making a Cartes Bancaires transaction. We do not recommend to use this field, because it overrides our exemption logic. The [exemption type](/online-payments/psd2-sca-compliance-and-implementation-guide/sca-options#apply-exemption) that you want to request for the particular transaction. Possible values:- **lowValue** - **secureCorporate** - **trustedBeneficiary** - **transactionRiskAnalysis** | | [shopperEmail](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperEmail) | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions; if you don't include this, you have to send the phone number in [telephoneNumber](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-telephoneNumber). We strongly recommend to include the email address for all transactions. The cardholder's email address. | | [shopperIP](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperIP) | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions for all web and mobile integrations. You must include `shopperIP` for native mobile integrations to support cases where the transaction is routed to the redirect flow. We recommend to include this field for all transactions, because it is used in a number of risk checks. The IP address of the shopper. | | [socialSecurityNumber](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-socialSecurityNumber) | ![Recommended](/user/pages/reuse/image-library/01.icons/recommended/recommended.svg?decoding=auto\&fetchpriority=auto) | 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](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-threeDS2RequestData) | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for certain 3D Secure 2 setups. See [the reference](#threeds2requestdata) to learn about its required sub-fields depending on integration type. | ## accountInfo The [accountInfo](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-accountInfo) object is not required, but we recommend to include it in your requests to increase the chances of achieving the [frictionless flow](/online-payments/3d-secure/#frictionless-flow). | Field | Type | Required | Description | | -------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `accountAgeIndicator` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-account-info/optional.svg?decoding=auto\&fetchpriority=auto) | Indicator for the length of time since this shopper account was created. Possible values:- **notApplicable** - **thisTransaction** - **lessThan30Days** - **from30To60Days** - **moreThan60Days** | | `accountChangeDate` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-account-info/optional.svg?decoding=auto\&fetchpriority=auto) | Date when the shopper's account was last changed. **Format**: [ISO 8601](http://www.w3.org/TR/NOTE-datetime) *YYYY-MM-DDThh:mm:ssTZD* **Example**: `2017-07-17T13:42:40+01:00` | | `accountChangeIndicator` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-account-info/optional.svg?decoding=auto\&fetchpriority=auto) | Indicator for when the shopper's account was last changed. Possible values:- **thisTransaction** - **lessThan30Days** - **from30To60Days** - **moreThan60Days** | | `accountCreationDate` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-account-info/optional.svg?decoding=auto\&fetchpriority=auto) | Date when the shopper's account was created. **Format**: [ISO 8601](http://www.w3.org/TR/NOTE-datetime) *YYYY-MM-DDThh:mm:ssTZD* **Example**: `2017-07-17T13:42:40+01:00` | | `accountType` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-account-info/optional.svg?decoding=auto\&fetchpriority=auto) | The type of the shopper's account. For example, for a multi-account card product. Possible values:- **notApplicable** - **credit** - **debit** | | `addCardAttemptsDay` | Integer | ![](/user/pages/reuse/3ds2-reuse-pages/reference-account-info/optional.svg?decoding=auto\&fetchpriority=auto) | Number of attempts the shopper made to add a card to their account in the last day. Maximum value: **999** | | `passwordChangeDate` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-account-info/optional.svg?decoding=auto\&fetchpriority=auto) | Date when the shopper last changed their password. **Format**: [ISO 8601](http://www.w3.org/TR/NOTE-datetime) *YYYY-MM-DDThh:mm:ssTZD* **Example**: `2017-07-17T13:42:40+01:00` | | `passwordChangeIndicator` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-account-info/optional.svg?decoding=auto\&fetchpriority=auto) | Indicator for when the shopper's account password was last changed. Possible values:- **thisTransaction** - **lessThan30Days** - **from30To60Days** - **moreThan60Days** | | `purchasesLast6Months` | Integer | ![](/user/pages/reuse/3ds2-reuse-pages/reference-account-info/optional.svg?decoding=auto\&fetchpriority=auto) | Number of purchases in the last 6 months. Maximum value: **9999** | | `pastTransactionsDay` | Integer | ![](/user/pages/reuse/3ds2-reuse-pages/reference-account-info/optional.svg?decoding=auto\&fetchpriority=auto) | Number of transactions from this shopper in the past 24 hours. Maximum value: **999** | | `pastTransactionsYear` | Integer | ![](/user/pages/reuse/3ds2-reuse-pages/reference-account-info/optional.svg?decoding=auto\&fetchpriority=auto) | Number of transactions from this shopper in the past year. Maximum value: **999** | | `paymentAccountAge` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-account-info/optional.svg?decoding=auto\&fetchpriority=auto) | Date this payment method was added to the shopper's account. **Format**: [ISO 8601](http://www.w3.org/TR/NOTE-datetime) *YYYY-MM-DDThh:mm:ssTZD* **Example**: `2017-07-17T13:42:40+01:00` | | `paymentAccountIndicator` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-account-info/optional.svg?decoding=auto\&fetchpriority=auto) | 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 | ![](/user/pages/reuse/3ds2-reuse-pages/reference-account-info/optional.svg?decoding=auto\&fetchpriority=auto) | Date when the selected delivery address was first used with the 3DS Requestor. **Format**: [ISO 8601](http://www.w3.org/TR/NOTE-datetime) *YYYY-MM-DDThh:mm:ssTZD* **Example**: `2017-07-17T13:42:40+01:00` | | `deliveryAddressUsageIndicator` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-account-info/optional.svg?decoding=auto\&fetchpriority=auto) | Indicator for when this delivery address was first used with the 3DS Requestor. Possible values:- **thisTransaction** - **lessThan30Days** - **from30To60Days** - **moreThan60Days** | | `suspiciousActivity` | Boolean | ![](/user/pages/reuse/3ds2-reuse-pages/reference-account-info/optional.svg?decoding=auto\&fetchpriority=auto) | Whether suspicious activity was recorded on this account. | | `homePhone` Deprecated in Checkout API v68 | String | | Use [`threeDSRequestData.homePhone` ](#threeds2requestdata)instead. Shopper's home phone number, including the country code. | | `mobilePhone` Deprecated in Checkout API v68 | String | | Use [`threeDSRequestData.mobilePhone` ](#threeds2requestdata)instead. Shopper's mobile phone number, including the country code. | | `workPhone` Deprecated in Checkout API v68 | String | | Use [`threeDSRequestData.workPhone` ](#threeds2requestdata)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](https://www.emvco.com/emv-technologies/3-d-secure/) as follows. | 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` | ## authenticationData The [authenticationData](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-authenticationData) object contains sub-fields that are required to include for certain 3D Secure 2 authentication scenarios. | Field | Type | Required | Description | | ----------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `authenticationOnly` | Boolean | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required to trigger [standalone authentication](/online-payments/3d-secure/standalone-authentication/). When set to **true**, you only perform the 3D Secure 2 authentication, and will not proceed to the payment authorization. The default value is **false**. | | `attemptAuthentication` | String | | Indicates whether to attempt 3D Secure 2 authentication for a transaction. We do not recommend to use this field. This overrides your [Dynamic 3D Secure](/risk-management/dynamic-3d-secure/#override-using-the-payment-request) settings. Possible values:- **always**: attempt 3D Secure 2. - **never**: do not attempt 3D Secure 2. If regulations require authentication, the transaction gets declined. | | `threeDSRequestData.challengeWindowSize` | String | | The size of the challenge window displayed to the shopper in the [challenge flow](/online-payments/3d-secure/#challenge-flow). Possible values:- **01**: \['250px', '400px'] - **02**: \['390px', '400px'] - **03**: \['500px', '600px'] - **04**: \['600px', '400px'] - **05**: \['100%', '100%'] | | `threeDSRequestData.dataOnly` Available on Checkout API v69 | String | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required to trigger the [data-only flow](/online-payments/3d-secure/data-only/). When set to **true**, forces the 3D Secure 2 data-only flow for all transactions where it is possible. If you are using Checkout API v68 or earlier, use the `additionalData.threeDSDataOnly` field instead. | | `threeDSRequestData.nativeThreeDS` | String | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required to trigger the native flow when using the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) endpoint, or to trigger the redirect flow when using the [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) endpoint. Indicates if [native 3D Secure 2](/online-payments/3d-secure/#implement-3d-secure-2) should be used when available. Adyen can still select to fallback to the redirect flow to optimize authorization rates and improve the shopper's experience. Possible values:- **preferred**: use native 3D Secure 2 when available. - **disabled**: only use the redirect 3D Secure 2 flow. | | `threeDSRequestData.threeDSVersion` | String | | The version of 3D Secure 2 to use. Possible values:- **2.1.0** - **2.2.0** | ## billingAddress The [billingAddress](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-billingAddress) object is not required, but we recommend to include it in your requests when available to improve authentication performance. This object includes some required sub-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 | ![](/user/pages/reuse/3ds2-reuse-pages/reference-billing-address/required.svg?decoding=auto\&fetchpriority=auto) | The name of the city. | | `country` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-billing-address/required.svg?decoding=auto\&fetchpriority=auto) | The country code. Format: the two-letter [ISO-3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. Exception: **QZ** (Kosovo). | | `houseNumberOrName` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-billing-address/required.svg?decoding=auto\&fetchpriority=auto) | The number or name of the house. | | `postalCode` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-billing-address/required.svg?decoding=auto\&fetchpriority=auto) | 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 | ![](/user/pages/reuse/3ds2-reuse-pages/reference-billing-address/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **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](https://en.wikipedia.org/wiki/ISO_3166-2). **Example**: **CA** in US, or **ON** in Canada. | | `street` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-billing-address/required.svg?decoding=auto\&fetchpriority=auto) | The name of the street. | ## browserInfo For web integrations ( [channel](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-channel): **Web**): the full object, except `javaScriptEnabled`, is required. For mobile integrations ( [channel](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-channel): **iOS**/**Android**): the object is not required but recommended to support cases where the payment is routed to [3D Secure 2 redirect](/online-payments/3d-secure/redirect-3ds2). | Field | Type | Required | Description | | ------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `acceptHeader` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-browser-info/required.svg?decoding=auto\&fetchpriority=auto) | The accept header value of the shopper's browser. | | `colorDepth` | Int | ![](/user/pages/reuse/3ds2-reuse-pages/reference-browser-info/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **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 | ![](/user/pages/reuse/3ds2-reuse-pages/reference-browser-info/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **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 | ![](/user/pages/reuse/3ds2-reuse-pages/reference-browser-info/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **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](https://en.wikipedia.org/wiki/IETF_language_tag). **Examples**: `nl-NL`, `fr-FR`, `en-US`. | | `screenHeight` | Int | ![](/user/pages/reuse/3ds2-reuse-pages/reference-browser-info/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: web integrations. The pixel height of the shopper's screen. | | `screenWidth` | Int | ![](/user/pages/reuse/3ds2-reuse-pages/reference-browser-info/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: web integrations. The pixel width of the shopper's screen. | | `timeZoneOffset` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-browser-info/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: web integrations. Time difference between UTC time and the shopper's browser local time, in minutes. **Example**: **-120** | | `userAgent` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-browser-info/required.svg?decoding=auto\&fetchpriority=auto) | The user agent value of the shopper's browser. | ## deliveryAddress Include the [deliveryAddress](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-deliveryAddress) object in your request if you want to submit the shopper's delivery address. If you include this object in your request, provide the required fields. | Field | Type | Required | Description | | ------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `city` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-delivery-address/required.svg?decoding=auto\&fetchpriority=auto) | The name of the city. | | `country` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-delivery-address/required.svg?decoding=auto\&fetchpriority=auto) | The country code. Format: the two-letter [ISO-3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. Exception: **QZ** (Kosovo). | | `houseNumberOrName` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-delivery-address/required.svg?decoding=auto\&fetchpriority=auto) | The number or name of the house. | | `postalCode` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-delivery-address/required.svg?decoding=auto\&fetchpriority=auto) | 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 | ![](/user/pages/reuse/3ds2-reuse-pages/reference-delivery-address/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **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](https://en.wikipedia.org/wiki/ISO_3166-2). **Example**: **CA** in US, or **ON** in Canada. | | `street` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-delivery-address/required.svg?decoding=auto\&fetchpriority=auto) | The name of the street. | ## installments Include the [installments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-installments) object in your request when you want to split the payment into [installments](/payment-methods/cards/credit-card-installments/). If you include this object in your request, some sub-fields are required. | Field | Type | Required | Description | | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `value` | Integer | ![](/user/pages/reuse/3ds2-reuse-pages/reference-installments/required.svg?decoding=auto\&fetchpriority=auto) | 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](/payment-methods/cards/credit-card-installments/#installment-options) 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 | ![](/user/pages/reuse/3ds2-reuse-pages/reference-installments/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for installments in Japan, and Mexico. The installment plan. Possible values:- **regular** - **revolving** - **bonus**The default value is **regular**. | ## merchantRiskIndicator The [merchantRiskIndicator](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-merchantRiskIndicator) object is not required, but we recommend to include it in your requests to increase the chances of achieving the [frictionless flow](/online-payments/3d-secure/#frictionless-flow). | Field | Type | Required | Description | | --------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `addressMatch` | Boolean | ![](/user/pages/reuse/3ds2-reuse-pages/reference-merchant-risk-indicator/optional.svg?decoding=auto\&fetchpriority=auto) | Whether the chosen delivery address is identical to the billing address. | | `deliveryEmail`Deprecated in Checkout API v68 | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-merchant-risk-indicator/optional.svg?decoding=auto\&fetchpriority=auto) | Use `deliveryEmailAddress` instead. The delivery email address (for digital goods). | | `deliveryEmailAddress` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-merchant-risk-indicator/optional.svg?decoding=auto\&fetchpriority=auto) | The delivery email address (for digital goods). | | `deliveryTimeframe` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-merchant-risk-indicator/optional.svg?decoding=auto\&fetchpriority=auto) | The estimated delivery time for the shopper to receive the goods. Possible values:- **electronicDelivery** - **sameDayShipping** - **overnightShipping** - **twoOrMoreDaysShipping** | | `giftCardAmount` | Integer | ![](/user/pages/reuse/3ds2-reuse-pages/reference-merchant-risk-indicator/optional.svg?decoding=auto\&fetchpriority=auto) | For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s). | | `giftCardCurr` | Integer | ![](/user/pages/reuse/3ds2-reuse-pages/reference-merchant-risk-indicator/optional.svg?decoding=auto\&fetchpriority=auto) | For prepaid or gift card purchase, [ISO 4217 three-digit currency code](https://www.iso.org/iso-4217-currency-codes.html) of the gift card, other than those listed in Table A.5 of the [EMVCo 3D Secure Protocol and Core Functions Specification](https://www.emvco.com/emv-technologies/3-d-secure/). | | `giftCardCount` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-merchant-risk-indicator/optional.svg?decoding=auto\&fetchpriority=auto) | For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased. | | `preOrderDate` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-merchant-risk-indicator/optional.svg?decoding=auto\&fetchpriority=auto) | For pre-order purchases, the expected date this product will be available to the shopper.- **Format**: [ISO 8601](http://www.w3.org/TR/NOTE-datetime) *YYYY-MM-DDThh:mm:ssTZD* - **Example**: *2017-07-17T13:42:40+01:00* | | `preOrderPurchase` | Boolean | ![](/user/pages/reuse/3ds2-reuse-pages/reference-merchant-risk-indicator/optional.svg?decoding=auto\&fetchpriority=auto) | Whether this transaction is for pre-ordering a product. | | `preOrderPurchaseInd` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-merchant-risk-indicator/optional.svg?decoding=auto\&fetchpriority=auto) | Indicates if this transaction is for placing an order for merchandise with a future availability or release date. | | `reorderItems` | Boolean | ![](/user/pages/reuse/3ds2-reuse-pages/reference-merchant-risk-indicator/optional.svg?decoding=auto\&fetchpriority=auto) | Whether the shopper has already purchased the same items in the past. | | `reorderItemsInd` | Boolean | ![](/user/pages/reuse/3ds2-reuse-pages/reference-merchant-risk-indicator/optional.svg?decoding=auto\&fetchpriority=auto) | Indicates if the he cardholder is reordering previously purchased merchandise. | | `deliveryAddressIndicator` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-merchant-risk-indicator/optional.svg?decoding=auto\&fetchpriority=auto) | Indicator regarding the delivery address. Possible values:- **shipToBillingAddress** - **shipToVerifiedAddress** - **shipToNewAddress** - **shipToStore** - **digitalGoods** - **goodsNotShipped** - **other** | | `shipIndicator` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-merchant-risk-indicator/optional.svg?decoding=auto\&fetchpriority=auto) | Indicates the shipping method for the purchase. | ### Mapping Adyen parameters to EMVCo fields The Adyen `merchantRiskIndicator` parameters map to the [EMVCo specifications](https://www.emvco.com/emv-technologies/3-d-secure/) as follows. | Adyen parameter | EMVCo parameter | | ------------------- | ---------------------- | | `deliveryEmail` | `deliveryEmailAddress` | | `deliveryTimeframe` | `deliveryTimeframe` | | `giftCardAmount` | `giftCardAmount` | | `giftCardCount` | `giftCardCount` | | `preOrderDate` | `preOrderDate` | | `preOrderPurchase` | `preOrderPurchaseInd` | | `reorderItems` | `reorderItemsInd` | ## mpiData The [mpiData](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-mpiData) object is required in your authorization requests with Adyen if you use authentication data from a [third-party](/online-payments/3d-secure/authorize-mpidata/) to authorize payments. Get the values from the authentication data produced by a 3D Secure 2 provider. When you make the request to Adyen, include all the fields you receive from the third-party authentication provider. | Field | Type | Required | Description | | -------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `authenticationResponse` | String | | The [`transStatus` ](#possible-transstatusreason-values)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](/online-payments/3d-secure/#frictionless-flow), or the `RReq` for the [challenge flow](/online-payments/3d-secure/#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](/online-payments/3d-secure/api-reference#possible-challengecancel-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 | ![](/user/pages/reuse/3ds2-reuse-pages/reference-mpidata/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **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](#possible-transstatusreason-values). | | `tokenAuthenticationVerificationValue` | String | | The network token authentication verification value (TAVV). This is the [network token](/online-payments/network-tokenization) cryptogram. | ### `transStatus` and `transStatusReason` values You receive the `transStatus` value in the response of your payment request. This field indicates whether a transaction was authenticated, or whether additional verification is required. | `transStatus` value | Description | | ------------------- | ---------------------------------------------------------------------------- | | **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](https://ca-test.adyen.com/). The `transStatusReason` field informs you why the `transStatus` field has the specified value. | `transStatusReason` 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` | Mastercard, Visa | Internal error while generating CAVV. | | `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. | ### `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. | ### MPI data combinations When you are [using authentication data from a third party to authorize payments with Adyen](/online-payments/3d-secure/authorize-mpidata/), 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. | Authentication flow | `directoryResponse` | `authenticationResponse` | `eci` | | --------------------- | -------------------------------------------------------------------------------- | ------------------------ | -------------------------------------------------------------------------------- | | Challenge flow | **C** | **Y** | Visa, Amex, JCB, CUB: **05** Mastercard, BCMC: **02** Cartes Bancaires: optional | | Frictionless flow | **Y** | | Visa, Amex, JCB, CUB: **05** Mastercard, BCMC: **02** Cartes Bancaires: optional | | Attempt | **A** | | Visa, Amex, JCB, CUB: **06** Mastercard, BCMC: **02** Cartes Bancaires: optional | | 3D Secure 2 exemption | **I** (all schemes) or **Y** (Cartes Bancaires with `threeDSVersion`: **2.1.0**) | | Visa, Amex, JCB, CUB: **07** Mastercard, BCMC: **02** Cartes Bancaires: optional | ### Mapping Adyen parameters to EMVCo fields The Adyen `mpiData` parameters map to the [EMVCo specifications](https://www.emvco.com/emv-technologies/3-d-secure/) as follows. | Adyen parameter | EMVCo parameter | | ------------------------ | ----------------------- | | `authenticationValue` | `authenticationValue` | | `dsTransID` | `dsTransID` | | `eci` | `eci` | | `threeDSVersion` | `messageVersion` | | `threeDSServerTransID` | `threeDSServerTransID` | | `authenticationResponse` | `transStatus` in `RReq` | | `directoryResponse` | `transStatus` in `ARes` | | `challengeCancel` | `challengeCancel` | ## paymentMethod The [paymentMethod](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod) object, and its sub-fields below, are required for 3D Secure 2 transactions. If you are [fully PCI compliant](/development-resources/pci-dss-compliance-guide) you can [pass the parameters for raw card](/payment-methods/cards/raw-card-data/#make-a-payment) data instead. | Field | Type | Required | Description | | ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Set to **scheme**. | | `encryptedCardNumber` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The encrypted card number. | | `encryptedExpiryMonth` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The encrypted card expiry month. | | `encryptedExpiryYear` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The encrypted card expiry year. | | `encryptedSecurityCode` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The encrypted card verification code. | | `brand` | String | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Cartes Bancaires transactions. The secondary brand of the card. | | `holderName` | String | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions. The name of the cardholder. We recommend to include this field whenever available for higher authentication rates. | | `threeDS2SdkVersion` | String | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for native mobile integrations. The 3D Secure 2 mobile SDK version. See our [integration guides](/online-payments/3d-secure/native-3ds2) to learn how you can get the SDK version. | ## threeDS2RequestData The [threeDS2RequestData](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-threeDS2RequestData) object contains additional request fields that are required for certain types of 3D Secure 2 integrations. | Field | Type | Required | Description | | -------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `acquirerBIN` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-3ds2requestdata/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required if you enrolled for 3D Secure 2 through a different acquirer or PSP and are performing the [authentication-only](/online-payments/3d-secure/standalone-authentication) flow. The acquiring BIN enrolled for 3D Secure 2. This string should match the value that you will use in the authorization. | | `acquirerMerchantID` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-3ds2requestdata/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required if you enrolled for 3D Secure 2 through a different acquirer or PSP and are performing the [authentication-only](/online-payments/3d-secure/standalone-authentication) 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 | ![](/user/pages/reuse/3ds2-reuse-pages/reference-3ds2requestdata/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **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 | ![](/user/pages/reuse/3ds2-reuse-pages/reference-3ds2requestdata/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required if you enrolled for 3D Secure 2 through a different acquirer or PSP and are performing the [authentication-only](/online-payments/3d-secure/standalone-authentication) flow. The four-digit code with which the `acquirerMerchantID` is registered at the scheme. | | `merchantName` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-3ds2requestdata/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required if you enrolled for 3D Secure 2 through a different acquirer or PSP and are performing the [authentication-only](/online-payments/3d-secure/standalone-authentication) 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 | ![](/user/pages/reuse/3ds2-reuse-pages/reference-3ds2requestdata/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **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 | ![](/user/pages/reuse/3ds2-reuse-pages/reference-3ds2requestdata/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for `deviceChannel` **app**. The `sdkAppID` value as received from the 3D Secure 2 SDK. | | `sdkEncData` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-3ds2requestdata/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for `deviceChannel` **app**. The `sdkEncData` value as received from the 3D Secure 2 SDK. | | `sdkEphemPubKey` | Object | ![](/user/pages/reuse/3ds2-reuse-pages/reference-3ds2requestdata/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **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 | ![](/user/pages/reuse/3ds2-reuse-pages/reference-3ds2requestdata/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for app-based integrations. The `sdkReferenceNumber` value as received from the 3D Secure 2 SDK. | | `sdkTransID` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-3ds2requestdata/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **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 | ![](/user/pages/reuse/3ds2-reuse-pages/reference-3ds2requestdata/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **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](/online-payments/3d-secure/data-only/) flow. | | `threeDSRequestorID` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-3ds2requestdata/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **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](/online-payments/3d-secure/standalone-authentication) flow. The unique requestor ID assigned by the Directory Server when you enrol for 3D Secure 2. | | `threeDSRequestorName` | String | ![](/user/pages/reuse/3ds2-reuse-pages/reference-3ds2requestdata/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **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](/online-payments/3d-secure/standalone-authentication) 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 | ![](/user/pages/reuse/3ds2-reuse-pages/reference-3ds2requestdata/optional.svg?decoding=auto\&fetchpriority=auto) | 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 | ![](/user/pages/reuse/3ds2-reuse-pages/reference-3ds2requestdata/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB payments if you did not include the [`shopperEmail` parameter](#3d-secure-2-additional-data-objects), and did not provide the phone number in [telephoneNumber](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-telephoneNumber). A phone number for the shopper. **Format**: The phone number must include 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. | ## Challenge flow objects When the 3D Secure 2 authentication has to go through the fingerprint or challenge flows, you initialize the flows using the following objects. The Component returns the `fingerprint` or the `challengeResult` that you need to pass when you submit the authentication result. | 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](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details#request-details-threeds2-fingerprint) | Base64 encoded string | Returned by the Component after the challenge flow. This contains the following parameters:- `threeDSCompInd`Pass this in the [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) request. | | [threeds2.challengeResult](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details#request-details-threeds2-challengeResult) | Base64 encoded string | Returned by the Component after the challenge flow. This contains the following parameters:- `transStatus`Pass this in the [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) request. |