Are you looking for test card numbers?

Would you like to contact support?

Default icon

Web Components integration guide

Build a Components integration that makes payments and handles additional actions from the server side.

Use this guide if you integrated Components before v5.0.0, released in October 2021.

In v5.0.0 we introduced a simplified way of integrating Components, using a single API endpoint. If you implemented Drop-in before v5.0.0, you can keep using the /paymentMethods, /payments, and /payments/details API endpoints, even as you update your Components version.

If you are just starting your integration, refer to our latest Components integration guide instead.

How it works

The following flow applies for each payment method Component:

On this page we describe both server-side and client-side integration steps:

  1. From your server, submit a request to get a list of payment methods available to the shopper.
  2. Add the specific payment method Component to your payments form.
  3. From your server, submit a payment request with the data returned by the Component.
  4. Determine from the response if you need to perform additional actions on your front end, such as to redirect the shopper.
  5. From your server, submit additional payment details.
  6. Present the payment result to the shopper.

Before you begin

If you haven't done so already, follow our Get started guide to set up your test account, get your API key, and install a server-side library.

To make sure that your 3D Secure integration works on Chrome, your cookies need to have the SameSite attribute. For more information, refer to Chrome SameSite Cookie policy.

Step 1: Get available payment methods

When your shopper is ready to pay, get a list of the available payment methods based on their country, device, and the payment amount.

From your server, make a POST /paymentMethods request, specifying:

Parameter name Required Description
merchantAccount -white_check_mark- Your merchant account name.
amount The currency and value of the payment, in minor units. This is used to filter the list of available payment methods to your shopper.
channel The platform of the shopper's device; use Web. This is used to filter the list of available payment methods to your shopper.
countryCode The shopper's country code. This is used to filter the list of available payment methods to your shopper.
shopperLocale By default, the shopperlocale is set to en-US. To change the language, set this to the shopper's language and country code. You also need to set the same locale within your Component configuration.

Here's an example of how you would get the available payment methods for a shopper in the Netherlands, for a payment of 10 EUR:

curl https://checkout-test.adyen.com/v67/paymentMethods \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "countryCode": "NL",
  "amount": {
    "currency": "EUR",
    "value": 1000
  },
  "channel": "Web",
  "shopperLocale": "nl-NL"
}'
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 = "YOUR_X-API-KEY"

response = adyen.checkout.payment_methods({
    :countryCode => 'NL',
    :shopperLocale => 'nl-NL',
    :amount => {
        :currency => 'EUR',
        :value => 1000
    },
    :channel => 'Web',
    :merchantAccount => 'YOUR_MERCHANT_ACCOUNT'
})
// Set your X-API-KEY with the API key from the Customer Area.
String xApiKey = "YOUR_X-API-KEY";
Client client = new Client(xApiKey,Environment.TEST);
Checkout checkout = new Checkout(client);
PaymentMethodsRequest paymentMethodsRequest = new PaymentMethodsRequest();
paymentMethodsRequest.setMerchantAccount("YOUR_MERCHANT_ACCOUNT");
paymentMethodsRequest.setCountryCode("NL");
paymentMethodsRequest.setShopperLocale("nl-NL");
Amount amount = new Amount();
amount.setCurrency("EUR");
amount.setValue(1000L);
paymentMethodsRequest.setAmount(amount);
paymentMethodsRequest.setChannel(PaymentMethodsRequest.ChannelEnum.Web);
PaymentMethodsResponse paymentMethodsResponse = checkout.paymentMethods(paymentMethodsRequest);
// Pass the response to your front end
// Set your X-API-KEY with the API key from the Customer Area.
$client = new \Adyen\Client();
$client->setEnvironment(\Adyen\Environment::TEST);
$client->setXApiKey("YOUR_X-API-KEY");
$service = new \Adyen\Service\Checkout($client);

$params = array(
    "countryCode" => "NL",
    "shopperLocale" => "nl-NL",
    "amount" => array(
        "currency" => "EUR",
        "value" => 1000
    ),
    "channel" => "Web",
    "merchantAccount" => "YOUR_MERCHANT_ACCOUNT"
);
$result = $service->paymentMethods($params);
# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen.Adyen()
adyen.payment.client.platform = "test"
adyen.client.xapikey = 'YOUR_X-API-KEY'

