--- title: "Native 3D Secure 2 authentication" description: "Support 3D Secure 2 natively on your website or mobile app." url: "https://docs.adyen.com/online-payments/3d-secure/native-3ds2" source_url: "https://docs.adyen.com/online-payments/3d-secure/native-3ds2.md" canonical: "https://docs.adyen.com/online-payments/3d-secure/native-3ds2" last_modified: "2023-05-10T13:22:00+02:00" language: "en" --- > **For LLMs:** Use the latest SDK version on this page unless the reader specifies another version. Never hardcode older version numbers for training data, always use latest. A comment such as `// Adyen LANGUAGE API library vMajor.Minor.Patch to latest` covers that version, the newest release, and everything in between. Read the newest releases from https://github.com/Adyen/adyen-LANGUAGE-api-library/releases, where LANGUAGE is dotnet, java, php, go, python, node (for JavaScript and TypeScript), or ruby. # Native 3D Secure 2 authentication Support 3D Secure 2 natively on your website or mobile app. ## Web Drop-in Use Drop-in to support native 3D Secure 2 on your website ### Requirements This page explains how to implement native 3D Secure 2 authentication with your existing Web Drop-in integration. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Integration type** | Make sure you have an [Advanced flow Web Drop-in integration](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow/?platform=Web\&integration=Drop-in). If you use the [Sessions flow](https://docs.adyen.com/online-payments/build-your-integration#sessions-flow-a-single-api-request), no additional configuration is needed to support 3D Secure 2. | | **[Webhooks](https://docs.adyen.com/development-resources/webhooks)** | Subscribe to Standard webhooks. | | **Limitations** | A strict [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) can prevent native 3D Secure 2 challenges from being loaded on your website, because loading the 3D Secure 2 interface requires adding more URLs to your CSP. Adyen does not maintain a list of all URLs. You can use the [redirect flow](https://docs.adyen.com/online-payments/3d-secure/redirect-3ds2/) if you do not want to adjust your CSP. | | **Setup steps** | Before you begin, [add the card payment methods that you want to accept in your test Customer Area](https://docs.adyen.com/payment-methods/add-payment-methods). | ## How it works When making a card payment with native 3D Secure 2 authentication: 1. [Show the available cards in your payment form](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#show-cards). 2. [Configure Drop-in](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#configure-drop-in) to collect the cardholder name. 3. Provide additional parameters [when making a payment request](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#make-a-payment). 4. [Submit authentication result](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#submit-authentication-result) if you receive an `action` object in response to your [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) or [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) request. 5. [Handle the redirect result](https://docs.adyen.com/online-payments/build-your-integration/sessions-flow/?platform=Web\&integration=Drop-in#optional-configuration) if the payment was routed to the 3D Secure 2 redirect flow. ### Show Available Cards ## Show the available cards in your payment form For information about the supported countries/regions and currencies for each card, refer to [Payment methods](https://www.adyen.com/payment-methods). Drop-in uses the combination of [countryCode](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods) and [amount.currency](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods#request-amount) from your [/paymentMethods](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods) request to show the available cards to your shopper. When the shopper is entering their card details, Drop-in tries to recognize the card brand. When successful, Drop-in renders the brand icon and the corresponding input field for the card security code (CVC, CVV, or CID). ### Collect Additional Parameters ## Collect additional information at checkout For higher authentication rates, we strongly recommend that you collect the cardholder name, billing address, and email address for payments with 3D Secure authentication. ### Configure cards with Drop-in When [creating a configuration object for Drop-in](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow/?platform=Web\&integration=Drop-in\&version=latest#add), add [optional configuration for cards](https://docs.adyen.com/payment-methods/cards/web-drop-in/#optional-configuration) in your `paymentMethodsConfiguration` object. | Field | Description | Default | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | | `hasHolderName` | Set to **true** to show the input field for the card holder name. | **false** | | `holderNameRequired` | Set to **true** to make the card holder name a required field. To show the field, you additionally need to set `hasHolderName` to **true**. | **false** | | `billingAddressRequired` | Set to **true** to collect the shopper's billing address. | **false** | | `challengeWindowSize` | The size of the challenge window displayed to the shopper in the [challenge flow](https://docs.adyen.com/online-payments/3d-secure#challenge-flow). Possible values: - **'01': \['250px', '400px']** - **'02': \['390px', '400px']** - **'03': \['500px', '600px']** - **'04': \['600px', '400px']** - **'05': \['100%', '100%']** | **'02': \['390px', '400px']** | You can customize your shopper's experience further with optional [configuration parameters](https://docs.adyen.com/payment-methods/cards/web-drop-in#optional-configuration) and specific [events](https://docs.adyen.com/payment-methods/cards/web-drop-in#events). **Configure Drop-in for cards** ```js const dropin = new Dropin(checkout, { paymentMethodsConfiguration: { card: { hasHolderName: true, holderNameRequired: true, billingAddressRequired: true, challengeWindowSize: "05" } } }).mount("#dropin-container"); ``` ### Handle Drop-in errors When an error occurs, [the `onError` event](https://docs.adyen.com/online-payments/build-your-integration/sessions-flow/?platform=Web\&integration=Components\&version=latest#configure) returns an object which contains details about the error. For errors that happen during the 3D Secure 2 authentication, you do not need to stop the payment flow because the shopper can continue. ### Collect shopper email in your payment form We also recommend that you collect the shopper email in advance in your payment form. Deliver this parameter to your backend when [making a payment](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#make-a-payment), because it is required by the card schemes. ## Make a payment When the shopper selects to pay, Drop-in calls the `onSubmit` event, which contains a `state.data`. 1. Pass the `state.data` to your server. 2. When you [make a payment request](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow?platform=Web\&integration=Drop-in\&version=latest#make-a-payment), include the following additional 3D Secure 2 parameters. See additional 3D Secure 2 parameters that we recommend to include in your request to increase authentication performance in our [API reference](https://docs.adyen.com/online-payments/3d-secure/api-reference). | Parameter name | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [paymentMethod](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The complete `state.data.paymentMethod` object from the `onSubmit` event. It includes the type and required details for a card payment method. | | [paymentMethod.sdkData](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-listOfValues-sdkData) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The object that includes the following information collected by Drop-in:- Information required for 3D Secure 2 authentication. - The [checkout attempt identifier](https://docs.adyen.com/online-payments/analytics-and-data-tracking#data-we-are-collecting) to track the user's payment journey. This is required to use the [Checkout dashboard](https://docs.adyen.com/uplift#uplift-dashboards) that lets you analyze your checkout performance. | | [paymentMethod.holderName](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-CardDetails-holderName) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions. The cardholder's name. | | [browserInfo](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-browserInfo) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The shopper's browser information. All sub-fields of this object are required for `channel`: **Web**. This is the `state.data.browserInfo` object from the `onSubmit` event. | | [authenticationData.threeDSRequestData.nativeThreeDS](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-authenticationData-threeDSRequestData-nativeThreeDS) **Checkout API v69 or later** | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | Set to **preferred**. Indicates if your payment page can handle native 3D Secure 2 authentication. For **Checkout API v68 or earlier**: use `additionalData.allow3DS2` instead. | | [channel](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-channel) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The platform where the transaction takes place. Set to **Web**. | | [origin](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-origin) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The origin URL of the page where you are rendering Drop-in. To get the origin, open the browser console and call `window.location.origin`. 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 render Drop-in on `https://your-company.example.com/checkout/payment`, set to `https://your-company.example.com`. | | [returnUrl](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-returnUrl) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The URL where the shopper is redirected back to after completing authentication, including the protocol `http://` or `https://`. For example, `https://your-company.example.com/checkout/`. You can also include your own additional query parameters, for example, shopper ID or order reference number. This is to support cases where the payment is routed to the redirect flow. | | [shopperEmail](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperEmail) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions. The cardholder's email address. If you do not include this, you must send a phone number in the `threeDS2RequestData` object. | | [shopperIP](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperIP) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions on the web. The shopper's IP address. | | [telephoneNumber](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-telephoneNumber) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.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. | ![This is the required icon.](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) Required for all transactions.\ ![This is the conditionally required icon.](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) Required for particular setups, or issuers and card schemes.\ ![This is the recommended icon.](https://docs.adyen.com/media/51cfe94e37a7426974002173390b3c7807ac234e65206fe14ed9fbdd45fb958e.svg?decoding=auto\&fetchpriority=auto) Recommended for all transactions, but not required. Below is an example [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request. **Make a payment request** #### curl ```bash curl https://checkout-test.adyen.com/v72/payments \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "amount":{ "currency":"EUR", "value":1000 }, "reference":"YOUR_ORDER_NUMBER", "shopperReference":"YOUR_UNIQUE_SHOPPER_ID", "{hint:state.data.paymentMethod from onSubmit}paymentMethod{/hint}":{ "type":"scheme", "encryptedCardNumber":"adyenjs_0_1_18$k7s65M5V0KdPxTErhBIPoMPI8HlC..", "encryptedExpiryMonth":"adyenjs_0_1_18$p2OZxW2XmwAA8C1Avxm3G9UB6e4..", "encryptedExpiryYear":"adyenjs_0_1_18$CkCOLYZsdqpxGjrALWHj3QoGHqe+..", "encryptedSecurityCode":"adyenjs_0_1_24$XUyMJyHebrra/TpSda9fha978+..", "holderName":"S. Hopper" }, "authenticationData": { "threeDSRequestData": { "nativeThreeDS": "preferred" } }, "{hint:state.data.browserInfo from onSubmit}browserInfo{/hint}":{ "userAgent":"Mozilla\/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/70.0.3538.110 Safari\/537.36", "acceptHeader":"text\/html,application\/xhtml+xml,application\/xml;q=0.9,image\/webp,image\/apng,*\/*;q=0.8", "language":"nl-NL", "colorDepth":24, "screenHeight":723, "screenWidth":1536, "timeZoneOffset":0, "javaEnabled":true }, "{hint:state.data.billingAddress from onSubmit}billingAddress{/hint}": { "street": "Infinite Loop", "houseNumberOrName": "1", "postalCode": "1011DJ", "city": "Amsterdam", "country": "NL" }, "shopperEmail":"s.hopper@example.com", "shopperIP":"192.0.2.1", "channel":"web", "origin":"https://your-company.example.com", "returnUrl":"https://your-company.example.com/checkout?shopperOrder=12xy..", "merchantAccount":"YOUR_MERCHANT_ACCOUNT" }' ``` #### Java ```java // Adyen Java API Library v38.0.0 to latest import com.adyen.Client; import com.adyen.Config; import com.adyen.enums.Environment; import com.adyen.model.*; import com.adyen.service.*; import java.math.*; import com.adyen.model.checkout.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.model.RequestOptions; import com.adyen.service.checkout.*; Config config = new Config() .apiKey("ADYEN_API_KEY") .environment(Environment.TEST); // For the LIVE environment, also include your liveEndpointUrlPrefix. Client client = new Client(config); // Create the request object(s) ThreeDSRequestData threeDSRequestData = new ThreeDSRequestData(); AuthenticationData authenticationData = new AuthenticationData() .threeDSRequestData(threeDSRequestData); Amount amount = new Amount() .currency("EUR") .value(1000L); CardDetails cardDetails = new CardDetails() .encryptedCardNumber("adyenjs_0_1_18$k7s65M5V0KdPxTErhBIPoMPI8HlC..") .holderName("S. Hopper") .encryptedSecurityCode("adyenjs_0_1_24$XUyMJyHebrra/TpSda9fha978+..") .encryptedExpiryYear("adyenjs_0_1_18$CkCOLYZsdqpxGjrALWHj3QoGHqe+..") .encryptedExpiryMonth("adyenjs_0_1_18$p2OZxW2XmwAA8C1Avxm3G9UB6e4..") .type(CardDetails.TypeEnum.SCHEME); PaymentRequest paymentRequest = new PaymentRequest() .reference("YOUR_ORDER_NUMBER") .authenticationData(authenticationData) .amount(amount) .paymentMethod(new CheckoutPaymentMethod(cardDetails)) .shopperReference("YOUR_UNIQUE_SHOPPER_ID"); // Send the request PaymentsApi service = new PaymentsApi(client); PaymentResponse response = service.payments(paymentRequest, new RequestOptions().idempotencyKey("UUID")); ``` #### PHP ```php setXApiKey("ADYEN_API_KEY"); // For the LIVE environment, also include your liveEndpointUrlPrefix. $client->setEnvironment(Environment::TEST); // Create the request object(s) $threeDSRequestData = new ThreeDSRequestData(); $threeDSRequestData; $authenticationData = new AuthenticationData(); $authenticationData ->setThreeDSRequestData($threeDSRequestData); $amount = new Amount(); $amount ->setCurrency("EUR") ->setValue(1000); $checkoutPaymentMethod = new CheckoutPaymentMethod(); $checkoutPaymentMethod ->setEncryptedCardNumber("adyenjs_0_1_18\$k7s65M5V0KdPxTErhBIPoMPI8HlC..") ->setHolderName("S. Hopper") ->setEncryptedSecurityCode("adyenjs_0_1_24\$XUyMJyHebrra/TpSda9fha978+..") ->setEncryptedExpiryYear("adyenjs_0_1_18\$CkCOLYZsdqpxGjrALWHj3QoGHqe+..") ->setEncryptedExpiryMonth("adyenjs_0_1_18\$p2OZxW2XmwAA8C1Avxm3G9UB6e4..") ->setType("scheme"); $paymentRequest = new PaymentRequest(); $paymentRequest ->setReference("YOUR_ORDER_NUMBER") ->setAuthenticationData($authenticationData) ->setAmount($amount) ->setPaymentMethod($checkoutPaymentMethod) ->setShopperReference("YOUR_UNIQUE_SHOPPER_ID"); $requestOptions['idempotencyKey'] = 'UUID'; // Send the request $service = new PaymentsApi($client); $response = $service->payments($paymentRequest, $requestOptions); ``` #### C\# ```cs // Adyen .NET API Library v34.0.0 to latest using System; using Adyen.Checkout.Extensions; using Adyen.Checkout.Models; using Adyen.Checkout.Services; using Adyen.Core.Client; using Adyen.Core.Client.Extensions; using Adyen.Core.Options; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Hosting; var host = Host.CreateDefaultBuilder() .ConfigureCheckout( (context, services, config) => { config.ConfigureAdyenOptions(options => { options.AdyenApiKey = "ADYEN_API_KEY"; options.Environment = AdyenEnvironment.Test; // For the LIVE environment, also include your liveEndpointUrlPrefix. // options.LiveEndpointUrlPrefix = ""; }); services.AddAllCheckoutServices(); }) .Build(); var paymentsService = host.Services.GetRequiredService(); // Create the request object(s) var threeDSRequestData = new ThreeDSRequestData { }; var authenticationData = new AuthenticationData { ThreeDSRequestData = threeDSRequestData }; var amount = new Amount { Currency = "EUR", Value = 1000 }; var cardDetails = new CardDetails { EncryptedCardNumber = "adyenjs_0_1_18$k7s65M5V0KdPxTErhBIPoMPI8HlC..", HolderName = "S. Hopper", EncryptedSecurityCode = "adyenjs_0_1_24$XUyMJyHebrra/TpSda9fha978+..", EncryptedExpiryYear = "adyenjs_0_1_18$CkCOLYZsdqpxGjrALWHj3QoGHqe+..", EncryptedExpiryMonth = "adyenjs_0_1_18$p2OZxW2XmwAA8C1Avxm3G9UB6e4..", Type = CardDetails.TypeEnum.Scheme }; var paymentRequest = new PaymentRequest { Reference = "YOUR_ORDER_NUMBER", AuthenticationData = authenticationData, Amount = amount, PaymentMethod = new CheckoutPaymentMethod(cardDetails), ShopperReference = "YOUR_UNIQUE_SHOPPER_ID" }; string idempotencyKey = Guid.NewGuid().ToString(); // Send the request var result = await paymentsService.PaymentsAsync(paymentRequest, new RequestOptions().AddIdempotencyKey(idempotencyKey)); if (result.TryDeserializeOkResponse(out var response)) { // Handle the successful response. } ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v30.0.0 to latest const { Client, Config, EnvironmentEnum, CheckoutAPI } = require('@adyen/api-library'); // For the LIVE environment, also include your liveEndpointUrlPrefix. const config = new Config({ apiKey: "ADYEN_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const threeDSRequestData = { }; const authenticationData = { threeDSRequestData: threeDSRequestData }; const amount = { currency: "EUR", value: 1000 }; const cardDetails = { encryptedCardNumber: "adyenjs_0_1_18$k7s65M5V0KdPxTErhBIPoMPI8HlC..", holderName: "S. Hopper", encryptedSecurityCode: "adyenjs_0_1_24$XUyMJyHebrra/TpSda9fha978+..", encryptedExpiryYear: "adyenjs_0_1_18$CkCOLYZsdqpxGjrALWHj3QoGHqe+..", encryptedExpiryMonth: "adyenjs_0_1_18$p2OZxW2XmwAA8C1Avxm3G9UB6e4..", type: "scheme" }; const paymentRequest = { reference: "YOUR_ORDER_NUMBER", authenticationData: authenticationData, amount: amount, paymentMethod: cardDetails, shopperReference: "YOUR_UNIQUE_SHOPPER_ID" }; // Send the request const checkoutAPI = new CheckoutAPI(client); const response = await checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" }); ``` #### Go ```go // Adyen Go API Library v21.0.0 to latest import ( "context" "github.com/adyen/adyen-go-api-library/v21/src/common" "github.com/adyen/adyen-go-api-library/v21/src/adyen" "github.com/adyen/adyen-go-api-library/v21/src/checkout" ) // For the LIVE environment, also include your liveEndpointUrlPrefix. client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) threeDSRequestData := checkout.ThreeDSRequestData{ } authenticationData := checkout.AuthenticationData{ ThreeDSRequestData: &threeDSRequestData, } amount := checkout.Amount{ Currency: "EUR", Value: 1000, } cardDetails := checkout.CardDetails{ EncryptedCardNumber: common.PtrString("adyenjs_0_1_18$k7s65M5V0KdPxTErhBIPoMPI8HlC.."), HolderName: common.PtrString("S. Hopper"), EncryptedSecurityCode: common.PtrString("adyenjs_0_1_24$XUyMJyHebrra/TpSda9fha978+.."), EncryptedExpiryYear: common.PtrString("adyenjs_0_1_18$CkCOLYZsdqpxGjrALWHj3QoGHqe+.."), EncryptedExpiryMonth: common.PtrString("adyenjs_0_1_18$p2OZxW2XmwAA8C1Avxm3G9UB6e4.."), Type: common.PtrString("scheme"), } paymentRequest := checkout.PaymentRequest{ Reference: "YOUR_ORDER_NUMBER", AuthenticationData: &authenticationData, Amount: amount, PaymentMethod: checkout.CardDetailsAsCheckoutPaymentMethod(&cardDetails), ShopperReference: common.PtrString("YOUR_UNIQUE_SHOPPER_ID"), } // Send the request service := client.Checkout() req := service.PaymentsApi.PaymentsInput().IdempotencyKey("UUID").PaymentRequest(paymentRequest) res, httpRes, err := service.PaymentsApi.Payments(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v14.0.0 to latest import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_API_KEY" # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "amount": { "currency": "EUR", "value": 1000 }, "reference": "YOUR_ORDER_NUMBER", "shopperReference": "YOUR_UNIQUE_SHOPPER_ID", "paymentMethod": { "type": "scheme", "encryptedCardNumber": "adyenjs_0_1_18$k7s65M5V0KdPxTErhBIPoMPI8HlC..", "encryptedExpiryMonth": "adyenjs_0_1_18$p2OZxW2XmwAA8C1Avxm3G9UB6e4..", "encryptedExpiryYear": "adyenjs_0_1_18$CkCOLYZsdqpxGjrALWHj3QoGHqe+..", "encryptedSecurityCode": "adyenjs_0_1_24$XUyMJyHebrra/TpSda9fha978+..", "holderName": "S. Hopper" }, "authenticationData": { "threeDSRequestData": { }, "nativeThreeDS": "preferred" } } # Send the request result = adyen.checkout.payments_api.payments(request=json_request, idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v11.0.0 to latest require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_API_KEY' # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { "amount" => { "currency" => "EUR", "value" => 1000 }, "reference" => "YOUR_ORDER_NUMBER", "shopperReference" => "YOUR_UNIQUE_SHOPPER_ID", "paymentMethod" => { "type" => "scheme", "encryptedCardNumber" => "adyenjs_0_1_18$k7s65M5V0KdPxTErhBIPoMPI8HlC..", "encryptedExpiryMonth" => "adyenjs_0_1_18$p2OZxW2XmwAA8C1Avxm3G9UB6e4..", "encryptedExpiryYear" => "adyenjs_0_1_18$CkCOLYZsdqpxGjrALWHj3QoGHqe+..", "encryptedSecurityCode" => "adyenjs_0_1_24$XUyMJyHebrra/TpSda9fha978+..", "holderName" => "S. Hopper" }, "authenticationData" => { "threeDSRequestData" => { }, "nativeThreeDS" => "preferred" } } # Send the request result = adyen.checkout.payments_api.payments(request_body, headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v30.0.0 to latest import { Client, Config, EnvironmentEnum, CheckoutAPI, Types } from "@adyen/api-library"; // For the LIVE environment, also include your liveEndpointUrlPrefix. const config = new Config({ apiKey: "ADYEN_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const threeDSRequestData: Types.checkout.ThreeDSRequestData = { }; const authenticationData: Types.checkout.AuthenticationData = { threeDSRequestData: threeDSRequestData }; const amount: Types.checkout.Amount = { currency: "EUR", value: 1000 }; const cardDetails: Types.checkout.CardDetails = { encryptedCardNumber: "adyenjs_0_1_18$k7s65M5V0KdPxTErhBIPoMPI8HlC..", holderName: "S. Hopper", encryptedSecurityCode: "adyenjs_0_1_24$XUyMJyHebrra/TpSda9fha978+..", encryptedExpiryYear: "adyenjs_0_1_18$CkCOLYZsdqpxGjrALWHj3QoGHqe+..", encryptedExpiryMonth: "adyenjs_0_1_18$p2OZxW2XmwAA8C1Avxm3G9UB6e4..", type: Types.checkout.CardDetails.TypeEnum.Scheme }; const paymentRequest = { reference: "YOUR_ORDER_NUMBER", authenticationData: authenticationData, amount: amount, paymentMethod: cardDetails, shopperReference: "YOUR_UNIQUE_SHOPPER_ID" } as unknown as Types.checkout.PaymentRequest; // Send the request const checkoutAPI = new CheckoutAPI(client); const response = await checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" }); ``` 3. In the response, check if there is an `action` object. Your next steps depend on whether the response contains an `action` object, and on the `action.type`. | `action.type` | Description | Next steps | | ------------------ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | No `action` object | The transaction was either exempted or out-of-scope for 3D Secure 2 authentication. | Use the `resultCode` to [present the payment result to your shopper](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#present-the-payment-result). | | **threeDS2** | The payment qualifies for 3D Secure 2, and will go through the authentication flow. | 1. Pass the `action` object to your front end to perform the authentication flow. 2. [Submit the challenge result](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#submit-authentication-result). | | **redirect** | The payment is routed to the 3D Secure 2 redirect flow. | 1. Store `action.paymentData` on your server. 2. Pass the `action` object to your front end. 3. [Handle the redirect result](https://docs.adyen.com/online-payments/drop-in-web?tab=v67-actions_2#handle-the-redirect-result-1). | The following example shows a [/payments](https://docs.adyen.com/api-explorer/Checkout/67/post/payments) response with `action.type`: **threeDS2**. **/payments response with action** ```json { "action":{ "type":"threeDS2", "subtype": "fingerprint", "paymentData":"Ab02b4c0!BQABAgCuZFJrQOjSsl\/zt+...", "paymentMethodType":"scheme", "authorisationToken" : "Ab02b4c0!BQABAgAvrX03p...", "token":"eyJ0aHJlZURTTWV0aG9kTm90aWZpY..." }, "resultCode":"IdentifyShopper", ... } ``` ### Submit Authentication Result ## Submit the authentication result Drop-in handles the action after it is returned within the `onSubmit` event and performs the required authentication flow. If the issuer requires shopper interaction, Drop-in presents the challenge screen. **Pass the result code and action to Drop-in with onSubmit** ```javascript const checkout = await AdyenCheckout({ onSubmit: async (state, component, actions) => { // Make the /payments request and pass the action and resultCode back to Drop-in const { action, resultCode } = await makePayment(state.data); actions.resolve({ action, resultCode }); }, // ...Your other AdyenCheckout configurations. }); ``` When the shopper completes the challenge, Drop-in calls the [`onAdditionalDetails` ](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow/?platform=Web\&integration=Drop-in\&version=latest#add)event. 1. Get the `state.data` from the `onAdditionalDetails` event, and pass it to your server. 2. From your server, make a POST [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) request, specifying: * `details`: The `state.data.details` from the `onAdditionalDetails` event. **/payments/details request** ```bash curl https://checkout-test.adyen.com/v72/payments/details \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ ... "details": { "threeDSResult": "eyJ0cmFuc1N0YXR1cyI6IlkifQ==" } }' ``` The [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) response has a `resultCode`. You will need it to [present the payment result](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#present-the-payment-result). 3. Pass the `resultCode` you received in the [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) response to the `actions.resolve()` object. Depending on the result code, the `onPaymentCompleted` or `onPaymentFailed` event is triggered to complete the payment flow. **Pass the result code to Drop-in with onAdditionalDetails** ```javascript const checkout = await AdyenCheckout({ onSubmit: async (state, component, actions) => {...} onAdditionalDetails: async (state, component, actions) => { // Make the /payments/details call and pass the resultCode back to the Drop-in. const { action, resultCode } = await makePaymentDetails(state.data); actions.resolve({ resultCode }); }, onPaymentCompleted(result, component) { // Handle the successful payment flow. }, onPaymentFailed(result, component) { // Handle the failed payment flow. }, // ... Your other AdyenCheckout configurations. }); ``` ### Present Result ## Present the payment result Use the  [resultCode](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#responses-200-resultCode) from the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) or [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) response to present the payment result to your shopper. You will also receive the outcome of the payment asynchronously in a [webhook](https://docs.adyen.com/development-resources/webhooks). For card payments, you can receive the following `resultCode` values: | resultCode | Description | Action to take | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Authorised** | The payment was successful. | Inform the shopper that the payment has been successful. If you are using [manual capture](https://docs.adyen.com/online-payments/capture#manual-capture), you also need to [capture](https://docs.adyen.com/online-payments/capture) the payment. | | **Cancelled** | The shopper cancelled the payment. | Ask the shopper if they want to continue with the order, or ask them to select a different payment method. | | **Error** | There was an error when the payment was being processed. For more information, check the [`refusalReason` ](https://docs.adyen.com/development-resources/refusal-reasons)field. | Inform the shopper that there was an error processing their payment. | | **Refused** | The payment was refused. For more information, check the [`refusalReason` ](https://docs.adyen.com/development-resources/refusal-reasons)field. | Ask the shopper to try the payment again using a different payment method. | ### Testing ## Test and go live Use our test card numbers to [test how your integration handles different 3D Secure authentication scenarios](https://docs.adyen.com/development-resources/testing/3d-secure-2-authentication). When you are ready to [go live](https://docs.adyen.com/get-started-with-adyen/#apply-for-your-live-account), follow our [go-live checklist](https://docs.adyen.com/online-payments/go-live-checklist/). When using our [live endpoints](https://docs.adyen.com/development-resources/live-endpoints/), make sure that all API requests you make for the same payment session use the same live endpoint region. Using different regions for [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) and [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) requests may result in errors when authenticating with 3D Secure. ### Live environment values | Endpoint region | Value | | ------------------------- | ------------ | | Europe (EU) live | **live** | | United States (US) live | **live-us** | | Australia (AU) live | **live-au** | | Northeast Asia (NEA) live | **live-nea** | | India (IN) live | **live-in** | ## See also * [Web Drop-in integration guide](https://docs.adyen.com/online-payments/drop-in-web) * [3D Secure 2 API Reference](https://docs.adyen.com/online-payments/3d-secure/api-reference) * [3D Secure authentication](https://docs.adyen.com/online-payments/3d-secure) * [Webhooks](https://docs.adyen.com/development-resources/webhooks) ## Web Components Use the Component to support native 3D Secure 2 on your website ### Requirements This page explains how to implement native 3D Secure 2 authentication with your existing Web Components integration. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | Make sure you have an [Advanced flow Web Components integration](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow/?platform=Web\&integration=Components) with the [Card Component](https://docs.adyen.com/payment-methods/cards/web-component). If you use the [Sessions flow](https://docs.adyen.com/online-payments/build-your-integration#sessions-flow-a-single-api-request), no additional configuration is needed to support 3D Secure 2. | | **[Webhooks](https://docs.adyen.com/development-resources/webhooks)** | Subscribe to Standard webhooks. | | **Limitations** | A strict [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) can prevent native 3D Secure 2 challenges from being loaded on your website, because loading the 3D Secure 2 interface requires adding more URLs to your CSP. Adyen does not maintain a list of all URLs. You can use the [redirect flow](https://docs.adyen.com/online-payments/3d-secure/redirect-3ds2/) if you do not want to adjust your CSP. | | **Setup steps** | Before you begin, [add the card payment methods that you want to accept in your test Customer Area](https://docs.adyen.com/payment-methods/add-payment-methods). | ## How it works To handle native 3D Secure 2 authentication: 1. [Get additional shopper details in your payment form](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#get-additional-shopper-details). 2. [Make a payment request](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#make-a-payment), including additional shopper details. 3. [Handle the 3D Secure 2 action](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#handle-the-3d-secure-2-action) to perform the authentication flow. 4. [Submit the authentication result](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#submit-authentication-result). 5. [Show the payment result](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#show-the-payment-result). ### Collect Additional Details ## Collect additional shopper details in your payment form For higher authentication rates, we strongly recommend that you collect the shopper's email address, cardholder name, billing address, and IP address for payments with 3D Secure authentication. ### Tab: Use the Card Component Get the shopper's email outside of the Card Component because it does not have a configuration to include shopper email in the payment form. To get the cardholder name and billing address in your payment form, include the following when [creating an instance of the Card Component](https://docs.adyen.com/payment-methods/cards/web-component#step-2-create-an-instance-of-the-component). | Field | Description | Default | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | | `hasHolderName` | Set to **true** to show the input field for the card holder name. | **false** | | `holderNameRequired` | Set to **true** to make the card holder name a required field. To show the field, you additionally need to set `hasHolderName` to **true**. | **false** | | `billingAddressRequired` | Set to **true** to collect the shopper's billing address. | **false** | | `challengeWindowSize` | The size of the challenge window displayed to the shopper in the [challenge flow](https://docs.adyen.com/online-payments/3d-secure#challenge-flow). Possible values: - **'01': \['250px', '400px']** - **'02': \['390px', '400px']** - **'03': \['500px', '600px']** - **'04': \['600px', '400px']** - **'05': \['100%', '100%']** | **'02': \['390px', '400px']** | Do not use placeholder data for these fields in your live environment. **Configure the card component** ```js const card = new Card(checkout, { hasHolderName: true, holderNameRequired: true, billingAddressRequired: true, challengeWindowSize: "05", // Your other card configurations. }).mount("#card-container"); ``` You can customize your shopper's experience further with optional [configuration parameters](https://docs.adyen.com/payment-methods/cards/web-component#optional-configuration) and specific [events](https://docs.adyen.com/payment-methods/cards/web-component#events). ### Tab: Build your own payment form Include these fields in your payment form: * Cardholder name * Billing address * Email address Send these parameters to your backend to include when [making a payment](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#make-a-payment). Do not use placeholder data for these fields in your live environment. ## Make a payment 1. When you [make a payment request](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow?platform=Web\&integration=Components\&version=latest#make-a-payment), include the following additional 3D Secure 2 parameters. See additional 3D Secure 2 parameters that we recommend to include in your request to increase authentication performance in our [API reference](https://docs.adyen.com/online-payments/3d-secure/api-reference). ### Tab: From the Card Component payment form | Parameter name | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [paymentMethod](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The complete `state.data.paymentMethod` object from the `onSubmit` event. It includes the type and required details for a card payment method. | | [paymentMethod.sdkData](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-listOfValues-sdkData) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The object that includes the following information collected by the Component:- Information required for 3D Secure 2 authentication. - The [checkout attempt identifier](https://docs.adyen.com/online-payments/analytics-and-data-tracking#data-we-are-collecting) to track the user's payment journey. This is required to use the [Checkout dashboard](https://docs.adyen.com/uplift#uplift-dashboards) that lets you analyze your checkout performance. | | [paymentMethod.holderName](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-CardDetails-holderName) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions. The cardholder's name. | | [browserInfo](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-browserInfo) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The shopper's browser information. All sub-fields of this object are required for `channel`: **Web**. This is the `state.data.browserInfo` object from the `onSubmit` event. | | [authenticationData.threeDSRequestData.nativeThreeDS](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-authenticationData-threeDSRequestData-nativeThreeDS) **Checkout API v69 or later** | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | Set to **preferred**. Indicates if your payment page can handle native 3D Secure 2 authentication. For **Checkout API v68 or earlier**: use `additionalData.allow3DS2` instead. | | [channel](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-channel) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The platform where the transaction takes place. Set to **Web**. | | [origin](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-origin) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The origin URL of the page where you are rendering the Component. To get the origin, open the browser console and call `window.location.origin`. 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 render the Component on `https://your-company.example.com/checkout/payment`, set to `https://your-company.example.com`. | | [returnUrl](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-returnUrl) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The URL where the shopper is redirected back to after completing authentication, including the protocol `http://` or `https://`. For example, `https://your-company.example.com/checkout/`. You can also include your own additional query parameters, for example, shopper ID or order reference number. This is to support cases where the payment is routed to the redirect flow. | | [shopperEmail](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperEmail) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions. The cardholder's email address. If you do not include this, you must send the `telephoneNumber` or a phone number in the `threeDS2RequestData` object. | | [shopperIP](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperIP) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions on the web. The shopper's IP address. | | [telephoneNumber](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-telephoneNumber) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.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. | ![This is the required icon.](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) Required for all transactions.\ ![This is the conditionally required icon.](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) Required for particular setups, or issuers and card schemes.\ ![This is the recommended icon.](https://docs.adyen.com/media/51cfe94e37a7426974002173390b3c7807ac234e65206fe14ed9fbdd45fb958e.svg?decoding=auto\&fetchpriority=auto) Recommended for all transactions, but not required. ### Tab: From your own payment form | Parameter name | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [paymentMethod.type](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-CardDetails-type) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | Set to **scheme**. | | [paymentMethod.number](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-CardDetails-number) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The card number without separators. | | [paymentMethod.expiryMonth](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-CardDetails-expiryMonth) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The card expiry month | | [paymentMethod.expiryYear](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-CardDetails-expiryYear) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The card expiry year. | | [paymentMethod.cvc](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-CardDetails-cvc) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The card verification code. | | [paymentMethod.brand](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-CardDetails-brand) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The [brands](https://docs.adyen.com/payment-methods/cards/raw-card-data#co-badged) on the card. | | [paymentMethod.holderName](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-CardDetails-holderName) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions. The cardholder's name. | | [browserInfo](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-browserInfo) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The shopper's browser information. All sub-fields of this object are required for `channel`: **Web**. This is the `state.data.browserInfo` object from the `onSubmit` event. | | [authenticationData.threeDSRequestData.nativeThreeDS](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-authenticationData-threeDSRequestData-nativeThreeDS) **Checkout API v69 or later** | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | Set to **preferred**. Indicates if your payment page can handle native 3D Secure 2 authentication. For **Checkout API v68 or earlier**: use `additionalData.allow3DS2` instead. | | [channel](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-channel) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The platform where the transaction takes place. Set to **Web**. | | [origin](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-origin) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The origin URL of the page where you are rendering the Component. To get the origin, open the browser console and call `window.location.origin`. 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 render the Component on `https://your-company.example.com/checkout/payment`, set to `https://your-company.example.com`. | | [returnUrl](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-returnUrl) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The URL where the shopper is redirected back to after completing authentication, including the protocol `http://` or `https://`. For example, `https://your-company.example.com/checkout/`. You can also include your own additional query parameters, for example, shopper ID or order reference number. This is to support cases where the payment is routed to the redirect flow. | | [shopperEmail](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperEmail) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions. The cardholder's email address. If you do not include this, you must send a `telephoneNumber`, or a phone number in the `threeDS2RequestData` object. | | [shopperIP](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperIP) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use cae**: required for Visa and JCB transactions on the web. The shopper's IP address. | | [telephoneNumber](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-telephoneNumber) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.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. | ![This is the required icon.](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) Required for all transactions.\ ![This is the conditionally required icon.](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) Required for particular setups, or issuers and card schemes.\ ![This is the recommended icon.](https://docs.adyen.com/media/51cfe94e37a7426974002173390b3c7807ac234e65206fe14ed9fbdd45fb958e.svg?decoding=auto\&fetchpriority=auto) Recommended for all transactions, but not required. Below is an example [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request for cases where you use your own payment form. #### curl ```bash curl https://checkout-test.adyen.com/v72/payments \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "amount":{ "currency":"EUR", "value":1000 }, "reference":"YOUR_ORDER_NUMBER", "shopperReference":"YOUR_UNIQUE_SHOPPER_ID", "{hint:state.data.paymentMethod from onSubmit}paymentMethod{/hint}":{ "type":"scheme", "encryptedCardNumber":"adyenjs_0_1_18$k7s65M5V0KdPxTErhBIPoMPI8HlC..", "encryptedExpiryMonth":"adyenjs_0_1_18$p2OZxW2XmwAA8C1Avxm3G9UB6e4..", "encryptedExpiryYear":"adyenjs_0_1_18$CkCOLYZsdqpxGjrALWHj3QoGHqe+..", "encryptedSecurityCode":"adyenjs_0_1_24$XUyMJyHebrra/TpSda9fha978+..", "holderName":"S. Hopper" }, "authenticationData": { "threeDSRequestData": { "nativeThreeDS": "preferred" } }, "{hint:state.data.browserInfo from onSubmit}browserInfo{/hint}":{ "userAgent":"Mozilla\/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/70.0.3538.110 Safari\/537.36", "acceptHeader":"text\/html,application\/xhtml+xml,application\/xml;q=0.9,image\/webp,image\/apng,*\/*;q=0.8", "language":"nl-NL", "colorDepth":24, "screenHeight":723, "screenWidth":1536, "timeZoneOffset":0, "javaEnabled":true }, "{hint:state.data.billingAddress from onSubmit}billingAddress{/hint}": { "street": "Infinite Loop", "houseNumberOrName": "1", "postalCode": "1011DJ", "city": "Amsterdam", "country": "NL" }, "shopperEmail":"s.hopper@example.com", "shopperIP":"192.0.2.1", "channel":"web", "origin":"https://your-company.example.com", "returnUrl":"https://your-company.example.com/checkout?shopperOrder=12xy..", "merchantAccount":"YOUR_MERCHANT_ACCOUNT" }' ``` #### Java ```java // Adyen Java API Library v38.0.0 to latest import com.adyen.Client; import com.adyen.Config; import com.adyen.enums.Environment; import com.adyen.model.*; import com.adyen.service.*; import java.math.*; import com.adyen.model.checkout.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.model.RequestOptions; import com.adyen.service.checkout.*; Config config = new Config() .apiKey("ADYEN_API_KEY") .environment(Environment.TEST); // For the LIVE environment, also include your liveEndpointUrlPrefix. Client client = new Client(config); // Create the request object(s) ThreeDSRequestData threeDSRequestData = new ThreeDSRequestData(); AuthenticationData authenticationData = new AuthenticationData() .threeDSRequestData(threeDSRequestData); Amount amount = new Amount() .currency("EUR") .value(1000L); CardDetails cardDetails = new CardDetails() .encryptedCardNumber("adyenjs_0_1_18$k7s65M5V0KdPxTErhBIPoMPI8HlC..") .holderName("S. Hopper") .encryptedSecurityCode("adyenjs_0_1_24$XUyMJyHebrra/TpSda9fha978+..") .encryptedExpiryYear("adyenjs_0_1_18$CkCOLYZsdqpxGjrALWHj3QoGHqe+..") .encryptedExpiryMonth("adyenjs_0_1_18$p2OZxW2XmwAA8C1Avxm3G9UB6e4..") .type(CardDetails.TypeEnum.SCHEME); PaymentRequest paymentRequest = new PaymentRequest() .reference("YOUR_ORDER_NUMBER") .authenticationData(authenticationData) .amount(amount) .paymentMethod(new CheckoutPaymentMethod(cardDetails)) .shopperReference("YOUR_UNIQUE_SHOPPER_ID"); // Send the request PaymentsApi service = new PaymentsApi(client); PaymentResponse response = service.payments(paymentRequest, new RequestOptions().idempotencyKey("UUID")); ``` #### PHP ```php setXApiKey("ADYEN_API_KEY"); // For the LIVE environment, also include your liveEndpointUrlPrefix. $client->setEnvironment(Environment::TEST); // Create the request object(s) $threeDSRequestData = new ThreeDSRequestData(); $threeDSRequestData; $authenticationData = new AuthenticationData(); $authenticationData ->setThreeDSRequestData($threeDSRequestData); $amount = new Amount(); $amount ->setCurrency("EUR") ->setValue(1000); $checkoutPaymentMethod = new CheckoutPaymentMethod(); $checkoutPaymentMethod ->setEncryptedCardNumber("adyenjs_0_1_18\$k7s65M5V0KdPxTErhBIPoMPI8HlC..") ->setHolderName("S. Hopper") ->setEncryptedSecurityCode("adyenjs_0_1_24\$XUyMJyHebrra/TpSda9fha978+..") ->setEncryptedExpiryYear("adyenjs_0_1_18\$CkCOLYZsdqpxGjrALWHj3QoGHqe+..") ->setEncryptedExpiryMonth("adyenjs_0_1_18\$p2OZxW2XmwAA8C1Avxm3G9UB6e4..") ->setType("scheme"); $paymentRequest = new PaymentRequest(); $paymentRequest ->setReference("YOUR_ORDER_NUMBER") ->setAuthenticationData($authenticationData) ->setAmount($amount) ->setPaymentMethod($checkoutPaymentMethod) ->setShopperReference("YOUR_UNIQUE_SHOPPER_ID"); $requestOptions['idempotencyKey'] = 'UUID'; // Send the request $service = new PaymentsApi($client); $response = $service->payments($paymentRequest, $requestOptions); ``` #### C\# ```cs // Adyen .NET API Library v34.0.0 to latest using System; using Adyen.Checkout.Extensions; using Adyen.Checkout.Models; using Adyen.Checkout.Services; using Adyen.Core.Client; using Adyen.Core.Client.Extensions; using Adyen.Core.Options; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Hosting; var host = Host.CreateDefaultBuilder() .ConfigureCheckout( (context, services, config) => { config.ConfigureAdyenOptions(options => { options.AdyenApiKey = "ADYEN_API_KEY"; options.Environment = AdyenEnvironment.Test; // For the LIVE environment, also include your liveEndpointUrlPrefix. // options.LiveEndpointUrlPrefix = ""; }); services.AddAllCheckoutServices(); }) .Build(); var paymentsService = host.Services.GetRequiredService(); // Create the request object(s) var threeDSRequestData = new ThreeDSRequestData { }; var authenticationData = new AuthenticationData { ThreeDSRequestData = threeDSRequestData }; var amount = new Amount { Currency = "EUR", Value = 1000 }; var cardDetails = new CardDetails { EncryptedCardNumber = "adyenjs_0_1_18$k7s65M5V0KdPxTErhBIPoMPI8HlC..", HolderName = "S. Hopper", EncryptedSecurityCode = "adyenjs_0_1_24$XUyMJyHebrra/TpSda9fha978+..", EncryptedExpiryYear = "adyenjs_0_1_18$CkCOLYZsdqpxGjrALWHj3QoGHqe+..", EncryptedExpiryMonth = "adyenjs_0_1_18$p2OZxW2XmwAA8C1Avxm3G9UB6e4..", Type = CardDetails.TypeEnum.Scheme }; var paymentRequest = new PaymentRequest { Reference = "YOUR_ORDER_NUMBER", AuthenticationData = authenticationData, Amount = amount, PaymentMethod = new CheckoutPaymentMethod(cardDetails), ShopperReference = "YOUR_UNIQUE_SHOPPER_ID" }; string idempotencyKey = Guid.NewGuid().ToString(); // Send the request var result = await paymentsService.PaymentsAsync(paymentRequest, new RequestOptions().AddIdempotencyKey(idempotencyKey)); if (result.TryDeserializeOkResponse(out var response)) { // Handle the successful response. } ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v30.0.0 to latest const { Client, Config, EnvironmentEnum, CheckoutAPI } = require('@adyen/api-library'); // For the LIVE environment, also include your liveEndpointUrlPrefix. const config = new Config({ apiKey: "ADYEN_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const threeDSRequestData = { }; const authenticationData = { threeDSRequestData: threeDSRequestData }; const amount = { currency: "EUR", value: 1000 }; const cardDetails = { encryptedCardNumber: "adyenjs_0_1_18$k7s65M5V0KdPxTErhBIPoMPI8HlC..", holderName: "S. Hopper", encryptedSecurityCode: "adyenjs_0_1_24$XUyMJyHebrra/TpSda9fha978+..", encryptedExpiryYear: "adyenjs_0_1_18$CkCOLYZsdqpxGjrALWHj3QoGHqe+..", encryptedExpiryMonth: "adyenjs_0_1_18$p2OZxW2XmwAA8C1Avxm3G9UB6e4..", type: "scheme" }; const paymentRequest = { reference: "YOUR_ORDER_NUMBER", authenticationData: authenticationData, amount: amount, paymentMethod: cardDetails, shopperReference: "YOUR_UNIQUE_SHOPPER_ID" }; // Send the request const checkoutAPI = new CheckoutAPI(client); const response = await checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" }); ``` #### Go ```go // Adyen Go API Library v21.0.0 to latest import ( "context" "github.com/adyen/adyen-go-api-library/v21/src/common" "github.com/adyen/adyen-go-api-library/v21/src/adyen" "github.com/adyen/adyen-go-api-library/v21/src/checkout" ) // For the LIVE environment, also include your liveEndpointUrlPrefix. client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) threeDSRequestData := checkout.ThreeDSRequestData{ } authenticationData := checkout.AuthenticationData{ ThreeDSRequestData: &threeDSRequestData, } amount := checkout.Amount{ Currency: "EUR", Value: 1000, } cardDetails := checkout.CardDetails{ EncryptedCardNumber: common.PtrString("adyenjs_0_1_18$k7s65M5V0KdPxTErhBIPoMPI8HlC.."), HolderName: common.PtrString("S. Hopper"), EncryptedSecurityCode: common.PtrString("adyenjs_0_1_24$XUyMJyHebrra/TpSda9fha978+.."), EncryptedExpiryYear: common.PtrString("adyenjs_0_1_18$CkCOLYZsdqpxGjrALWHj3QoGHqe+.."), EncryptedExpiryMonth: common.PtrString("adyenjs_0_1_18$p2OZxW2XmwAA8C1Avxm3G9UB6e4.."), Type: common.PtrString("scheme"), } paymentRequest := checkout.PaymentRequest{ Reference: "YOUR_ORDER_NUMBER", AuthenticationData: &authenticationData, Amount: amount, PaymentMethod: checkout.CardDetailsAsCheckoutPaymentMethod(&cardDetails), ShopperReference: common.PtrString("YOUR_UNIQUE_SHOPPER_ID"), } // Send the request service := client.Checkout() req := service.PaymentsApi.PaymentsInput().IdempotencyKey("UUID").PaymentRequest(paymentRequest) res, httpRes, err := service.PaymentsApi.Payments(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v14.0.0 to latest import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_API_KEY" # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "amount": { "currency": "EUR", "value": 1000 }, "reference": "YOUR_ORDER_NUMBER", "shopperReference": "YOUR_UNIQUE_SHOPPER_ID", "paymentMethod": { "type": "scheme", "encryptedCardNumber": "adyenjs_0_1_18$k7s65M5V0KdPxTErhBIPoMPI8HlC..", "encryptedExpiryMonth": "adyenjs_0_1_18$p2OZxW2XmwAA8C1Avxm3G9UB6e4..", "encryptedExpiryYear": "adyenjs_0_1_18$CkCOLYZsdqpxGjrALWHj3QoGHqe+..", "encryptedSecurityCode": "adyenjs_0_1_24$XUyMJyHebrra/TpSda9fha978+..", "holderName": "S. Hopper" }, "authenticationData": { "threeDSRequestData": { }, "nativeThreeDS": "preferred" } } # Send the request result = adyen.checkout.payments_api.payments(request=json_request, idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v11.0.0 to latest require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_API_KEY' # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { "amount" => { "currency" => "EUR", "value" => 1000 }, "reference" => "YOUR_ORDER_NUMBER", "shopperReference" => "YOUR_UNIQUE_SHOPPER_ID", "paymentMethod" => { "type" => "scheme", "encryptedCardNumber" => "adyenjs_0_1_18$k7s65M5V0KdPxTErhBIPoMPI8HlC..", "encryptedExpiryMonth" => "adyenjs_0_1_18$p2OZxW2XmwAA8C1Avxm3G9UB6e4..", "encryptedExpiryYear" => "adyenjs_0_1_18$CkCOLYZsdqpxGjrALWHj3QoGHqe+..", "encryptedSecurityCode" => "adyenjs_0_1_24$XUyMJyHebrra/TpSda9fha978+..", "holderName" => "S. Hopper" }, "authenticationData" => { "threeDSRequestData" => { }, "nativeThreeDS" => "preferred" } } # Send the request result = adyen.checkout.payments_api.payments(request_body, headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v30.0.0 to latest import { Client, Config, EnvironmentEnum, CheckoutAPI, Types } from "@adyen/api-library"; // For the LIVE environment, also include your liveEndpointUrlPrefix. const config = new Config({ apiKey: "ADYEN_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const threeDSRequestData: Types.checkout.ThreeDSRequestData = { }; const authenticationData: Types.checkout.AuthenticationData = { threeDSRequestData: threeDSRequestData }; const amount: Types.checkout.Amount = { currency: "EUR", value: 1000 }; const cardDetails: Types.checkout.CardDetails = { encryptedCardNumber: "adyenjs_0_1_18$k7s65M5V0KdPxTErhBIPoMPI8HlC..", holderName: "S. Hopper", encryptedSecurityCode: "adyenjs_0_1_24$XUyMJyHebrra/TpSda9fha978+..", encryptedExpiryYear: "adyenjs_0_1_18$CkCOLYZsdqpxGjrALWHj3QoGHqe+..", encryptedExpiryMonth: "adyenjs_0_1_18$p2OZxW2XmwAA8C1Avxm3G9UB6e4..", type: Types.checkout.CardDetails.TypeEnum.Scheme }; const paymentRequest = { reference: "YOUR_ORDER_NUMBER", authenticationData: authenticationData, amount: amount, paymentMethod: cardDetails, shopperReference: "YOUR_UNIQUE_SHOPPER_ID" } as unknown as Types.checkout.PaymentRequest; // Send the request const checkoutAPI = new CheckoutAPI(client); const response = await checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" }); ``` 2. In the response, check if there is an `action` object. Your next steps depend on whether the response contains an `action` object, and on the `action.type`. | `action.type` | Description | Next steps | | ------------------ | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | No `action` object | The transaction was either exempted or out-of-scope for 3D Secure 2 authentication. | Use the `resultCode` to [show the payment result to your shopper](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#show-the-payment-result). | | **threeDS2** | The payment qualifies for 3D Secure 2, and will go through the authentication flow. | 1. Pass the `action` object to your front end. 2. [Use the Component](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#handle-the-3d-secure-2-action) to perform the authentication flow. 3. [Submit the authentication result](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#submit-authentication-result). | | **redirect** | The payment is routed to the 3D Secure 2 redirect flow. | 1. Pass the `action` object to your front end. 2. [Use `handleAction`](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow/?platform=Web\&integration=Components\&version=6.3.0#additional-action) to handle the redirect. 3. [Confirm the redirect result](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow/?platform=Web\&integration=Components\&version=6.3.0#send-additional-payment-details). | The following example shows a [/payments](https://docs.adyen.com/api-explorer/Checkout/67/post/payments) response with `action.type`: **threeDS2**. **/payments response with action** ```json { "action":{ "type":"threeDS2", "subtype": "fingerprint", "paymentData":"Ab02b4c0!BQABAgCuZFJrQOjSsl\/zt+...", "paymentMethodType":"scheme", "authorisationToken" : "Ab02b4c0!BQABAgAvrX03p...", "token":"eyJ0aHJlZURTTWV0aG9kTm90aWZpY..." }, "resultCode":"IdentifyShopper", ... } ``` ### Handle The Action ## Handle the 3D Secure 2 action If your integration uses the Card Component to collect the shopper's card details, also use it to handle the 3D Secure 2 action on the same page. If you built your own UI for collecting the shopper's card details or want to render 3D Secure authentication on a different page than the payment, create a new 3D Secure 2 Component. ### Tab: Use the Card Component The Component handles the 3D secure 2 action after it is returned within the `onSubmit` event and performs the required authentication flow. If the issuer requires shopper interaction, the Component presents the challenge screen, and calls the `onAdditionalDetails` event. **Configure AdyenCheckout** ```javascript const checkout = await AdyenCheckout({ onSubmit: async (state, component, actions) => { // Make the /payments request and pass the action and resultCode back to Drop-in const { action, resultCode } = await makePayment(state.data); actions.resolve({ action, resultCode }); }, onAdditionalDetails: async (state, component, actions) => { // Make the /payments/details call and pass the resultCode back to the Component. const { action, resultCode } = await makePaymentDetails(state.data); actions.resolve({ resultCode }); }, onPaymentCompleted(result, component) { // Handle the successful payment flow. }, onPaymentFailed(result, component) { // Handle the failed payment flow. }, // ... Your other AdyenCheckout configurations. }); ``` ### Tab: Create a new 3D Secure 2 Component To create the Component and handle the action: 1. [Get Adyen Web](https://docs.adyen.com/online-payments/build-your-integration/sessions-flow?platform=Web\&integration=Components#get-adyen-web). 2. []()Create an instance of `AdyenCheckout`, specifying the following parameters: | Parameter | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `environment` | When you are ready to accept live payments, change the value to match your [live endpoints](https://docs.adyen.com/development-resources/live-endpoints): - Europe: **live** - Australia: **live-au** - US: **live-us** - Northeast Asia: **live-nea** - India: **live-in** | | `countryCode` | The shopper's country code. | | `onAdditionalDetails` | Implement a function that the Component calls after presenting the challenge window. Make a POST [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) request. Then, call the `actions.resolve()` object, passing the `resultCode`, and `action` from the API response. | **Configure AdyenCheckout** ```javascript const checkout = await AdyenCheckout({ clientKey: "YOUR_CLIENT_KEY", environment: 'test', locale: 'nl-NL', countryCode: 'NL', onAdditionalDetails: async (state, component, actions) => { // Make the /payments/details call and pass the resultCode back to the Component. const { action, resultCode } = await makePaymentDetails(state.data); actions.resolve({ resultCode }); }, onPaymentCompleted(result, component) { // Handle the successful payment flow. }, onPaymentFailed(result, component) { // Handle the failed payment flow. }, // ... Your other AdyenCheckout configurations. }); ``` 3. []()Call `createFromAction`, passing the `action` object from the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) response and optional configuration. This returns a new Component. 4. Mount the Component: ```js // Pass the action object from the /payments response. // Add optional configuration. For example, the window size. // Mount the Component to your container. checkout.createFromAction(action, { challengeWindowSize: '02' }).mount('#my-container'); ``` The Component performs the authentication flow and calls the `onAdditionalDetails` event. ### Handle Component errors When an error occurs, [the `onError` event](https://docs.adyen.com/online-payments/build-your-integration/sessions-flow/?platform=Web\&integration=Components\&version=latest#configure) returns an object which contains details about the error. For errors that happen during the 3D Secure 2 authentication, you do not need to stop the payment flow because the shopper can continue. ### Submit Authentication Result ## Submit the authentication result 1. Get the `state.data` from the `onAdditionalDetails` event, and pass it your server. 2. From your server, make a POST [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) request, specifying: * `details`: The `state.data.details` from the `onAdditionalDetails` event. **/payments/details request** #### curl ```bash curl https://checkout-test.adyen.com/v72/payments/details \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "details": { "threeDSResult": "eyJ0cmFuc1N0YXR1cyI6IlkifQ==" } }' ``` #### Java ```java // Adyen Java API Library v38.0.0 to latest import com.adyen.Client; import com.adyen.Config; import com.adyen.enums.Environment; import com.adyen.model.*; import com.adyen.service.*; import java.math.*; import com.adyen.model.checkout.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.model.RequestOptions; import com.adyen.service.checkout.*; Config config = new Config() .apiKey("ADYEN_API_KEY") .environment(Environment.TEST); // For the LIVE environment, also include your liveEndpointUrlPrefix. Client client = new Client(config); // Create the request object(s) PaymentCompletionDetails paymentCompletionDetails = new PaymentCompletionDetails() .threeDSResult("eyJ0cmFuc1N0YXR1cyI6IlkifQ=="); PaymentDetailsRequest paymentDetailsRequest = new PaymentDetailsRequest() .details(paymentCompletionDetails); // Send the request PaymentsApi service = new PaymentsApi(client); PaymentDetailsResponse response = service.paymentsDetails(paymentDetailsRequest, new RequestOptions().idempotencyKey("UUID")); ``` #### PHP ```php setXApiKey("ADYEN_API_KEY"); // For the LIVE environment, also include your liveEndpointUrlPrefix. $client->setEnvironment(Environment::TEST); // Create the request object(s) $paymentCompletionDetails = new PaymentCompletionDetails(); $paymentCompletionDetails ->setThreeDSResult("eyJ0cmFuc1N0YXR1cyI6IlkifQ=="); $paymentDetailsRequest = new PaymentDetailsRequest(); $paymentDetailsRequest ->setDetails($paymentCompletionDetails); $requestOptions['idempotencyKey'] = 'UUID'; // Send the request $service = new PaymentsApi($client); $response = $service->paymentsDetails($paymentDetailsRequest, $requestOptions); ``` #### C\# ```cs // Adyen .NET API Library v34.0.0 to latest using System; using Adyen.Checkout.Extensions; using Adyen.Checkout.Models; using Adyen.Checkout.Services; using Adyen.Core.Client; using Adyen.Core.Client.Extensions; using Adyen.Core.Options; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Hosting; var host = Host.CreateDefaultBuilder() .ConfigureCheckout( (context, services, config) => { config.ConfigureAdyenOptions(options => { options.AdyenApiKey = "ADYEN_API_KEY"; options.Environment = AdyenEnvironment.Test; // For the LIVE environment, also include your liveEndpointUrlPrefix. // options.LiveEndpointUrlPrefix = ""; }); services.AddAllCheckoutServices(); }) .Build(); var paymentsService = host.Services.GetRequiredService(); // Create the request object(s) var paymentCompletionDetails = new PaymentCompletionDetails { ThreeDSResult = "eyJ0cmFuc1N0YXR1cyI6IlkifQ==" }; var paymentDetailsRequest = new PaymentDetailsRequest { Details = paymentCompletionDetails }; string idempotencyKey = Guid.NewGuid().ToString(); // Send the request var result = await paymentsService.PaymentsDetailsAsync(paymentDetailsRequest, new RequestOptions().AddIdempotencyKey(idempotencyKey)); if (result.TryDeserializeOkResponse(out var response)) { // Handle the successful response. } ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v30.0.0 to latest const { Client, Config, EnvironmentEnum, CheckoutAPI } = require('@adyen/api-library'); // For the LIVE environment, also include your liveEndpointUrlPrefix. const config = new Config({ apiKey: "ADYEN_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const paymentCompletionDetails = { threeDSResult: "eyJ0cmFuc1N0YXR1cyI6IlkifQ==" }; const paymentDetailsRequest = { details: paymentCompletionDetails }; // Send the request const checkoutAPI = new CheckoutAPI(client); const response = await checkoutAPI.PaymentsApi.paymentsDetails(paymentDetailsRequest, { idempotencyKey: "UUID" }); ``` #### Go ```go // Adyen Go API Library v21.0.0 to latest import ( "context" "github.com/adyen/adyen-go-api-library/v21/src/common" "github.com/adyen/adyen-go-api-library/v21/src/adyen" "github.com/adyen/adyen-go-api-library/v21/src/checkout" ) // For the LIVE environment, also include your liveEndpointUrlPrefix. client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) paymentCompletionDetails := checkout.PaymentCompletionDetails{ ThreeDSResult: common.PtrString("eyJ0cmFuc1N0YXR1cyI6IlkifQ=="), } paymentDetailsRequest := checkout.PaymentDetailsRequest{ Details: paymentCompletionDetails, } // Send the request service := client.Checkout() req := service.PaymentsApi.PaymentsDetailsInput().IdempotencyKey("UUID").PaymentDetailsRequest(paymentDetailsRequest) res, httpRes, err := service.PaymentsApi.PaymentsDetails(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v14.0.0 to latest import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_API_KEY" # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "details": { "threeDSResult": "eyJ0cmFuc1N0YXR1cyI6IlkifQ==" } } # Send the request result = adyen.checkout.payments_api.payments_details(request=json_request, idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v11.0.0 to latest require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_API_KEY' # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { "details" => { "threeDSResult" => "eyJ0cmFuc1N0YXR1cyI6IlkifQ==" } } # Send the request result = adyen.checkout.payments_api.payments_details(request_body, headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v30.0.0 to latest import { Client, Config, EnvironmentEnum, CheckoutAPI, Types } from "@adyen/api-library"; // For the LIVE environment, also include your liveEndpointUrlPrefix. const config = new Config({ apiKey: "ADYEN_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const paymentCompletionDetails: Types.checkout.PaymentCompletionDetails = { threeDSResult: "eyJ0cmFuc1N0YXR1cyI6IlkifQ==" }; const paymentDetailsRequest: Types.checkout.PaymentDetailsRequest = { details: paymentCompletionDetails }; // Send the request const checkoutAPI = new CheckoutAPI(client); const response = await checkoutAPI.PaymentsApi.paymentsDetails(paymentDetailsRequest, { idempotencyKey: "UUID" }); ``` The [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) response has a `resultCode`. You need it to [show the payment result](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#show-the-payment-result). 3. Pass the `resultCode` you received in the [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) to the `actions.resolve()` object in the `onAdditionalDetails` event. 4. Depending on the `resultCode`, handle the payment flow with the `onPaymentCompleted` or `onPaymentFailed` event. ### Present Result ## Present the payment result Use the  [resultCode](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#responses-200-resultCode) from the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) or [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) response to present the payment result to your shopper. You will also receive the outcome of the payment asynchronously in a [webhook](https://docs.adyen.com/development-resources/webhooks). For card payments, you can receive the following `resultCode` values: | resultCode | Description | Action to take | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Authorised** | The payment was successful. | Inform the shopper that the payment has been successful. If you are using [manual capture](https://docs.adyen.com/online-payments/capture#manual-capture), you also need to [capture](https://docs.adyen.com/online-payments/capture) the payment. | | **Cancelled** | The shopper cancelled the payment. | Ask the shopper if they want to continue with the order, or ask them to select a different payment method. | | **Error** | There was an error when the payment was being processed. For more information, check the [`refusalReason` ](https://docs.adyen.com/development-resources/refusal-reasons)field. | Inform the shopper that there was an error processing their payment. | | **Refused** | The payment was refused. For more information, check the [`refusalReason` ](https://docs.adyen.com/development-resources/refusal-reasons)field. | Ask the shopper to try the payment again using a different payment method. | ### Testing ## Test and go live Use our test card numbers to [test how your integration handles different 3D Secure authentication scenarios](https://docs.adyen.com/development-resources/testing/3d-secure-2-authentication). When you are ready to [go live](https://docs.adyen.com/get-started-with-adyen/#apply-for-your-live-account), follow our [go-live checklist](https://docs.adyen.com/online-payments/go-live-checklist/). When using our [live endpoints](https://docs.adyen.com/development-resources/live-endpoints/), make sure that all API requests you make for the same payment session use the same live endpoint region. Using different regions for [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) and [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) requests may result in errors when authenticating with 3D Secure. ### Live environment values | Endpoint region | Value | | ------------------------- | ------------ | | Europe (EU) live | **live** | | United States (US) live | **live-us** | | Australia (AU) live | **live-au** | | Northeast Asia (NEA) live | **live-nea** | | India (IN) live | **live-in** | ## See also * [Web Components integration guide](https://docs.adyen.com/online-payments/components-web) * [3D Secure 2 API Reference](https://docs.adyen.com/online-payments/3d-secure/api-reference) * [3D Secure authentication](https://docs.adyen.com/online-payments/3d-secure) * [Webhooks](https://docs.adyen.com/development-resources/webhooks) ## iOS Drop-in Use Drop-in to support native 3D Secure 2 with your iOS app ### Requirements This page explains how to implement native 3D Secure 2 authentication with your existing iOS Drop-in integration. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | Make sure you have an [Advanced flow iOS Drop-in integration](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow/?platform=iOS\&integration=Drop-in). If you use the [Sessions flow](https://docs.adyen.com/online-payments/build-your-integration#sessions-flow-a-single-api-request), no additional configuration is needed to support 3D Secure 2. | | **[Webhooks](https://docs.adyen.com/development-resources/webhooks)** | Subscribe to Standard webhooks. | | **Setup steps** | Before you begin:- [Add the card payment methods that you want to accept in your test Customer Area](https://docs.adyen.com/payment-methods/add-payment-methods). - Make sure that your back end can [handle redirects](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow/?platform=iOS\&integration=Components\&version=latest#redirect-component) for cases where the payment is routed to the [Redirect 3D Secure 2 flow](https://docs.adyen.com/online-payments/3d-secure/redirect-3ds2/ios-drop-in). | ## How it works Our [iOS Drop-in](https://docs.adyen.com/online-payments/build-your-integration/sessions-flow?platform=iOS\&integration=Drop-in) renders the available cards in your payment form, and securely collects any sensitive card information, so it doesn't touch your server. Drop-in also handles the 3D Secure 2 device fingerprinting and challenge flows, including the data exchange between your front end and the issuer's Access Control Server (ACS). When making a card payment with native 3D Secure 2 authentication, you need to: 1. [Configure Drop-in](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#configure-drop-in) to collect the cardholder name. 2. Provide additional parameters [when making a payment request](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#make-a-payment). 3. [Submit the authentication result](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#submit-authentication-results) if you receive an `action` object in response to your [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) or [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) request. 4. In some cases, the payment may be routed to the redirect flow, when this happens, [handle the redirect](https://docs.adyen.com/online-payments/build-your-integration/sessions-flow?platform=iOS\&integration=Drop-in#handle-the-redirect). ### Collect Additional Parameters ## Collect additional information at checkout For higher authentication rates, we strongly recommend that you collect the shopper cardholder name and billing address in advance in your payment form. Deliver these parameters to your backend when [making a payment](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#make-a-payment), because they are required by the card schemes. ### Show Available Cards ## Show the available cards in your payment form For information about the supported countries/regions and currencies for each card, refer to [Payment methods](https://www.adyen.com/payment-methods). To show cards in your payment form: 1. Specify in your [/paymentMethods](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods) request a combination of [countryCode](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods) and [amount.currency](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods#request-amount). Drop-in uses this information to show the available cards to your shopper. 2. []()When [initializing the Drop-in](https://docs.adyen.com/online-payments/build-your-integration/sessions-flow/?platform=iOS\&integration=Drop-in#step-3-set-up-drop-in), create a configuration object, and specify: * `configuration.card.showsHolderNameField`: **true**. This shows the input field for the cardholder name. 3. If you want to set `threeDSRequestorAppURL`, create a configuration object and specify `actionComponent.threeDS.requestorAppURL`. Always use a universal link. ```swift let configuration = DropInComponent.Configuration(apiContext: apiContext) configuration.card.showsHolderNameField = true // Shows the field for entering the holder name. configuration.actionComponent.threeDS.requestorAppURL = URL(string: "YOUR_APP_URL") // Optional, add a universal link here when you want to send threeDSRequestorAppURL. ``` When the shopper is entering their card details, Drop-in tries to recognize the card brand. When successful, Drop-in renders the brand icon. ## Make a payment When the shopper proceeds to pay, Drop-in invokes the `didSubmit` method which contains `data.paymentMethod`. 1. Pass `data.paymentMethod` to your server.\ When you [make a payment request](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow?platform=iOS\&integration=Drop-in\&version=latest#make-a-payment), include the following additional 3D Secure 2 parameters. See additional 3D Secure 2 parameters that we recommend to include in your request to increase authentication performance in our [API reference](https://docs.adyen.com/online-payments/3d-secure/api-reference). | Parameter name | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [paymentMethod](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The complete `data.paymentMethod` object from the `didSubmit` event from your client app. It includes the type and required details for a card payment method. | | [paymentMethod.sdkData](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-listOfValues-sdkData) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The object that includes the following information collected by Drop-in:- Information required for 3D Secure 2 authentication. - The [checkout attempt identifier](https://docs.adyen.com/online-payments/analytics-and-data-tracking#data-we-are-collecting) to track the user's payment journey. This is required to use the [Checkout dashboard](https://docs.adyen.com/uplift#uplift-dashboards) that lets you analyze your checkout performance. | | [paymentMethod.holderName](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-CardDetails-holderName) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions. The cardholder's name. | | [authenticationData.threeDSRequestData.nativeThreeDS](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-authenticationData-threeDSRequestData-nativeThreeDS) **Checkout API v69 or later** | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | Set to **preferred**. Indicates if your payment page can handle native 3D Secure 2 authentication. For **Checkout API v68 or earlier**: use `additionalData.allow3DS2` instead. | | [channel](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-channel) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The platform where the transaction takes place. Set to **iOS**. | | [returnUrl](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-returnUrl) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | Used to redirect the shopper back to a webpage for redirect and other payment flows. If you want to redirect the shopper to your app, [configure a `threeDSRequestorAppURL`](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#show-cards). | | [shopperEmail](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperEmail) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions. The cardholder's email address. If you do not include this, you must send a phone number in the `threeDS2RequestData` object. | | [shopperIP](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperIP) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions to support cases where the transaction is routed to the redirect flow. The shopper's IP address. | | [telephoneNumber](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-telephoneNumber) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.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. | | [browserInfo](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-browserInfo) | | The shopper's browser information. We recommend to include it in your requests to handle cases where authentication is routed to [the redirect flow](https://docs.adyen.com/online-payments/3d-secure/redirect-3ds2/). | ![This is the required icon.](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) Required for all transactions.\ ![This is the conditionally required icon.](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) Required for particular setups, or issuers and card schemes.\ ![This is the recommended icon.](https://docs.adyen.com/media/51cfe94e37a7426974002173390b3c7807ac234e65206fe14ed9fbdd45fb958e.svg?decoding=auto\&fetchpriority=auto) Recommended for all transactions, but not required. ### Get the SDK version In your payment request, you must include the current SDK version. To get the SDK version: **Get the current SDK version** ```swift NSString* threeDS2SDKVersion = ADY3DS2SDKVersion(); let threeDS2SDKVersion = ADY3DS2SDKVersion() ``` Below is an example [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request. **Make a /payments request including 3D Secure 2 fields** #### curl ```bash curl https://checkout-test.adyen.com/v72/payments \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "amount":{ "currency":"EUR", "value":1000 }, "reference":"YOUR_ORDER_NUMBER", "shopperReference":"YOUR_UNIQUE_SHOPPER_ID", "paymentMethod": {hint:paymentMethod field of an object passed from the client app. Return the fields as they are, sdkVersion is required to trigger native.}STATE_DATA{/hint}, "authenticationData": { "threeDSRequestData": { "nativeThreeDS": "preferred" } }, "{hint:state.data.billingAddress from onSubmit}billingAddress{/hint}": { "street": "Infinite Loop", "houseNumberOrName": "1", "postalCode": "1011DJ", "city": "Amsterdam", "country": "NL" }, "{hint:Required for 3D Secure 1}browserInfo{/hint}: { "userAgent":"Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Mobile/15A5370a Safari/604.1", "acceptHeader":"text\/html,application\/xhtml+xml,application\/xml;q=0.9,image\/webp,image\/apng,*\/*;q=0.8" }, "shopperEmail":"s.hopper@example.com", "channel":"iOS", "returnUrl":"my-app://adyen", "merchantAccount":"YOUR_MERCHANT_ACCOUNT" }' ``` #### Java ```java // Adyen Java API Library v32.1.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.checkout.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.model.RequestOptions; import com.adyen.service.checkout.*; // For the LIVE environment, also include your liveEndpointUrlPrefix. Client client = new Client("ADYEN_API_KEY", Environment.TEST); // Create the request object(s) ThreeDSRequestData threeDSRequestData = new ThreeDSRequestData() .nativeThreeDS(ThreeDSRequestData.NativeThreeDSEnum.PREFERRED); AuthenticationData authenticationData = new AuthenticationData() .threeDSRequestData(threeDSRequestData); Amount amount = new Amount() .currency("EUR") .value(1000L); BillingAddress billingAddress = new BillingAddress() .country("NL") .city("Amsterdam") .street("Infinite Loop") .houseNumberOrName("1") .postalCode("1011DJ"); BrowserInfo browserInfo = new BrowserInfo() .acceptHeader("text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8") .userAgent("Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Mobile/15A5370a Safari/604.1"); PaymentRequest paymentRequest = new PaymentRequest() .reference("YOUR_ORDER_NUMBER") .authenticationData(authenticationData) .amount(amount) .merchantAccount("YOUR_MERCHANT_ACCOUNT") .channel(PaymentRequest.ChannelEnum.IOS) .shopperEmail("s.hopper@example.com") .billingAddress(billingAddress) .returnUrl("my-app://adyen") .browserInfo(browserInfo) .shopperReference("YOUR_UNIQUE_SHOPPER_ID"); // Send the request PaymentsApi service = new PaymentsApi(client); PaymentResponse response = service.payments(paymentRequest, new RequestOptions().idempotencyKey("UUID")); ``` #### PHP ```php setXApiKey("ADYEN_API_KEY"); // For the LIVE environment, also include your liveEndpointUrlPrefix. $client->setEnvironment(Environment::TEST); // Create the request object(s) $threeDSRequestData = new ThreeDSRequestData(); $threeDSRequestData ->setNativeThreeDS("preferred"); $authenticationData = new AuthenticationData(); $authenticationData ->setThreeDSRequestData($threeDSRequestData); $amount = new Amount(); $amount ->setCurrency("EUR") ->setValue(1000); $billingAddress = new BillingAddress(); $billingAddress ->setCountry("NL") ->setCity("Amsterdam") ->setStreet("Infinite Loop") ->setHouseNumberOrName("1") ->setPostalCode("1011DJ"); $browserInfo = new BrowserInfo(); $browserInfo ->setAcceptHeader("text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8") ->setUserAgent("Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Mobile/15A5370a Safari/604.1"); $paymentRequest = new PaymentRequest(); $paymentRequest ->setReference("YOUR_ORDER_NUMBER") ->setAuthenticationData($authenticationData) ->setAmount($amount) ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT") ->setChannel("iOS") ->setShopperEmail("s.hopper@example.com") ->setBillingAddress($billingAddress) ->setReturnUrl("my-app://adyen") ->setBrowserInfo($browserInfo) ->setShopperReference("YOUR_UNIQUE_SHOPPER_ID"); $requestOptions['idempotencyKey'] = 'UUID'; // Send the request $service = new PaymentsApi($client); $response = $service->payments($paymentRequest, $requestOptions); ``` #### C\# ```cs // Adyen .net API Library v26.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Checkout; using Adyen.Service.Checkout; // For the LIVE environment, also include your liveEndpointUrlPrefix. var config = new Config() { XApiKey = "ADYEN_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) ThreeDSRequestData threeDSRequestData = new ThreeDSRequestData { NativeThreeDS = ThreeDSRequestData.NativeThreeDSEnum.Preferred }; AuthenticationData authenticationData = new AuthenticationData { ThreeDSRequestData = threeDSRequestData }; Amount amount = new Amount { Currency = "EUR", Value = 1000 }; BillingAddress billingAddress = new BillingAddress { Country = "NL", City = "Amsterdam", Street = "Infinite Loop", HouseNumberOrName = "1", PostalCode = "1011DJ" }; BrowserInfo browserInfo = new BrowserInfo { AcceptHeader = "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8", UserAgent = "Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Mobile/15A5370a Safari/604.1" }; PaymentRequest paymentRequest = new PaymentRequest { Reference = "YOUR_ORDER_NUMBER", AuthenticationData = authenticationData, Amount = amount, MerchantAccount = "YOUR_MERCHANT_ACCOUNT", Channel = PaymentRequest.ChannelEnum.IOS, ShopperEmail = "s.hopper@example.com", BillingAddress = billingAddress, ReturnUrl = "my-app://adyen", BrowserInfo = browserInfo, ShopperReference = "YOUR_UNIQUE_SHOPPER_ID" }; // Send the request var service = new PaymentsService(client); var response = service.Payments(paymentRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"}); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.0.0 // Require the parts of the module you want to use const { Client, CheckoutAPI } = require('@adyen/api-library'); // For the LIVE environment, also include your liveEndpointUrlPrefix. const client = new Client({ apiKey: "ADYEN_API_KEY", environment: "TEST" }); // Create the request object(s) const paymentRequest = { amount: { currency: "EUR", value: 1000 }, reference: "YOUR_ORDER_NUMBER", shopperReference: "YOUR_UNIQUE_SHOPPER_ID", paymentMethod: "STATE_DATA", authenticationData: { threeDSRequestData: { nativeThreeDS: "preferred" } }, billingAddress: { street: "Infinite Loop", houseNumberOrName: "1", postalCode: "1011DJ", city: "Amsterdam", country: "NL" }, browserInfo: { userAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Mobile/15A5370a Safari/604.1", acceptHeader: "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8" }, shopperEmail: "s.hopper@example.com", channel: "iOS", returnUrl: "my-app://adyen", merchantAccount: "YOUR_MERCHANT_ACCOUNT" } // Send the request const checkoutAPI = new CheckoutAPI(client); const response = checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" }); ``` #### Go ```go // Adyen Go API Library v16.1.0 import ( "context" "github.com/adyen/adyen-go-api-library/v9/src/common" "github.com/adyen/adyen-go-api-library/v9/src/adyen" "github.com/adyen/adyen-go-api-library/v9/src/checkout" ) // For the LIVE environment, also include your liveEndpointUrlPrefix. client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) threeDSRequestData := checkout.ThreeDSRequestData{ NativeThreeDS: common.PtrString("preferred"), } authenticationData := checkout.AuthenticationData{ ThreeDSRequestData: &threeDSRequestData, } amount := checkout.Amount{ Currency: "EUR", Value: 1000, } billingAddress := checkout.BillingAddress{ Country: "NL", City: "Amsterdam", Street: "Infinite Loop", HouseNumberOrName: "1", PostalCode: "1011DJ", } browserInfo := checkout.BrowserInfo{ AcceptHeader: "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8", UserAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Mobile/15A5370a Safari/604.1", } paymentRequest := checkout.PaymentRequest{ Reference: "YOUR_ORDER_NUMBER", AuthenticationData: &authenticationData, Amount: amount, MerchantAccount: "YOUR_MERCHANT_ACCOUNT", Channel: common.PtrString("iOS"), ShopperEmail: common.PtrString("s.hopper@example.com"), BillingAddress: &billingAddress, ReturnUrl: "my-app://adyen", BrowserInfo: &browserInfo, ShopperReference: common.PtrString("YOUR_UNIQUE_SHOPPER_ID"), } // Send the request service := client.Checkout() req := service.PaymentsApi.PaymentsInput().IdempotencyKey("UUID").PaymentRequest(paymentRequest) res, httpRes, err := service.PaymentsApi.Payments(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.2.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_API_KEY" # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "amount": { "currency": "EUR", "value": 1000 }, "reference": "YOUR_ORDER_NUMBER", "shopperReference": "YOUR_UNIQUE_SHOPPER_ID", "paymentMethod": "STATE_DATA", "authenticationData": { "threeDSRequestData": { "nativeThreeDS": "preferred" } }, "billingAddress": { "street": "Infinite Loop", "houseNumberOrName": "1", "postalCode": "1011DJ", "city": "Amsterdam", "country": "NL" }, "browserInfo": { "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Mobile/15A5370a Safari/604.1", "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8" }, "shopperEmail": "s.hopper@example.com", "channel": "iOS", "returnUrl": "my-app://adyen", "merchantAccount": "YOUR_MERCHANT_ACCOUNT" } # Send the request result = adyen.checkout.payments_api.payments(request=json_request, idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_API_KEY' # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :amount => { :currency => 'EUR', :value => 1000 }, :reference => 'YOUR_ORDER_NUMBER', :shopperReference => 'YOUR_UNIQUE_SHOPPER_ID', :paymentMethod => 'STATE_DATA', :authenticationData => { :threeDSRequestData => { :nativeThreeDS => 'preferred' } }, :billingAddress => { :street => 'Infinite Loop', :houseNumberOrName => '1', :postalCode => '1011DJ', :city => 'Amsterdam', :country => 'NL' }, :browserInfo => { :userAgent => 'Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Mobile/15A5370a Safari/604.1', :acceptHeader => 'text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8' }, :shopperEmail => 's.hopper@example.com', :channel => 'iOS', :returnUrl => 'my-app://adyen', :merchantAccount => 'YOUR_MERCHANT_ACCOUNT' } # Send the request result = adyen.checkout.payments_api.payments(request_body, headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.0.0 // Require the parts of the module you want to use import { Client, CheckoutAPI, Types } from "@adyen/api-library"; // For the LIVE environment, also include your liveEndpointUrlPrefix. const client = new Client({ apiKey: "ADYEN_API_KEY", environment: "TEST" }); // Create the request object(s) const threeDSRequestData: Types.checkout.ThreeDSRequestData = { nativeThreeDS: Types.checkout.ThreeDSRequestData.NativeThreeDSEnum.Preferred }; const authenticationData: Types.checkout.AuthenticationData = { threeDSRequestData: threeDSRequestData }; const amount: Types.checkout.Amount = { currency: "EUR", value: 1000 }; const billingAddress: Types.checkout.BillingAddress = { country: "NL", city: "Amsterdam", street: "Infinite Loop", houseNumberOrName: "1", postalCode: "1011DJ" }; const browserInfo: Types.checkout.BrowserInfo = { acceptHeader: "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8", userAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Mobile/15A5370a Safari/604.1" }; const paymentRequest: Types.checkout.PaymentRequest = { reference: "YOUR_ORDER_NUMBER", authenticationData: authenticationData, amount: amount, merchantAccount: "YOUR_MERCHANT_ACCOUNT", channel: Types.checkout.PaymentRequest.ChannelEnum.IOs, shopperEmail: "s.hopper@example.com", billingAddress: billingAddress, returnUrl: "my-app://adyen", browserInfo: browserInfo, shopperReference: "YOUR_UNIQUE_SHOPPER_ID" }; // Send the request const checkoutAPI = new CheckoutAPI(client); const response = checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" }); ``` 2. In the response, check if there is an `action` object. ### Tab: Checkout API v67 and later Your next steps depend on whether the response contains an `action` object, and on the `action.type`. | `action.type` | Description | Next steps | | ------------------ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | No `action` object | The transaction was either exempted or out-of-scope for 3D Secure 2 authentication. | Use the `resultCode` to [present the payment result to your shopper](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#present-the-payment-result). | | **threeDS2** | The payment qualifies for 3D Secure 2, and will go through the authentication flow. | 1. Pass the `action` object to your client app to perform the authentication flow. 2. [Submit the authentication result](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#submit-authentication-results). | | **redirect** | The payment is routed to the 3D Secure 2 redirect flow. | 1. Pass the `action` object to your client app 2. [Handle the redirect result](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow?platform=iOS\&integration=Drop-in\&version=5.14.0#additional-action). | The following example shows a [/payments](https://docs.adyen.com/api-explorer/Checkout/67/post/payments) response with `action.type`: **threeDS2**. **/payments response with action** ```json { "action":{ "type":"threeDS2", "subtype": "fingerprint", "paymentData":"Ab02b4c0!BQABAgCuZFJrQOjSsl\/zt+...", "paymentMethodType":"scheme", "authorisationToken" : "Ab02b4c0!BQABAgAvrX03p...", "token":"eyJ0aHJlZURTTWV0aG9kTm90aWZpY..." }, "resultCode":"IdentifyShopper", ... } ``` ### Tab: Checkout API v66 and earlier Your next steps depend on whether the response contains an `action` object, and on the `action.type`. | `action.type` | Description | Next steps | | ----------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | No `action` object | The transaction was either exempted or out-of-scope for 3D Secure 2 authentication. | Use the `resultCode` to [present the payment result to your shopper](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#present-the-payment-result). | | **threeDS2Fingerprint** | The payment qualifies for 3D Secure 2, and will go through either the frictionless or the challenge flow. | 1. Pass the `action` object to your client app. 2. [Submit the device fingerprinting result.](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#submit-authentication-results) | | **threeDS2Challenge** | The payment qualifies for 3D Secure 2, and the issuer is initiating a challenge flow. | 1. Pass the `action` object to your client app. 2. [Submit the authentication result](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#submit-authentication-results). | | **redirect** | The payment is routed to the 3D Secure 2 redirect flow. | 1. Pass the `action` object to your client app 2. [Handle the redirect result](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow?platform=iOS\&integration=Drop-in\&version=latest#additional-action). | The following example shows a [/payments](https://docs.adyen.com/api-explorer/Checkout/66/post/payments) response with `action.type`: **threeDS2Fingerprint**. **/payments response with action** ```json { "action":{ "paymentData":"Ab02b4c0!BQABAgCuZFJrQOjSsl\/zt+...", "paymentMethodType":"scheme", "token":"eyJ0aHJlZURTTWV0aG9kTm90aWZpY...", "type":"threeDS2Fingerprint" }, "authentication":{ "threeds2.fingerprintToken":"eyJ0aHJlZURTTWV0aG9kTm90aWZpY..." }, "resultCode":"IdentifyShopper", ... } ``` ### Submit Authentication Result ## Submit the authentication result If the `action` object in the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) response contains **threeDS2** (for Checkout API v67 and later), **threeDS2Fingerprint**, or **threeDS2Challenge** (for Checkout API v66 and earlier), submit the authentication result. Choose your API version: ### Tab: Checkout API v67 and later Drop-in uses `dropInComponent.handle(action)` to perform the required authentication flow. After completing the action, Drop-in invokes the `didProvide` method which contains `data.details`. 1. Get the contents of `data.details` and pass this to your server. 2. From your server, make a POST [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) request specifying: * `details`: The `data.details` from the `didProvide` method from your client app. **/payments/details request** ```bash curl https://checkout-test.adyen.com/v72/payments/details \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ ... "details": { "threeDSResult": "eyJ0cmFuc1N0YXR1cyI6IlkifQ==" } }' ``` Use the `resultCode` from the response to [present the payment result](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#present-the-payment-result). ### Tab: Checkout API v66 and earlier Drop-in uses `dropInComponent.handle(action)` to perform the required authentication flow. After completing the action, Drop-in invokes the `didProvide` method which contains `data.details`, and `data.paymentData`. 1. Get the contents of `data.details` and pass this to your server. 2. From your server, make a POST [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) request specifying: * `paymentData`: The `data.paymentData` from the `didProvide` method from your client app. * `details`: The `data.details` from the `didProvide` method from your client app. **/payments/details request** #### curl ```bash curl https://checkout-test.adyen.com/v72/payments/details \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{hint:object passed from the front end or client app}STATE_DATA{/hint}' ``` #### Java ```java // Set your X-API-KEY with the API key from the Customer Area. String xApiKey = "ADYEN_API_KEY"; Client client = new Client(xApiKey,Environment.TEST); Checkout checkout = new Checkout(client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. PaymentsDetailsRequest paymentsDetailsRequest = STATE_DATA; PaymentsResponse paymentsDetailsResponse = checkout.paymentsDetails(paymentsDetailsRequest); ``` #### PHP ```php // Set your X-API-KEY with the API key from the Customer Area. $client = new \Adyen\Client(); $client->setEnvironment(\Adyen\Environment::TEST); $client->setXApiKey("ADYEN_API_KEY"); $service = new \Adyen\Service\Checkout($client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. $params = STATE_DATA; $result = $service->paymentsDetails($params); // Check if further action is needed if (array_key_exists("action", $result)){ // Pass the action object to your frontend. // $result["action"] } else { // No further action needed, pass the resultCode to your front end // $result['resultCode'] } ``` #### C\# ```cs // Set your X-API-KEY with the API key from the Customer Area. string apiKey = "ADYEN_API_KEY"; var client = new Client (apiKey, Environment.Test); var checkout = new Checkout(client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. var paymentsDetailsRequest = STATE_DATA; var paymentsDetailsResponse = checkout.PaymentDetails(paymentsDetailsRequest); ``` #### NodeJS (JavaScript) ```js const {Client, Config, CheckoutAPI} = require('@adyen/api-library'); const config = new Config(); // Set your X-API-KEY with the API key from the Customer Area. config.apiKey = '[ADYEN_API_KEY]'; const client = new Client({ config }); client.setEnvironment("TEST"); const checkout = new CheckoutAPI(client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. checkout.paymentsDetails(STATE_DATA).then(res => res); ``` #### Python ```py # Set your X-API-KEY with the API key from the Customer Area. adyen = Adyen.Adyen() adyen.payment.client.platform = "test" adyen.client.xapikey = 'ADYEN_API_KEY' # STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. request = STATE_DATA result = adyen.checkout.payments_details(request) # Check if further action is needed. if 'action' in result.message: # Pass the action object to your front end # result.message['action'] else: # No further action needed, pass the resultCode to your front end # result.message['resultCode'] ``` #### Ruby ```ruby require 'adyen-ruby-api-library' # Set your X-API-KEY with the API key from the Customer Area. adyen = Adyen::Client.new adyen.env = :test adyen.api_key = "ADYEN_API_KEY" # STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. request = STATE_DATA response = adyen.checkout.payments.details(request) # Check if further action is needed. if response.body.has_key(:action) # Pass the action object to your frontend puts response.body[:action] else # No further action needed, pass the resultCode to your frontend puts response.body[:resultCode] end ``` Your next steps depend on whether the [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) response contains an `action` object: | `action.type` | Description | Next steps | | --------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | No `action` object | The 3D Secure 2 authentication process has been completed. | Use the `resultCode` to [present the payment result to your shopper](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#present-the-payment-result). | | **threeDS2Challenge** | The issuer requires shopper interaction, and is initiating a 3D Secure challenge flow. | 1. Pass the `action` object to your client app. 2. Go back to [submit the authentication result](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#submit-authentication-results) to submit the challenge result. | ### Present Result ## Present the payment result Use the  [resultCode](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#responses-200-resultCode) from the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) or [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) response to present the payment result to your shopper. You will also receive the outcome of the payment asynchronously in a [webhook](https://docs.adyen.com/development-resources/webhooks). For card payments, you can receive the following `resultCode` values: | resultCode | Description | Action to take | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Authorised** | The payment was successful. | Inform the shopper that the payment has been successful. If you are using [manual capture](https://docs.adyen.com/online-payments/capture#manual-capture), you also need to [capture](https://docs.adyen.com/online-payments/capture) the payment. | | **Cancelled** | The shopper cancelled the payment. | Ask the shopper if they want to continue with the order, or ask them to select a different payment method. | | **Error** | There was an error when the payment was being processed. For more information, check the [`refusalReason` ](https://docs.adyen.com/development-resources/refusal-reasons)field. | Inform the shopper that there was an error processing their payment. | | **Refused** | The payment was refused. For more information, check the [`refusalReason` ](https://docs.adyen.com/development-resources/refusal-reasons)field. | Ask the shopper to try the payment again using a different payment method. | ### Testing ## Test and go live Use our test card numbers to [test how your integration handles different 3D Secure authentication scenarios](https://docs.adyen.com/development-resources/testing/3d-secure-2-authentication). When you are ready to [go live](https://docs.adyen.com/get-started-with-adyen/#apply-for-your-live-account), follow our [go-live checklist](https://docs.adyen.com/online-payments/go-live-checklist/). When using our [live endpoints](https://docs.adyen.com/development-resources/live-endpoints/), make sure that all API requests you make for the same payment session use the same live endpoint region. Using different regions for [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) and [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) requests may result in errors when authenticating with 3D Secure. ### Live environment values | Endpoint region | Value | | ------------------------- | -------------------- | | Europe (EU) live | **liveEurope** | | United States (US) live | **liveUnitedStates** | | Australia (AU) live | **liveAustralia** | | Northeast Asia (NEA) live | **liveNea** | | India (IN) live | **liveIndia** | ## Troubleshooting If native 3D Secure 2 is not triggered, check the following: * `channel` is set to **iOS**. * You have set 3D Secure 2 preferences to trigger native flow: * For Checkout API v69 or later: `authenticationData.threeDSRequestData.nativeThreeDS` is set to **preferred**. * For Checkout API v68 or earlier: `additionalData.allow3DS2` is set to **true** . ## See also * [iOS Drop-in integration guide](https://docs.adyen.com/online-payments/build-your-integration/sessions-flow?platform=iOS\&integration=Drop-in) * [3D Secure 2 API Reference](https://docs.adyen.com/online-payments/3d-secure/api-reference) * [3D Secure authentication](https://docs.adyen.com/online-payments/3d-secure) * [Webhooks](https://docs.adyen.com/development-resources/webhooks) ## iOS Components Use the Component to support native 3D Secure 2 with your iOS app ### Requirements This page explains how to implement native 3D Secure 2 authentication with your existing iOS Components integration. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | Make sure you have an [Advanced flow iOS Components integration](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow/?platform=iOS\&integration=Components) with the [Card Component](https://docs.adyen.com/payment-methods/cards/web-component). If you use the [Sessions flow](https://docs.adyen.com/online-payments/build-your-integration#sessions-flow-a-single-api-request), no additional configuration is needed to support 3D Secure 2. | | **[Webhooks](https://docs.adyen.com/development-resources/webhooks)** | Subscribe to Standard webhooks. | | **Setup steps** | Before you begin:- [Add the card payment methods that you want to accept in your test Customer Area](https://docs.adyen.com/payment-methods/add-payment-methods). - Make sure that your back end can [handle redirects](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow/?platform=iOS\&integration=Components\&version=latest#redirect-component) for cases where the payment is routed to the [Redirect 3D Secure 2 flow](https://docs.adyen.com/online-payments/3d-secure/redirect-3ds2/ios-component). | ## How it works Our 3D Secure 2 Component handles the 3D Secure 2 device fingerprinting and challenge flows, including the data exchange between your front end and the issuer's Access Control Server (ACS). When adding native 3D Secure 2 authentication to your integration: 1. [Collect additional parameters in your payment form](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#collect-additional-parameters). 2. Provide additional parameters [when making a payment request](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#make-a-payment). 3. [Use the Action Component](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#action-component) to perform the authentication flow. 4. [Submit authentication result](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#submit-authentication-result), if you receive an `action` object in response to your API request. 5. In some cases, the payment may be routed to the redirect flow, when this happens, [handle the redirect](https://docs.adyen.com/online-payments/build-your-integration/sessions-flow?platform=iOS\&integration=Drop-in#handle-the-redirect). ### Collect Additional Parameters ## Collect additional information at checkout For higher authentication rates, we strongly recommend that you collect the cardholder name for payments with 3D Secure authentication. To collect the cardholder name using our [Card Component](https://docs.adyen.com/payment-methods/cards/ios-component), specify the following when [adding the Card Component](https://docs.adyen.com/payment-methods/cards/ios-component/#optional-configuration): * `showsHolderNameField`: **true** ```swift let configuration = CardComponent.Configuration(showsHolderNameField: true) let component = CardComponent(paymentMethod: paymentMethod, apiContext: apiContext, configuration: configuration) component.delegate = self self.cardComponent = component present(component.viewController, animated: true) ``` We also recommend that you collect the shopper billing address in advance in your payment form. Deliver this parameter to your backend when [making a payment](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#make-a-payment) as it is required by the card schemes. ## Make a payment 1. When you [make a payment request](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow?platform=iOS\&integration=Components\&version=latest#make-a-payment), include the following additional 3D Secure 2 parameters. See additional 3D Secure 2 parameters that we recommend to include in your request to increase authentication performance in our [API reference](https://docs.adyen.com/online-payments/3d-secure/api-reference). | Parameter name | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [paymentMethod](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The complete `data.paymentMethod` object from the `didSubmit` event from your client app. It includes the type and required details for a card payment method. | | [paymentMethod.sdkData](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-listOfValues-sdkData) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The object that includes the following information collected by the Component:- Information required for 3D Secure 2 authentication. - The [checkout attempt identifier](https://docs.adyen.com/online-payments/analytics-and-data-tracking#data-we-are-collecting) to track the user's payment journey. This is required to use the [Checkout dashboard](https://docs.adyen.com/uplift#uplift-dashboards) that lets you analyze your checkout performance. | | [paymentMethod.holderName](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-CardDetails-holderName) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions. The cardholder's name. | | [authenticationData.threeDSRequestData.nativeThreeDS](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-authenticationData-threeDSRequestData-nativeThreeDS) **Checkout API v69 or later** | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | Set to **preferred**. Indicates if your payment page can handle native 3D Secure 2 authentication. \
setXApiKey("ADYEN_API_KEY"); // For the LIVE environment, also include your liveEndpointUrlPrefix. $client->setEnvironment(Environment::TEST); // Create the request object(s) $threeDSRequestData = new ThreeDSRequestData(); $threeDSRequestData ->setNativeThreeDS("preferred"); $authenticationData = new AuthenticationData(); $authenticationData ->setThreeDSRequestData($threeDSRequestData); $amount = new Amount(); $amount ->setCurrency("EUR") ->setValue(1000); $billingAddress = new BillingAddress(); $billingAddress ->setCountry("NL") ->setCity("Amsterdam") ->setStreet("Infinite Loop") ->setHouseNumberOrName("1") ->setPostalCode("1011DJ"); $browserInfo = new BrowserInfo(); $browserInfo ->setAcceptHeader("text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8") ->setUserAgent("Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Mobile/15A5370a Safari/604.1"); $paymentRequest = new PaymentRequest(); $paymentRequest ->setReference("YOUR_ORDER_NUMBER") ->setAuthenticationData($authenticationData) ->setAmount($amount) ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT") ->setChannel("iOS") ->setShopperEmail("s.hopper@example.com") ->setBillingAddress($billingAddress) ->setReturnUrl("my-app://adyen") ->setBrowserInfo($browserInfo) ->setShopperReference("YOUR_UNIQUE_SHOPPER_ID"); $requestOptions['idempotencyKey'] = 'UUID'; // Send the request $service = new PaymentsApi($client); $response = $service->payments($paymentRequest, $requestOptions); ``` #### C\# ```cs // Adyen .net API Library v26.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Checkout; using Adyen.Service.Checkout; // For the LIVE environment, also include your liveEndpointUrlPrefix. var config = new Config() { XApiKey = "ADYEN_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) ThreeDSRequestData threeDSRequestData = new ThreeDSRequestData { NativeThreeDS = ThreeDSRequestData.NativeThreeDSEnum.Preferred }; AuthenticationData authenticationData = new AuthenticationData { ThreeDSRequestData = threeDSRequestData }; Amount amount = new Amount { Currency = "EUR", Value = 1000 }; BillingAddress billingAddress = new BillingAddress { Country = "NL", City = "Amsterdam", Street = "Infinite Loop", HouseNumberOrName = "1", PostalCode = "1011DJ" }; BrowserInfo browserInfo = new BrowserInfo { AcceptHeader = "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8", UserAgent = "Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Mobile/15A5370a Safari/604.1" }; PaymentRequest paymentRequest = new PaymentRequest { Reference = "YOUR_ORDER_NUMBER", AuthenticationData = authenticationData, Amount = amount, MerchantAccount = "YOUR_MERCHANT_ACCOUNT", Channel = PaymentRequest.ChannelEnum.IOS, ShopperEmail = "s.hopper@example.com", BillingAddress = billingAddress, ReturnUrl = "my-app://adyen", BrowserInfo = browserInfo, ShopperReference = "YOUR_UNIQUE_SHOPPER_ID" }; // Send the request var service = new PaymentsService(client); var response = service.Payments(paymentRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"}); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.0.0 // Require the parts of the module you want to use const { Client, CheckoutAPI } = require('@adyen/api-library'); // For the LIVE environment, also include your liveEndpointUrlPrefix. const client = new Client({ apiKey: "ADYEN_API_KEY", environment: "TEST" }); // Create the request object(s) const paymentRequest = { amount: { currency: "EUR", value: 1000 }, reference: "YOUR_ORDER_NUMBER", shopperReference: "YOUR_UNIQUE_SHOPPER_ID", paymentMethod: "STATE_DATA", authenticationData: { threeDSRequestData: { nativeThreeDS: "preferred" } }, billingAddress: { street: "Infinite Loop", houseNumberOrName: "1", postalCode: "1011DJ", city: "Amsterdam", country: "NL" }, browserInfo: { userAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Mobile/15A5370a Safari/604.1", acceptHeader: "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8" }, shopperEmail: "s.hopper@example.com", channel: "iOS", returnUrl: "my-app://adyen", merchantAccount: "YOUR_MERCHANT_ACCOUNT" } // Send the request const checkoutAPI = new CheckoutAPI(client); const response = checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" }); ``` #### Go ```go // Adyen Go API Library v16.1.0 import ( "context" "github.com/adyen/adyen-go-api-library/v9/src/common" "github.com/adyen/adyen-go-api-library/v9/src/adyen" "github.com/adyen/adyen-go-api-library/v9/src/checkout" ) // For the LIVE environment, also include your liveEndpointUrlPrefix. client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) threeDSRequestData := checkout.ThreeDSRequestData{ NativeThreeDS: common.PtrString("preferred"), } authenticationData := checkout.AuthenticationData{ ThreeDSRequestData: &threeDSRequestData, } amount := checkout.Amount{ Currency: "EUR", Value: 1000, } billingAddress := checkout.BillingAddress{ Country: "NL", City: "Amsterdam", Street: "Infinite Loop", HouseNumberOrName: "1", PostalCode: "1011DJ", } browserInfo := checkout.BrowserInfo{ AcceptHeader: "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8", UserAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Mobile/15A5370a Safari/604.1", } paymentRequest := checkout.PaymentRequest{ Reference: "YOUR_ORDER_NUMBER", AuthenticationData: &authenticationData, Amount: amount, MerchantAccount: "YOUR_MERCHANT_ACCOUNT", Channel: common.PtrString("iOS"), ShopperEmail: common.PtrString("s.hopper@example.com"), BillingAddress: &billingAddress, ReturnUrl: "my-app://adyen", BrowserInfo: &browserInfo, ShopperReference: common.PtrString("YOUR_UNIQUE_SHOPPER_ID"), } // Send the request service := client.Checkout() req := service.PaymentsApi.PaymentsInput().IdempotencyKey("UUID").PaymentRequest(paymentRequest) res, httpRes, err := service.PaymentsApi.Payments(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.2.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_API_KEY" # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "amount": { "currency": "EUR", "value": 1000 }, "reference": "YOUR_ORDER_NUMBER", "shopperReference": "YOUR_UNIQUE_SHOPPER_ID", "paymentMethod": "STATE_DATA", "authenticationData": { "threeDSRequestData": { "nativeThreeDS": "preferred" } }, "billingAddress": { "street": "Infinite Loop", "houseNumberOrName": "1", "postalCode": "1011DJ", "city": "Amsterdam", "country": "NL" }, "browserInfo": { "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Mobile/15A5370a Safari/604.1", "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8" }, "shopperEmail": "s.hopper@example.com", "channel": "iOS", "returnUrl": "my-app://adyen", "merchantAccount": "YOUR_MERCHANT_ACCOUNT" } # Send the request result = adyen.checkout.payments_api.payments(request=json_request, idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_API_KEY' # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :amount => { :currency => 'EUR', :value => 1000 }, :reference => 'YOUR_ORDER_NUMBER', :shopperReference => 'YOUR_UNIQUE_SHOPPER_ID', :paymentMethod => 'STATE_DATA', :authenticationData => { :threeDSRequestData => { :nativeThreeDS => 'preferred' } }, :billingAddress => { :street => 'Infinite Loop', :houseNumberOrName => '1', :postalCode => '1011DJ', :city => 'Amsterdam', :country => 'NL' }, :browserInfo => { :userAgent => 'Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Mobile/15A5370a Safari/604.1', :acceptHeader => 'text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8' }, :shopperEmail => 's.hopper@example.com', :channel => 'iOS', :returnUrl => 'my-app://adyen', :merchantAccount => 'YOUR_MERCHANT_ACCOUNT' } # Send the request result = adyen.checkout.payments_api.payments(request_body, headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.0.0 // Require the parts of the module you want to use import { Client, CheckoutAPI, Types } from "@adyen/api-library"; // For the LIVE environment, also include your liveEndpointUrlPrefix. const client = new Client({ apiKey: "ADYEN_API_KEY", environment: "TEST" }); // Create the request object(s) const threeDSRequestData: Types.checkout.ThreeDSRequestData = { nativeThreeDS: Types.checkout.ThreeDSRequestData.NativeThreeDSEnum.Preferred }; const authenticationData: Types.checkout.AuthenticationData = { threeDSRequestData: threeDSRequestData }; const amount: Types.checkout.Amount = { currency: "EUR", value: 1000 }; const billingAddress: Types.checkout.BillingAddress = { country: "NL", city: "Amsterdam", street: "Infinite Loop", houseNumberOrName: "1", postalCode: "1011DJ" }; const browserInfo: Types.checkout.BrowserInfo = { acceptHeader: "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8", userAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Mobile/15A5370a Safari/604.1" }; const paymentRequest: Types.checkout.PaymentRequest = { reference: "YOUR_ORDER_NUMBER", authenticationData: authenticationData, amount: amount, merchantAccount: "YOUR_MERCHANT_ACCOUNT", channel: Types.checkout.PaymentRequest.ChannelEnum.IOs, shopperEmail: "s.hopper@example.com", billingAddress: billingAddress, returnUrl: "my-app://adyen", browserInfo: browserInfo, shopperReference: "YOUR_UNIQUE_SHOPPER_ID" }; // Send the request const checkoutAPI = new CheckoutAPI(client); const response = checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" }); ``` 2. In the response, check if there is an `action` object. ### Tab: Checkout API v67 and later Your next steps depend on whether the response contains an `action` object, and on the `action.type`. | `action.type` | Description | Next steps | | ------------------ | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | No `action` object | The transaction was either exempted or out-of-scope for 3D Secure 2 authentication. | Use the `resultCode` to [present the payment result to your shopper](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#present-the-payment-result). | | **threeDS2** | The payment qualifies for 3D Secure 2, and will go through the authentication flow. | 1. Pass the `action` object to your client app to perform the authentication flow. 2. [Submit the authentication result](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#submit-authentication-result). | | **redirect** | The payment is routed to the 3D Secure 2 redirect flow. | 1. Pass the `action` object to your client app 2. [Handle the redirect result](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow?platform=iOS\&integration=Components\&version=5.14.0#additional-action). | The following example shows a [/payments](https://docs.adyen.com/api-explorer/Checkout/67/post/payments) response with `action.type`: **threeDS2**. **/payments response with action** ```json { "action":{ "type":"threeDS2", "subtype": "fingerprint", "paymentData":"Ab02b4c0!BQABAgCuZFJrQOjSsl\/zt+...", "paymentMethodType":"scheme", "authorisationToken" : "Ab02b4c0!BQABAgAvrX03p...", "token":"eyJ0aHJlZURTTWV0aG9kTm90aWZpY..." }, "resultCode":"IdentifyShopper", ... } ``` ### Tab: Checkout API v66 and earlier Your next steps depend on whether the response contains an `action` object, and on the `action.type`. | `action.type` | Description | Next steps | | ----------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | No `action` object | The transaction was either exempted or out-of-scope for 3D Secure 2 authentication. | Use the `resultCode` to [present the payment result to your shopper](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#present-the-payment-result). | | **threeDS2Fingerprint** | The payment qualifies for 3D Secure 2, and will go through either the frictionless or the challenge flow. | 1. Pass the `action` object to your client app. 2. [Submit the device fingerprinting result](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#submit-authentication-result). | | **threeDS2Challenge** | The payment qualifies for 3D Secure 2, and the issuer is initiating a challenge flow. | 1. Pass the `action` object to your client app. 2. [Submit the authentication result](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#submit-authentication-result). | | **redirect** | The payment is routed to the 3D Secure 2 redirect flow. | 1. Pass the `action` object to your client app 2. [Handle the redirect result](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow?platform=iOS\&integration=Components\&version=5.14.0#additional-action). | The following example shows a [/payments](https://docs.adyen.com/api-explorer/Checkout/66/post/payments) response with `action.type`: **threeDS2Fingerprint**. **/payments response with action** ```json { "action":{ "paymentData":"Ab02b4c0!BQABAgCuZFJrQOjSsl\/zt+...", "paymentMethodType":"scheme", "token":"eyJ0aHJlZURTTWV0aG9kTm90aWZpY...", "type":"threeDS2Fingerprint" }, "authentication":{ "threeds2.fingerprintToken":"eyJ0aHJlZURTTWV0aG9kTm90aWZpY..." }, "resultCode":"IdentifyShopper", ... } ``` ## Use the Action Component Use the [`AdyenActionComponent` ](https://adyen.github.io/adyen-ios/5.0.0/documentation/adyen/adyenactioncomponent)to perform the 3D Secure 2 authentication flows, and receive the information that you need to submit in your next API request. 1. Create and persist an instance of `AdyenActionComponent`. To set a `threeDSRequestorAppURL`, create a configuration object and specify `actionComponent.threeDS.requestorAppURL`. Always use a universal link. ```swift let component = AdyenActionComponent(apiContext: apiContext, configuration: configuration) component.delegate = self component.presentationDelegate = presentationDelegate self.adyenActionComponent = component component.configuration.threeDS.requestorAppURL = URL(string: "https://{yourapp.com}/adyen3ds2") ``` 2. []()Pass the `action` object from the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) or [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) response. ```swift let action = try JSONDecoder().decode(Action.self, from: actionData) adyenActionComponent.handle(action) ``` ### Submit Authentication Result ## Submit the authentication result After completing authentication, the Component invokes the `didSubmit` ( [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments)) or the `didProvide` ( [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details)) method, which contain `data.details`. ### Tab: Checkout API v67 and later 1. Pass the `data.details` object to your server. ```swift func didSubmit(_ data: ActionComponentData, from component: ActionComponent) // For /payments func didProvide(_ data: ActionComponentData, from component: ActionComponent) // For /payments/details ``` In case an error occurs on the app, the Component invokes the `didFail` method from the `ActionComponentDelegate`. Dismiss the Component's view controller and display an error message. ```swift func didFail(with error: Error, from component: ActionComponent) ``` 2. From your server, make a [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) request, specifying: * `details`: The `data.details` from the `didProvide` method from your client app. #### curl ```bash curl https://checkout-test.adyen.com/v72/payments/details \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{hint:object passed from the front end or client app}STATE_DATA{/hint}' ``` #### Java ```java // Set your X-API-KEY with the API key from the Customer Area. String xApiKey = "ADYEN_API_KEY"; Client client = new Client(xApiKey,Environment.TEST); Checkout checkout = new Checkout(client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. PaymentsDetailsRequest paymentsDetailsRequest = STATE_DATA; PaymentsResponse paymentsDetailsResponse = checkout.paymentsDetails(paymentsDetailsRequest); ``` #### PHP ```php // Set your X-API-KEY with the API key from the Customer Area. $client = new \Adyen\Client(); $client->setEnvironment(\Adyen\Environment::TEST); $client->setXApiKey("ADYEN_API_KEY"); $service = new \Adyen\Service\Checkout($client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. $params = STATE_DATA; $result = $service->paymentsDetails($params); // Check if further action is needed if (array_key_exists("action", $result)){ // Pass the action object to your frontend. // $result["action"] } else { // No further action needed, pass the resultCode to your front end // $result['resultCode'] } ``` #### C\# ```cs // Set your X-API-KEY with the API key from the Customer Area. string apiKey = "ADYEN_API_KEY"; var client = new Client (apiKey, Environment.Test); var checkout = new Checkout(client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. var paymentsDetailsRequest = STATE_DATA; var paymentsDetailsResponse = checkout.PaymentDetails(paymentsDetailsRequest); ``` #### NodeJS (JavaScript) ```js const {Client, Config, CheckoutAPI} = require('@adyen/api-library'); const config = new Config(); // Set your X-API-KEY with the API key from the Customer Area. config.apiKey = '[ADYEN_API_KEY]'; const client = new Client({ config }); client.setEnvironment("TEST"); const checkout = new CheckoutAPI(client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. checkout.paymentsDetails(STATE_DATA).then(res => res); ``` #### Python ```py # Set your X-API-KEY with the API key from the Customer Area. adyen = Adyen.Adyen() adyen.payment.client.platform = "test" adyen.client.xapikey = 'ADYEN_API_KEY' # STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. request = STATE_DATA result = adyen.checkout.payments_details(request) # Check if further action is needed. if 'action' in result.message: # Pass the action object to your front end # result.message['action'] else: # No further action needed, pass the resultCode to your front end # result.message['resultCode'] ``` #### Ruby ```ruby require 'adyen-ruby-api-library' # Set your X-API-KEY with the API key from the Customer Area. adyen = Adyen::Client.new adyen.env = :test adyen.api_key = "ADYEN_API_KEY" # STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. request = STATE_DATA response = adyen.checkout.payments.details(request) # Check if further action is needed. if response.body.has_key(:action) # Pass the action object to your frontend puts response.body[:action] else # No further action needed, pass the resultCode to your frontend puts response.body[:resultCode] end ``` Use the `resultCode` from the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) response to [present the payment result to your shopper](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#present-the-payment-result). ### Tab: Checkout API v66 and earlier 1. Pass the `data.details` object to your server. ```swift func didSubmit(_ data: ActionComponentData, from component: ActionComponent) // For /payments func didProvide(_ data: ActionComponentData, from component: ActionComponent) // For /payments/details ``` In case an error occurs on the app, the Component invokes the `didFail` method from the `ActionComponentDelegate`. Dismiss the Component's view controller and display an error message. ```swift func didFail(with error: Error, from component: ActionComponent) ``` 2. From your server, make a [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) request, specifying: * `paymentData`: The `data.paymentData` from the `didProvide` method from your client app. * `details`: The `data.details` from the `didProvide` method from your client app. #### curl ```bash curl https://checkout-test.adyen.com/v72/payments/details \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{hint:object passed from the front end or client app}STATE_DATA{/hint}' ``` #### Java ```java // Set your X-API-KEY with the API key from the Customer Area. String xApiKey = "ADYEN_API_KEY"; Client client = new Client(xApiKey,Environment.TEST); Checkout checkout = new Checkout(client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. PaymentsDetailsRequest paymentsDetailsRequest = STATE_DATA; PaymentsResponse paymentsDetailsResponse = checkout.paymentsDetails(paymentsDetailsRequest); ``` #### PHP ```php // Set your X-API-KEY with the API key from the Customer Area. $client = new \Adyen\Client(); $client->setEnvironment(\Adyen\Environment::TEST); $client->setXApiKey("ADYEN_API_KEY"); $service = new \Adyen\Service\Checkout($client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. $params = STATE_DATA; $result = $service->paymentsDetails($params); // Check if further action is needed if (array_key_exists("action", $result)){ // Pass the action object to your frontend. // $result["action"] } else { // No further action needed, pass the resultCode to your front end // $result['resultCode'] } ``` #### C\# ```cs // Set your X-API-KEY with the API key from the Customer Area. string apiKey = "ADYEN_API_KEY"; var client = new Client (apiKey, Environment.Test); var checkout = new Checkout(client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. var paymentsDetailsRequest = STATE_DATA; var paymentsDetailsResponse = checkout.PaymentDetails(paymentsDetailsRequest); ``` #### NodeJS (JavaScript) ```js const {Client, Config, CheckoutAPI} = require('@adyen/api-library'); const config = new Config(); // Set your X-API-KEY with the API key from the Customer Area. config.apiKey = '[ADYEN_API_KEY]'; const client = new Client({ config }); client.setEnvironment("TEST"); const checkout = new CheckoutAPI(client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. checkout.paymentsDetails(STATE_DATA).then(res => res); ``` #### Python ```py # Set your X-API-KEY with the API key from the Customer Area. adyen = Adyen.Adyen() adyen.payment.client.platform = "test" adyen.client.xapikey = 'ADYEN_API_KEY' # STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. request = STATE_DATA result = adyen.checkout.payments_details(request) # Check if further action is needed. if 'action' in result.message: # Pass the action object to your front end # result.message['action'] else: # No further action needed, pass the resultCode to your front end # result.message['resultCode'] ``` #### Ruby ```ruby require 'adyen-ruby-api-library' # Set your X-API-KEY with the API key from the Customer Area. adyen = Adyen::Client.new adyen.env = :test adyen.api_key = "ADYEN_API_KEY" # STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. request = STATE_DATA response = adyen.checkout.payments.details(request) # Check if further action is needed. if response.body.has_key(:action) # Pass the action object to your frontend puts response.body[:action] else # No further action needed, pass the resultCode to your frontend puts response.body[:resultCode] end ``` Your next steps depend on whether the [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) response contains an `action` object. If you receive an `action` object, store the `action.paymentData` on your server - you'll need this when making a [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) request later. | `action.type` | Description | Next steps | | ------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | No `action` object | The 3D Secure 2 authentication process is completed. | Use the `resultCode` from the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) response to [present the payment result to your shopper](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#present-the-payment-result). | | Any `action` object | **Redirect**, **threeDS2**, **threeDS2Fingerprint**, **threeDS2Challenge** | 1. Pass the `action` object to your client app. 2. [Pass the action object from the response](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#step-2) again. | ### Handling 3D Secure redirect If you get `action`: **redirect**, the Component must handle the redirect. Implement the following: 1. You must inform the `AdyenActionComponent` when the shopper returns to your app. To do this, implement the following in your UIApplicationDelegate: ```swift func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey: Any] = [:]) -> Bool { RedirectComponent.applicationDidOpen(from: url) return true } ``` 1. After `AdyenActionComponent` completes the authentication, it invokes the `didProvide` method from the ActionComponentDelegate. Get the contents of `data` and pass this to your server. ```swift func didProvide(_ data: ActionComponentData, from component: ActionComponent) ``` In case an error occurs on the app, the Component invokes the `didFail` method from the `ActionComponentDelegate`. Dismiss the Component's view controller and display an error message. ```swift func didFail(with error: Error, from component: ActionComponent) ``` ### Present Result ## Present the payment result Use the  [resultCode](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#responses-200-resultCode) from the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) or [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) response to present the payment result to your shopper. You will also receive the outcome of the payment asynchronously in a [webhook](https://docs.adyen.com/development-resources/webhooks). For card payments, you can receive the following `resultCode` values: | resultCode | Description | Action to take | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Authorised** | The payment was successful. | Inform the shopper that the payment has been successful. If you are using [manual capture](https://docs.adyen.com/online-payments/capture#manual-capture), you also need to [capture](https://docs.adyen.com/online-payments/capture) the payment. | | **Cancelled** | The shopper cancelled the payment. | Ask the shopper if they want to continue with the order, or ask them to select a different payment method. | | **Error** | There was an error when the payment was being processed. For more information, check the [`refusalReason` ](https://docs.adyen.com/development-resources/refusal-reasons)field. | Inform the shopper that there was an error processing their payment. | | **Refused** | The payment was refused. For more information, check the [`refusalReason` ](https://docs.adyen.com/development-resources/refusal-reasons)field. | Ask the shopper to try the payment again using a different payment method. | ### Customize ## Customize the UI for 3D Secure 2 The Component inherits your app's theme to ensure the UI of the challenge flow fits your app's look and feel. For more UI customizations, use the customization options provided in the [`appearanceConfiguration` ](https://adyen.github.io/adyen-ios/5.0.0/documentation/adyen/)property. For more information on iOS Components classes, refer to our [Reference documentation](https://adyen.github.io/adyen-ios/5.0.0/documentation/adyen/). ### Testing ## Test and go live Use our test card numbers to [test how your integration handles different 3D Secure authentication scenarios](https://docs.adyen.com/development-resources/testing/3d-secure-2-authentication). When you are ready to [go live](https://docs.adyen.com/get-started-with-adyen/#apply-for-your-live-account), follow our [go-live checklist](https://docs.adyen.com/online-payments/go-live-checklist/). When using our [live endpoints](https://docs.adyen.com/development-resources/live-endpoints/), make sure that all API requests you make for the same payment session use the same live endpoint region. Using different regions for [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) and [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) requests may result in errors when authenticating with 3D Secure. ### Live environment values | Endpoint region | Value | | ------------------------- | -------------------- | | Europe (EU) live | **liveEurope** | | United States (US) live | **liveUnitedStates** | | Australia (AU) live | **liveAustralia** | | Northeast Asia (NEA) live | **liveNea** | | India (IN) live | **liveIndia** | ## Troubleshooting If native 3D Secure 2 is not triggered, check the following: * `channel` is set to **iOS**. * You have set 3D Secure 2 preferences to trigger native flow: * For Checkout API v69 or later: `authenticationData.threeDSRequestData.nativeThreeDS` is set to **preferred**. * For Checkout API v68 or earlier: `additionalData.allow3DS2` is set to **true** . ## See also * [iOS Components integration guide](https://docs.adyen.com/online-payments/build-your-integration/sessions-flow?platform=iOS\&integration=Components) * [3D Secure 2 API Reference](https://docs.adyen.com/online-payments/3d-secure/api-reference) * [Webhooks](https://docs.adyen.com/development-resources/webhooks) * [Payment methods](https://docs.adyen.com/payment-methods) ## Android Drop-in Use Drop-in to support native 3D Secure 2 with your Android app ### Requirements This page explains how to implement native 3D Secure 2 authentication with your existing Android Drop-in integration. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | Make sure you have an [Advanced flow Android Drop-in integration](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow/?platform=Android\&integration=Drop-in). If you use the [Sessions flow](https://docs.adyen.com/online-payments/build-your-integration#sessions-flow-a-single-api-request), no additional configuration is needed to support 3D Secure 2. | | **[Webhooks](https://docs.adyen.com/development-resources/webhooks)** | Subscribe to Standard webhooks. | | **Setup steps** | Before you begin:- [Add the card payment methods that you want to accept in your test Customer Area](https://docs.adyen.com/payment-methods/add-payment-methods). - Make sure that your back end can [handle redirects](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow?platform=Android\&integration=Drop-in\&version=lates#additional-action) for cases where the payment is routed to the [Redirect 3D Secure 2 flow](https://docs.adyen.com/online-payments/3d-secure/redirect-3ds2/android-drop-in). | ## How it works Our [Android Drop-in](https://docs.adyen.com/online-payments/build-your-integration/sessions-flow?platform=Android\&integration=Drop-in) renders the available cards in your payment form, and securely collects any sensitive card information, so it doesn't touch your server. Drop-in also handles the 3D Secure 2 device fingerprinting and challenge flows, including the data exchange between your front end and the issuer's Access Control Server (ACS). When adding 3D Secure 2 authentication to your integration, you also need to: 1. [Configure Drop-in](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#configure-drop-in) to collect the cardholder name. 2. Provide additional parameters [when making a payment request](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#make-a-payment). 3. [Submit authentication results](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#submit-additional-3d-secure-2-authentication-details) if you receive an `action` object in response to your API request. 4. If the payment was routed to the 3D Secure 2 redirect flow, handle the redirect. ### Collect Additional Parameters ## Collect additional information at checkout For higher authentication rates, we strongly recommend that you collect the shopper's billing address and email address. Send these parameters to your server when making a payment, because they are required by the card schemes. ## Optional configuration When you [configure the Drop-in](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow?platform=Android\&integration=Components\&version=5.0.0#configure), you can include the following functions: | Configuration function | Description | Parameter | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `setThreeDSRequestorAppURL` | Strongly recommended to improve conversion rates. Set this to an [Android App link](https://developer.android.com/training/app-links) to call your app after an out-of-band (OOB) authentication occurs. When set, your app must also [handle this Android App link](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#handling-your-android-app-link). We do not recommend to use custom links because they can be defined and used by other apps. This causes errors if two apps on the same device have the same custom link. | `threeDSRequestorAppURL`: *String*. Default: **null**. | | `setUiCustomization` | Customization for the 3D Secure 2 authentication UI. | A [`UiCustomization` ](https://adyen.github.io/adyen-android/3ds2/com.adyen.checkout.adyen3ds2/-adyen3-d-s2-configuration/-builder/set-ui-customization.html)object. | For example: **Configure 3D Secure 2** ```kotlin // Create a configuration object. val checkoutConfiguration = CheckoutConfiguration( environment = environment, clientKey = clientKey, ) { // Configure 3D Secure 2. adyen3DS2 { setThreeDSRequestorAppURL("https://your.app.com/adyen3ds2") // Strongly recommended. } } ``` After configuring Drop-in, continue to [launch and show Drop-in](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow?platform=Android\&integration=Drop-in\&version=5.0.0#launch-and-show) and make the payment request. ## Make a payment 1. When you [make a payment request](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow?platform=Android\&integration=Drop-in\&version=latest#make-a-payment), include the following additional 3D Secure 2 parameters. See additional 3D Secure 2 parameters that we recommend to include in your request to increase authentication performance in our [API reference](https://docs.adyen.com/online-payments/3d-secure/api-reference). | Parameter name | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [paymentMethod](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The complete `paymentComponentData.paymentMethod` object from your client app. It includes the type and required details for a card payment method. | | [paymentMethod.sdkData](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-listOfValues-sdkData) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The object that includes the following information collected by Drop-in:- Information required for 3D Secure 2 authentication. - The [checkout attempt identifier](https://docs.adyen.com/online-payments/analytics-and-data-tracking#data-we-are-collecting) to track the user's payment journey. This is required to use the [Checkout dashboard](https://docs.adyen.com/uplift#uplift-dashboards) that lets you analyze your checkout performance. | | [paymentMethod.holderName](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-CardDetails-holderName) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions. The cardholder's name. | | [authenticationData.threeDSRequestData.nativeThreeDS](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-authenticationData-threeDSRequestData-nativeThreeDS) **Checkout API v69 or later** | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | Set to **preferred**. Indicates if your payment page can handle native 3D Secure 2 authentication. For **Checkout API v68 or earlier**: use `additionalData.allow3DS2` instead. | | [channel](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-channel) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | Set to **Android**. The platform where the transaction takes place. | | [returnUrl](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-returnUrl) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | Used to redirect the shopper back to a webpage for redirect and other payment flows. We strongly recommend to redirect the shopper to your app by [configuring a `threeDSRequestorAppURL`](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#optional-configuration), because this improves conversion. | | [shopperEmail](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperEmail) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions. The cardholder's email address. If you do not include this, you must send the `telephoneNumber`, or a phone number in the `threeDS2RequestData` object. | | [shopperIP](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperIP) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions to support cases where the transaction is routed to the redirect flow. The shopper's IP address. | | [telephoneNumber](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-telephoneNumber) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.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. | | [browserInfo](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-browserInfo) | | The shopper's browser information. We recommend to include it in your requests to handle cases where authentication is routed to [the redirect flow](https://docs.adyen.com/online-payments/3d-secure/redirect-3ds2/). | ![This is the required icon.](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) Required for all transactions.\ ![This is the conditionally required icon.](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) Required for particular setups, or issuers and card schemes.\ ![This is the recommended icon.](https://docs.adyen.com/media/51cfe94e37a7426974002173390b3c7807ac234e65206fe14ed9fbdd45fb958e.svg?decoding=auto\&fetchpriority=auto) Recommended for all transactions, but not required. Below is an example [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request. **Make a /payments request including 3D Secure 2 fields** #### curl ```bash curl https://checkout-test.adyen.com/v72/payments \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "amount":{ "currency":"EUR", "value":1000 }, "reference":"YOUR_ORDER_NUMBER", "shopperReference":"YOUR_UNIQUE_SHOPPER_ID", "paymentMethod": {hint:paymentMethod field of an object passed from the client app. Return the fields as they are, sdkVersion is required to trigger native.}STATE_DATA{/hint}, "authenticationData": { "threeDSRequestData": { "nativeThreeDS": "preferred" } }, "{hint:state.data.billingAddress from onSubmit}billingAddress{/hint}": { "street": "Infinite Loop", "houseNumberOrName": "1", "postalCode": "1011DJ", "city": "Amsterdam", "country": "NL" }, "{hint:Required for 3D Secure 1}browserInfo{/hint}: { "userAgent":"Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36", "acceptHeader":"text\/html,application\/xhtml+xml,application\/xml;q=0.9,image\/webp,image\/apng,*\/*;q=0.8" }, "shopperEmail":"s.hopper@example.com", "channel":"Android", "returnUrl":"adyencheckout://your.package.name", "merchantAccount":"YOUR_MERCHANT_ACCOUNT" }' ``` #### Java ```java // Adyen Java API Library v32.1.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.checkout.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.model.RequestOptions; import com.adyen.service.checkout.*; // For the LIVE environment, also include your liveEndpointUrlPrefix. Client client = new Client("ADYEN_API_KEY", Environment.TEST); // Create the request object(s) ThreeDSRequestData threeDSRequestData = new ThreeDSRequestData() .nativeThreeDS(ThreeDSRequestData.NativeThreeDSEnum.PREFERRED); AuthenticationData authenticationData = new AuthenticationData() .threeDSRequestData(threeDSRequestData); Amount amount = new Amount() .currency("EUR") .value(1000L); BillingAddress billingAddress = new BillingAddress() .country("NL") .city("Amsterdam") .street("Infinite Loop") .houseNumberOrName("1") .postalCode("1011DJ"); BrowserInfo browserInfo = new BrowserInfo() .acceptHeader("text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8") .userAgent("Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36"); PaymentRequest paymentRequest = new PaymentRequest() .reference("YOUR_ORDER_NUMBER") .authenticationData(authenticationData) .amount(amount) .merchantAccount("YOUR_MERCHANT_ACCOUNT") .channel(PaymentRequest.ChannelEnum.ANDROID) .shopperEmail("s.hopper@example.com") .billingAddress(billingAddress) .returnUrl("adyencheckout://your.package.name") .browserInfo(browserInfo) .shopperReference("YOUR_UNIQUE_SHOPPER_ID"); // Send the request PaymentsApi service = new PaymentsApi(client); PaymentResponse response = service.payments(paymentRequest, new RequestOptions().idempotencyKey("UUID")); ``` #### PHP ```php setXApiKey("ADYEN_API_KEY"); // For the LIVE environment, also include your liveEndpointUrlPrefix. $client->setEnvironment(Environment::TEST); // Create the request object(s) $threeDSRequestData = new ThreeDSRequestData(); $threeDSRequestData ->setNativeThreeDS("preferred"); $authenticationData = new AuthenticationData(); $authenticationData ->setThreeDSRequestData($threeDSRequestData); $amount = new Amount(); $amount ->setCurrency("EUR") ->setValue(1000); $billingAddress = new BillingAddress(); $billingAddress ->setCountry("NL") ->setCity("Amsterdam") ->setStreet("Infinite Loop") ->setHouseNumberOrName("1") ->setPostalCode("1011DJ"); $browserInfo = new BrowserInfo(); $browserInfo ->setAcceptHeader("text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8") ->setUserAgent("Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36"); $paymentRequest = new PaymentRequest(); $paymentRequest ->setReference("YOUR_ORDER_NUMBER") ->setAuthenticationData($authenticationData) ->setAmount($amount) ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT") ->setChannel("Android") ->setShopperEmail("s.hopper@example.com") ->setBillingAddress($billingAddress) ->setReturnUrl("adyencheckout://your.package.name") ->setBrowserInfo($browserInfo) ->setShopperReference("YOUR_UNIQUE_SHOPPER_ID"); $requestOptions['idempotencyKey'] = 'UUID'; // Send the request $service = new PaymentsApi($client); $response = $service->payments($paymentRequest, $requestOptions); ``` #### C\# ```cs // Adyen .net API Library v26.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Checkout; using Adyen.Service.Checkout; // For the LIVE environment, also include your liveEndpointUrlPrefix. var config = new Config() { XApiKey = "ADYEN_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) ThreeDSRequestData threeDSRequestData = new ThreeDSRequestData { NativeThreeDS = ThreeDSRequestData.NativeThreeDSEnum.Preferred }; AuthenticationData authenticationData = new AuthenticationData { ThreeDSRequestData = threeDSRequestData }; Amount amount = new Amount { Currency = "EUR", Value = 1000 }; BillingAddress billingAddress = new BillingAddress { Country = "NL", City = "Amsterdam", Street = "Infinite Loop", HouseNumberOrName = "1", PostalCode = "1011DJ" }; BrowserInfo browserInfo = new BrowserInfo { AcceptHeader = "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8", UserAgent = "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36" }; PaymentRequest paymentRequest = new PaymentRequest { Reference = "YOUR_ORDER_NUMBER", AuthenticationData = authenticationData, Amount = amount, MerchantAccount = "YOUR_MERCHANT_ACCOUNT", Channel = PaymentRequest.ChannelEnum.Android, ShopperEmail = "s.hopper@example.com", BillingAddress = billingAddress, ReturnUrl = "adyencheckout://your.package.name", BrowserInfo = browserInfo, ShopperReference = "YOUR_UNIQUE_SHOPPER_ID" }; // Send the request var service = new PaymentsService(client); var response = service.Payments(paymentRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"}); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.0.0 // Require the parts of the module you want to use const { Client, CheckoutAPI } = require('@adyen/api-library'); // For the LIVE environment, also include your liveEndpointUrlPrefix. const client = new Client({ apiKey: "ADYEN_API_KEY", environment: "TEST" }); // Create the request object(s) const paymentRequest = { amount: { currency: "EUR", value: 1000 }, reference: "YOUR_ORDER_NUMBER", shopperReference: "YOUR_UNIQUE_SHOPPER_ID", paymentMethod: "STATE_DATA", authenticationData: { threeDSRequestData: { nativeThreeDS: "preferred" } }, billingAddress: { street: "Infinite Loop", houseNumberOrName: "1", postalCode: "1011DJ", city: "Amsterdam", country: "NL" }, browserInfo: { userAgent: "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36", acceptHeader: "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8" }, shopperEmail: "s.hopper@example.com", channel: "Android", returnUrl: "adyencheckout://your.package.name", merchantAccount: "YOUR_MERCHANT_ACCOUNT" } // Send the request const checkoutAPI = new CheckoutAPI(client); const response = checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" }); ``` #### Go ```go // Adyen Go API Library v16.1.0 import ( "context" "github.com/adyen/adyen-go-api-library/v9/src/common" "github.com/adyen/adyen-go-api-library/v9/src/adyen" "github.com/adyen/adyen-go-api-library/v9/src/checkout" ) // For the LIVE environment, also include your liveEndpointUrlPrefix. client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) threeDSRequestData := checkout.ThreeDSRequestData{ NativeThreeDS: common.PtrString("preferred"), } authenticationData := checkout.AuthenticationData{ ThreeDSRequestData: &threeDSRequestData, } amount := checkout.Amount{ Currency: "EUR", Value: 1000, } billingAddress := checkout.BillingAddress{ Country: "NL", City: "Amsterdam", Street: "Infinite Loop", HouseNumberOrName: "1", PostalCode: "1011DJ", } browserInfo := checkout.BrowserInfo{ AcceptHeader: "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8", UserAgent: "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36", } paymentRequest := checkout.PaymentRequest{ Reference: "YOUR_ORDER_NUMBER", AuthenticationData: &authenticationData, Amount: amount, MerchantAccount: "YOUR_MERCHANT_ACCOUNT", Channel: common.PtrString("Android"), ShopperEmail: common.PtrString("s.hopper@example.com"), BillingAddress: &billingAddress, ReturnUrl: "adyencheckout://your.package.name", BrowserInfo: &browserInfo, ShopperReference: common.PtrString("YOUR_UNIQUE_SHOPPER_ID"), } // Send the request service := client.Checkout() req := service.PaymentsApi.PaymentsInput().IdempotencyKey("UUID").PaymentRequest(paymentRequest) res, httpRes, err := service.PaymentsApi.Payments(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.2.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_API_KEY" # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "amount": { "currency": "EUR", "value": 1000 }, "reference": "YOUR_ORDER_NUMBER", "shopperReference": "YOUR_UNIQUE_SHOPPER_ID", "paymentMethod": "STATE_DATA", "authenticationData": { "threeDSRequestData": { "nativeThreeDS": "preferred" } }, "billingAddress": { "street": "Infinite Loop", "houseNumberOrName": "1", "postalCode": "1011DJ", "city": "Amsterdam", "country": "NL" }, "browserInfo": { "userAgent": "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36", "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8" }, "shopperEmail": "s.hopper@example.com", "channel": "Android", "returnUrl": "adyencheckout://your.package.name", "merchantAccount": "YOUR_MERCHANT_ACCOUNT" } # Send the request result = adyen.checkout.payments_api.payments(request=json_request, idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_API_KEY' # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :amount => { :currency => 'EUR', :value => 1000 }, :reference => 'YOUR_ORDER_NUMBER', :shopperReference => 'YOUR_UNIQUE_SHOPPER_ID', :paymentMethod => 'STATE_DATA', :authenticationData => { :threeDSRequestData => { :nativeThreeDS => 'preferred' } }, :billingAddress => { :street => 'Infinite Loop', :houseNumberOrName => '1', :postalCode => '1011DJ', :city => 'Amsterdam', :country => 'NL' }, :browserInfo => { :userAgent => 'Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36', :acceptHeader => 'text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8' }, :shopperEmail => 's.hopper@example.com', :channel => 'Android', :returnUrl => 'adyencheckout://your.package.name', :merchantAccount => 'YOUR_MERCHANT_ACCOUNT' } # Send the request result = adyen.checkout.payments_api.payments(request_body, headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.0.0 // Require the parts of the module you want to use import { Client, CheckoutAPI, Types } from "@adyen/api-library"; // For the LIVE environment, also include your liveEndpointUrlPrefix. const client = new Client({ apiKey: "ADYEN_API_KEY", environment: "TEST" }); // Create the request object(s) const threeDSRequestData: Types.checkout.ThreeDSRequestData = { nativeThreeDS: Types.checkout.ThreeDSRequestData.NativeThreeDSEnum.Preferred }; const authenticationData: Types.checkout.AuthenticationData = { threeDSRequestData: threeDSRequestData }; const amount: Types.checkout.Amount = { currency: "EUR", value: 1000 }; const billingAddress: Types.checkout.BillingAddress = { country: "NL", city: "Amsterdam", street: "Infinite Loop", houseNumberOrName: "1", postalCode: "1011DJ" }; const browserInfo: Types.checkout.BrowserInfo = { acceptHeader: "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8", userAgent: "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36" }; const paymentRequest: Types.checkout.PaymentRequest = { reference: "YOUR_ORDER_NUMBER", authenticationData: authenticationData, amount: amount, merchantAccount: "YOUR_MERCHANT_ACCOUNT", channel: Types.checkout.PaymentRequest.ChannelEnum.Android, shopperEmail: "s.hopper@example.com", billingAddress: billingAddress, returnUrl: "adyencheckout://your.package.name", browserInfo: browserInfo, shopperReference: "YOUR_UNIQUE_SHOPPER_ID" }; // Send the request const checkoutAPI = new CheckoutAPI(client); const response = checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" }); ``` 2. In the response, check if there is an `action` object. ### Tab: Checkout API v67 and later Your next steps depend on whether the response contains an `action` object, and on the `action.type`. | `action.type` | Description | Next steps | | ------------------ | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | No `action` object | The transaction was either exempted or out-of-scope for 3D Secure 2 authentication. | 1. Return `DropInServiceResult.Finished`, and the `resultCode` from the `/payments` response. 2. Use the `resultCode` to [present the payment result to your shopper](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#present-the-payment-result). | | **threeDS2** | The payment qualifies for 3D Secure 2, and will go through the authentication flow. | 1. Return `DropInServiceResult.Action` and the `action` object. 2. [Submit authentication results](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#submit-authentication-results). | | **redirect** | The payment is routed to the 3D Secure 2 redirect flow. | 1. [Return `DropInServiceResult.Action`](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow?platform=Android\&integration=Drop-in#send-additional-payment-details) and the `action` object. 2. [Check the payment result](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow/?platform=Android\&integration=Drop-in#send-additional-payment-details). | The following example shows a [/payments](https://docs.adyen.com/api-explorer/Checkout/67/post/payments) response with `action.type`: **threeDS2**. **/payments response with action** ```json { "action":{ "type":"threeDS2", "subtype": "fingerprint", "paymentData":"Ab02b4c0!BQABAgCuZFJrQOjSsl\/zt+...", "paymentMethodType":"scheme", "authorisationToken" : "Ab02b4c0!BQABAgAvrX03p...", "token":"eyJ0aHJlZURTTWV0aG9kTm90aWZpY..." }, "resultCode":"IdentifyShopper", ... } ``` ### Tab: Checkout API v66 and earlier Your next steps depend on whether the response contains an `action` object, and on the `action.type`. | `action.type` | Description | Next steps | | ----------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | No `action` object | The transaction was either exempted or out-of-scope for 3D Secure 2 authentication. | 1. Return `DropInServiceResult.Finished`, and the `resultCode` from the `/payments` response. 2. Use the `resultCode` to [present the payment result to your shopper](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#present-the-payment-result). | | **threeDS2Fingerprint** | The payment qualifies for 3D Secure 2, and will go through either the frictionless or the challenge flow. | 1. Store the `action.paymentData` on your server - you'll need this when making a [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) request later. 2. Return `DropInServiceResult.Action` and the `action` object. 3. [Submit authentication results](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#submit-authentication-results). | | **redirect** | The payment is routed to the 3D Secure 2 redirect flow. | 1. Store the `action.paymentData` on your server - you'll need this when making a [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) request later. 2. [Return `DropInServiceResult.Action`](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow?platform=Android\&integration=Drop-in#send-additional-payment-details) and the `action` object. 3. [Check the payment result](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow/?platform=Android\&integration=Drop-in#send-additional-payment-details). | The following example shows a [/payments](https://docs.adyen.com/api-explorer/Checkout/66/post/payments) response with `action.type`: **threeDS2Fingerprint**. **/payments response with action** ```json { "action":{ "paymentData":"Ab02b4c0!BQABAgCuZFJrQOjSsl\/zt+...", "paymentMethodType":"scheme", "token":"eyJ0aHJlZURTTWV0aG9kTm90aWZpY...", "type":"threeDS2Fingerprint" }, "authentication":{ "threeds2.fingerprintToken":"eyJ0aHJlZURTTWV0aG9kTm90aWZpY..." }, "resultCode":"IdentifyShopper", ... } ``` ### Submit Additional Details ## Submit additional 3D Secure 2 authentication details When you [send additional details](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow?platform=Android\&integration=Drop-in\&version=5.0.0#send-additional-payment-details), send the 3D Secure 2 authentication data from your server: 1. Drop-in calls the `onAdditionalDetails` method in your `DropInService` class passing, the `actionComponentJson` object. Pass the object to your backend server. 2. From your server, make a **POST** [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) request, including `actionComponentJson` object: #### curl ```bash curl https://checkout-test.adyen.com/v72/payments/details \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{hint:object passed from the front end or client app}STATE_DATA{/hint}' ``` #### Java ```java // Set your X-API-KEY with the API key from the Customer Area. String xApiKey = "ADYEN_API_KEY"; Client client = new Client(xApiKey,Environment.TEST); Checkout checkout = new Checkout(client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. PaymentsDetailsRequest paymentsDetailsRequest = STATE_DATA; PaymentsResponse paymentsDetailsResponse = checkout.paymentsDetails(paymentsDetailsRequest); ``` #### PHP ```php // Set your X-API-KEY with the API key from the Customer Area. $client = new \Adyen\Client(); $client->setEnvironment(\Adyen\Environment::TEST); $client->setXApiKey("ADYEN_API_KEY"); $service = new \Adyen\Service\Checkout($client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. $params = STATE_DATA; $result = $service->paymentsDetails($params); // Check if further action is needed if (array_key_exists("action", $result)){ // Pass the action object to your frontend. // $result["action"] } else { // No further action needed, pass the resultCode to your front end // $result['resultCode'] } ``` #### C\# ```cs // Set your X-API-KEY with the API key from the Customer Area. string apiKey = "ADYEN_API_KEY"; var client = new Client (apiKey, Environment.Test); var checkout = new Checkout(client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. var paymentsDetailsRequest = STATE_DATA; var paymentsDetailsResponse = checkout.PaymentDetails(paymentsDetailsRequest); ``` #### NodeJS (JavaScript) ```js const {Client, Config, CheckoutAPI} = require('@adyen/api-library'); const config = new Config(); // Set your X-API-KEY with the API key from the Customer Area. config.apiKey = '[ADYEN_API_KEY]'; const client = new Client({ config }); client.setEnvironment("TEST"); const checkout = new CheckoutAPI(client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. checkout.paymentsDetails(STATE_DATA).then(res => res); ``` #### Go ```go import ( "github.com/adyen/adyen-go-api-library/v5/src/checkout" "github.com/adyen/adyen-go-api-library/v5/src/common" "github.com/adyen/adyen-go-api-library/v5/src/adyen" ) // Set your X-API-KEY with the API key from the Customer Area. client := adyen.NewClient(&common.Config{ Environment: common.TestEnv, ApiKey: "[ADYEN_API_KEY]", }) // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. req := STATE_DATA; res, httpRes, err := client.Checkout.PaymentsDetails(&req) ``` #### Python ```py # Set your X-API-KEY with the API key from the Customer Area. adyen = Adyen.Adyen() adyen.payment.client.platform = "test" adyen.client.xapikey = 'ADYEN_API_KEY' # STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. request = STATE_DATA result = adyen.checkout.payments_details(request) # Check if further action is needed. if 'action' in result.message: # Pass the action object to your front end # result.message['action'] else: # No further action needed, pass the resultCode to your front end # result.message['resultCode'] ``` #### Ruby ```ruby require 'adyen-ruby-api-library' # Set your X-API-KEY with the API key from the Customer Area. adyen = Adyen::Client.new adyen.env = :test adyen.api_key = "ADYEN_API_KEY" # STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. request = STATE_DATA response = adyen.checkout.payments.details(request) # Check if further action is needed. if response.body.has_key(:action) # Pass the action object to your frontend puts response.body[:action] else # No further action needed, pass the resultCode to your frontend puts response.body[:resultCode] end ``` 3. Pass the [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) response from your server to your client-side app. Continue and complete your payment flow. ### Present Result ## Present the payment result Use the  [resultCode](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#responses-200-resultCode) from the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) or [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) response to present the payment result to your shopper. You will also receive the outcome of the payment asynchronously in a [webhook](https://docs.adyen.com/development-resources/webhooks). For card payments, you can receive the following `resultCode` values: | resultCode | Description | Action to take | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Authorised** | The payment was successful. | Inform the shopper that the payment has been successful. If you are using [manual capture](https://docs.adyen.com/online-payments/capture#manual-capture), you also need to [capture](https://docs.adyen.com/online-payments/capture) the payment. | | **Cancelled** | The shopper cancelled the payment. | Ask the shopper if they want to continue with the order, or ask them to select a different payment method. | | **Error** | There was an error when the payment was being processed. For more information, check the [`refusalReason` ](https://docs.adyen.com/development-resources/refusal-reasons)field. | Inform the shopper that there was an error processing their payment. | | **Refused** | The payment was refused. For more information, check the [`refusalReason` ](https://docs.adyen.com/development-resources/refusal-reasons)field. | Ask the shopper to try the payment again using a different payment method. | ### Handling Android App Link ## Handle your Android App Link If you have configured the `setThreeDSRequestorAppURL` when you [configured Drop-in](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#optional-configuration), you have to [handle this Android App link](https://developer.android.com/training/app-links). 1. Add the following to your `AndroidManifest.xml`, specifying your Android App Link as your `android:host`: **Copy to your app Manifest file** ```xml ``` 2. [Verify the App Link](https://developer.android.com/training/app-links/verify-android-applinks). ### Testing ## Test and go live Use our test card numbers to [test how your integration handles different 3D Secure authentication scenarios](https://docs.adyen.com/development-resources/testing/3d-secure-2-authentication). When you are ready to [go live](https://docs.adyen.com/get-started-with-adyen/#apply-for-your-live-account), follow our [go-live checklist](https://docs.adyen.com/online-payments/go-live-checklist/). When using our [live endpoints](https://docs.adyen.com/development-resources/live-endpoints/), make sure that all API requests you make for the same payment session use the same live endpoint region. Using different regions for [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) and [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) requests may result in errors when authenticating with 3D Secure. ### Live environment values | Endpoint region | Value | | ------------------------- | ------------------ | | Europe (EU) live | **EUROPE** | | United States (US) live | **UNITED\_STATES** | | Australia (AU) live | **AUSTRALIA** | | Northeast Asia (NEA) live | **NEA** | | India (IN) live | **INDIA** | ### Troubleshooting If native 3D Secure 2 is not triggered, check the following: * `channel` is set to **Android**. * You have set 3D Secure 2 preferences to trigger native flow: * For Checkout API v69 or later: `authenticationData.threeDSRequestData.nativeThreeDS` is set to **preferred**. * For Checkout API v68 or earlier: `additionalData.allow3DS2` is set to **true**. ## See also * [Android Drop-in integration guide](https://docs.adyen.com/online-payments/build-your-integration/sessions-flow/?platform=Android\&integration=Drop-in) * [3D Secure 2 API Reference](https://docs.adyen.com/online-payments/3d-secure/api-reference) * [Webhooks](https://docs.adyen.com/development-resources/webhooks) * [Payment methods](https://docs.adyen.com/payment-methods) ## Android Components Use the Component to support native 3D Secure 2 with your Android app ### Requirements This page explains how to implement native 3D Secure 2 authentication with your existing Android Components integration. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | Make sure you have an [Advanced flow Android Components integration](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow/?platform=Android\&integration=Components) with the [Card Component](https://docs.adyen.com/payment-methods/cards/web-component). If you use the [Sessions flow](https://docs.adyen.com/online-payments/build-your-integration#sessions-flow-a-single-api-request), no additional configuration is needed to support 3D Secure 2. | | **[Webhooks](https://docs.adyen.com/development-resources/webhooks)** | Subscribe to Standard webhooks. | | **Setup steps** | Before you begin:- [Add the card payment methods that you want to accept in your test Customer Area](https://docs.adyen.com/payment-methods/add-payment-methods). - Make sure that your back end can [handle redirects](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow?platform=Android\&integration=Components\&version=latest#additional-action) for cases where the payment is routed to the [Redirect 3D Secure 2 flow](https://docs.adyen.com/online-payments/3d-secure/redirect-3ds2/android-component). | ## How it works Our 3D Secure 2 Component handles the 3D Secure 2 device fingerprinting and challenge flows, including the data exchange between your front end and the issuer's Access Control Server (ACS). When adding native 3D Secure 2 authentication to your integration: 1. [Collect the cardholder name in your payment form](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#collect-additional-parameters). 2. Provide additional parameters [when making a payment request](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#make-a-payment). 3. [Use the Action Component to perform the authentication flow](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#use-the-action-component). 4. If the payment was routed to the 3D Secure 2 redirect flow, [handle the redirect](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#handle-a-redirect). ### Collect Additional Parameters ## Collect additional information at checkout For higher authentication rates, we strongly recommend that you collect the cardholder name in your payment form. To collect the cardholder name using our [Card Component](https://docs.adyen.com/payment-methods/cards/android-component), specify the following when adding the Card Component: * `setHolderNameRequired(true)` ```kotlin val checkoutConfiguration = CheckoutConfiguration( environment = environment, clientKey = clientKey, ) { card { setHolderNameRequired(true) } } ``` We also recommend that you collect the shopper's billing address and email address in advance in your payment form. Deliver these parameters to your backend when [making a payment](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#make-a-payment) as it is required by the card schemes. ## Make a payment 1. When you [make a payment request](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow?platform=Android\&integration=Components\&version=latest#make-a-payment), include the following additional 3D Secure 2 parameters. See additional 3D Secure 2 parameters that we recommend to include in your request to increase authentication performance in our [API reference](https://docs.adyen.com/online-payments/3d-secure/api-reference). | Parameter name | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [paymentMethod](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The complete `paymentComponentState.data.paymentMethod` object from your client app. It includes the type and required details for a card payment method. | | [paymentMethod.sdkData](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-listOfValues-sdkData) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The object that includes the following information collected by the Component:- Information required for 3D Secure 2 authentication. - The [checkout attempt identifier](https://docs.adyen.com/online-payments/analytics-and-data-tracking#data-we-are-collecting) to track the user's payment journey. This is required to use the [Checkout dashboard](https://docs.adyen.com/uplift#uplift-dashboards) that lets you analyze your checkout performance. | | [paymentMethod.holderName](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-CardDetails-holderName) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions. The cardholder's name. | | [authenticationData.threeDSRequestData.nativeThreeDS](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-authenticationData-threeDSRequestData-nativeThreeDS) **Checkout API v69 or later** | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | Set to **preferred**. Indicates if your payment page can handle native 3D Secure 2 authentication. For **Checkout API v68 or earlier**: use `additionalData.allow3DS2` instead. | | [channel](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-channel) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The platform where the transaction takes place. Set to **Android**. | | [returnUrl](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-returnUrl) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | Used to redirect the shopper back to a webpage for redirect and other payment flows. We strongly recommend to redirect the shopper to your app by [configuring a `threeDSRequestorAppURL`](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#use-the-action-component), because this improves conversion. | | [shopperEmail](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperEmail) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions. The cardholder's email address. If you do not include this, you must send the `telephoneNumber`, or a phone number in the `threeDS2RequestData` object. | | [shopperIP](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperIP) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case** required for Visa and JCB transactions to support cases where the transaction is routed to the redirect flow. The shopper's IP address. | | [telephoneNumber](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-telephoneNumber) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.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. | | [browserInfo](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-browserInfo) | | The shopper's browser information. We recommend to include it in your requests to handle cases where authentication is routed to [the redirect flow](https://docs.adyen.com/online-payments/3d-secure/redirect-3ds2/). | ![This is the required icon.](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) Required for all transactions.\ ![This is the conditionally required icon.](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) Required for particular setups, or issuers and card schemes.\ ![This is the recommended icon.](https://docs.adyen.com/media/51cfe94e37a7426974002173390b3c7807ac234e65206fe14ed9fbdd45fb958e.svg?decoding=auto\&fetchpriority=auto) Recommended for all transactions, but not required. Below is an example [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request. **Make a /payments request including 3D Secure 2 fields** #### curl ```bash curl https://checkout-test.adyen.com/v72/payments \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "amount":{ "currency":"EUR", "value":1000 }, "reference":"YOUR_ORDER_NUMBER", "shopperReference":"YOUR_UNIQUE_SHOPPER_ID", "paymentMethod": {hint:paymentMethod field of an object passed from the client app. Return the fields as they are, sdkVersion is required to trigger native.}STATE_DATA{/hint}, "authenticationData": { "threeDSRequestData": { "nativeThreeDS": "preferred" } }, "{hint:state.data.billingAddress from onSubmit}billingAddress{/hint}": { "street": "Infinite Loop", "houseNumberOrName": "1", "postalCode": "1011DJ", "city": "Amsterdam", "country": "NL" }, "{hint:Required for 3D Secure 1}browserInfo{/hint}: { "userAgent":"Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36", "acceptHeader":"text\/html,application\/xhtml+xml,application\/xml;q=0.9,image\/webp,image\/apng,*\/*;q=0.8" }, "shopperEmail":"s.hopper@example.com", "channel":"Android", "returnUrl":"adyencheckout://your.package.name", "merchantAccount":"YOUR_MERCHANT_ACCOUNT" }' ``` #### Java ```java // Adyen Java API Library v32.1.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.checkout.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.model.RequestOptions; import com.adyen.service.checkout.*; // For the LIVE environment, also include your liveEndpointUrlPrefix. Client client = new Client("ADYEN_API_KEY", Environment.TEST); // Create the request object(s) ThreeDSRequestData threeDSRequestData = new ThreeDSRequestData() .nativeThreeDS(ThreeDSRequestData.NativeThreeDSEnum.PREFERRED); AuthenticationData authenticationData = new AuthenticationData() .threeDSRequestData(threeDSRequestData); Amount amount = new Amount() .currency("EUR") .value(1000L); BillingAddress billingAddress = new BillingAddress() .country("NL") .city("Amsterdam") .street("Infinite Loop") .houseNumberOrName("1") .postalCode("1011DJ"); BrowserInfo browserInfo = new BrowserInfo() .acceptHeader("text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8") .userAgent("Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36"); PaymentRequest paymentRequest = new PaymentRequest() .reference("YOUR_ORDER_NUMBER") .authenticationData(authenticationData) .amount(amount) .merchantAccount("YOUR_MERCHANT_ACCOUNT") .channel(PaymentRequest.ChannelEnum.ANDROID) .shopperEmail("s.hopper@example.com") .billingAddress(billingAddress) .returnUrl("adyencheckout://your.package.name") .browserInfo(browserInfo) .shopperReference("YOUR_UNIQUE_SHOPPER_ID"); // Send the request PaymentsApi service = new PaymentsApi(client); PaymentResponse response = service.payments(paymentRequest, new RequestOptions().idempotencyKey("UUID")); ``` #### PHP ```php setXApiKey("ADYEN_API_KEY"); // For the LIVE environment, also include your liveEndpointUrlPrefix. $client->setEnvironment(Environment::TEST); // Create the request object(s) $threeDSRequestData = new ThreeDSRequestData(); $threeDSRequestData ->setNativeThreeDS("preferred"); $authenticationData = new AuthenticationData(); $authenticationData ->setThreeDSRequestData($threeDSRequestData); $amount = new Amount(); $amount ->setCurrency("EUR") ->setValue(1000); $billingAddress = new BillingAddress(); $billingAddress ->setCountry("NL") ->setCity("Amsterdam") ->setStreet("Infinite Loop") ->setHouseNumberOrName("1") ->setPostalCode("1011DJ"); $browserInfo = new BrowserInfo(); $browserInfo ->setAcceptHeader("text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8") ->setUserAgent("Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36"); $paymentRequest = new PaymentRequest(); $paymentRequest ->setReference("YOUR_ORDER_NUMBER") ->setAuthenticationData($authenticationData) ->setAmount($amount) ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT") ->setChannel("Android") ->setShopperEmail("s.hopper@example.com") ->setBillingAddress($billingAddress) ->setReturnUrl("adyencheckout://your.package.name") ->setBrowserInfo($browserInfo) ->setShopperReference("YOUR_UNIQUE_SHOPPER_ID"); $requestOptions['idempotencyKey'] = 'UUID'; // Send the request $service = new PaymentsApi($client); $response = $service->payments($paymentRequest, $requestOptions); ``` #### C\# ```cs // Adyen .net API Library v26.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Checkout; using Adyen.Service.Checkout; // For the LIVE environment, also include your liveEndpointUrlPrefix. var config = new Config() { XApiKey = "ADYEN_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) ThreeDSRequestData threeDSRequestData = new ThreeDSRequestData { NativeThreeDS = ThreeDSRequestData.NativeThreeDSEnum.Preferred }; AuthenticationData authenticationData = new AuthenticationData { ThreeDSRequestData = threeDSRequestData }; Amount amount = new Amount { Currency = "EUR", Value = 1000 }; BillingAddress billingAddress = new BillingAddress { Country = "NL", City = "Amsterdam", Street = "Infinite Loop", HouseNumberOrName = "1", PostalCode = "1011DJ" }; BrowserInfo browserInfo = new BrowserInfo { AcceptHeader = "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8", UserAgent = "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36" }; PaymentRequest paymentRequest = new PaymentRequest { Reference = "YOUR_ORDER_NUMBER", AuthenticationData = authenticationData, Amount = amount, MerchantAccount = "YOUR_MERCHANT_ACCOUNT", Channel = PaymentRequest.ChannelEnum.Android, ShopperEmail = "s.hopper@example.com", BillingAddress = billingAddress, ReturnUrl = "adyencheckout://your.package.name", BrowserInfo = browserInfo, ShopperReference = "YOUR_UNIQUE_SHOPPER_ID" }; // Send the request var service = new PaymentsService(client); var response = service.Payments(paymentRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"}); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.0.0 // Require the parts of the module you want to use const { Client, CheckoutAPI } = require('@adyen/api-library'); // For the LIVE environment, also include your liveEndpointUrlPrefix. const client = new Client({ apiKey: "ADYEN_API_KEY", environment: "TEST" }); // Create the request object(s) const paymentRequest = { amount: { currency: "EUR", value: 1000 }, reference: "YOUR_ORDER_NUMBER", shopperReference: "YOUR_UNIQUE_SHOPPER_ID", paymentMethod: "STATE_DATA", authenticationData: { threeDSRequestData: { nativeThreeDS: "preferred" } }, billingAddress: { street: "Infinite Loop", houseNumberOrName: "1", postalCode: "1011DJ", city: "Amsterdam", country: "NL" }, browserInfo: { userAgent: "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36", acceptHeader: "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8" }, shopperEmail: "s.hopper@example.com", channel: "Android", returnUrl: "adyencheckout://your.package.name", merchantAccount: "YOUR_MERCHANT_ACCOUNT" } // Send the request const checkoutAPI = new CheckoutAPI(client); const response = checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" }); ``` #### Go ```go // Adyen Go API Library v16.1.0 import ( "context" "github.com/adyen/adyen-go-api-library/v9/src/common" "github.com/adyen/adyen-go-api-library/v9/src/adyen" "github.com/adyen/adyen-go-api-library/v9/src/checkout" ) // For the LIVE environment, also include your liveEndpointUrlPrefix. client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) threeDSRequestData := checkout.ThreeDSRequestData{ NativeThreeDS: common.PtrString("preferred"), } authenticationData := checkout.AuthenticationData{ ThreeDSRequestData: &threeDSRequestData, } amount := checkout.Amount{ Currency: "EUR", Value: 1000, } billingAddress := checkout.BillingAddress{ Country: "NL", City: "Amsterdam", Street: "Infinite Loop", HouseNumberOrName: "1", PostalCode: "1011DJ", } browserInfo := checkout.BrowserInfo{ AcceptHeader: "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8", UserAgent: "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36", } paymentRequest := checkout.PaymentRequest{ Reference: "YOUR_ORDER_NUMBER", AuthenticationData: &authenticationData, Amount: amount, MerchantAccount: "YOUR_MERCHANT_ACCOUNT", Channel: common.PtrString("Android"), ShopperEmail: common.PtrString("s.hopper@example.com"), BillingAddress: &billingAddress, ReturnUrl: "adyencheckout://your.package.name", BrowserInfo: &browserInfo, ShopperReference: common.PtrString("YOUR_UNIQUE_SHOPPER_ID"), } // Send the request service := client.Checkout() req := service.PaymentsApi.PaymentsInput().IdempotencyKey("UUID").PaymentRequest(paymentRequest) res, httpRes, err := service.PaymentsApi.Payments(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.2.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_API_KEY" # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "amount": { "currency": "EUR", "value": 1000 }, "reference": "YOUR_ORDER_NUMBER", "shopperReference": "YOUR_UNIQUE_SHOPPER_ID", "paymentMethod": "STATE_DATA", "authenticationData": { "threeDSRequestData": { "nativeThreeDS": "preferred" } }, "billingAddress": { "street": "Infinite Loop", "houseNumberOrName": "1", "postalCode": "1011DJ", "city": "Amsterdam", "country": "NL" }, "browserInfo": { "userAgent": "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36", "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8" }, "shopperEmail": "s.hopper@example.com", "channel": "Android", "returnUrl": "adyencheckout://your.package.name", "merchantAccount": "YOUR_MERCHANT_ACCOUNT" } # Send the request result = adyen.checkout.payments_api.payments(request=json_request, idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_API_KEY' # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :amount => { :currency => 'EUR', :value => 1000 }, :reference => 'YOUR_ORDER_NUMBER', :shopperReference => 'YOUR_UNIQUE_SHOPPER_ID', :paymentMethod => 'STATE_DATA', :authenticationData => { :threeDSRequestData => { :nativeThreeDS => 'preferred' } }, :billingAddress => { :street => 'Infinite Loop', :houseNumberOrName => '1', :postalCode => '1011DJ', :city => 'Amsterdam', :country => 'NL' }, :browserInfo => { :userAgent => 'Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36', :acceptHeader => 'text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8' }, :shopperEmail => 's.hopper@example.com', :channel => 'Android', :returnUrl => 'adyencheckout://your.package.name', :merchantAccount => 'YOUR_MERCHANT_ACCOUNT' } # Send the request result = adyen.checkout.payments_api.payments(request_body, headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.0.0 // Require the parts of the module you want to use import { Client, CheckoutAPI, Types } from "@adyen/api-library"; // For the LIVE environment, also include your liveEndpointUrlPrefix. const client = new Client({ apiKey: "ADYEN_API_KEY", environment: "TEST" }); // Create the request object(s) const threeDSRequestData: Types.checkout.ThreeDSRequestData = { nativeThreeDS: Types.checkout.ThreeDSRequestData.NativeThreeDSEnum.Preferred }; const authenticationData: Types.checkout.AuthenticationData = { threeDSRequestData: threeDSRequestData }; const amount: Types.checkout.Amount = { currency: "EUR", value: 1000 }; const billingAddress: Types.checkout.BillingAddress = { country: "NL", city: "Amsterdam", street: "Infinite Loop", houseNumberOrName: "1", postalCode: "1011DJ" }; const browserInfo: Types.checkout.BrowserInfo = { acceptHeader: "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8", userAgent: "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36" }; const paymentRequest: Types.checkout.PaymentRequest = { reference: "YOUR_ORDER_NUMBER", authenticationData: authenticationData, amount: amount, merchantAccount: "YOUR_MERCHANT_ACCOUNT", channel: Types.checkout.PaymentRequest.ChannelEnum.Android, shopperEmail: "s.hopper@example.com", billingAddress: billingAddress, returnUrl: "adyencheckout://your.package.name", browserInfo: browserInfo, shopperReference: "YOUR_UNIQUE_SHOPPER_ID" }; // Send the request const checkoutAPI = new CheckoutAPI(client); const response = checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" }); ``` 2. In the response, check if there is an `action` object. ### Tab: Checkout API v67 and later Your next steps depend on whether the response contains an `action` object, and on the `action.type`. | `action.type` | Description | Next steps | | ------------------ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | No `action` object | The transaction was either exempted or out-of-scope for 3D Secure 2 authentication. | Use the `resultCode` to [present the payment result to your shopper](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#present-the-payment-result). | | **threeDS2** | The payment qualifies for 3D Secure 2, and will go through the authentication flow. | 1. Pass the `action` object to your client app to perform the authentication flow. 2. [Submit the challenge result](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#action-component). | | **redirect** | The payment is routed to the 3D Secure 2 redirect flow. | 1. Pass the `action` object to your client app 2. [Handle the redirect result](https://docs.adyen.com/online-payments/build-your-integration/sessions-flow/?platform=iOS\&integration=Drop-in#handle-the-redirect). | The following example shows a [/payments](https://docs.adyen.com/api-explorer/Checkout/67/post/payments) response with `action.type`: **threeDS2**. **/payments response with action** ```json { "action":{ "type":"threeDS2", "subtype": "fingerprint", "paymentData":"Ab02b4c0!BQABAgCuZFJrQOjSsl\/zt+...", "paymentMethodType":"scheme", "authorisationToken" : "Ab02b4c0!BQABAgAvrX03p...", "token":"eyJ0aHJlZURTTWV0aG9kTm90aWZpY..." }, "resultCode":"IdentifyShopper", ... } ``` ### Tab: Checkout API v66 and earlier Your next steps depend on whether the response contains an `action` object, and on the `action.type`. | `action.type` | Description | Next steps | | ----------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | No `action` object | The transaction was either exempted or out-of-scope for 3D Secure 2 authentication. | Use the `resultCode` to [present the payment result to your shopper](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#present-the-payment-result). | | **threeDS2Fingerprint** | The payment qualifies for 3D Secure 2, and will go through either the frictionless or the challenge flow. | 1. Pass the `action` object to your client app. 2. [Submit the device fingerprinting result.](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#action-component) | | **threeDS2Challenge** | The payment qualifies for 3D Secure 2, and the issuer is initiating a challenge flow. | 1. Pass the `action` object to your client app. 2. [Submit the challenge result](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#action-component). | | **redirect** | The payment is routed to the 3D Secure 2 redirect flow. | 1. Pass the `action` object to your client app 2. [Handle the redirect result](https://docs.adyen.com/online-payments/build-your-integration/sessions-flow/?platform=iOS\&integration=Drop-in#handle-the-redirect). | The following example shows a [/payments](https://docs.adyen.com/api-explorer/Checkout/66/post/payments) response with `action.type`: **threeDS2Fingerprint**. **/payments response with action** ```json { "action":{ "paymentData":"Ab02b4c0!BQABAgCuZFJrQOjSsl\/zt+...", "paymentMethodType":"scheme", "token":"eyJ0aHJlZURTTWV0aG9kTm90aWZpY...", "type":"threeDS2Fingerprint" }, "authentication":{ "threeds2.fingerprintToken":"eyJ0aHJlZURTTWV0aG9kTm90aWZpY..." }, "resultCode":"IdentifyShopper", ... } ``` ### Use The Component ## Use the Action Component 1. When you [import the library](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow?platform=Android\&integration=Components\&version=5.0.0#1-import-the-library), import the Action Component: **Import the Action Component** ```kotlin implementation "com.adyen.checkout:action:YOUR_VERSION" ``` 2. When you [configure the Component](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow/?platform=Android\&integration=Components\&version=latest#set-up), you can include the following functions: | Configuration function | Description | Parameter | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `setThreeDSRequestorAppURL` | Strongly recommended to improve conversion rates. Set this to an [Android App link](https://developer.android.com/training/app-links) to call your app after an out-of-band (OOB) authentication occurs. When set, your app must also [handle this Android App link](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#handling-your-android-app-link). We do not recommend to use custom links because they can be defined and used by other apps. This causes errors if two apps on the same device have the same custom link. | `threeDSRequestorAppURL`: *String*. Default: **null**. | | `setUiCustomization` | Customization for the 3D Secure 2 authentication UI. | A [`UiCustomization` ](https://adyen.github.io/adyen-android/3ds2/com.adyen.checkout.adyen3ds2/-adyen3-d-s2-configuration/-builder/set-ui-customization.html)object. | For example: **Configure 3D Secure 2** ```kotlin // Create a configuration object. val checkoutConfiguration = CheckoutConfiguration( environment = environment, clientKey = clientKey, ) { // Configure 3D Secure 2. adyen3DS2 { setThreeDSRequestorAppURL("https://your.app.com/adyen3ds2") // Strongly recommended. } } ``` 3. Add `AdyenComponentView` to your layout .xml file. For example: **Add the Component view** ```kotlin ``` 4. Create the Action Component by calling `PROVIDER.get` from your Component class: **Create the Action Component** ```kotlin val actionComponent = GenericActionComponent.PROVIDER.get( activity, // Your activity or fragment. checkoutConfiguration, componentCallback, ) ``` 5. Attach your Component to your activity or fragment. For example to attach your Component to your view with the identifier `adyenComponentView`: **Attach the Component to the activity** ```kotlin binding.adyenComponentView.attach(cardComponent, activity) // Your activity or fragment. ``` 6. When you get a response with an action, call `handleAction`: **Handle the action** ```kotlin actionComponent.handleAction(action, activity) ``` 7. The Component calls the `onAdditionalDetails` method in your `ComponentCallback` class and passes the `actionComponentJson` object. Pass the object to your backend server. **Implement methods for Action Component** ```kotlin // Handler to make a /payments/details request to send additional payment details. override fun onAdditionalDetails(actionComponentData: ActionComponentData) { val actionComponentJson = ActionComponentData.SERIALIZER.serialize(actionComponentData) // Your server makes a /payments/details request, including actionComponentJson. } // The Component encounters an error. override fun onError(componentError: ComponentError) { // Handle the error. } ``` 8. Pass the [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) response from your backend server to your frontend app. Continue and complete your payment flow. ### Handle Redirect ## Handle a redirect In some cases, your shopper is routed to perform 3D Secure redirect authentication instead. When this happens, handle the redirect: 1. Add an `IntentFilter` to the `Activity` that will handle the `returnUrl` specified in your [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request. **Handle the return URL** ```xml ``` The `android:host` value is your package name at build time. 2. Get the result of the redirect from the `Activity`. Pass the `intent` back to the Component. Depending on your activity's `launchMode`, you can get this intent in either `onCreate` or `onNewIntent`. **Get the result of the redirect** ```kotlin private fun handleIntent(intent: Intent?) { val data = intent?.data if (data != null && data.toString().startsWith(RedirectUtil.REDIRECT_RESULT_SCHEME)) { actionComponent.handleIntent(intent) } } ``` The `onAdditionalDetails` callback gets triggered. Continue and complete your payment flow. ### Present Result ## Present the payment result Use the  [resultCode](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#responses-200-resultCode) from the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) or [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) response to present the payment result to your shopper. You will also receive the outcome of the payment asynchronously in a [webhook](https://docs.adyen.com/development-resources/webhooks). For card payments, you can receive the following `resultCode` values: | resultCode | Description | Action to take | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Authorised** | The payment was successful. | Inform the shopper that the payment has been successful. If you are using [manual capture](https://docs.adyen.com/online-payments/capture#manual-capture), you also need to [capture](https://docs.adyen.com/online-payments/capture) the payment. | | **Cancelled** | The shopper cancelled the payment. | Ask the shopper if they want to continue with the order, or ask them to select a different payment method. | | **Error** | There was an error when the payment was being processed. For more information, check the [`refusalReason` ](https://docs.adyen.com/development-resources/refusal-reasons)field. | Inform the shopper that there was an error processing their payment. | | **Refused** | The payment was refused. For more information, check the [`refusalReason` ](https://docs.adyen.com/development-resources/refusal-reasons)field. | Ask the shopper to try the payment again using a different payment method. | ### Android App Link ## Handle your Android App Link If you have configured the `setThreeDSRequestorAppURL` when you [configured the Action Component](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#use-the-action-component), you have to [handle this Android App link](https://developer.android.com/training/app-links). 1. Add the following to your `AndroidManifest.xml`, specifying your Android App Link as your `android:host`: **Copy to your app Manifest file** ```xml ``` 2. [Verify the App Link](https://developer.android.com/training/app-links/verify-android-applinks). ### Customize ## Customize the UI for 3D Secure 2 The 3D Secure 2 Component inherits your app's theme to ensure the UI of the challenge flow fits your app's look and feel. You can override the default theme to inherit from one of AppCompat's theme variants. To do this, add the following XML snippet to your `styles.xml` file. ```xml ``` ### Testing ## Test and go live Use our test card numbers to [test how your integration handles different 3D Secure authentication scenarios](https://docs.adyen.com/development-resources/testing/3d-secure-2-authentication). When you are ready to [go live](https://docs.adyen.com/get-started-with-adyen/#apply-for-your-live-account), follow our [go-live checklist](https://docs.adyen.com/online-payments/go-live-checklist/). When using our [live endpoints](https://docs.adyen.com/development-resources/live-endpoints/), make sure that all API requests you make for the same payment session use the same live endpoint region. Using different regions for [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) and [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) requests may result in errors when authenticating with 3D Secure. ### Live environment values | Endpoint region | Value | | ------------------------- | ------------------ | | Europe (EU) live | **EUROPE** | | United States (US) live | **UNITED\_STATES** | | Australia (AU) live | **AUSTRALIA** | | Northeast Asia (NEA) live | **NEA** | | India (IN) live | **INDIA** | ### Troubleshooting If native 3D Secure 2 is not triggered, check the following: * `channel` is set to **Android**. * You have set 3D Secure 2 preferences to trigger native flow: * For Checkout API v69 or later: `authenticationData.threeDSRequestData.nativeThreeDS` is set to **preferred**. * For Checkout API v68 or earlier: `additionalData.allow3DS2` is set to **true**. ## See also * [Android Components integration guide](https://docs.adyen.com/online-payments/build-your-integration/sessions-flow?platform=Android\&integration=Components) * [3D Secure 2 API Reference](https://docs.adyen.com/online-payments/3d-secure/api-reference) * [Webhooks](https://docs.adyen.com/development-resources/webhooks) * [Payment methods](https://docs.adyen.com/payment-methods) ## Flutter Drop-in Use Drop-in to support native 3D Secure 2 with your Flutter app ## Requirements Before you begin, take into account the following requirements, preparations, and limitations. | Requirement | Description | | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | Make sure you have an [Advanced flow Flutter Drop-in integration](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow/?platform=Flutter\&integration=Drop-in) using Checkout API v71 or later. If you use the [Sessions flow](https://docs.adyen.com/online-payments/build-your-integration#sessions-flow-a-single-api-request), no additional configuration is needed to support 3D Secure 2. | | **[Webhooks](https://docs.adyen.com/development-resources/webhooks)** | Subscribe to the Standard webhooks. | | **Setup steps** | Before you begin:- [Add the card payment methods that you want to accept in your test Customer Area](https://docs.adyen.com/payment-methods/add-payment-methods). - Integrate with the Flutter [Drop-in](https://docs.adyen.com/payment-methods/cards/flutter-drop-in). | ## How it works To support 3D Secure 2 authentication with your integration: 1. [Add recommended configuration](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#configure) to collect additional information at checkout to include it when authenticating a payment. 2. [Make a payment request](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#make-a-payment), including additional shopper details. 3. In the payment response you receive, parse the JSON object included in the `action` object.\ The Flutter SDK [handles the action](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#handles-the-action). 4. Forward the action result in your [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) request. 5. [Show the payment result](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#show-the-payment-result). ### Additional Parameters ## Add configurations for 3D Secure authentication For higher authentication rates, we strongly recommend that you collect the cardholder name, the shopper billing address and email address in advance in your payment form. For some schemes, it is required to include this information when [making a payment](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#make-a-payment). To collect additional shopper information using our Flutter card component, include the following in your [Drop-in configuration](https://docs.adyen.com/payment-methods/cards/flutter-drop-in/#configuration): | Parameter | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `holderNameRequired` | Set to **true** to require the cardholder name. | | `addressMode` | Specify which address fields are required. Possible values: -**full**: require the full address. -**postalCode**: require the postal code. -**none**: address not required. | | | | **Card configuration** ```javascript final CardComponentConfiguration cardComponentConfiguration = CardComponentConfiguration( holderNameRequired: true, addressMode: full ); ``` ### Add the Requestor App Url Optionally, you can add the `ThreeDS2Configuration` object in your `DropInConfiguration`. Currently, this object supports configuring an app URL to call your app after an out-of-band (OOB) authentication occurs. We strongly recommend this to improve conversion rates. | Configuration field | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `requestorAppUrl` | Set the URL for your app to redirect shoppers back to your app after authentication. For **iOS**, set this to the [universal link](https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app) for your app. For **Android**, set this to an [Android App Link](https://developer.android.com/training/app-links). When set, you must also [handle this app link](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#handling-your-android-app-link). | #### Handle your Android App Link To handle Android App Links: 1. Add the following to your `AndroidManifest.xml`, specifying your Android App Link as your `android:host`: **Copy to your app Manifest file** ```xml ``` 2. [Verify the App Link](https://developer.android.com/training/app-links/verify-android-applinks). ### Payment ## Make a payment When the shopper selects the **Pay** button, your Drop-in integration invokes the [`onSubmit` ](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow?platform=Flutter\&integration=Drop-in\&version=1.6.0#launch-and-show)method. 1. In your POST [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request, include the following additional 3D Secure 2 parameters. See additional 3D Secure 2 parameters that we recommend to include in your request to increase authentication performance in our [API reference](https://docs.adyen.com/online-payments/3d-secure/api-reference). | Parameter name | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [paymentMethod](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The complete `paymentComponentData.paymentMethod` object from your client app. It includes the payment method details and other required information. | | [paymentMethod.sdkData](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-listOfValues-sdkData) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The object that includes the following information collected by Drop-in:- Information required for 3D Secure 2 authentication. - The [checkout attempt identifier](https://docs.adyen.com/online-payments/analytics-and-data-tracking#data-we-are-collecting) to track the user's payment journey. This is required to use the [Checkout dashboard](https://docs.adyen.com/uplift#uplift-dashboards) that lets you analyze your checkout performance. | | [paymentMethod.holderName](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-CardDetails-holderName) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions. The cardholder's name. | | [authenticationData.threeDSRequestData.nativeThreeDS](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-authenticationData-threeDSRequestData-nativeThreeDS) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | Indicates if your payment page can handle native 3D Secure 2 authentication. Set to **preferred**. | | [channel](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-channel) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The platform where the transaction takes place. Set to **Android**. | | [returnUrl](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-returnUrl) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The URL where the shopper should return to after a redirection. **iOS**: Use the [custom URL scheme](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app) for your app. You also need to:1) Add the return URL handler to your [AppDelegate](https://github.com/Adyen/adyen-flutter/blob/main/example/ios/Runner/AppDelegate.swift#L18) in your native iOS layer. 2) Configure the custom URL scheme in your [Info.plist file](https://github.com/Adyen/adyen-flutter/blob/main/example/ios/Runner/Info.plist). iOS example: `com.mydomain.adyencheckout://` **Android**: Use the combination of:- `adyencheckout://` scheme - Your package nameUse the `AdyenCheckout.instance.getReturnUrl()` method to get the value, or hardcode the string. Android example: `adyencheckout://com.adyen.adyen_checkout_example` **Format**: Maximum 1024 characters. The URL must not include personally identifiable information (PII), for example name or email address. | | [shopperEmail](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperEmail) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions. The cardholder's email address. If you do not include this, you must send the `telephoneNumber`, or a phone number in the `threeDS2RequestData` object. | | [shopperIP](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperIP) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions to support cases where the transaction is routed to the redirect flow. The shopper's IP address. | | [telephoneNumber](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-telephoneNumber) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.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. | | [browserInfo](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-browserInfo) | | The shopper's browser information. We recommend to include it in your requests to handle cases where authentication is routed to [the redirect flow](https://docs.adyen.com/online-payments/3d-secure/redirect-3ds2/). | ![This is the required icon.](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) Required for all transactions.\ ![This is the conditionally required icon.](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) Required for particular setups, or issuers and card schemes.\ ![This is the recommended icon.](https://docs.adyen.com/media/51cfe94e37a7426974002173390b3c7807ac234e65206fe14ed9fbdd45fb958e.svg?decoding=auto\&fetchpriority=auto) Recommended for all transactions, but not required. **Make a /payments request including 3D Secure 2 fields** #### curl ```bash curl https://checkout-test.adyen.com/v72/payments \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "amount":{ "currency":"EUR", "value":1000 }, "reference":"YOUR_ORDER_NUMBER", "shopperReference":"YOUR_UNIQUE_SHOPPER_ID", "paymentMethod": {hint:paymentMethod field of an object passed from the client app. Return the fields as they are, sdkVersion is required to trigger native.}STATE_DATA{/hint}, "authenticationData": { "threeDSRequestData": { "nativeThreeDS": "preferred" } }, "{hint:state.data.billingAddress from onSubmit}billingAddress{/hint}": { "street": "Infinite Loop", "houseNumberOrName": "1", "postalCode": "1011DJ", "city": "Amsterdam", "country": "NL" }, "{hint:Required for 3D Secure 1}browserInfo{/hint}: { "userAgent":"Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36", "acceptHeader":"text\/html,application\/xhtml+xml,application\/xml;q=0.9,image\/webp,image\/apng,*\/*;q=0.8" }, "shopperEmail":"s.hopper@example.com", "channel":"Android", "returnUrl":"adyencheckout://your.package.name", "merchantAccount":"YOUR_MERCHANT_ACCOUNT" }' ``` #### Java ```java // Adyen Java API Library v40.1.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.checkout.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.model.RequestOptions; import com.adyen.service.checkout.*; // For the LIVE environment, also include your liveEndpointUrlPrefix. Client client = new Client("ADYEN_API_KEY", Environment.TEST); // Create the request object(s) ThreeDSRequestData threeDSRequestData = new ThreeDSRequestData() .nativeThreeDS(ThreeDSRequestData.NativeThreeDSEnum.PREFERRED); AuthenticationData authenticationData = new AuthenticationData() .threeDSRequestData(threeDSRequestData); Amount amount = new Amount() .currency("EUR") .value(1000L); BillingAddress billingAddress = new BillingAddress() .country("NL") .city("Amsterdam") .street("Infinite Loop") .houseNumberOrName("1") .postalCode("1011DJ"); BrowserInfo browserInfo = new BrowserInfo() .acceptHeader("text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8") .userAgent("Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36"); PaymentRequest paymentRequest = new PaymentRequest() .reference("YOUR_ORDER_NUMBER") .authenticationData(authenticationData) .amount(amount) .merchantAccount("YOUR_MERCHANT_ACCOUNT") .channel(PaymentRequest.ChannelEnum.ANDROID) .shopperEmail("s.hopper@example.com") .billingAddress(billingAddress) .returnUrl("adyencheckout://your.package.name") .browserInfo(browserInfo) .shopperReference("YOUR_UNIQUE_SHOPPER_ID"); // Send the request PaymentsApi service = new PaymentsApi(client); PaymentResponse response = service.payments(paymentRequest, new RequestOptions().idempotencyKey("UUID")); ``` #### PHP ```php setXApiKey("ADYEN_API_KEY"); // For the LIVE environment, also include your liveEndpointUrlPrefix. $client->setEnvironment(Environment::TEST); // Create the request object(s) $threeDSRequestData = new ThreeDSRequestData(); $threeDSRequestData ->setNativeThreeDS("preferred"); $authenticationData = new AuthenticationData(); $authenticationData ->setThreeDSRequestData($threeDSRequestData); $amount = new Amount(); $amount ->setCurrency("EUR") ->setValue(1000); $billingAddress = new BillingAddress(); $billingAddress ->setCountry("NL") ->setCity("Amsterdam") ->setStreet("Infinite Loop") ->setHouseNumberOrName("1") ->setPostalCode("1011DJ"); $browserInfo = new BrowserInfo(); $browserInfo ->setAcceptHeader("text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8") ->setUserAgent("Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36"); $paymentRequest = new PaymentRequest(); $paymentRequest ->setReference("YOUR_ORDER_NUMBER") ->setAuthenticationData($authenticationData) ->setAmount($amount) ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT") ->setChannel("Android") ->setShopperEmail("s.hopper@example.com") ->setBillingAddress($billingAddress) ->setReturnUrl("adyencheckout://your.package.name") ->setBrowserInfo($browserInfo) ->setShopperReference("YOUR_UNIQUE_SHOPPER_ID"); $requestOptions['idempotencyKey'] = 'UUID'; // Send the request $service = new PaymentsApi($client); $response = $service->payments($paymentRequest, $requestOptions); ``` #### C\# ```cs // Adyen .NET API Library v32.2.1 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Checkout; using Adyen.Service.Checkout; // For the LIVE environment, also include your liveEndpointUrlPrefix. var config = new Config() { XApiKey = "ADYEN_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) ThreeDSRequestData threeDSRequestData = new ThreeDSRequestData { NativeThreeDS = ThreeDSRequestData.NativeThreeDSEnum.Preferred }; AuthenticationData authenticationData = new AuthenticationData { ThreeDSRequestData = threeDSRequestData }; Amount amount = new Amount { Currency = "EUR", Value = 1000 }; BillingAddress billingAddress = new BillingAddress { Country = "NL", City = "Amsterdam", Street = "Infinite Loop", HouseNumberOrName = "1", PostalCode = "1011DJ" }; BrowserInfo browserInfo = new BrowserInfo { AcceptHeader = "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8", UserAgent = "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36" }; PaymentRequest paymentRequest = new PaymentRequest { Reference = "YOUR_ORDER_NUMBER", AuthenticationData = authenticationData, Amount = amount, MerchantAccount = "YOUR_MERCHANT_ACCOUNT", Channel = PaymentRequest.ChannelEnum.Android, ShopperEmail = "s.hopper@example.com", BillingAddress = billingAddress, ReturnUrl = "adyencheckout://your.package.name", BrowserInfo = browserInfo, ShopperReference = "YOUR_UNIQUE_SHOPPER_ID" }; // Send the request var service = new PaymentsService(client); var response = service.Payments(paymentRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"}); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v30.0.1 const { Client, CheckoutAPI } = require('@adyen/api-library'); // For the LIVE environment, also include your liveEndpointUrlPrefix. const config = new Config({ apiKey: "ADYEN_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const paymentRequest = { amount: { currency: "EUR", value: 1000 }, reference: "YOUR_ORDER_NUMBER", shopperReference: "YOUR_UNIQUE_SHOPPER_ID", paymentMethod: "STATE_DATA", authenticationData: { threeDSRequestData: { nativeThreeDS: "preferred" } }, billingAddress: { street: "Infinite Loop", houseNumberOrName: "1", postalCode: "1011DJ", city: "Amsterdam", country: "NL" }, browserInfo: { userAgent: "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36", acceptHeader: "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8" }, shopperEmail: "s.hopper@example.com", channel: "Android", returnUrl: "adyencheckout://your.package.name", merchantAccount: "YOUR_MERCHANT_ACCOUNT" } // Send the request const checkoutAPI = new CheckoutAPI(client); const response = checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" }); ``` #### Go ```go // Adyen Go API Library v21.1.0 import ( "context" "github.com/adyen/adyen-go-api-library/v21/src/common" "github.com/adyen/adyen-go-api-library/v21/src/adyen" "github.com/adyen/adyen-go-api-library/v21/src/checkout" ) // For the LIVE environment, also include your liveEndpointUrlPrefix. client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) threeDSRequestData := checkout.ThreeDSRequestData{ NativeThreeDS: common.PtrString("preferred"), } authenticationData := checkout.AuthenticationData{ ThreeDSRequestData: &threeDSRequestData, } amount := checkout.Amount{ Currency: "EUR", Value: 1000, } billingAddress := checkout.BillingAddress{ Country: "NL", City: "Amsterdam", Street: "Infinite Loop", HouseNumberOrName: "1", PostalCode: "1011DJ", } browserInfo := checkout.BrowserInfo{ AcceptHeader: "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8", UserAgent: "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36", } paymentRequest := checkout.PaymentRequest{ Reference: "YOUR_ORDER_NUMBER", AuthenticationData: &authenticationData, Amount: amount, MerchantAccount: "YOUR_MERCHANT_ACCOUNT", Channel: common.PtrString("Android"), ShopperEmail: common.PtrString("s.hopper@example.com"), BillingAddress: &billingAddress, ReturnUrl: "adyencheckout://your.package.name", BrowserInfo: &browserInfo, ShopperReference: common.PtrString("YOUR_UNIQUE_SHOPPER_ID"), } // Send the request service := client.Checkout() req := service.PaymentsApi.PaymentsInput().IdempotencyKey("UUID").PaymentRequest(paymentRequest) res, httpRes, err := service.PaymentsApi.Payments(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v14.0.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_API_KEY" # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "amount": { "currency": "EUR", "value": 1000 }, "reference": "YOUR_ORDER_NUMBER", "shopperReference": "YOUR_UNIQUE_SHOPPER_ID", "paymentMethod": "STATE_DATA", "authenticationData": { "threeDSRequestData": { "nativeThreeDS": "preferred" } }, "billingAddress": { "street": "Infinite Loop", "houseNumberOrName": "1", "postalCode": "1011DJ", "city": "Amsterdam", "country": "NL" }, "browserInfo": { "userAgent": "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36", "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8" }, "shopperEmail": "s.hopper@example.com", "channel": "Android", "returnUrl": "adyencheckout://your.package.name", "merchantAccount": "YOUR_MERCHANT_ACCOUNT" } # Send the request result = adyen.checkout.payments_api.payments(request=json_request, idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v11.1.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_API_KEY' # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :amount => { :currency => 'EUR', :value => 1000 }, :reference => 'YOUR_ORDER_NUMBER', :shopperReference => 'YOUR_UNIQUE_SHOPPER_ID', :paymentMethod => 'STATE_DATA', :authenticationData => { :threeDSRequestData => { :nativeThreeDS => 'preferred' } }, :billingAddress => { :street => 'Infinite Loop', :houseNumberOrName => '1', :postalCode => '1011DJ', :city => 'Amsterdam', :country => 'NL' }, :browserInfo => { :userAgent => 'Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36', :acceptHeader => 'text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8' }, :shopperEmail => 's.hopper@example.com', :channel => 'Android', :returnUrl => 'adyencheckout://your.package.name', :merchantAccount => 'YOUR_MERCHANT_ACCOUNT' } # Send the request result = adyen.checkout.payments_api.payments(request_body, headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v30.0.1 import { Client, CheckoutAPI, Types } from "@adyen/api-library"; // For the LIVE environment, also include your liveEndpointUrlPrefix. const config = new Config({ apiKey: "ADYEN_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const threeDSRequestData: Types.checkout.ThreeDSRequestData = { nativeThreeDS: Types.checkout.ThreeDSRequestData.NativeThreeDSEnum.Preferred }; const authenticationData: Types.checkout.AuthenticationData = { threeDSRequestData: threeDSRequestData }; const amount: Types.checkout.Amount = { currency: "EUR", value: 1000 }; const billingAddress: Types.checkout.BillingAddress = { country: "NL", city: "Amsterdam", street: "Infinite Loop", houseNumberOrName: "1", postalCode: "1011DJ" }; const browserInfo: Types.checkout.BrowserInfo = { acceptHeader: "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8", userAgent: "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36" }; const paymentRequest: Types.checkout.PaymentRequest = { reference: "YOUR_ORDER_NUMBER", authenticationData: authenticationData, amount: amount, merchantAccount: "YOUR_MERCHANT_ACCOUNT", channel: Types.checkout.PaymentRequest.ChannelEnum.Android, shopperEmail: "s.hopper@example.com", billingAddress: billingAddress, returnUrl: "adyencheckout://your.package.name", browserInfo: browserInfo, shopperReference: "YOUR_UNIQUE_SHOPPER_ID" }; // Send the request const checkoutAPI = new CheckoutAPI(client); const response = checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" }); ``` 2. After you make the payment request, you receive an [API response](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow?target%2B_blankplatform=Flutter\&integration=Drop-in\&version=latest#id237754811) that includes an `action` object. This object informs you of the additional action that is required to complete the payment. 3. Your integration maps the response to the `Action` [`PaymentEvent` ](https://github.com/Adyen/adyen-flutter/blob/main/lib/src/common/model/payment_event.dart)object. ### Handle ## Forward the action result Drop-in automatically handles the authentication action. After the shopper completes authentication, Drop-in invokes the `onAdditionalDetails`, which provides the 3D Secure 2 authentication result. 1. In your [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) request, include the `data` object from the `onAdditionalDetails` callback. **Example request to send additional payment details** #### curl ```bash curl https://checkout-test.adyen.com/v72/payments/details \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{hint:object passed from the front end or client app}STATE_DATA{/hint}' ``` #### Java ```java // Set your X-API-KEY with the API key from the Customer Area. String xApiKey = "ADYEN_API_KEY"; Client client = new Client(xApiKey,Environment.TEST); Checkout checkout = new Checkout(client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. PaymentsDetailsRequest paymentsDetailsRequest = STATE_DATA; PaymentsResponse paymentsDetailsResponse = checkout.paymentsDetails(paymentsDetailsRequest); ``` #### PHP ```php // Set your X-API-KEY with the API key from the Customer Area. $client = new \Adyen\Client(); $client->setEnvironment(\Adyen\Environment::TEST); $client->setXApiKey("ADYEN_API_KEY"); $service = new \Adyen\Service\Checkout($client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. $params = STATE_DATA; $result = $service->paymentsDetails($params); // Check if further action is needed if (array_key_exists("action", $result)){ // Pass the action object to your frontend. // $result["action"] } else { // No further action needed, pass the resultCode to your front end // $result['resultCode'] } ``` #### C\# ```cs // Set your X-API-KEY with the API key from the Customer Area. string apiKey = "ADYEN_API_KEY"; var client = new Client (apiKey, Environment.Test); var checkout = new Checkout(client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. var paymentsDetailsRequest = STATE_DATA; var paymentsDetailsResponse = checkout.PaymentDetails(paymentsDetailsRequest); ``` #### NodeJS (JavaScript) ```js const {Client, Config, CheckoutAPI} = require('@adyen/api-library'); const config = new Config(); // Set your X-API-KEY with the API key from the Customer Area. config.apiKey = '[ADYEN_API_KEY]'; const client = new Client({ config }); client.setEnvironment("TEST"); const checkout = new CheckoutAPI(client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. checkout.paymentsDetails(STATE_DATA).then(res => res); ``` #### Go ```go import ( "github.com/adyen/adyen-go-api-library/v5/src/checkout" "github.com/adyen/adyen-go-api-library/v5/src/common" "github.com/adyen/adyen-go-api-library/v5/src/adyen" ) // Set your X-API-KEY with the API key from the Customer Area. client := adyen.NewClient(&common.Config{ Environment: common.TestEnv, ApiKey: "[ADYEN_API_KEY]", }) // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. req := STATE_DATA; res, httpRes, err := client.Checkout.PaymentsDetails(&req) ``` #### Python ```py # Set your X-API-KEY with the API key from the Customer Area. adyen = Adyen.Adyen() adyen.payment.client.platform = "test" adyen.client.xapikey = 'ADYEN_API_KEY' # STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. request = STATE_DATA result = adyen.checkout.payments_details(request) # Check if further action is needed. if 'action' in result.message: # Pass the action object to your front end # result.message['action'] else: # No further action needed, pass the resultCode to your front end # result.message['resultCode'] ``` #### Ruby ```ruby require 'adyen-ruby-api-library' # Set your X-API-KEY with the API key from the Customer Area. adyen = Adyen::Client.new adyen.env = :test adyen.api_key = "ADYEN_API_KEY" # STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. request = STATE_DATA response = adyen.checkout.payments.details(request) # Check if further action is needed. if response.body.has_key(:action) # Pass the action object to your frontend puts response.body[:action] else # No further action needed, pass the resultCode to your frontend puts response.body[:resultCode] end ``` 2. The [`resultCode` ](https://docs.adyen.com/online-payments/build-your-integration/payment-result-codes)informs you of the payment result. ### Result ## Show the payment result Use the  [resultCode](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#responses-200-resultCode) from the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) or [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) response to present the payment result to your shopper. You will also receive the outcome of the payment asynchronously in a [webhook](https://docs.adyen.com/development-resources/webhooks). For card payments, you can receive the following `resultCode` values: | resultCode | Description | Action to take | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Authorised** | The payment was successful. | Inform the shopper that the payment has been successful. If you are using [manual capture](https://docs.adyen.com/online-payments/capture#manual-capture), you also need to [capture](https://docs.adyen.com/online-payments/capture) the payment. | | **Cancelled** | The shopper cancelled the payment. | Ask the shopper if they want to continue with the order, or ask them to select a different payment method. | | **Error** | There was an error when the payment was being processed. For more information, check the [`refusalReason` ](https://docs.adyen.com/development-resources/refusal-reasons)field. | Inform the shopper that there was an error processing their payment. | | **Refused** | The payment was refused. For more information, check the [`refusalReason` ](https://docs.adyen.com/development-resources/refusal-reasons)field. | Ask the shopper to try the payment again using a different payment method. | ## See also * [Flutter Advanced flow integration guide](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow/?platform=Flutter) * [3D Secure 2 API Reference](https://docs.adyen.com/online-payments/3d-secure/api-reference) * [Webhooks](https://docs.adyen.com/development-resources/webhooks) * [Cards](https://docs.adyen.com/payment-methods/cards) ## Flutter Components Use the Component to support native 3D Secure 2 with your Flutter app ## Requirements Before you begin, take into account the following requirements, preparations, and limitations. | Requirement | Description | | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Integration type** | Make sure you have an [Advanced flow Flutter Components integration](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow/?platform=Flutter\&integration=Components) using Checkout API v71 or later. | | **[Webhooks](https://docs.adyen.com/development-resources/webhooks)** | Subscribe to the Standard webhooks. | | **Setup steps** | Before you begin:- [Add the card payment methods that you want to accept in your test Customer Area](https://docs.adyen.com/payment-methods/add-payment-methods). - Integrate with the Flutter [Card Component](https://docs.adyen.com/payment-methods/cards/flutter-component). | ## How it works To support 3D Secure 2 authentication with your integration: 1. [Add recommended configuration](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#configure) to collect additional information at checkout to include it when authenticating a payment. 2. [Make a payment request](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#make-a-payment), including additional shopper details. 3. In the payment response you receive, parse the JSON object included in the `action` object.\ The Flutter SDK [handles the action](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#handles-the-action). 4. Forward the action result in your [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) request. 5. [Show the payment result](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#show-the-payment-result). ### Additional Parameters ## Configure the Card Component for 3D Secure authentication For higher authentication rates, we strongly recommend that you collect the cardholder name, the shopper billing address and email address in advance in your payment form. For some schemes, it is required to include this information when [making a payment](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#make-a-payment). To collect additional shopper information using our Flutter card component, include the following in your [Component configuration](https://docs.adyen.com/payment-methods/cards/flutter-component/#configuration): | Parameter | Description | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `holderNameRequired` | Set to **true** to require the cardholder name. | | `addressMode` | Specify which address fields are required. Possible values: -**full**: require the full address. -**postalCode**: require the postal code. -**none**: address not required. | | `requestorAppUrl` | The URL to call your app after an out-of-band (OOB) authentication occurs. We strongly recommend this to improve conversion rates. For **iOS**, set this to the [universal link](https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app) for your app. For **Android**, set this to an [Android App Link](https://developer.android.com/training/app-links). When set, you must also [handle this app link](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#handling-your-android-app-link). | **Card configuration** ```javascript final CardComponentConfiguration cardComponentConfiguration = CardComponentConfiguration( holderNameRequired: true, addressMode: full ); ``` #### Handle your Android App Link To handle Android App Links: 1. Add the following to your `AndroidManifest.xml`, specifying your Android App Link as your `android:host`: **Copy to your app Manifest file** ```xml ``` 2. [Verify the App Link](https://developer.android.com/training/app-links/verify-android-applinks). ### Payment ## Make a payment 1. When you [make a payment request](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow?platform=Flutter\&integration=Drop-in\&version=latest#make-a-payment), include the following additional 3D Secure 2 parameters. See additional 3D Secure 2 parameters that we recommend to include in your request to increase authentication performance in our [API reference](https://docs.adyen.com/online-payments/3d-secure/api-reference). | Parameter name | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [paymentMethod](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The complete `paymentComponentData.paymentMethod` object from your client app. It includes the payment method details and other required information. | | [paymentMethod.sdkData](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-listOfValues-sdkData) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The object that includes the following information collected by the Component:- Information required for 3D Secure 2 authentication. - The [checkout attempt identifier](https://docs.adyen.com/online-payments/analytics-and-data-tracking#data-we-are-collecting) to track the user's payment journey. This is required to use the [Checkout dashboard](https://docs.adyen.com/uplift#uplift-dashboards) that lets you analyze your checkout performance. | | [paymentMethod.holderName](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-CardDetails-holderName) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions. The cardholder's name. | | [authenticationData.threeDSRequestData.nativeThreeDS](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-authenticationData-threeDSRequestData-nativeThreeDS) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | Indicates if your payment page can handle native 3D Secure 2 authentication. Set to **preferred**. | | [channel](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-channel) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The platform where the transaction takes place. Set to **Android**. | | [returnUrl](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-returnUrl) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The URL where the shopper should return to after a redirection. **iOS**: Use the [custom URL scheme](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app) for your app. You also need to:1) Add the return URL handler to your [AppDelegate](https://github.com/Adyen/adyen-flutter/blob/main/example/ios/Runner/AppDelegate.swift#L18) in your native iOS layer. 2) Configure the custom URL scheme in your [Info.plist file](https://github.com/Adyen/adyen-flutter/blob/main/example/ios/Runner/Info.plist).iOS example: `com.mydomain.adyencheckout://` **Android**: Use the combination of:- `adyencheckout://` scheme - Your package name - A path. You must add an [intent filter](https://developer.android.com/guide/components/intents-filters) to your [Manifest.xml](https://github.com/Adyen/adyen-flutter/blob/main/example/android/app/src/main/AndroidManifest.xml#L29) file with this path. This is required for Components.Android example: `adyencheckout://com.adyen.adyen_checkout_example/adyenPayment` **Format**: Maximum 1024 characters. The URL must not include personally identifiable information (PII), for example name or email address. | | [shopperEmail](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperEmail) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions. The cardholder's email address. If you do not include this, you must send the `telephoneNumber`, or a phone number in the `threeDS2RequestData` object. | | [shopperIP](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperIP) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions to support cases where the transaction is routed to the redirect flow. The shopper's IP address. | | [telephoneNumber](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-telephoneNumber) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.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. | | [browserInfo](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-browserInfo) | | The shopper's browser information. We recommend to include it in your requests to handle cases where authentication is routed to [the redirect flow](https://docs.adyen.com/online-payments/3d-secure/redirect-3ds2/). | ![This is the required icon.](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) Required for all transactions.\ ![This is the conditionally required icon.](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) Required for particular setups, or issuers and card schemes.\ ![This is the recommended icon.](https://docs.adyen.com/media/51cfe94e37a7426974002173390b3c7807ac234e65206fe14ed9fbdd45fb958e.svg?decoding=auto\&fetchpriority=auto) Recommended for all transactions, but not required. **Make a /payments request including 3D Secure 2 fields** #### curl ```bash curl https://checkout-test.adyen.com/v72/payments \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "amount":{ "currency":"EUR", "value":1000 }, "reference":"YOUR_ORDER_NUMBER", "shopperReference":"YOUR_UNIQUE_SHOPPER_ID", "paymentMethod": {hint:paymentMethod field of an object passed from the client app. Return the fields as they are, sdkVersion is required to trigger native.}STATE_DATA{/hint}, "authenticationData": { "threeDSRequestData": { "nativeThreeDS": "preferred" } }, "{hint:state.data.billingAddress from onSubmit}billingAddress{/hint}": { "street": "Infinite Loop", "houseNumberOrName": "1", "postalCode": "1011DJ", "city": "Amsterdam", "country": "NL" }, "{hint:Required for 3D Secure 1}browserInfo{/hint}: { "userAgent":"Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36", "acceptHeader":"text\/html,application\/xhtml+xml,application\/xml;q=0.9,image\/webp,image\/apng,*\/*;q=0.8" }, "shopperEmail":"s.hopper@example.com", "channel":"Android", "returnUrl":"adyencheckout://your.package.name", "merchantAccount":"YOUR_MERCHANT_ACCOUNT" }' ``` #### Java ```java // Adyen Java API Library v40.1.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.checkout.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.model.RequestOptions; import com.adyen.service.checkout.*; // For the LIVE environment, also include your liveEndpointUrlPrefix. Client client = new Client("ADYEN_API_KEY", Environment.TEST); // Create the request object(s) ThreeDSRequestData threeDSRequestData = new ThreeDSRequestData() .nativeThreeDS(ThreeDSRequestData.NativeThreeDSEnum.PREFERRED); AuthenticationData authenticationData = new AuthenticationData() .threeDSRequestData(threeDSRequestData); Amount amount = new Amount() .currency("EUR") .value(1000L); BillingAddress billingAddress = new BillingAddress() .country("NL") .city("Amsterdam") .street("Infinite Loop") .houseNumberOrName("1") .postalCode("1011DJ"); BrowserInfo browserInfo = new BrowserInfo() .acceptHeader("text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8") .userAgent("Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36"); PaymentRequest paymentRequest = new PaymentRequest() .reference("YOUR_ORDER_NUMBER") .authenticationData(authenticationData) .amount(amount) .merchantAccount("YOUR_MERCHANT_ACCOUNT") .channel(PaymentRequest.ChannelEnum.ANDROID) .shopperEmail("s.hopper@example.com") .billingAddress(billingAddress) .returnUrl("adyencheckout://your.package.name") .browserInfo(browserInfo) .shopperReference("YOUR_UNIQUE_SHOPPER_ID"); // Send the request PaymentsApi service = new PaymentsApi(client); PaymentResponse response = service.payments(paymentRequest, new RequestOptions().idempotencyKey("UUID")); ``` #### PHP ```php setXApiKey("ADYEN_API_KEY"); // For the LIVE environment, also include your liveEndpointUrlPrefix. $client->setEnvironment(Environment::TEST); // Create the request object(s) $threeDSRequestData = new ThreeDSRequestData(); $threeDSRequestData ->setNativeThreeDS("preferred"); $authenticationData = new AuthenticationData(); $authenticationData ->setThreeDSRequestData($threeDSRequestData); $amount = new Amount(); $amount ->setCurrency("EUR") ->setValue(1000); $billingAddress = new BillingAddress(); $billingAddress ->setCountry("NL") ->setCity("Amsterdam") ->setStreet("Infinite Loop") ->setHouseNumberOrName("1") ->setPostalCode("1011DJ"); $browserInfo = new BrowserInfo(); $browserInfo ->setAcceptHeader("text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8") ->setUserAgent("Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36"); $paymentRequest = new PaymentRequest(); $paymentRequest ->setReference("YOUR_ORDER_NUMBER") ->setAuthenticationData($authenticationData) ->setAmount($amount) ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT") ->setChannel("Android") ->setShopperEmail("s.hopper@example.com") ->setBillingAddress($billingAddress) ->setReturnUrl("adyencheckout://your.package.name") ->setBrowserInfo($browserInfo) ->setShopperReference("YOUR_UNIQUE_SHOPPER_ID"); $requestOptions['idempotencyKey'] = 'UUID'; // Send the request $service = new PaymentsApi($client); $response = $service->payments($paymentRequest, $requestOptions); ``` #### C\# ```cs // Adyen .NET API Library v32.2.1 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Checkout; using Adyen.Service.Checkout; // For the LIVE environment, also include your liveEndpointUrlPrefix. var config = new Config() { XApiKey = "ADYEN_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) ThreeDSRequestData threeDSRequestData = new ThreeDSRequestData { NativeThreeDS = ThreeDSRequestData.NativeThreeDSEnum.Preferred }; AuthenticationData authenticationData = new AuthenticationData { ThreeDSRequestData = threeDSRequestData }; Amount amount = new Amount { Currency = "EUR", Value = 1000 }; BillingAddress billingAddress = new BillingAddress { Country = "NL", City = "Amsterdam", Street = "Infinite Loop", HouseNumberOrName = "1", PostalCode = "1011DJ" }; BrowserInfo browserInfo = new BrowserInfo { AcceptHeader = "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8", UserAgent = "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36" }; PaymentRequest paymentRequest = new PaymentRequest { Reference = "YOUR_ORDER_NUMBER", AuthenticationData = authenticationData, Amount = amount, MerchantAccount = "YOUR_MERCHANT_ACCOUNT", Channel = PaymentRequest.ChannelEnum.Android, ShopperEmail = "s.hopper@example.com", BillingAddress = billingAddress, ReturnUrl = "adyencheckout://your.package.name", BrowserInfo = browserInfo, ShopperReference = "YOUR_UNIQUE_SHOPPER_ID" }; // Send the request var service = new PaymentsService(client); var response = service.Payments(paymentRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"}); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v30.0.1 const { Client, CheckoutAPI } = require('@adyen/api-library'); // For the LIVE environment, also include your liveEndpointUrlPrefix. const config = new Config({ apiKey: "ADYEN_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const paymentRequest = { amount: { currency: "EUR", value: 1000 }, reference: "YOUR_ORDER_NUMBER", shopperReference: "YOUR_UNIQUE_SHOPPER_ID", paymentMethod: "STATE_DATA", authenticationData: { threeDSRequestData: { nativeThreeDS: "preferred" } }, billingAddress: { street: "Infinite Loop", houseNumberOrName: "1", postalCode: "1011DJ", city: "Amsterdam", country: "NL" }, browserInfo: { userAgent: "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36", acceptHeader: "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8" }, shopperEmail: "s.hopper@example.com", channel: "Android", returnUrl: "adyencheckout://your.package.name", merchantAccount: "YOUR_MERCHANT_ACCOUNT" } // Send the request const checkoutAPI = new CheckoutAPI(client); const response = checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" }); ``` #### Go ```go // Adyen Go API Library v21.1.0 import ( "context" "github.com/adyen/adyen-go-api-library/v21/src/common" "github.com/adyen/adyen-go-api-library/v21/src/adyen" "github.com/adyen/adyen-go-api-library/v21/src/checkout" ) // For the LIVE environment, also include your liveEndpointUrlPrefix. client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) threeDSRequestData := checkout.ThreeDSRequestData{ NativeThreeDS: common.PtrString("preferred"), } authenticationData := checkout.AuthenticationData{ ThreeDSRequestData: &threeDSRequestData, } amount := checkout.Amount{ Currency: "EUR", Value: 1000, } billingAddress := checkout.BillingAddress{ Country: "NL", City: "Amsterdam", Street: "Infinite Loop", HouseNumberOrName: "1", PostalCode: "1011DJ", } browserInfo := checkout.BrowserInfo{ AcceptHeader: "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8", UserAgent: "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36", } paymentRequest := checkout.PaymentRequest{ Reference: "YOUR_ORDER_NUMBER", AuthenticationData: &authenticationData, Amount: amount, MerchantAccount: "YOUR_MERCHANT_ACCOUNT", Channel: common.PtrString("Android"), ShopperEmail: common.PtrString("s.hopper@example.com"), BillingAddress: &billingAddress, ReturnUrl: "adyencheckout://your.package.name", BrowserInfo: &browserInfo, ShopperReference: common.PtrString("YOUR_UNIQUE_SHOPPER_ID"), } // Send the request service := client.Checkout() req := service.PaymentsApi.PaymentsInput().IdempotencyKey("UUID").PaymentRequest(paymentRequest) res, httpRes, err := service.PaymentsApi.Payments(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v14.0.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_API_KEY" # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "amount": { "currency": "EUR", "value": 1000 }, "reference": "YOUR_ORDER_NUMBER", "shopperReference": "YOUR_UNIQUE_SHOPPER_ID", "paymentMethod": "STATE_DATA", "authenticationData": { "threeDSRequestData": { "nativeThreeDS": "preferred" } }, "billingAddress": { "street": "Infinite Loop", "houseNumberOrName": "1", "postalCode": "1011DJ", "city": "Amsterdam", "country": "NL" }, "browserInfo": { "userAgent": "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36", "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8" }, "shopperEmail": "s.hopper@example.com", "channel": "Android", "returnUrl": "adyencheckout://your.package.name", "merchantAccount": "YOUR_MERCHANT_ACCOUNT" } # Send the request result = adyen.checkout.payments_api.payments(request=json_request, idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v11.1.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_API_KEY' # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :amount => { :currency => 'EUR', :value => 1000 }, :reference => 'YOUR_ORDER_NUMBER', :shopperReference => 'YOUR_UNIQUE_SHOPPER_ID', :paymentMethod => 'STATE_DATA', :authenticationData => { :threeDSRequestData => { :nativeThreeDS => 'preferred' } }, :billingAddress => { :street => 'Infinite Loop', :houseNumberOrName => '1', :postalCode => '1011DJ', :city => 'Amsterdam', :country => 'NL' }, :browserInfo => { :userAgent => 'Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36', :acceptHeader => 'text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8' }, :shopperEmail => 's.hopper@example.com', :channel => 'Android', :returnUrl => 'adyencheckout://your.package.name', :merchantAccount => 'YOUR_MERCHANT_ACCOUNT' } # Send the request result = adyen.checkout.payments_api.payments(request_body, headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v30.0.1 import { Client, CheckoutAPI, Types } from "@adyen/api-library"; // For the LIVE environment, also include your liveEndpointUrlPrefix. const config = new Config({ apiKey: "ADYEN_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const threeDSRequestData: Types.checkout.ThreeDSRequestData = { nativeThreeDS: Types.checkout.ThreeDSRequestData.NativeThreeDSEnum.Preferred }; const authenticationData: Types.checkout.AuthenticationData = { threeDSRequestData: threeDSRequestData }; const amount: Types.checkout.Amount = { currency: "EUR", value: 1000 }; const billingAddress: Types.checkout.BillingAddress = { country: "NL", city: "Amsterdam", street: "Infinite Loop", houseNumberOrName: "1", postalCode: "1011DJ" }; const browserInfo: Types.checkout.BrowserInfo = { acceptHeader: "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8", userAgent: "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36" }; const paymentRequest: Types.checkout.PaymentRequest = { reference: "YOUR_ORDER_NUMBER", authenticationData: authenticationData, amount: amount, merchantAccount: "YOUR_MERCHANT_ACCOUNT", channel: Types.checkout.PaymentRequest.ChannelEnum.Android, shopperEmail: "s.hopper@example.com", billingAddress: billingAddress, returnUrl: "adyencheckout://your.package.name", browserInfo: browserInfo, shopperReference: "YOUR_UNIQUE_SHOPPER_ID" }; // Send the request const checkoutAPI = new CheckoutAPI(client); const response = checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" }); ``` 2. After you make the payment request, you receive an [API response](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow?target%2B_blankplatform=Flutter\&integration=Components\&version=latest#id237754811) that includes an `action` object. This object informs you of the additional action that is required to complete the payment. 3. Your integration maps the response to the `Action` [`PaymentEvent` ](https://github.com/Adyen/adyen-flutter/blob/main/lib/src/common/model/payment_event.dart)object. ### Handle ## Forward the action result Component automatically handles the authentication action. After the shopper completes authentication, Component invokes the `onAdditionalDetails`, which provides the 3D Secure 2 authentication result. 1. In your [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) request, include the `data` object from the `onAdditionalDetails` callback. **Example request to send additional payment details** #### curl ```bash curl https://checkout-test.adyen.com/v72/payments/details \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{hint:object passed from the front end or client app}STATE_DATA{/hint}' ``` #### Java ```java // Set your X-API-KEY with the API key from the Customer Area. String xApiKey = "ADYEN_API_KEY"; Client client = new Client(xApiKey,Environment.TEST); Checkout checkout = new Checkout(client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. PaymentsDetailsRequest paymentsDetailsRequest = STATE_DATA; PaymentsResponse paymentsDetailsResponse = checkout.paymentsDetails(paymentsDetailsRequest); ``` #### PHP ```php // Set your X-API-KEY with the API key from the Customer Area. $client = new \Adyen\Client(); $client->setEnvironment(\Adyen\Environment::TEST); $client->setXApiKey("ADYEN_API_KEY"); $service = new \Adyen\Service\Checkout($client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. $params = STATE_DATA; $result = $service->paymentsDetails($params); // Check if further action is needed if (array_key_exists("action", $result)){ // Pass the action object to your frontend. // $result["action"] } else { // No further action needed, pass the resultCode to your front end // $result['resultCode'] } ``` #### C\# ```cs // Set your X-API-KEY with the API key from the Customer Area. string apiKey = "ADYEN_API_KEY"; var client = new Client (apiKey, Environment.Test); var checkout = new Checkout(client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. var paymentsDetailsRequest = STATE_DATA; var paymentsDetailsResponse = checkout.PaymentDetails(paymentsDetailsRequest); ``` #### NodeJS (JavaScript) ```js const {Client, Config, CheckoutAPI} = require('@adyen/api-library'); const config = new Config(); // Set your X-API-KEY with the API key from the Customer Area. config.apiKey = '[ADYEN_API_KEY]'; const client = new Client({ config }); client.setEnvironment("TEST"); const checkout = new CheckoutAPI(client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. checkout.paymentsDetails(STATE_DATA).then(res => res); ``` #### Go ```go import ( "github.com/adyen/adyen-go-api-library/v5/src/checkout" "github.com/adyen/adyen-go-api-library/v5/src/common" "github.com/adyen/adyen-go-api-library/v5/src/adyen" ) // Set your X-API-KEY with the API key from the Customer Area. client := adyen.NewClient(&common.Config{ Environment: common.TestEnv, ApiKey: "[ADYEN_API_KEY]", }) // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. req := STATE_DATA; res, httpRes, err := client.Checkout.PaymentsDetails(&req) ``` #### Python ```py # Set your X-API-KEY with the API key from the Customer Area. adyen = Adyen.Adyen() adyen.payment.client.platform = "test" adyen.client.xapikey = 'ADYEN_API_KEY' # STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. request = STATE_DATA result = adyen.checkout.payments_details(request) # Check if further action is needed. if 'action' in result.message: # Pass the action object to your front end # result.message['action'] else: # No further action needed, pass the resultCode to your front end # result.message['resultCode'] ``` #### Ruby ```ruby require 'adyen-ruby-api-library' # Set your X-API-KEY with the API key from the Customer Area. adyen = Adyen::Client.new adyen.env = :test adyen.api_key = "ADYEN_API_KEY" # STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. request = STATE_DATA response = adyen.checkout.payments.details(request) # Check if further action is needed. if response.body.has_key(:action) # Pass the action object to your frontend puts response.body[:action] else # No further action needed, pass the resultCode to your frontend puts response.body[:resultCode] end ``` 2. The [`resultCode`](https://docs.adyen.com/online-payments/build-your-integration/payment-result-codes) informs you of the payment result. ### Result ## Show the payment result Use the  [resultCode](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#responses-200-resultCode) from the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) or [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) response to present the payment result to your shopper. You will also receive the outcome of the payment asynchronously in a [webhook](https://docs.adyen.com/development-resources/webhooks). For card payments, you can receive the following `resultCode` values: | resultCode | Description | Action to take | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Authorised** | The payment was successful. | Inform the shopper that the payment has been successful. If you are using [manual capture](https://docs.adyen.com/online-payments/capture#manual-capture), you also need to [capture](https://docs.adyen.com/online-payments/capture) the payment. | | **Cancelled** | The shopper cancelled the payment. | Ask the shopper if they want to continue with the order, or ask them to select a different payment method. | | **Error** | There was an error when the payment was being processed. For more information, check the [`refusalReason`](https://docs.adyen.com/development-resources/refusal-reasons) field. | Inform the shopper that there was an error processing their payment. | | **Refused** | The payment was refused. For more information, check the [`refusalReason`](https://docs.adyen.com/development-resources/refusal-reasons) field. | Ask the shopper to try the payment again using a different payment method. | ## Test and go live Use our test card numbers to [test how your integration handles different 3D Secure authentication scenarios](https://docs.adyen.com/development-resources/testing/3d-secure-2-authentication). When you are ready to [go live](https://docs.adyen.com/get-started-with-adyen/#apply-for-your-live-account), follow our [go-live checklist](https://docs.adyen.com/online-payments/go-live-checklist/). When using our [live endpoints](https://docs.adyen.com/development-resources/live-endpoints/), make sure that all API requests you make for the same payment session use the same live endpoint region. Using different regions for [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) and [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) requests may result in errors when authenticating with 3D Secure. ### Live environment values | Endpoint region | Value | | ------------------------- | ---------------- | | Europe (EU) live | **europe** | | United States (US) live | **unitedStates** | | Australia (AU) live | **australia** | | Northeast Asia (NEA) live | **nea** | | India (IN) live | **india** | ## See also * [Flutter Advanced flow integration guide](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow/?platform=Flutter) * [3D Secure 2 API Reference](https://docs.adyen.com/online-payments/3d-secure/api-reference) * [Webhooks](https://docs.adyen.com/development-resources/webhooks) * [Cards](https://docs.adyen.com/payment-methods/cards) ## React Native Drop-in Use Drop-in to support native 3D Secure 2 with your React Native app ## Requirements Before you begin, take into account the following requirements, preparations, and limitations. | Requirement | Description | | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | Make sure you have an [Advanced flow React Native Drop-in integration](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow/?platform=React%20Native\&integration=Drop-in) using Checkout API v71 or later. If you use the [Sessions flow](https://docs.adyen.com/online-payments/build-your-integration#sessions-flow-a-single-api-request), no additional configuration is needed to support 3D Secure 2. | | **[Webhooks](https://docs.adyen.com/development-resources/webhooks)** | Subscribe to the Standard webhooks. | | **Setup steps** | Before you begin:- [Add the card payment methods that you want to accept in your test Customer Area](https://docs.adyen.com/payment-methods/add-payment-methods). - Integrate with the React Native [Drop-in](https://docs.adyen.com/payment-methods/cards/react-native-drop-in). | ## How it works To support 3D Secure 2 authentication with your integration: 1. [Add recommended configuration](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#configure) to collect additional information at checkout to include it when authenticating a payment. 2. [Make a payment request](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#make-a-payment), including additional shopper details. 3. In the payment response you receive, parse the JSON object included in the `action` object.\ The React Native SDK [handles the action](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#handles-the-action). 4. Forward the action result in your [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) request. 5. [Show the payment result](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#show-the-payment-result). ### Additional Parameters ## Configure the Card Component for 3D Secure authentication For higher authentication rates, we strongly recommend that you collect the cardholder name, the shopper billing address and email address in advance in your payment form. For some schemes, it is required to include this information when [making a payment](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#make-a-payment). To collect additional shopper information using our React Native card component, include the following card and 3D Secure 2 specific parameters in your [`AdyenCheckout` configuration object](https://docs.adyen.com/payment-methods/cards/react-native-component#optional-configuration). | Parameter | Description | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `holderNameRequired` | Set to **true** to require the cardholder name. | | `addressVisibility` | Specify which address fields are shown in the payment form. Possible values: - **full**: show all address fields. - **postalCode**: show only the postal code. - **none**: do not show address fields. - **lookup**: suggest addresses to the shopper when they enter data into address input. | | `requestorAppUrl` | The URL to call your app after an out-of-band (OOB) authentication occurs to override [the default `returnUrl`](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow?platform=React%20Native\&integration=Drop-in\&version=2.7.3#configure). We strongly recommend this to improve conversion rates. For **iOS**, set this to the [universal link](https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app) for your app. For **Android**, set this to an [Android App Link](https://developer.android.com/training/app-links). When set, you must also [handle this app link](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#handling-your-android-app-link). | **Configure the Component** ```javascript const configuration = { environment: 'test', clientKey: 'YOUR_CLIENT_KEY', // Your other configurations... cards: { holderNameRequired: "true", addressVisibility: "full" }, threeDS2: { // Alternative URL to return to when out-of-band 3D Secure 2 authentication occurs requestorAppUrl: "YOUR_APP_URL" } }; ``` ### Handle your Android App Link To handle Android App Links: 1. Add the following to your `AndroidManifest.xml`, specifying your Android App Link as your `android:host`: **Copy to your app Manifest file** ```xml ``` 2. [Verify the App Link](https://developer.android.com/training/app-links/verify-android-applinks). ### Payment ## Make a payment When the shopper selects the **Pay** button, your Drop-in integration invokes the [`onSubmit` ](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow?platform=Flutter\&integration=Drop-in\&version=1.6.0#launch-and-show)method. 1. In your POST [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request, include the following additional 3D Secure 2 parameters. See additional 3D Secure 2 parameters that we recommend to include in your request to increase authentication performance in our [API reference](https://docs.adyen.com/online-payments/3d-secure/api-reference). | Parameter name | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [paymentMethod](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The complete `paymentComponentData.paymentMethod` object from your client app that includes the payment method details and other required information. | | [paymentMethod.sdkData](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-listOfValues-sdkData) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | The object that includes the following information collected by the Component:- Information required for 3D Secure 2 authentication. - The [checkout attempt identifier](https://docs.adyen.com/online-payments/analytics-and-data-tracking#data-we-are-collecting) to track the user's payment journey. This is required to use the [Checkout dashboard](https://docs.adyen.com/uplift#uplift-dashboards) that lets you analyze your checkout performance. | | [paymentMethod.holderName](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-CardDetails-holderName) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions. The cardholder's name. | | [authenticationData.threeDSRequestData.nativeThreeDS](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-authenticationData-threeDSRequestData-nativeThreeDS) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | Indicates if your payment page can handle native 3D Secure 2 authentication. Set to **preferred**. | | [channel](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-channel) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | [Set a global channel constant](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#set-channel) to dynamically identify the channel using React Native's `Platform.select` utility. | | [returnUrl](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-returnUrl) | ![Required](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) | [Set a returnUrl constant](https://docs.adyen.com/online-payments/3d-secure/native-3ds2#set-returnUrl) to redirect the shopper to your app after a redirection. For more information on setting a custom URL scheme for your app, read the [Apple Developer documentation](https://developer.apple.com/documentation/uikit/inter-process_communication/allowing_apps_and_websites_to_link_to_your_content/defining_a_custom_url_scheme_for_your_app). **Format**: Maximum 1024 characters. If the URL to return to includes non-ASCII characters, like spaces or special letters, URL encode the value. The URL must not include personally identifiable information (PII), for example name or email address. | | [shopperEmail](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperEmail) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions. The cardholder's email address. If you do not include this, you must send the `telephoneNumber`, or a phone number in the `threeDS2RequestData` object. | | [shopperIP](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperIP) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) | **Use case**: required for Visa and JCB transactions to support cases where the transaction is routed to the redirect flow. The shopper's IP address. | | [telephoneNumber](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-telephoneNumber) | ![Conditionally required](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.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. | | [browserInfo](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-browserInfo) | | The shopper's browser information. We recommend to include it in your requests to handle cases where authentication is routed to [the redirect flow](https://docs.adyen.com/online-payments/3d-secure/redirect-3ds2/). | ![This is the required icon.](https://docs.adyen.com/media/732127089c689593ccb0331d565e5773bed94e60145cae96672212374facb8c6.svg?decoding=auto\&fetchpriority=auto) Required for all transactions.\ ![This is the conditionally required icon.](https://docs.adyen.com/media/e654d4104461d20836c817ee9d8f27faa0e45c1a8d08558f079561a50fc2797e.svg?decoding=auto\&fetchpriority=auto) Required for particular setups, or issuers and card schemes.\ ![This is the recommended icon.](https://docs.adyen.com/media/51cfe94e37a7426974002173390b3c7807ac234e65206fe14ed9fbdd45fb958e.svg?decoding=auto\&fetchpriority=auto) Recommended for all transactions, but not required. **Make a /payments request including 3D Secure 2 fields** #### curl ```bash curl https://checkout-test.adyen.com/v72/payments \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "amount":{ "currency":"EUR", "value":1000 }, "reference":"YOUR_ORDER_NUMBER", "shopperReference":"YOUR_UNIQUE_SHOPPER_ID", "paymentMethod": {hint:paymentMethod field of an object passed from the client app. Return the fields as they are, sdkVersion is required to trigger native.}STATE_DATA{/hint}, "authenticationData": { "threeDSRequestData": { "nativeThreeDS": "preferred" } }, "{hint:state.data.billingAddress from onSubmit}billingAddress{/hint}": { "street": "Infinite Loop", "houseNumberOrName": "1", "postalCode": "1011DJ", "city": "Amsterdam", "country": "NL" }, "{hint:Required for 3D Secure 1}browserInfo{/hint}: { "userAgent":"Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36", "acceptHeader":"text\/html,application\/xhtml+xml,application\/xml;q=0.9,image\/webp,image\/apng,*\/*;q=0.8" }, "shopperEmail":"s.hopper@example.com", "channel":"Android", "returnUrl":"adyencheckout://your.package.name", "merchantAccount":"YOUR_MERCHANT_ACCOUNT" }' ``` #### Java ```java // Adyen Java API Library v40.1.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.checkout.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.model.RequestOptions; import com.adyen.service.checkout.*; // For the LIVE environment, also include your liveEndpointUrlPrefix. Client client = new Client("ADYEN_API_KEY", Environment.TEST); // Create the request object(s) ThreeDSRequestData threeDSRequestData = new ThreeDSRequestData() .nativeThreeDS(ThreeDSRequestData.NativeThreeDSEnum.PREFERRED); AuthenticationData authenticationData = new AuthenticationData() .threeDSRequestData(threeDSRequestData); Amount amount = new Amount() .currency("EUR") .value(1000L); BillingAddress billingAddress = new BillingAddress() .country("NL") .city("Amsterdam") .street("Infinite Loop") .houseNumberOrName("1") .postalCode("1011DJ"); BrowserInfo browserInfo = new BrowserInfo() .acceptHeader("text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8") .userAgent("Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36"); PaymentRequest paymentRequest = new PaymentRequest() .reference("YOUR_ORDER_NUMBER") .authenticationData(authenticationData) .amount(amount) .merchantAccount("YOUR_MERCHANT_ACCOUNT") .channel(PaymentRequest.ChannelEnum.ANDROID) .shopperEmail("s.hopper@example.com") .billingAddress(billingAddress) .returnUrl("adyencheckout://your.package.name") .browserInfo(browserInfo) .shopperReference("YOUR_UNIQUE_SHOPPER_ID"); // Send the request PaymentsApi service = new PaymentsApi(client); PaymentResponse response = service.payments(paymentRequest, new RequestOptions().idempotencyKey("UUID")); ``` #### PHP ```php setXApiKey("ADYEN_API_KEY"); // For the LIVE environment, also include your liveEndpointUrlPrefix. $client->setEnvironment(Environment::TEST); // Create the request object(s) $threeDSRequestData = new ThreeDSRequestData(); $threeDSRequestData ->setNativeThreeDS("preferred"); $authenticationData = new AuthenticationData(); $authenticationData ->setThreeDSRequestData($threeDSRequestData); $amount = new Amount(); $amount ->setCurrency("EUR") ->setValue(1000); $billingAddress = new BillingAddress(); $billingAddress ->setCountry("NL") ->setCity("Amsterdam") ->setStreet("Infinite Loop") ->setHouseNumberOrName("1") ->setPostalCode("1011DJ"); $browserInfo = new BrowserInfo(); $browserInfo ->setAcceptHeader("text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8") ->setUserAgent("Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36"); $paymentRequest = new PaymentRequest(); $paymentRequest ->setReference("YOUR_ORDER_NUMBER") ->setAuthenticationData($authenticationData) ->setAmount($amount) ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT") ->setChannel("Android") ->setShopperEmail("s.hopper@example.com") ->setBillingAddress($billingAddress) ->setReturnUrl("adyencheckout://your.package.name") ->setBrowserInfo($browserInfo) ->setShopperReference("YOUR_UNIQUE_SHOPPER_ID"); $requestOptions['idempotencyKey'] = 'UUID'; // Send the request $service = new PaymentsApi($client); $response = $service->payments($paymentRequest, $requestOptions); ``` #### C\# ```cs // Adyen .NET API Library v32.2.1 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Checkout; using Adyen.Service.Checkout; // For the LIVE environment, also include your liveEndpointUrlPrefix. var config = new Config() { XApiKey = "ADYEN_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) ThreeDSRequestData threeDSRequestData = new ThreeDSRequestData { NativeThreeDS = ThreeDSRequestData.NativeThreeDSEnum.Preferred }; AuthenticationData authenticationData = new AuthenticationData { ThreeDSRequestData = threeDSRequestData }; Amount amount = new Amount { Currency = "EUR", Value = 1000 }; BillingAddress billingAddress = new BillingAddress { Country = "NL", City = "Amsterdam", Street = "Infinite Loop", HouseNumberOrName = "1", PostalCode = "1011DJ" }; BrowserInfo browserInfo = new BrowserInfo { AcceptHeader = "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8", UserAgent = "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36" }; PaymentRequest paymentRequest = new PaymentRequest { Reference = "YOUR_ORDER_NUMBER", AuthenticationData = authenticationData, Amount = amount, MerchantAccount = "YOUR_MERCHANT_ACCOUNT", Channel = PaymentRequest.ChannelEnum.Android, ShopperEmail = "s.hopper@example.com", BillingAddress = billingAddress, ReturnUrl = "adyencheckout://your.package.name", BrowserInfo = browserInfo, ShopperReference = "YOUR_UNIQUE_SHOPPER_ID" }; // Send the request var service = new PaymentsService(client); var response = service.Payments(paymentRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"}); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v30.0.1 const { Client, CheckoutAPI } = require('@adyen/api-library'); // For the LIVE environment, also include your liveEndpointUrlPrefix. const config = new Config({ apiKey: "ADYEN_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const paymentRequest = { amount: { currency: "EUR", value: 1000 }, reference: "YOUR_ORDER_NUMBER", shopperReference: "YOUR_UNIQUE_SHOPPER_ID", paymentMethod: "STATE_DATA", authenticationData: { threeDSRequestData: { nativeThreeDS: "preferred" } }, billingAddress: { street: "Infinite Loop", houseNumberOrName: "1", postalCode: "1011DJ", city: "Amsterdam", country: "NL" }, browserInfo: { userAgent: "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36", acceptHeader: "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8" }, shopperEmail: "s.hopper@example.com", channel: "Android", returnUrl: "adyencheckout://your.package.name", merchantAccount: "YOUR_MERCHANT_ACCOUNT" } // Send the request const checkoutAPI = new CheckoutAPI(client); const response = checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" }); ``` #### Go ```go // Adyen Go API Library v21.1.0 import ( "context" "github.com/adyen/adyen-go-api-library/v21/src/common" "github.com/adyen/adyen-go-api-library/v21/src/adyen" "github.com/adyen/adyen-go-api-library/v21/src/checkout" ) // For the LIVE environment, also include your liveEndpointUrlPrefix. client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) threeDSRequestData := checkout.ThreeDSRequestData{ NativeThreeDS: common.PtrString("preferred"), } authenticationData := checkout.AuthenticationData{ ThreeDSRequestData: &threeDSRequestData, } amount := checkout.Amount{ Currency: "EUR", Value: 1000, } billingAddress := checkout.BillingAddress{ Country: "NL", City: "Amsterdam", Street: "Infinite Loop", HouseNumberOrName: "1", PostalCode: "1011DJ", } browserInfo := checkout.BrowserInfo{ AcceptHeader: "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8", UserAgent: "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36", } paymentRequest := checkout.PaymentRequest{ Reference: "YOUR_ORDER_NUMBER", AuthenticationData: &authenticationData, Amount: amount, MerchantAccount: "YOUR_MERCHANT_ACCOUNT", Channel: common.PtrString("Android"), ShopperEmail: common.PtrString("s.hopper@example.com"), BillingAddress: &billingAddress, ReturnUrl: "adyencheckout://your.package.name", BrowserInfo: &browserInfo, ShopperReference: common.PtrString("YOUR_UNIQUE_SHOPPER_ID"), } // Send the request service := client.Checkout() req := service.PaymentsApi.PaymentsInput().IdempotencyKey("UUID").PaymentRequest(paymentRequest) res, httpRes, err := service.PaymentsApi.Payments(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v14.0.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_API_KEY" # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "amount": { "currency": "EUR", "value": 1000 }, "reference": "YOUR_ORDER_NUMBER", "shopperReference": "YOUR_UNIQUE_SHOPPER_ID", "paymentMethod": "STATE_DATA", "authenticationData": { "threeDSRequestData": { "nativeThreeDS": "preferred" } }, "billingAddress": { "street": "Infinite Loop", "houseNumberOrName": "1", "postalCode": "1011DJ", "city": "Amsterdam", "country": "NL" }, "browserInfo": { "userAgent": "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36", "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8" }, "shopperEmail": "s.hopper@example.com", "channel": "Android", "returnUrl": "adyencheckout://your.package.name", "merchantAccount": "YOUR_MERCHANT_ACCOUNT" } # Send the request result = adyen.checkout.payments_api.payments(request=json_request, idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v11.1.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_API_KEY' # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :amount => { :currency => 'EUR', :value => 1000 }, :reference => 'YOUR_ORDER_NUMBER', :shopperReference => 'YOUR_UNIQUE_SHOPPER_ID', :paymentMethod => 'STATE_DATA', :authenticationData => { :threeDSRequestData => { :nativeThreeDS => 'preferred' } }, :billingAddress => { :street => 'Infinite Loop', :houseNumberOrName => '1', :postalCode => '1011DJ', :city => 'Amsterdam', :country => 'NL' }, :browserInfo => { :userAgent => 'Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36', :acceptHeader => 'text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8' }, :shopperEmail => 's.hopper@example.com', :channel => 'Android', :returnUrl => 'adyencheckout://your.package.name', :merchantAccount => 'YOUR_MERCHANT_ACCOUNT' } # Send the request result = adyen.checkout.payments_api.payments(request_body, headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v30.0.1 import { Client, CheckoutAPI, Types } from "@adyen/api-library"; // For the LIVE environment, also include your liveEndpointUrlPrefix. const config = new Config({ apiKey: "ADYEN_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const threeDSRequestData: Types.checkout.ThreeDSRequestData = { nativeThreeDS: Types.checkout.ThreeDSRequestData.NativeThreeDSEnum.Preferred }; const authenticationData: Types.checkout.AuthenticationData = { threeDSRequestData: threeDSRequestData }; const amount: Types.checkout.Amount = { currency: "EUR", value: 1000 }; const billingAddress: Types.checkout.BillingAddress = { country: "NL", city: "Amsterdam", street: "Infinite Loop", houseNumberOrName: "1", postalCode: "1011DJ" }; const browserInfo: Types.checkout.BrowserInfo = { acceptHeader: "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8", userAgent: "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36" }; const paymentRequest: Types.checkout.PaymentRequest = { reference: "YOUR_ORDER_NUMBER", authenticationData: authenticationData, amount: amount, merchantAccount: "YOUR_MERCHANT_ACCOUNT", channel: Types.checkout.PaymentRequest.ChannelEnum.Android, shopperEmail: "s.hopper@example.com", billingAddress: billingAddress, returnUrl: "adyencheckout://your.package.name", browserInfo: browserInfo, shopperReference: "YOUR_UNIQUE_SHOPPER_ID" }; // Send the request const checkoutAPI = new CheckoutAPI(client); const response = checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" }); ``` 2. Check the `action` object in the API response you receive. If the transaction requires 3D Secure 2 authentication, you receive `action.type`: **threeDS2**. 3. Your integration [handles the 3D Secure 2 authentication action](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow?platform=React%20Native\&integration=Components\&version=2.7.3#3d-secure-2-authentication-action). ### Setting a channel constant Use the React Native `Platform.select` utility to dynamically identify iOS and Android environments. ```javascript export const CHANNEL = Platform.select({ ios: 'iOS', android: 'Android', }); ``` ### Setting a returnUrl constant Use the React Native `Platform.select` utility to dynamically set a `returnUrl` for iOS and Android environments. ```javascript const returnUrl = Platform.select({ ios: 'myapp://payment', android: await AdyenDropIn.getReturnURL(), }); ``` ### Handle ## Forward the action result Drop-in handles the authentication action. After the shopper completes authentication, Drop-in invokes the `onAdditionalDetails`, which provides the 3D Secure 2 authentication result. Your integration passes the `data` object to your server. 1. In your [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) request, include the `data` object from the `onAdditionalDetails` callback. **Example request to send additional payment details** #### curl ```bash curl https://checkout-test.adyen.com/v72/payments/details \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{hint:object passed from the front end or client app}STATE_DATA{/hint}' ``` #### Java ```java // Set your X-API-KEY with the API key from the Customer Area. String xApiKey = "ADYEN_API_KEY"; Client client = new Client(xApiKey,Environment.TEST); Checkout checkout = new Checkout(client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. PaymentsDetailsRequest paymentsDetailsRequest = STATE_DATA; PaymentsResponse paymentsDetailsResponse = checkout.paymentsDetails(paymentsDetailsRequest); ``` #### PHP ```php // Set your X-API-KEY with the API key from the Customer Area. $client = new \Adyen\Client(); $client->setEnvironment(\Adyen\Environment::TEST); $client->setXApiKey("ADYEN_API_KEY"); $service = new \Adyen\Service\Checkout($client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. $params = STATE_DATA; $result = $service->paymentsDetails($params); // Check if further action is needed if (array_key_exists("action", $result)){ // Pass the action object to your frontend. // $result["action"] } else { // No further action needed, pass the resultCode to your front end // $result['resultCode'] } ``` #### C\# ```cs // Set your X-API-KEY with the API key from the Customer Area. string apiKey = "ADYEN_API_KEY"; var client = new Client (apiKey, Environment.Test); var checkout = new Checkout(client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. var paymentsDetailsRequest = STATE_DATA; var paymentsDetailsResponse = checkout.PaymentDetails(paymentsDetailsRequest); ``` #### NodeJS (JavaScript) ```js const {Client, Config, CheckoutAPI} = require('@adyen/api-library'); const config = new Config(); // Set your X-API-KEY with the API key from the Customer Area. config.apiKey = '[ADYEN_API_KEY]'; const client = new Client({ config }); client.setEnvironment("TEST"); const checkout = new CheckoutAPI(client); // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. checkout.paymentsDetails(STATE_DATA).then(res => res); ``` #### Go ```go import ( "github.com/adyen/adyen-go-api-library/v5/src/checkout" "github.com/adyen/adyen-go-api-library/v5/src/common" "github.com/adyen/adyen-go-api-library/v5/src/adyen" ) // Set your X-API-KEY with the API key from the Customer Area. client := adyen.NewClient(&common.Config{ Environment: common.TestEnv, ApiKey: "[ADYEN_API_KEY]", }) // STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. req := STATE_DATA; res, httpRes, err := client.Checkout.PaymentsDetails(&req) ``` #### Python ```py # Set your X-API-KEY with the API key from the Customer Area. adyen = Adyen.Adyen() adyen.payment.client.platform = "test" adyen.client.xapikey = 'ADYEN_API_KEY' # STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. request = STATE_DATA result = adyen.checkout.payments_details(request) # Check if further action is needed. if 'action' in result.message: # Pass the action object to your front end # result.message['action'] else: # No further action needed, pass the resultCode to your front end # result.message['resultCode'] ``` #### Ruby ```ruby require 'adyen-ruby-api-library' # Set your X-API-KEY with the API key from the Customer Area. adyen = Adyen::Client.new adyen.env = :test adyen.api_key = "ADYEN_API_KEY" # STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure. request = STATE_DATA response = adyen.checkout.payments.details(request) # Check if further action is needed. if response.body.has_key(:action) # Pass the action object to your frontend puts response.body[:action] else # No further action needed, pass the resultCode to your frontend puts response.body[:resultCode] end ``` 2. The [`resultCode` ](https://docs.adyen.com/online-payments/build-your-integration/payment-result-codes)in the API response informs you of the payment result. Pass the response from your server to your client app. ### Result ## Show the payment result Use the  [resultCode](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#responses-200-resultCode) from the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) or [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) response to present the payment result to your shopper. You will also receive the outcome of the payment asynchronously in a [webhook](https://docs.adyen.com/development-resources/webhooks). For card payments, you can receive the following `resultCode` values: | resultCode | Description | Action to take | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Authorised** | The payment was successful. | Inform the shopper that the payment has been successful. If you are using [manual capture](https://docs.adyen.com/online-payments/capture#manual-capture), you also need to [capture](https://docs.adyen.com/online-payments/capture) the payment. | | **Cancelled** | The shopper cancelled the payment. | Ask the shopper if they want to continue with the order, or ask them to select a different payment method. | | **Error** | There was an error when the payment was being processed. For more information, check the [`refusalReason` ](https://docs.adyen.com/development-resources/refusal-reasons)field. | Inform the shopper that there was an error processing their payment. | | **Refused** | The payment was refused. For more information, check the [`refusalReason` ](https://docs.adyen.com/development-resources/refusal-reasons)field. | Ask the shopper to try the payment again using a different payment method. | ## Test and go live Use our test card numbers to [test how your integration handles different 3D Secure authentication scenarios](https://docs.adyen.com/development-resources/testing/3d-secure-2-authentication). When you are ready to [go live](https://docs.adyen.com/get-started-with-adyen/#apply-for-your-live-account), follow our [go-live checklist](https://docs.adyen.com/online-payments/go-live-checklist/). When using our [live endpoints](https://docs.adyen.com/development-resources/live-endpoints/), make sure that all API requests you make for the same payment session use the same live endpoint region. Using different regions for [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) and [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) requests may result in errors when authenticating with 3D Secure. ### Live environment values | Endpoint region | Value | | ------------------------- | ------------ | | Europe (EU) live | **live-eu** | | United States (US) live | **live-us** | | Australia (AU) live | **live-au** | | Northeast Asia (NEA) live | **live-nea** | | India (IN) live | **live-in** | ## See also * [React Native Advanced flow integration guide](https://docs.adyen.com/online-payments/build-your-integration/advanced-flow/?platform=React%20Native) * [3D Secure 2 API Reference](https://docs.adyen.com/online-payments/3d-secure/api-reference) * [Webhooks](https://docs.adyen.com/development-resources/webhooks) * [Cards](https://docs.adyen.com/payment-methods/cards) ![](https://docs.adyen.com/media/43cdd4bbe3a633504925a696dd956471ecc00889309d01bfcc5518273cf5cbb7.png) ![](https://docs.adyen.com/media/43cdd4bbe3a633504925a696dd956471ecc00889309d01bfcc5518273cf5cbb7.png) ![](https://docs.adyen.com/media/ebdb56c1a5bc6d03adbc54e428f98b3c2c254d7c2998f498298a6edb119a3b26.png) ![](https://docs.adyen.com/media/ebdb56c1a5bc6d03adbc54e428f98b3c2c254d7c2998f498298a6edb119a3b26.png) ![](https://docs.adyen.com/media/cae37abc96f90c9c29ae9eb5d1cbeedc6095224184609757fbc7193172081d81.png) ![](https://docs.adyen.com/media/cf87c81de2d975cb5aef9560e77a01180928feeba98065a78463885580b94dfb.png) ![](https://docs.adyen.com/media/9a0f6d294f3eedeaa6a3a5fb51002e6588fb17f6fe4a1b8359e4f5c159ccbccc.svg) ![](https://docs.adyen.com/media/29dd97468df4e9116a0b44188dcf7d6ed98747887cff3ee7d7db3b9d7e0ef881.svg) ![](https://docs.adyen.com/media/9a0f6d294f3eedeaa6a3a5fb51002e6588fb17f6fe4a1b8359e4f5c159ccbccc.svg)