How it works

From an implementation perspective, a integration contains:

Server-side: makes API requests to get available payment methods, make a payment, and (if required) submit additional payment data.
Client-side: Redirect collects the shopper's details to make the payment request and to handle any other actions like redirects or 3D Secure authentication.
Webhook server: receives the webhooks with the outcome of each payment.

The flow, including server-side and client-side steps, is as follows:

From your server, submit a request to get a list of payment methods available to the shopper.
Configure and launch the Component to collect the shopper's details.
From your server, make a payment request with data that you receive from the Component.
Handle additional client-side actions, if required.
From your server, send additional payment details that you receive from the Component, if required.
Get the payment outcome to inform the shopper and update your order management system.

This flow applies for every payment method Component.

Before you begin

Before you begin to integrate, make sure you have followed the Get started with Adyen guide to:

Get an overview of the steps needed to accept live payments.
Create your test account.

After you have created your test account:

Get your API key.
Get your client key.
Set up webhooks to know the payment outcome.

Step 1: Install an API library

We provide server-side API libraries for several programming languages, available through common package managers, like Gradle and npm, for easier installation and version management. Our API libraries will save you development time, because they:

Use an API version that is up to date.
Have generated models to help you construct requests.
Send the request to Adyen using their built-in HTTP client, so you don't have to create your own.

Try our example integration

Run it in Gitpod.
Clone the repository.

Requirements

Java 11 or later.

Installation

You can use Maven, adding this dependency to your project's POM.

You can find the latest version on GitHub. Alternatively, you can download the release on GitHub.

Setting up the client

Create a singleton resource that you use for the API requests to Adyen:

Try our example integration

Run it in Gitpod.
Clone the repository.

Requirements

PHP 7.3 or later.
cURL with SSL support.
The JSON PHP extension.
The list of dependencies from the composer require list.

Installation

You can use Composer. Follow the installation instructions if you don't already have composer installed.

In your PHP script, make sure you include the autoloader:

Alternatively, you can download the release on GitHub.

Set up the client

Create a singleton resource that you use for the API requests to Adyen:

Requirements

.NET standard 2.0 or later.
For Terminal API certificate validation, set the application to either of the following:
- .NET core 2.1 or later
- .NET framework 4.6.1 or later

Installation

You can use NuGet:

Alternatively, you can download the release on GitHub.

Set up the client

Create a singleton resource that you use for the API requests to Adyen:

Try our example integration

Run it in Gitpod.
Clone the repository.

Requirements

Node.js version 18 or later.

Installation

You can use npm:

Alternatively, you can download the release on GitHub.

Setting up the client

Create a singleton resource that you use for the API requests to Adyen:

Try our example integration

Run it in Gitpod.
Clone the repository.

Requirements

Go 1.13 or later.

Installation

You can use Go modules:

Alternatively, you can download the release on GitHub.

Set up the client

Create a singleton resource that you use for the API requests to Adyen:

Try our example integration

Run it in Gitpod.
Clone the repository.

Requirements

Python 3.6 or later.
(Optional) Packages: Requests or PycURL

Installation

You can use pip:

Alternatively, you can download the release on GitHub.

Set up the client

Create a singleton resource that you use for the API requests to Adyen:

Try our example integration

Run it in Gitpod.
Clone the repository.

Requirements

Ruby 2.7 or later.

Installation

You can use RubyGems:

Alternatively, you can download the release on GitHub.

Run bundle install to install dependencies.

Set up the client

Create a singleton resource that you use for the API requests to Adyen:

Step 2: Get available payment methods

When the 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, including:

We recommend that you include all the optional parameters to get the most accurate list of available payment methods.