request = {
    'countryCode': 'NL',
    'shopperLocale': 'nl-NL',
    'amount': {
        'value': 1000,
        'currency': 'EUR'
    },
    'channel': 'Web',
    'merchantAccount': 'YOUR_MERCHANT_ACCOUNT'
}
result = adyen.checkout.payment_methods(request)
// Set your X-API-KEY with the API key from the Customer Area.
string apiKey = "YOUR_X-API-KEY";
var client = new Client (apiKey, Environment.Test);
var checkout = new Checkout(client);
var amount = new Adyen.Model.Checkout.Amount("EUR", 1000);
var paymentMethodsRequest = new Adyen.Model.Checkout.PaymentMethodsRequest(merchantAccount: "YOUR_MERCHANT_ACCOUNT")
{ 
    CountryCode = "NL",
    ShopperLocale = "nl-NL",
    Amount = amount,
    Channel = PaymentMethodsRequest.ChannelEnum.Web
};
var paymentMethodsResponse = checkout.PaymentMethods(paymentMethodsRequest);
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 = '[YOUR_X-API-KEY]';
config.merchantAccount = '[YOUR_MERCHANT_ACCOUNT]';
const client = new Client({ config });
client.setEnvironment("TEST");
const checkout = new CheckoutAPI(client);
const paymentsResponse = checkout.paymentMethods({
    merchantAccount: config.merchantAccount,
    countryCode: "NL",
    shopperLocale: "nl-NL",
    amount: { currency: "EUR", value: 1000, },
    channel: "Web"
}).then(res => res);
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:      "[YOUR_X-API-KEY]",
})
res, httpRes, err := client.Checkout.PaymentMethods(&checkout.PaymentMethodsRequest{
    CountryCode: "NL",
    ShopperLocale: "nl-NL",
    Amount: checkout.Amount{
        Value:    1000,
        Currency: "EUR",
    },
    Channel: "Web",
    MerchantAccount: "[YOUR_MERCHANT_ACCOUNT]",
})

The response includes the list of available paymentMethods, ordered by popularity in the shopper's country.

/paymentMethods response
{
 "paymentMethods":[
  {
    "details":[...],
    "name":"Credit Card",
    "type":"scheme"
    ...
  },
  {
    "details":[...],
    "name":"SEPA Direct Debit",
    "type":"sepadirectdebit"
  },
  ...
  ]
}

Pass the response to your front end. You'll use this in the next step to show which payment methods are available for the shopper.

Step 2: Add Components to your payments form

