Sessions flow integration guide

Start accepting payments on your website or app.

Web

iOS

Android

React Native

Flutter

Drop-in

Use our pre-built UI for accepting payments

Components

Use our customizable UI components

Flutter Components

Render individual payment methods anywhere in your app.

Supported payment methods

Cards, buy now pay later, wallets, and many more.

See all supported payment methods

Features

Low development time to integrate each payment method component
UI styling customization for each payment method
Flexibility to add payment method components with configuration for each
3D Secure 2 support using the 3D Secure 2 Component

Start integrating with Flutter Components

Choose your version

1.2.0

Adyen Flutter on GitHub

View the Adyen Flutter repository
View our example integrations

Components are our pre-built UI solution for accepting payments in your app. Each Component renders a payment method you can render anywhere in your app. Your server makes one API request to the /sessions endpoint.

Requirements

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.

Required versions:

iOS 12 or later.
Android 5.0 or later.
Kotlin 1.8 or later.
Gradle v8 or later.

How it works

For a Components integration, you must implement the following parts:

Your payment server: sends the API request to create a payment session.
Your client app: shows the the Component UI where the shopper makes the payment. The Component uses the data from the API responses to handle the payment flow and additional actions on your client app.
Your webhook server: receives webhooks that include the outcome of each payment.

The parts of your integration work together to complete the payment flow:

The shopper goes to the checkout page.
Your server uses the shopper's country and currency information from your client to create a payment session.
Your client creates an instance of the Component using the session data from the server.
The Component collects the shopper's payment details, handles additional actions, and presents the payment result to the shopper.
Your webhook server receives the notification containing the payment outcome.

If you are integrating these parts separately, you can start at the corresponding part of this integration guide:

Payment server

Go to the integration steps for your server.

Client

Go to the integration steps for your client app.

Webhook server

Go to the integration steps for your webhook server.

Install an API library

Payment server

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 do not 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.

Add the API library

 <dependency>
  <groupId>com.adyen</groupId>
  <artifactId>adyen-java-api-library</artifactId>
  <version>LATEST_VERSION</version>
</dependency>

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:

Set up your client

 // Import the required classes.
package com.adyen.service;
 
import com.adyen.Client;
import com.adyen.service.checkout.PaymentsApi;
import com.adyen.model.checkout.Amount;
import com.adyen.model.checkout.CreateCheckoutSessionRequest;
import com.adyen.model.checkout.CreateCheckoutSessionResponse;
import com.adyen.enums.Environment;
import com.adyen.service.exception.ApiException;
 
import java.io.IOException;
 
public class Snippet {
 
    public Snippet() throws IOException, ApiException {
        // Set up the client and service.
        Client client = new Client("ADYEN_API_KEY", Environment.TEST);
    }
}

Create a payment session

Payment server

A payment session is a resource with information about a payment flow initiated by the shopper. This resource has all the information required to handle all the stages of a payment flow. You can configure this resource with information like available payment methods, payment amount, or line items.

To create a payment session, make a POST /sessions request, including:

Parameter name	Required	Description
`merchantAccount`		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.
`returnUrl`		The URL where the shopper should return after a redirection. For iOS, use the custom URL for your app, for example, `my-app://adyen`, to take the shopper back to your app. For more information on setting a custom URL scheme, read the Apple Developer documentation. You can also include your own additional query parameters, for example, shopper ID or order reference number. Maximum length: 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.
`reference`		Your unique reference for the payment. Minimum length: three characters.
`expiresAt`		The session expiry date in ISO8601 format, for example 2023-11-23T12:25:28Z, or 2023-05-27T20:25:28+08:00. When not specified, the expiry date is set to 1 hour after session creation. You cannot set the session expiry to more than 24 hours after session creation.
`countryCode`		The shopper's country/region. This is used to filter the list of available payment methods to your shopper. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).
`channel`		The platform where the payment is taking place. Use iOS or Android. Strongly recommended because this field is used for 3D Secure.
`shopperLocale`		The language that the payment methods will appear in. Set it to the shopper's language and country code. The default is en-US. the Component also uses this locale, if it is available.
`shopperEmail`		The shopper's email address. Strongly recommended because this field is used in a number of risk checks, and for 3D Secure.
`shopperReference`		Your reference to uniquely identify this shopper. Minimum length: three characters. Do not include personally identifiable information, for example name or email address. Strongly recommended because this field is used in a number of risk checks.
`applicationInfo`		If you are 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.