Parameter name	Required	Description
`merchantAccount`		Your merchant account name.
`amount`		The `currency` and `value` of the payment, in minor units.
`channel`		Use Android. Adyen returns only the payment methods available for Android.
`countryCode`		The shopper's country code. Adyen returns only the payment methods available in this country.
`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 `ShopperLocale` within your Drop-in configuration.

For example, to get available payment methods for a shopper in the Netherlands, for a payment of 10 EUR:

The response includes the list of available paymentMethods:

You must pass the response to your front end to launch and show Components.

Step 3: Set up Components

1: Import the library

The default implementation is with Jetpack Compose, but you can import the library without Jetpack Compose instead.

Import the compatibility module in your build.gradle file:

2: Create the configuration object

Set the following properties in the configuration object:

Property	Required	Description
`amount`	If you want to show the amount on the Pay button.	The currency and value of the payment amount shown on the Pay button.
`shopperLocale`		The shopper's locale. To use the device's default locale, replace this with your context.
`environment`		Use `Environment.TEST` for testing. When going live, use one of our live environments.
`clientKey`		Your client key.

Call the build function.

For example, to configure the card Component:
Implement methods in ComponentCallback to pass data between your frontend app and your backend server.

Method Description

onSubmit Make a /payments request.

onAdditionalDetails Make a /payments/details request.

onError Handle an error if the Component encounters one.

For example, for the card Component:

Step 4: Launch and show the Component

Deserialize the /paymentMethods response to a PaymentMethodsApiResponse object:
Create the Component and attach it to a view. For example:

Your app shows the Component.

Step 5: Make a payment

When the shopper enters their payment details and selects the Pay button, the onSubmit method in your ComponentCallback class is called, passing the paymentComponentJson object.

Pass the paymentComponentJson object to your backend server.

From your server, make a POST /payments request, including:

Parameter name	Required	Description
`merchantAccount`		Your merchant account name.
`amount`		The `currency` and `value` of the payment, in minor units.
`reference`		Your unique reference for this payment.
`paymentMethod`		The `paymentComponentData.paymentMethod` from your client app.
`returnUrl`		In case of a redirection, this is the URL to where your shopper is redirected after they complete the payment. Maximum length: 256 characters. Get this URL from the `RedirectComponent.getReturnUrl(context)`.
`applicationInfo`		If you're building an Adyen solution for multiple merchants, include some basic identifying information, so that we can offer you better support.

You must include additional parameters in your payment request to:

Integrate some payment methods. For more information, refer to our payment method integration guides.
Make use of our risk management features. For more information, see Required risk fields.
Use native 3D Secure 2 authentication.
Tokenize your shopper's payment details or make recurring payments.

For example, to make a payment request for EUR 10:

Your next steps depend on if the /payments response contains an action object:

	Description	Next steps
No `action` object	No additional steps are needed to complete the payment.	1. Pass the `resultCode` from your backend server to your frontend app. 2. Get the payment outcome.
With `action` object	The shopper needs to do additional actions to complete the payment.	1. Pass the `action` object from your backend server to your frontend app. 2. Call `handleAction` from your Component, passing the `action` object and your `activity`. 3. Send additional payment details.

The following example shows a /payments response with action.type: threeDS2 that you need to handle:

Error handling

If the /payments request fails, show the error to the shopper in your client-side UI.

Step 6: Send additional payment details

Some payment methods require you to handle additional frontend actions. For example, to authenticate a payment with 3D Secure or to redirect the shopper to another app.

Handle an action without a redirect

If you get an action without a redirect:

The Component calls the onAdditionalDetails method in your ComponentCallback class passing, the actionComponentJson object. Pass the object to your backend server.
From your server, make a POST /payments/details request, including actionComponentJson object:
Pass the /payments/details response from your backend server to your frontend app.

Handle a redirect

If the shopper was redirected to another website or app, handle when the shopper is redirected back to your app:

Add an IntentFilter to your Activity that handles redirects.

The android:host value is your package name at build time. This must match the returnUrl from the /payments request. To get your returnUrl, you can use the RedirectComponent.getReturnUrl(context) function.
Get the result of the redirect from your Activity. Pass the Intent to the Component. Depending on your activity's launch mode, you get the intent in either onCreate or onNewIntent.
The Component notifies you through the ComponentCallback.onAdditionalDetails method with the actionComponentData object from intent.data. Pass the object to your backend server.
From your server, make a POST /payments/details request.
Pass the /payments/details response from your server to your frontend app.

Step 7: Get the payment outcome

1. Inform the shopper

Use the resultCode from the API response to show the shopper the current payment status. This synchronous response doesn't give you the final outcome of the payment. You get the final payment status in a webhook that you use to update your order management system.

2. Update your order management system

You get the outcome of each payment asynchronously, in an AUTHORISATION webhook. Use the merchantReference from the webhook to match it to your order reference.
For a successful payment, the event contains success: true.

For an unsuccessful payment, you get success: false, and the reason field has details about why the payment was unsuccessful.

Test and go live

Before going live, use our list of test cards and other payment methods 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 Transactions > Payments.

To debug or troubleshoot test payments, you can also use API logs in your test environment.

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

Apply for a live account. Review the process to start accepting payments on Get started with Adyen.
Assess your PCI DSS compliance by submitting the Self-Assessment Questionnaire-A.
Configure your live account.
Submit a request to add payment methods in your live Customer Area .
Switch from test to our live endpoints.
Load from one of our live environments and set the environment to match your live endpoints:

Endpoint region Android

EU EUROPE

APSE APSE

AU AUSTRALIA

US UNITED_STATES

IN INDIA

Next steps

required

Modify payments

Find out how to cancel, refund, or capture a payment using our API.

Add payment methods

Learn about payment methods and how to add them to your account.

Tokenization

Save shopper payment details for later payments.

3D Secure authentication

Comply with regulations such as PSD2 SCA in Europe.

Advanced flow integration guide