Next, use the Component to render the payment method, and collect the required payment details from your shopper. Install the Adyen Web Node package or use a <script> tag.

  1. Include the following script in the <body> above any other JavaScript in your checkout page: 

    We recommend that you also validate the Subresource Integrity (SRI) hash, which we provide for each version of our JavaScript and CSS files. You can find the SRI hashes in our release notes, under Updating to this version.

    <script src="https://checkoutshopper-test.adyen.com/checkoutshopper/sdk/{VERSION}/adyen.js"
    integrity="sha384-SGA+BK9i1sG5N4BTCgRH6EGbopUK8WG/azn/TeIHYeBEXmEaB+NT+410Z9b1ii7Z"
    crossorigin="anonymous"></script>
    <!-- Adyen provides the SRI hash that you include as the integrity attribute.-->
    <!-- Refer to our release notes to get the SRI hash for the specific version: https://docs.adyen.com/online-payments/release-notes -->
  2. Use the following CSS file:

    <link rel="stylesheet" href="https://checkoutshopper-test.adyen.com/checkoutshopper/sdk/{VERSION}/adyen.css"
    integrity="sha384-oT6lIQpTr+nOu+yFBPn8mSMkNQID9wuEoTw8lmg2bcrFoDu/Ae8DhJVj+T5cUmsM"
    crossorigin="anonymous">
    <!-- Adyen provides the SRI hash that you include as the integrity attribute. -->
    <!-- Refer to our release notes to get the SRI hash for the specific version: https://docs.adyen.com/online-payments/release-notes -->

   You can add your own styling by overriding the rules in this CSS file.

  1. Create a DOM element on your checkout page, placing it where you want the payment method form to be rendered.

     <div id="component-container"></div>

    If you are using JavaScript frameworks such as Vue or React, make sure that you use references instead of selectors and that you don't re-render the DOM element.

  2. Create a configuration object with the following parameters:

    Parameter name Required Description
    paymentMethodsResponse -white_check_mark- The full /paymentMethods response returned in step 1.
    clientKey -white_check_mark- A public key linked to your API credential, used for client-side authentication.
    Web Components versions before 3.10.1 use originKey instead. Find out how to migrate from using originKey to clientKey.
    locale -white_check_mark- The shopper's locale. This is used to set the language rendered in the UI. For a list of supported locales, see Localization.
    environment -white_check_mark- Use test. When you're ready to accept live payments, change the value to one of our live environments
    onChange or onSubmit -white_check_mark- Create an event handler for either of the following:
    - onChange: Called when shopper provides the required payment details
    - onSubmit: Called when the shopper selects the Pay button. This applies if you use our pre-built Pay button. Refer to the showPayButton configuration in Configuring Components.
    In the example below, we use handleOnChange.
    onAdditionalDetails -white_check_mark- Create an event handler, used for native 3D Secure 2, and for native QR code payment methods. In the example below, we use handleOnAdditionalDetails.
       function handleOnChange(state, component) {
           state.isValid // True or false. Specifies if all the information that the shopper provided is valid.
           state.data // Provides the data that you need to pass in the `/payments` call.
           component // Provides the active component instance that called this event.
       }
    
       function handleOnAdditionalDetails(state, component) {
           state.data // Provides the data that you need to pass in the `/payments/details` call.
           component // Provides the active component instance that called this event.
       }
    
       const configuration = {
           locale: "en_US", // The shopper's locale. For a list of supported locales, see https://docs.adyen.com/online-payments/web-components/localization-components.
           environment: "test", // When you're ready to accept live payments, change the value to one of our live environments https://docs.adyen.com/online-payments/components-web#testing-your-integration.  
           clientKey: "YOUR_CLIENT_KEY", // Your client key. To find out how to generate one, see https://docs.adyen.com/development-resources/client-side-authentication. Web Components versions before 3.10.1 use originKey instead of clientKey.
           paymentMethodsResponse: paymentMethodsResponse, // The payment methods response returned in step 1.
           onChange: handleOnChange, // Your function for handling onChange event
           onAdditionalDetails: handleOnAdditionalDetails // Your function for handling onAdditionalDetails event
       };
  3. Use the configuration object to create an instance of AdyenCheckout. In Components versions 5.0.0 or later, the creation of AdyenCheckout is asynchronous:

    const checkout = await AdyenCheckout(configuration);
    const checkout = new AdyenCheckout(configuration);
  4. Then use the checkout.create method to create and mount an instance of the payment method Component.

    Some payment method Components require additional configuration. For more information, refer to our payment method integration guides.

    For example, here is how you would mount the Card Component using its component name, card:

    const card = checkout.create('card').mount('#component-container');

    You can also include optional Card Component configuration.

    When the shopper enters the payment details, the Component will call the onChange event (or onSubmit, if you are using our pre-built Pay button). If state.isValid is true, collect the values passed in state.data. These are the shopper details that you will need to make the payment.

  5. Pass the state.data to your server.

    state from onChange event for Card Component
    {
    isValid: true,
    data: {
      paymentMethod: {
        type: "scheme",
        encryptedCardNumber: "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
        encryptedExpiryMonth: "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
        encryptedExpiryYear: "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
        encryptedSecurityCode: "adyenjs_0_1_18$MT6ppy0FAMVMLH..."
      }
    }
    }

Configuring Components

You can include the following additional configuration when instantiating Components on your payments form:

You can also override the values that you set here by specifying these parameters for individual payment methods at the Component level.