The following example shows how to create a session for a payment of 10 EUR:

 curl https://checkout-test.adyen.com/checkout/v70/sessions \
-H 'x-api-key: ADYEN_API_KEY' \
-H "idempotency-key: YOUR_IDEMPOTENCY_KEY" \
-H 'content-type: application/json' \
-d '{
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "amount": {
      "value": 1000,
      "currency": "EUR"
  },
  "returnUrl": "my-app://adyen",
  "reference": "YOUR_PAYMENT_REFERENCE",
  "countryCode": "NL"
}'

The response contains:

sessionData: the payment session data.
id: a unique identifier for the session data.
The request body.

Pass the response to your client app, putting it in the sessionResponse object.

HTTP 201 /sessions response body

 {
    "amount": {
        "currency": "EUR",
        "value": 1000
    },
    "countryCode": "NL",
    "expiresAt": "2021-08-24T13:35:16+02:00",
    "id": "CSD9CAC34EBAE225DD",
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "reference": "YOUR_PAYMENT_REFERENCE",
    "returnUrl": "my-app://adyen",
    "sessionData": "Ab02b4c.."
}

API error handling

If you do not get an HTTP 201 response, use the errorCode field and the list of API error codes to troubleshoot.

Add Components to your app

Client app

Add different configurations for iOS and Android, 'the Component', and some payment methods.

1. Add platform-specific configurations

Add the return URL handler to your AppDelegate.swift file:

Add return URL handler

 override func application(_: UIApplication, open url: URL, options _: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
    RedirectComponent.applicationDidOpen(from: url)
return true
}

In your app, add a custom URL scheme that matches the return URL.
For Apple Pay, do the following:
- Complete the steps to set up Apple Pay with your own certificate.
- In your Runner target, add Apple Pay as a capability.
- In your Runner target, enter your merchant ID.

2. Create a configuration object

Create a configuration object with the following properties:

Parameter	Required	Description
`environment`		Use test. When you are ready to accept live payments, change the value to one of our live environments.
`clientKey`		A public key linked to your API credential, used for client-side authentication.
`countryCode`		The shopper's country/region. This is used to filter the list of available payment methods to your shopper. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).
`shopperLocale`		By default, this is set to en-US. To change the language, set this to the shopper's language and country code. If you included `shopperLocale` in your /sessions request, the Component uses that one.
`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.

Most payment methods use the InstantComponent that takes the InstantComponentConfiguration, so they do not have specific configuration.

Some payment methods use another type of Component that requires specific configuration. Check the Github repo for configuration for different payment method Components.

Create an InstantComponentConfiguration object:

Create the configuration object

 final InstantComponentConfiguration instantComponentConfiguration = InstantComponentConfiguration(
  // Change the environment to live to accept live payments.
  environment: Environment.test,
   clientKey: CLIENT_KEY,
   countryCode: COUNTRY_CODE,
   shopperLocale: SHOPPER_LOCALE, // Optional.
   amount: AMOUNT, // Optional.
);

3. Initialize Components

Call the create method, passing the following:

Parameter	Required	Description
`sessionId`		`sessionResponse.id`: the `id` from the /sessions response.
`sessionData`		`sessionData`: the `sessionData` from the /sessions response.
`configuration`		The configuration object you created.

Call the create method

 final SessionCheckout sessionCheckout = await AdyenCheckout.session.create(
   sessionId: sessionResponse.id,
   sessionData: sessionResponse.sessionData,
   configuration: instantComponentConfiguration, // In this example, we use the InstantComponentConfiguration you created.
);