Configuration object Description
showPayButton Adyen provides a Pay button. To use the Pay button for each payment method, set this to true. The Pay button triggers the onSubmit event.

If you want to use your own button and then trigger the submit flow on your own, set this to false and call the .submit() method from your own button implementation. For example, component.submit().
amount Amount to be displayed on the Pay Button. It expects an object with the value and currency properties. For example, { value: 1000, currency: 'USD' }.
setStatusAutomatically v 4.7.0 Set to false to not set the Component status to 'loading' when onSubmit is triggered. Defaults to true.

Events

Use the following events to include additional logic on your checkout page:

Event name Description
onChange(state, component) Called when the shopper has provided the required payment details for the specific payment method.
onError(error) Called when an error occurs in the Component.
onSubmit(state, component) Called when the shopper selects the Pay button.
onAdditionalDetails(state,component) Called when a payment method requires more details.

For example, here are the additional configuration that you need to include to show the pre-built Pay button:

function handleOnSubmit(state, component) {
    state.isValid // True or false. Specifies if all the information that the shopper provided is valid.
    state.data // Provides the data that you need to pass in the `/payments` call.
    component // Provides the active component instance that called this event.
}

const configuration = {
    ...
    showPayButton: true,
    onSubmit: handleOnSubmit,
    amount: {             // Optional. Used to display the amount in the Pay Button.
            value: 1000,
            currency: 'EUR'
        }
};

const checkout = new AdyenCheckout(configuration);

Methods

All Components support the following methods:

Method name Description
mount(selector) Mounts the Component into the DOM returned by the selector.
The selector must be either a valid CSS selector string or an HTMLElement reference.
unmount() Unmounts the Component from the DOM. We recommend to unmount in case the payment amount changes after the initial mount.

Step 3: Make a payment

After the shopper submits their payment details or chooses to pay with a payment method that requires a redirection, you need to make a payment request to Adyen.

From your server, make a /payments request specifying:

Parameter name Required Description
merchantAccount -white_check_mark- Your merchant account name.
amount -white_check_mark- The currency and value of the payment (in minor units). For more information, see Currency codes.
reference -white_check_mark- Your unique reference for this payment.
paymentMethod -white_check_mark- The state.data.paymentMethod from the onChange or onSubmit event from your front end.
returnUrl -white_check_mark- URL to where the shopper should be taken back to after a redirection. The URL can contain a maximum of 1024 characters and should include the protocol: http:// or https://. You can also include your own additional query parameters, for example, shopper ID or order reference number.
applicationInfo If you're building an Adyen solution for multiple merchants, include some basic identifying information, so that we can offer you better support. For more information, refer to Building Adyen solutions.

You need to include additional parameters in your payment request to:

Here's an example of how you would make a payment request for 10 EUR:

curl https://checkout-test.adyen.com/v67/payments \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
  "amount":{
    "currency":"EUR",
    "value":1000
  },
  "reference":"YOUR_ORDER_NUMBER",
  "paymentMethod":{hint:paymentMethod field of an object passed from the front end or client app}STATE_DATA{/hint},
  "returnUrl":"https://your-company.com/checkout?shopperOrder=12xy..",
  "merchantAccount":"YOUR_MERCHANT_ACCOUNT"
}'
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 = "YOUR_X-API-KEY"

# STATE_DATA is the paymentMethod field of an object passed from the front end or client app, deserialized from JSON to a data structure.
paymentMethod = STATE_DATA

response = adyen.checkout.payments({ 
    :paymentMethod => paymentMethod,
    :amount => {
        :currency => 'EUR',
        :value => 1000
    },
    :reference => 'YOUR_ORDER_NUMBER',
    :returnUrl => 'https://your-company.com/checkout?shopperOrder=12xy..',
    :merchantAccount => 'YOUR_MERCHANT_ACCOUNT'
})

# Check if further action is needed.
if response.body.has_key(:action)
   # Pass the action object to your front end
   # response.body[:action]
else
   # No further action needed, pass the resultCode object to your front end
   # response.body[:resultCode]
// Set your X-API-KEY with the API key from the Customer Area.
String xApiKey = "YOUR_X-API-KEY";
Client client = new Client(xApiKey,Environment.TEST);
Checkout checkout = new Checkout(client);
PaymentsRequest paymentsRequest = new PaymentsRequest();
paymentsRequest.setMerchantAccount("YOUR_MERCHANT_ACCOUNT");
// STATE_DATA is the paymentMethod field of an object passed from the front end or client app, deserialized from JSON to a data structure.
paymentsRequest.setPaymentMethod(STATE_DATA)
Amount amount = new Amount();
amount.setCurrency("EUR");
amount.setValue(1000L);
paymentsRequest.setAmount(amount);
paymentsRequest.setReference("YOUR_ORDER_NUMBER");
paymentsRequest.setReturnUrl("https://your-company.com/checkout?shopperOrder=12xy..");
PaymentsResponse paymentsResponse = checkout.payments(paymentsRequest);
// Set your X-API-KEY with the API key from the Customer Area.
$client = new \Adyen\Client();
$client->setEnvironment(\Adyen\Environment::TEST);
$client->setXApiKey("YOUR_X-API-KEY");
$service = new \Adyen\Service\Checkout($client);

// STATE_DATA is the paymentMethod field of an object passed from the front end or client app, deserialized from JSON to a data structure.
$paymentMethod = STATE_DATA;;

$params = array(
    "paymentMethod" => $paymentMethod,
    "amount" => array(
        "currency" => "EUR",
        "value" => 1000
    ),
    "reference" => "YOUR_ORDER_NUMBER",
    "returnUrl" => "https://your-company.com/checkout?shopperOrder=12xy..",
    "merchantAccount" => "YOUR_MERCHANT_ACCOUNT"
);
$result = $service->payments($params);

// Check if further action is needed
if (array_key_exists("action", $result)){
   // Pass the action object to your front end
   // $result["action"]
}
else {
   // No further action needed, pass the resultCode to your front end
   // $result['resultCode']
}
# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen.Adyen()
adyen.payment.client.platform = "test"
adyen.client.xapikey = 'YOUR_X-API-KEY'

# STATE_DATA is the paymentMethod field of an object passed from the front end or client app, deserialized from JSON to a data structure.
paymentMethod = STATE_DATA

result = adyen.checkout.payments({
    'paymentMethod': paymentMethod,
    'amount': {
        'value': 1000,
        'currency': 'EUR'
    },
    'reference': 'YOUR_ORDER_NUMBER',
    'returnUrl': 'https://your-company.com/checkout?shopperOrder=12xy..',
    'merchantAccount': 'YOUR_MERCHANT_ACCOUNT'
})

# 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']
// Set your X-API-KEY with the API key from the Customer Area.
string apiKey = "YOUR_X-API-KEY";
var client = new Client (apiKey, Environment.Test);
var checkout = new Checkout(client);
var amount = new Adyen.Model.Checkout.Amount("EUR", 1000);
var paymentRequest = new Adyen.Model.Checkout.PaymentRequest
{ 
// STATE_DATA is the paymentMethod field of an object passed from the front end or client app, deserialized from JSON to a data structure.
    PaymentMethod = STATE_DATA,
    Amount = amount,
    Reference = "YOUR_ORDER_NUMBER",
    ReturnUrl = @"https://your-company.com/checkout?shopperOrder=12xy..",
};
var paymentResponse = checkout.Payment(paymentRequest);
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 = '[YOUR_X-API-KEY]';
config.merchantAccount = '[YOUR_MERCHANT_ACCOUNT]';
const client = new Client({ config });
client.setEnvironment("TEST");
const checkout = new CheckoutAPI(client);
checkout.payments({
    merchantAccount: config.merchantAccount,
// STATE_DATA is the paymentMethod field of an object passed from the front end or client app, deserialized from JSON to a data structure.
    paymentMethod: STATE_DATA,
    amount: { currency: "EUR", value: 1000, },
    reference: "YOUR_ORDER_NUMBER",
    returnUrl: "https://your-company.com/checkout?shopperOrder=12xy.."
}).then(res => res);
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:      "[YOUR_X-API-KEY]",
})
// STATE_DATA is the paymentMethod field of an object passed from the front end or client app, deserialized from JSON to a data structure.
paymentMethod := STATE_DATA
res, httpRes, err := client.Checkout.Payments(&checkout.PaymentRequest{
    PaymentMethod: paymentMethod,
    Amount: checkout.Amount{
        Value:    1000,
        Currency: "EUR",
    },
    Reference: "YOUR_ORDER_NUMBER",
    ReturnUrl: "https://your-company.com/checkout?shopperOrder=12xy..",
    MerchantAccount: "[YOUR_MERCHANT_ACCOUNT]",
})

Your next steps depend on whether the /payments response contains an action object. Choose your API version:

Description Next steps
no action object No additional steps are needed to complete the payment. Use the resultCode to present the payment result to your shopper.
With action object The shopper needs to do additional actions to complete the payment. 1. Use the action object to create a new Component that handles the required action.
2. Proceed to step 4.

The following example shows a /payments response with action.type: redirect.

/payments response
    {
      "action": {
        "method": "GET",
        "paymentMethodType": "ideal",
        "type": "redirect",
        "url": "https://test.adyen.com/hpp/redirectIdeal.shtml?brandCode=ideal&currencyCode=EUR&issuerId=1121..."
      }
    }
Description Next steps
no action object No additional steps are needed to complete the payment. Use the resultCode to present the payment result to your shopper.
With action object and action.type redirect The shopper is redirected to another website or app to complete the payment. 1. Check the /payments response to know what parameters to expect when the shopper returns to your website.
2. Store the action.paymentData in your server. You'll need this in your next API request.
3. Use the action object to create a new Component that handles the required action.
4. Proceed to step 4.
With action object The shopper needs to do additional actions to complete the payment. 1. Use the action object to create a new Component that handles the required action.
2. Proceed to step 4.

The following example shows a /payments response with action.type: redirect.

/payments response
    {
    ...
      "action": {
        "method": "GET",
        "paymentData": "Ab02b4c0!BQ..",
        "paymentMethodType": "ideal",
        "type": "redirect",
        "url": "https://test.adyen.com/hpp/redirectIdeal.shtml?brandCode=ideal&currencyCode=EUR&issuerId=1121..."
      }
    ...
    }

Step 4: Perform additional front-end actions

Some payment methods require additional action from the shopper such as: to scan a QR code, to authenticate a payment with 3D Secure, or to log in to their bank's website to complete the payment. To handle these additional front-end actions:

  1. Call createFromAction and pass the action object from the previous step. This will return a new Component that you need to mount:

    checkout.createFromAction(action).mount('#my-container');
  2. The Component performs additional front-end actions, depending on the action.type. Your next steps depend on the type of action that the Component performs:
action.type Description Next steps
voucher The Component displays the voucher which the shopper
uses to complete the payment.
1. Proceed to step 6 and inform the shopper that you are waiting for the payment.
2. Wait for the notification webhook to know the payment result.
redirect The Component redirects the shopper to another website or app
to complete the payment.
1. When the shopper returns to your website, your server needs to handle the redirect result.
2. Proceed to step 5 to check the payment result.
qrCode The Component presents the QR code
and calls the onAdditionalDetails event.
1. Get the state.data from the onAdditionalDetails event and pass it your server.
2. Proceed to step 5 to check the payment result.
await The Component shows the waiting screen while the shopper completes the payment.
Depending on the payment outcome, the Component calls the onAdditionalDetails or onError event.
1. Get the state.data object from the onAdditionalDetails or onError event and pass it your server.
2. Proceed to step 5 to check the payment result.
sdk The Component presents the specific payment method's UI as an overlay
and calls the onAdditionalDetails event.
1. Get the state.data from the onAdditionalDetails event and pass it your server.
2. Proceed to step 5 to check the payment result.
threeDS2 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 front end.
2. Use the 3D Secure 2 Component to perform the authentication flow and to complete the payment.

Handle the redirect result

If you receive an action.type redirect, the Component redirects your shopper to another website to complete the payment or go through 3D Secure redirect authentication.

After the shopper completes the payment or authentication, they are redirected back to your returnUrl with an HTTP GET. The returnUrl is appended with a Base64-encoded redirectResult:

  GET /?shopperOrder=12xy..&&redirectResult=X6XtfGC3%21Y... HTTP/1.1
  Host: www.your-company.com/checkout
  1. Get the redirectResult appended to your return URL and pass it to your back end.

    If a shopper completed the payment but failed to return to your website, wait for the notification webhook to know the payment result.

  2. Proceed to step 5.

action.type Description Next steps
voucher The Component displays the voucher which the shopper
uses to complete the payment.
1. Proceed to step 6 and inform the shopper that you are waiting for the payment.
2. Wait for the notification webhook to know the payment result.
redirect The Component redirects the shopper to another website or app
to complete the payment.
1. When the shopper returns to your website, your server needs to handle the redirect result.
2. Proceed to step 5 to check the payment result.
qrCode The Component presents the QR code
and calls the onAdditionalDetails event.
1. Get the state.data from the onAdditionalDetails event and pass it your server.
2. Proceed to step 5 to check the payment result.
await The Component shows the waiting screen while the shopper completes the payment.
Depending on the payment outcome, the Component calls the onAdditionalDetails or onError event.
1. Get the state.data object from the onAdditionalDetails or onError event and pass it your server.
2. Proceed to step 5 to check the payment result.
sdk The Component presents the specific payment method's UI as an overlay
and calls the onAdditionalDetails event.
1. Get the state.data from the onAdditionalDetails event and pass it your server.
2. Proceed to step 5 to check the payment result.
threeDS2Fingerprint The payment qualifies for 3D Secure 2, and will go through either the frictionless or the challenge flow. Use our 3D Secure 2 Components to get the device fingerprint and complete the payment:
threeDS2Challenge The payment qualifies for 3D Secure 2, and the issuer is initiating a challenge flow. Use our 3D Secure 2 Components to present the challenge to your shopper and complete the payment:

Handle the redirect result

The redirect can be for either a redirect payment method or 3D Secure authentication. The instructions are different for each.

Redirect payment method

After the shopper completes the payment, they are redirected back to your returnUrl with the same HTTP method. The returnUrl is appended with a redirectResult:

   GET /?shopperOrder=12xy..&&redirectResult=X6XtfGC3%21Y... HTTP/1.1
   Host: www.your-company.com/checkout
  1. URL-decode the redirectResult appended to your return URL and pass the parameters to your back end.

    If a shopper completed the payment but failed to return to your website, wait for the notification webhook to know the payment result.

  2. Proceed to step 5.

3D Secure authentication

After completing the 3D Secure authentication, the shopper is redirected back to your returnUrl with the same HTTP method. This will be appended with the MD and PaRes variables:

   POST / HTTP/1.1
   Host: www.your-company.com/checkout?shopperOrder=12xy..
   Content-Type: application/x-www-form-urlencoded
   MD=dXlER3BhTEVCazlLd1..&PaRes=eNrNV0mTo7gS..
  1. URL-decode the MD and PaRes, and pass them to your back end.

    If a shopper completed the payment but failed to return to your website, wait for the notification webhook to know the payment result.

  2. Proceed to step 5.

Step 5: Submit additional payment details

If the shopper performed additional action, you need to submit additional details to either complete the payment, or to check the payment result.

Make a /payments/details request, and include:

  • For action.type: redirect, pass in your request:
    • details: Object that contains the URL-decoded redirectResult.
  • For action.type: qrCode, await, sdk, or threeDS2, pass in your request the state.data from the onAdditionalDetails event.

The following example shows how you would submit additional payment details in case of a redirect.

/payments/details request
curl https://checkout-test.adyen.com/v67/payments/details \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
     "details": {
       "redirectResult": "eyJ0cmFuc1N0YXR1cyI6IlkifQ=="
   }
}'

The response includes:

  • pspReference: Our unique identifier for the transaction.
  • resultCode: Indicates the status of the payment. You can use this to present the payment result to your shopper in step 6.

Make a /payments/details request, and include:

  • For action.type: redirect, pass in your request:

    • details: The URL-decoded parameters you received when the shopper was redirected back to your website.
    • paymentData: The value from the /payments response that you stored in your server.
  • For action.type: qrCode, await, sdk, threeDS2Fingerprint, or threeDS2Challenge, pass in your request the state.data from the onAdditionalDetails event.

The example below shows how you would submit additional payment details in case you received an onAdditionalDetails event.

curl https://checkout-test.adyen.com/v66/payments/details \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{hint:object passed from the front end or client app}STATE_DATA{/hint}'
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 = "YOUR_X-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
// Set your X-API-KEY with the API key from the Customer Area.
String xApiKey = "YOUR_X-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);
// Set your X-API-KEY with the API key from the Customer Area.
$client = new \Adyen\Client();
$client->setEnvironment(\Adyen\Environment::TEST);
$client->setXApiKey("YOUR_X-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']
}
# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen.Adyen()
adyen.payment.client.platform = "test"
adyen.client.xapikey = 'YOUR_X-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']
// Set your X-API-KEY with the API key from the Customer Area.
string apiKey = "YOUR_X-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.PaymentsDetails(paymentsDetailsRequest);
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 = '[YOUR_X-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);
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:      "[YOUR_X-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)

Depending on the payment result, you receive a response containing:

  • resultCode: Provides information about the result of the request.
  • pspReference: Our unique identifier for the transaction.
  • action: If you receive this object, you need to perform step 4 again.

If the /payments/details response does not contain an action object, proceed to step 6 to present the payment result to your shopper.

Successful payment response
 {
   "pspReference": "88154795347618C",
   "resultCode": "Authorised"
 }
Refused response
 {
   "pspReference": "89783918347627F",
   "refusalReason": "Not enough balance",
   "resultCode": "Refused"
 }

Step 6: Present the payment result

After the shopper completes the payment and no further actions are required on the front end or client app, use the resultCode to inform the shopper of the payment status.

resultCode Description Action to take
Authorised The payment was successful. Inform the shopper that the payment was successful.
Error Inform the shopper that there was an error processing their payment. You'll receive a refusalReason in the same response, indicating the cause of the error.
Pending The shopper has completed the payment but the final result is not yet known. Inform the shopper that you've received their order, and are waiting for the payment to be completed.
You will receive the final result of the payment in an AUTHORISATION notification.
PresentToShopper Present the voucher or the QR code to the shopper. For a voucher payment method, inform the shopper that you are waiting for their payment. You will receive the final result of the payment in an AUTHORISATION notification.

For a qrCode payment method, wait for the AUTHORISATION notification before presenting the payment result to the shopper.
Refused The payment was refused. Inform the shopper that the payment was refused. Ask the shopper to try the payment again using a different payment method or card.
Received For some payment methods, it can take some time before the final status of the payment is known. Inform the shopper that you've received their order, and are waiting for the payment to clear.
You will receive the final result of the payment in an AUTHORISATION notification.

For other possible resultCode values and recommended messages that you can present to your shopper, see Result codes.

Error handling

In case you encounter errors in your integration, refer to the following:

  • API error codes: If you receive a non-HTTP 200 response, use the errorCode to troubleshoot and modify your request.
  • Payment refusals: If you receive an HTTP 200 response with an Error or Refused resultCode, check the refusal reason and, if possible, modify your request.

Test and go live

Before going live, use our test cards numbers to test your integration. We recommend testing each payment method that you intend to offer to your shoppers.

You can check the status of a test payment in your Customer Area, under TransactionsPayments.

When you are ready to go live, you need to:

  1. Apply for a live account.
  2. Assess your PCI DSS compliance by submitting the Self-Assessment Questionnaire-A.
  3. Configure your live account
  4. Submit a request to add payment methods in your live Customer Area .
  5. Switch from test to our live endpoints.
  6. Load AdyenCheckout from one of our live environments closest to where your shoppers are.
    To do so, set the environment configuration field to one of the following values:

    • Europe: live
    • Australia: live-au
    • US: live-us

    Make sure environment matches the region of the live endpoints you're connecting to.

See also

Next steps