---
title: "Sessions flow integration guide"
description: "Start accepting payments on your website or app."
url: "https://docs.adyen.com/online-payments/build-your-integration/sessions-flow"
source_url: "https://docs.adyen.com/online-payments/build-your-integration/sessions-flow.md"
canonical: "https://docs.adyen.com/online-payments/build-your-integration/sessions-flow"
last_modified: "2023-03-10T14:38:00+01:00"
language: "en"
---

# Sessions flow integration guide

Start accepting payments on your website or app.

[View source](/online-payments/build-your-integration/sessions-flow.md)

## Web Drop-in

Use our pre-built UI for accepting payments

### Version Update

## Introducing Web v6

### Improvements

The Web v6 library introduces the following improvements:

* Reduced bundle size through tree shaking
* Enhanced design
* Enhanced Typescript developer experience
* Better alignment of express payment methods
* Added support for 6 localizations
* Support for Apple Pay Order tracking
* Improve AVS checks for Google Pay and Apple Pay

To upgrade your existing integration, see [Upgrade to Adyen Web v6](/online-payments/upgrade-your-integration/upgrade-to-web-v6)

### Before You Begin

## Requirements

Before you begin, take into account the following requirements, limitations, and preparations.

| Requirement                                                                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Integration type**                                                            | Use this information to build an online payments integration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| **[Customer Area roles](/account/user-roles)**                                  | Make sure that you have the following roles:- **Merchant admin role**
- **Manage API credentials**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| **[Adyen API credentials](/development-resources/api-credentials)**             | Make sure that you have created the following:- [API credential](/development-resources/api-credentials/#new-credential)
- [API key](/development-resources/api-credentials/#generate-api-key)
- [Client key](/development-resources/client-side-authentication/#get-your-client-key)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| **[Adyen API credential roles](/development-resources/api-credentials/roles/)** | Make sure that you have the [roles for payments](/development-resources/api-credentials/roles/#roles-for-payments) that are assigned by default.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| **[Webhooks](/development-resources/webhooks)**                                 | Subscribe to the following webhooks:- Standard webhook with [default event codes](/development-resources/webhooks/webhook-types/#default-event-codes)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| **Limitations**                                                                 | Make sure that your integration follows our recommended best practices:- **[\<iframe>](/online-payments/best-practices/#avoid-iframe-elements)**: an \<iframe> must be hosted on the same domain as the parent window to support payment flows that use redirects.
- **[WebViews](/online-payments/best-practices/#avoid-webviews)**: we do not recommend using WebViews in native apps due to security and functionality limitations. Use native equivalents instead.
- **[Server-side Rendering (SSR)](/online-payments/best-practices/#manage-server-side-rendering-ssr-)**: if you use SSR, ensure the `AdyenCheckout` instance and Components are initialized on the client side.
- **[Browser support](/online-payments/best-practices/#supported-browsers)**: we support recent versions of all major browsers.For [3D Secure 2](/online-payments/3d-secure):- A strict [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/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 specify to use the redirect flow when creating a session if you do not want to adjust your CSP. |
| **Setup steps**                                                                 | Make sure that you have done the following:- [Set up your test account](/online-payments/integration-checklist/#set-up-your-test-account).
- [Got an overview of what is required before you accept live payments](/online-payments/integration-checklist/#set-up-your-test-account).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

## How it works

For a Drop-in integration, you must implement the following parts:

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

### Integration steps

To integrate Drop-in in your web application:

1. [Install an API library](#install-api-library) on your server.
2. [Create a session](#create-payment-session) from your server.
3. [Install the Adyen Web library](#install-adyen-web) on your front end.
4. [Create a DOM element](#create-container-element) for Drop-in.
5. [Configure and create an instance of `AdyenCheckout`](#configure).
6. [Configure and create an instance of Drop-in](#create-instance).
7. [Handle redirects](#handle-the-redirect).
8. [Show the payment status](#inform-the-shopper) to your shopper.
9. [Update your order management system](#update-your-order-management-system).
10. [Test your integration and go live](#test-and-go-live).

### Payment flow

The parts of your integration work together to complete the payment flow. The payment flow is the same for all payments:

1. The shopper goes to the checkout page.
2. Your server uses the shopper's country and currency information from your client to create a payment session.
3. Your client creates an instance of Drop-in using the session data from the server.
4. Drop-in shows the available payment methods, collects the shopper's payment details, handles additional actions, and presents the payment result to the shopper.
5. Your webhook server receives the notification containing the payment outcome.

![](/user/pages/filters/sessions-flow-integration/web/5-12-0/02.how-it-works/sessions-drop-in.svg?decoding=auto\&fetchpriority=auto)

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

[![](/user/pages/reuse/online-payments/how-it-works-parts/servers.svg?decoding=auto\&fetchpriority=auto)](/#install-api-library)

[Payment server](/#install-api-library)

[Go to the integration steps for your server.](/#install-api-library)

[![](/user/pages/reuse/online-payments/how-it-works-parts/browser-developers.svg?decoding=auto\&fetchpriority=auto)](/#prepare-your-front-end)

[Client website](/#prepare-your-front-end)

[Go to the integration steps for your client website.](/#prepare-your-front-end)

[![](/user/pages/reuse/online-payments/how-it-works-parts/event-code.svg?decoding=auto\&fetchpriority=auto)](/#update-your-order-management-system)

[Webhook server](/#update-your-order-management-system)

[Go to the integration steps for your webhook server.](/#update-your-order-management-system)

### Install Api Library

## 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.

### Tab: Java

##### Try our example integration

![](/reuse/development-resources/install-api-library/java/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-java-spring-online-payments#checkout-example).\
![](/reuse/development-resources/install-api-library/java/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-java-spring-online-payments).

#### Requirements

* Java 11 or later.

#### Installation

You can use [Maven](https://maven.apache.org), adding this dependency to your project's POM.

**Add the API library**

```xml
<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](https://github.com/Adyen/adyen-java-api-library/releases).

#### Setting up the client

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

**Set up your client**

```java
// 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);
    }
}
```

### Tab: PHP

##### Try our example integration

![](/reuse/development-resources/install-api-library/php/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-php-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/php/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-php-online-payments).

#### 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](https://getcomposer.org/). Follow the [installation instructions](https://getcomposer.org/doc/00-intro.md) if you do not already have composer installed.

**Install the API library**

```bash
composer require adyen/php-api-library
```

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

**Include the autoloader**

```php
require __DIR__ . '/vendor/autoload.php';
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-php-api-library/releases).

#### Set up the client

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

**Set up your client**

```php
use Adyen\Model\Checkout\Amount;
use Adyen\Model\Checkout\CreateCheckoutSessionRequest;
use Adyen\Service\Checkout\PaymentsApi;

// Include your idempotency key when you make an API request.
$requestOptions['idempotencyKey'] = "YOUR_IDEMPOTENCY_KEY";

// Set up the client and service.
$client = new \Adyen\Client();
$client->setXApiKey('ADYEN_API_KEY');
$client->setEnvironment(\Adyen\Environment::TEST);

$service = new PaymentsApi($client);
```

### Tab: C\#

#### 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](https://www.nuget.org/packages/Adyen/):

**Install the API library**

```bash
PM> Install-Package Adyen -Version LATEST_VERSION
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-dotnet-api-library).

#### Set up the client

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

**Set up your client**

```cs
using Adyen;
using Adyen.Model.Checkout;
using Adyen.Service.Checkout;
using Environment = Adyen.Model.Environment;

class Program
{
    static void Main()
    {
        // Set up the client and service.
        var config = new Config
        {
            XApiKey = "ADYEN_API_KEY",
            Environment = Environment.Test
        };
        var client = new Client(config);
        var checkout = new PaymentsService(client);

        // Include your idempotency key when you make an API request.
        var requestOptions = new Adyen.Model.RequestOptions { IdempotencyKey = "YOUR_IDEMPOTENCY_KEY" };
    }
}
```

### Tab: NodeJS

##### Try our example integration

![](/reuse/development-resources/install-api-library/node-js/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-node-online-payments#checkout-example).\
![](/reuse/development-resources/install-api-library/node-js/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-node-online-payments).

#### Requirements

* Node.js version 18 or later.

#### Installation

You can use [npm](https://www.npmjs.com/):

**Install the API library**

```bash
npm install --save @adyen/api-library
npm update @adyen/api-library
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-node-api-library/releases).

#### Setting up the client

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

**Set up your client**

```js
// Require the parts of the module you want to use.
const { Client, CheckoutAPI, Types} = require("@adyen/api-library");

// Set up the client and service.
const client = new Client({ apiKey: "ADYEN_API_KEY", environment: "TEST" });
const checkoutApi = new CheckoutAPI(client);

// Include your idempotency key when you make an API request.
const requestOptions = { idempotencyKey: "YOUR_IDEMPOTENCY_KEY" };
```

### Tab: Go

##### Try our example integration

![](/reuse/development-resources/install-api-library/go/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-golang-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/go/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-golang-online-payments).

#### Requirements

* Go 1.13 or later.

#### Installation

You can use [Go modules](https://github.com/golang/go/wiki/Modules):

**Install the API library**

```shell
go get github.com/adyen/adyen-go-api-library/vLATEST_VERSION
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-go-api-library).

#### Set up the client

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

**Set up your client**

```go
package main

import (
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/adyen"
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/checkout"
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/common"
)

// Create a payment object.

func main () {
	client := adyen.NewClient(&common.Config{
		ApiKey: "ADYEN_API_KEY",
		Environment: common.TestEnv,
	})
	service := client.Checkout()
```

### Tab: Python

##### Try our example integration

![](/reuse/development-resources/install-api-library/python/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-python-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/python/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-python-online-payments).

#### Requirements

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

#### Installation

You can use [pip](https://pip.pypa.io/en/stable/):

**Install the API library**

```py
pip install Adyen
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-python-api-library).

#### Set up the client

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

**Set up your client**

```py
import Adyen

# Set up the client and service.
adyen = Adyen.Adyen()
adyen.client.xapikey = "ADYEN_API_KEY"
adyen.client.platform = "test" # The environment that the library is used in.
```

### Tab: Ruby

##### Try our example integration

![](/reuse/development-resources/install-api-library/ruby/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-rails-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/ruby/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-rails-online-payments).

#### Requirements

* Ruby 2.7 or later.

#### Installation

You can use [RubyGems](https://rubygems.org/):

**Install the API library**

```bash
gem install adyen-ruby-api-library
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-ruby-api-library/releases).

Run `bundle install` to install dependencies.

#### Set up the client

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

**Set up your client**

```ruby
require 'adyen-ruby-api-library'

# Set up the client and service.
adyen = Adyen::Client.new
adyen.api_key = 'ADYEN_API_KEY'
adyen.env = :test # The environment that the library is used in.
```

## Create a 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 [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) request, including:

| Parameter name                                                                                                                                 | Required                                                                                                      | Description                                                                                                                                                                                                                                                                                                     |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `merchantAccount`                                                                                                                              | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your merchant account name.                                                                                                                                                                                                                                                                                     |
| `amount`                                                                                                                                       | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The `currency` and `value` of the payment, in [minor units](/development-resources/currency-codes). This is used to filter the list of available payment methods to your shopper.                                                                                                                               |
| `returnUrl`                                                                                                                                    | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | URL to where the shopper should be taken back to after a redirection. 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`                                                                                                                                    | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your unique reference for the payment. Minimum length: three characters.                                                                                                                                                                                                                                        |
| `countryCode`                                                                                                                                  |                                                                                                               | The shopper's country code. This is used to filter the list of available payment methods to your shopper. If not set, setting the `locale` is required in the front-end [global configuration](#configure).                                                                                                     |
| `channel`                                                                                                                                      |                                                                                                               | The platform where the payment is taking place. Use **Web**.                                                                                                                                                                                                                                                    |
| `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.                                 |
| `shopperLocale`                                                                                                                                |                                                                                                               | The language that the payment methods will appear in if the `locale` in your front-end [global configuration](#configure) isn't set. Set it to the shopper's language and country code. The default is **en-US**.                                                                                               |
| `shopperEmail`                                                                                                                                 |                                                                                                               | The shopper's email address. Strongly recommended because this field is used in a number of [risk checks](/risk-management/configure-your-risk-profile/risk-field-reference), and for 3D Secure.                                                                                                                |
| `shopperReference`                                                                                                                             |                                                                                                               | Your reference to uniquely identify this shopper. Strongly recommended because this field is used in a number of [risk checks](/risk-management/configure-your-risk-profile/risk-field-reference).                                                                                                              |
| `payable`                                                                                                                                      |                                                                                                               | Checkout API v72 or later. If you want to support [updating the amount](#update-amount) after creating the payment session, set to **false**.                                                                                                                                                                   |
| [`applicationInfo`](/development-resources/building-adyen-solutions)                                                                           |                                                                                                               | If you are building an Adyen solution for multiple merchants, include some basic identifying information, so that we can offer you better support.                                                                                                                                                              |
| [nativeThreeDS](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-authenticationData-threeDSRequestData-nativeThreeDS) |                                                                                                               | When set to **disabled**, the redirect flow is used for [3D Secure 2 authentication](/online-payments/3d-secure). This lets you use the redirect flow to avoid adjusting your [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) to load the 3D Secure 2 interfaces. |

Here is an example of how to create a session for a payment of **10** EUR:

#### curl

```bash
curl https://checkout-test.adyen.com/v71/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": "https://your-company.example.com/checkout?shopperOrder=12xy..",
  "reference": "YOUR_PAYMENT_REFERENCE",
  "countryCode": "NL"
}'
```

#### Java

```java
// Adyen Java API Library v27.0.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, additionally include your liveEndpointUrlPrefix.
Client client = new Client("ADYEN_API_KEY", Environment.TEST);

// Create the request object(s)
Amount amount = new Amount()
  .currency("EUR")
  .value(1000L);

CreateCheckoutSessionRequest createCheckoutSessionRequest = new CreateCheckoutSessionRequest()
  .reference("YOUR_PAYMENT_REFERENCE")
  .amount(amount)
  .merchantAccount("YOUR_MERCHANT_ACCOUNT")
  .countryCode("NL")
  .returnUrl("https://your-company.example.com/checkout?shopperOrder=12xy..");

// Send the request
PaymentsApi service = new PaymentsApi(client);
CreateCheckoutSessionResponse response = service.sessions(createCheckoutSessionRequest, new RequestOptions().idempotencyKey("UUID"));
```

#### PHP

```php
// Adyen PHP API Library v19.0.0
use Adyen\Client;
use Adyen\Environment;
use Adyen\Model\Checkout\Amount;
use Adyen\Model\Checkout\CreateCheckoutSessionRequest;
use Adyen\Service\Checkout\PaymentsApi;

$client = new Client();
$client->setXApiKey("ADYEN_API_KEY");
// For the live environment, additionally include your liveEndpointUrlPrefix.
$client->setEnvironment(Environment::TEST);


// Create the request object(s)
$amount = new Amount();
$amount
  ->setCurrency("EUR")
  ->setValue(1000);

$createCheckoutSessionRequest = new CreateCheckoutSessionRequest();
$createCheckoutSessionRequest
  ->setReference("YOUR_PAYMENT_REFERENCE")
  ->setAmount($amount)
  ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT")
  ->setCountryCode("NL")
  ->setReturnUrl("https://your-company.example.com/checkout?shopperOrder=12xy..");

$requestOptions['idempotencyKey'] = 'UUID';

// Send the request
$service = new PaymentsApi($client);
$response = $service->sessions($createCheckoutSessionRequest, $requestOptions);
```

#### C\#

```cs
// Adyen .net API Library v17.0.0
using Adyen;
using Environment = Adyen.Model.Environment;
using Adyen.Model;
using Adyen.Model.Checkout;
using Adyen.Service.Checkout;

// For the live environment, additionally include your liveEndpointUrlPrefix.
var config = new Config()
{
    XApiKey = "ADYEN_API_KEY",
    Environment = Environment.Test
};
var client = new Client(config);

// Create the request object(s)
Amount amount = new Amount
{
  Currency = "EUR",
  Value = 1000
};

CreateCheckoutSessionRequest createCheckoutSessionRequest = new CreateCheckoutSessionRequest
{
  Reference = "YOUR_PAYMENT_REFERENCE",
  Amount = amount,
  MerchantAccount = "YOUR_MERCHANT_ACCOUNT",
  CountryCode = "NL",
  ReturnUrl = "https://your-company.example.com/checkout?shopperOrder=12xy.."
};

// Send the request
var service = new PaymentsService(client);
var response = service.Sessions(createCheckoutSessionRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"});
```

#### Go

```go
// Adyen Go API Library v10.4.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, additionally include your liveEndpointUrlPrefix.
client := adyen.NewClient(&common.Config{
  ApiKey:      "ADYEN_API_KEY",
  Environment: common.TestEnv,
})

// Create the request object(s)
amount := checkout.Amount{
  Currency: "EUR",
  Value: 1000,
}

createCheckoutSessionRequest := checkout.CreateCheckoutSessionRequest{
  Reference: "YOUR_PAYMENT_REFERENCE",
  Amount: amount,
  MerchantAccount: "YOUR_MERCHANT_ACCOUNT",
  CountryCode: common.PtrString("NL"),
  ReturnUrl: "https://your-company.example.com/checkout?shopperOrder=12xy..",
}

// Send the request
service := client.Checkout()
req := service.PaymentsApi.SessionsInput().IdempotencyKey("UUID").CreateCheckoutSessionRequest(createCheckoutSessionRequest)
res, httpRes, err := service.PaymentsApi.Sessions(context.Background(), req)
```

#### Python

```py
# Adyen Python API Library v12.5.1
import Adyen

adyen = Adyen.Adyen()
adyen.client.xapikey = "ADYEN_API_KEY"
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.client.platform = "test" # The environment to use library in.

# Create the request object(s)
json_request = {
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "amount": {
    "value": 1000,
    "currency": "EUR"
  },
  "returnUrl": "https://your-company.example.com/checkout?shopperOrder=12xy..",
  "reference": "YOUR_PAYMENT_REFERENCE",
  "countryCode": "NL"
}

# Send the request
result = adyen.checkout.payments_api.sessions(request=json_request, idempotency_key="UUID")
```

#### Ruby

```rb
# Adyen Ruby API Library v9.5.1
require "adyen-ruby-api-library"

adyen = Adyen::Client.new
adyen.api_key = 'ADYEN_API_KEY'
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.env = :test # Set to "live" for live environment

# Create the request object(s)
request_body = {
  :merchantAccount => 'YOUR_MERCHANT_ACCOUNT',
  :amount => {
    :value => 1000,
    :currency => 'EUR'
  },
  :returnUrl => 'https://your-company.example.com/checkout?shopperOrder=12xy..',
  :reference => 'YOUR_PAYMENT_REFERENCE',
  :countryCode => 'NL'
}

# Send the request
result = adyen.checkout.payments_api.sessions(request_body, headers: { 'Idempotency-Key' => 'UUID' })
```

#### NodeJS (TypeScript)

```ts
// Adyen Node API Library v18.0.0
// Require the parts of the module you want to use
import { Client, CheckoutAPI, Types } from "@adyen/api-library";
// Initialize the client object
// For the live environment, additionally include your liveEndpointUrlPrefix.
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object(s)
const amount: Types.checkout.Amount = {
  currency: "EUR",
  value: 1000
};

const createCheckoutSessionRequest: Types.checkout.CreateCheckoutSessionRequest = {
  reference: "YOUR_PAYMENT_REFERENCE",
  amount: amount,
  merchantAccount: "YOUR_MERCHANT_ACCOUNT",
  countryCode: "NL",
  returnUrl: "https://your-company.example.com/checkout?shopperOrder=12xy.."
};

// Send the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.sessions(createCheckoutSessionRequest, { idempotencyKey: "UUID" });
```

The response contains:

* `sessionData`: the payment session data you need to pass to your front end.
* `id`: a unique identifier for the session data.
* The request body.

**HTTP 201 /sessions response body**

```json
{
    "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": "https://your-company.example.com/checkout?shopperOrder=12xy..",
    "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](/development-resources/error-codes) to troubleshoot.

### Prepare Front End

## Prepare your front end

Client website

Use Drop-in to show the available payment methods, and to collect payment details from your shoppers.

### Get Adyen Web

### Install Adyen Web

Use the Adyen Web npm package, or embed the Adyen Web script and stylesheet into your HTML file:

### Tab: npm (recommended)

We offer two ways of importing with npm:

* [Import Drop-in with all payment methods](#import-drop-in-with-all-payment-methods): you import all payment methods. The bundle size is larger than if you import individual payment methods.
* [Import Drop-in with individual payment methods](#import-drop-in-with-individual-payment-methods): use [tree shaking](https://webpack.js.org/guides/tree-shaking/) to import only the payment methods you use. The smaller bundler size speeds up loading time. When you add a payment method after creating your integration, you must also import it.

#### Import Drop-in with all payment methods

Install the [Adyen Web Node package](https://www.npmjs.com/package/@adyen/adyen-web):

```bash
npm install @adyen/adyen-web --save
```

Import Adyen Web into your application:

```js
import { AdyenCheckout, Dropin } from '@adyen/adyen-web/auto';
import '@adyen/adyen-web/styles/adyen.css';
```

#### Import Drop-in with individual payment methods

Install the [Adyen Web Node package](https://www.npmjs.com/package/@adyen/adyen-web):

```bash
npm install @adyen/adyen-web --save
```

Import Adyen Web into your application.

```js
import { AdyenCheckout, Dropin, Card, GooglePay, PayPal } from '@adyen/adyen-web';
import '@adyen/adyen-web/styles/adyen.css';
```

### Tab: Embed script and stylesheet

Use the `integrity` attribute so browsers can verify that the script and stylesheet have not been changed unexpectedly.

The value of the `integrity` attribute is the [Subresource Integrity (SRI) hash](/online-payments/web-best-practices#implement-subresource-integrity-hashes) which Adyen provides for each version of the Adyen Web JavaScript and CSS files.

Get the SRI hashes in the [release notes](/online-payments/release-notes?integration_type=web), under **Updating to this version**.

**checkout.html**

```html
<!-- Embed the Adyen Web script element above any other JavaScript in your checkout page. -->
<script src="https://checkoutshopper-test.cdn.adyen.com/sdk/VERSION/adyen.js"
   integrity="JS_INTEGRITY_HASH_FOR_YOUR_VERSION"
   crossorigin="anonymous"></script>

<!-- Embed the Adyen Web stylesheet. You can add your own styling by overriding the rules in the CSS file -->
<link rel="stylesheet" href="https://checkoutshopper-test.cdn.adyen.com/checkoutshopper/sdk/VERSION/adyen.css"
    integrity="CSS_INTEGRITY_HASH_FOR_YOUR_VERSION"
    crossorigin="anonymous">
```

Drop-in resources are available on the `window` global variable.

### Create Dom Element

### Create a DOM element for Drop-in

Create a DOM container element on your checkout page where you want Drop-in to be rendered and give it a descriptive `id`. We strongly recommend that you do not put it in an [iframe element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe), because it may cause issues.

**Create a DOM element**

```html
<div id="dropin-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 do not re-render the DOM element.

### Configure And Create Instances

## Create Drop-in

Client website

Drop-in consists of:

* `AdyenCheckout`: represents one payment [session](#create-payment-session).
* `Dropin`: represents the interface where a shopper completes their payment.

With the `AdyenCheckout` instance, you can create a `Dropin` instance.

### Create your instance of AdyenCheckout

Create a global configuration object that you use to create the instance of `AdyenCheckout`. The object contains configuration parameters and event handlers.

1. Add configuration parameters.

   | Parameter name    | Required                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
   | ----------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | `session`         | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The payment session object from your call to `/sessions`. Contains a `session.id` and `session.sessionData`.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
   | `environment`     | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Use **test**. When you are ready to accept live payments, change the value to one of our [live environments](#test-and-go-live).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
   | `amount`          | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | An object representing the amount to be displayed on the **Pay** Button. Its properties are `value` (the amount in the currencies smallest unit, for example cents for EUR) and `currency`.                                                                                                                                                                                                                                                                                                                                                                               |
   | `countryCode`     | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The shopper's country code. This is used to filter the list of available payment methods to your shopper.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
   | `locale`          | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The language used in the Drop-in UI. For possible values, see the [list of available languages](https://github.com/Adyen/adyen-web/tree/main/packages/server/translations). By default, this is the either the `shopperLocale` from your `/sessions` request or, if this locale is not available on Drop-in, **en-US**.                                                                                                                                                                                                                                                   |
   | `showPayButton`   |                                                                                                               | Shows or hides a **Pay** Button for each payment method. Defaults to **true**. When set to **false**, you must override it in [`paymentMethodsConfiguration` ](#payment-methods-configuration-parameter). The **Pay** button triggers the `onSubmit` event when payment details are valid. If you want to disable the button and then trigger the submit flow on your own, set this to **false** and call the `.submit()` method from your own button implementation. PayPal Smart Payment Buttons doesn't support the `.submit()` method.                                |
   | `secondaryAmount` |                                                                                                               | Shows the payment amount in an additional currency on the **Pay** button. You must do the currency conversion and set the amount. This object has properties:- `currency`: The three-character [ISO currency code](/development-resources/currency-codes).
   - `value`: The amount of the transaction, in [minor units](/development-resources/currency-codes).
   - `currencyDisplay`: Sets the [currency formatting](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#currencydisplay). Default: **symbol**.
    |
   | `donation`        |                                                                                                               | An object for configuring [donations](/online-payments/donations/integration-options/sessions-flow/) after a successful payment.                                                                                                                                                                                                                                                                                                                                                                                                                                          |

2. Add event handlers, to handle events that get triggered during the payment.

   | Event handler name                               | Required                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
   | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | `onPaymentCompleted(result, component)`          | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Create an event handler, called when the payment is completed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
   | `onPaymentFailed(result, component)`             | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Create an event handler, called when the payment failed. A failed payment has result code **Cancelled**, **Error** or **Refused**.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
   | `onError(error)`                                 |                                                                                                               | Create an event handler, called when an error occurs in Drop-in.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
   | `beforeSubmit(data, component, actions)`         |                                                                                                               | Create an event handler, called when the shopper selects the **Pay** button. Do not use if you are implementing an [additional use case](/online-payments/build-your-integration#supported-use-cases). Allows you to add parameters to the payment request that Drop-in makes. For example, you can add shopper details like [`billingAddress` ](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-billingAddress), [`deliveryAddress` ](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-deliveryAddress), [`shopperEmail` ](https://docs.adyen.com/api-explorer/Checkout/latest/payments#request-shopperEmail), or [`shopperName` ](https://docs.adyen.com/api-explorer/Checkout/latest/payments#request-shopperName). When the `beforeSubmit` event is triggered, you need to continue or stop the payment flow using methods available in the event handler:- Continue the payment flow (`actions.resolve()`): You should call the `actions.resolve()` method regardless of the `resultCode`, including when the payment is unsuccessful.
   - Stop the payment flow (`actions.reject()`): Stop the payment flow only when your server-side API request to Adyen failed, or when experiencing network connection issues. |
   | `onSubmit(state, component, actions)`            |                                                                                                               | Required if you need to [update the payment amount after rendering Drop-in](/online-payments/build-your-integration#supported-use-cases). For this additional use case, you need to integrate additional endpoints. Creates an event handler, called when the shopper selects the **Pay** button and payment details are valid. When the `onSubmit` event is triggered, you need to continue or stop the payment flow using methods available in the event handler:- Continue the payment flow (`actions.resolve()`): You should call the `actions.resolve()` method regardless of the `resultCode`, including when the payment is unsuccessful.
   - Stop the payment flow (`actions.reject()`): Stop the payment flow only when your server-side API request to Adyen failed, or when experiencing network connection issues.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
   | []()`onActionHandled`                            |                                                                                                               | Create an event handler, called when an action, for example a QR code or 3D Secure 2 authentication screen, is shown to the shopper. The following `action.type` values trigger this callback:- `threeDS`
   - `qr`
   - `await`Returns data that contains:- `componentType`: The type of component that shows the action to the shopper.
   - `actionDescription`: A description of the action shown to the shopper.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
   | `onAdditionalDetails(state, component, actions)` |                                                                                                               | Required if you need to [confirm an additional action on your server](/online-payments/build-your-integration#supported-use-cases). For this additional use case, you need to integrate additional endpoints. Create an event handler, called when a payment method requires more details, for example for native 3D Secure 2, or native QR code payment methods.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
   | `onChange(state, component)`                     |                                                                                                               | Create an event handler, called when a change happens in the payment form.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

   If an error occurs, the `onError` event returns an object which contains details about the error:

   | Error field     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
   | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | `error.name`    | The type of error. Use the values it returns to configure localized error messages for your shoppers:- **NETWORK\_ERROR**: a call that Drop-in made to the server has failed, for example because of a timeout, or if there is missing information in the request. Ask the shopper to try again.
   - **CANCEL**: the shopper canceled the payment. Only applies for payment methods that allow explicit cancellation in the UI, for example Apple Pay or PayPal.
   - **IMPLEMENTATION\_ERROR**: the method or parameter is incorrect or not supported.
   - **ERROR**: generic catch-all error. Tell the shopper something went wrong and ask them to try paying again, maybe with a different payment method. |
   | `error.message` | Gives more information for each type of error. The message is technical so you shouldn't show it to your shoppers. For `error.name`: **NETWORK\_ERROR**, the information in the `message` field depends on the environment:- **test**: you get a message with a [generic error code](/development-resources/error-codes#generic-error-codes) to help you troubleshoot.
   - **live**: the message from the response.                                                                                                                                                                                                                                                                                       |
   | `component`     | The name of the variable where you [created the instance of Drop-in](#create-and-mount-instance), for example **dropinComponent**.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

   The `error` object may contain additional fields inherited from the [`Error()` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/Error).

   Combine the configuration parameters and event handlers into your global configuration object.

   **Create a global configuration object**

   ```js
   const globalConfiguration = {
     session: {
       id: 'CSD9CAC3...', // Unique identifier for the payment session.
       sessionData: 'Ab02b4c...' // The payment session data.
     },
     environment: 'test', // Change to 'live' for the live environment.
     amount: {
       value: 1000,
       currency: 'EUR'
     },
     locale: 'nl-NL',
     countryCode: 'NL',
     clientKey: 'test_870be2...', // Public key used for client-side authentication: https://docs.adyen.com/development-resources/client-side-authentication
     onPaymentCompleted: (result, component) => {
       console.info(result, component);
     },
     onPaymentFailed: (result, component) => {
       console.info(result, component);
     },
     onError: (error, component) => {
       console.error(error.name, error.message, error.stack, component);
     }
   };
   ```

3. Use this global configuration object to create an instance of `AdyenCheckout`.

   **Create an instance of AdyenCheckout**

   ```javascript
   // All of the resources that you imported are properties of the window.
   // In this example you imported Card, GooglePay, and Paypal individually.
   const { AdyenCheckout, Dropin, Card, GooglePay, PayPal  } = window.AdyenWeb;

   const checkout = await AdyenCheckout(globalConfiguration);
   ```

   **Initializing in a reactive framework**\
   Modern frameworks can re-render UI components, which can cause unexpected behavior in the checkout. As a rule, [initialize `AdyenCheckout` and mount your Components only once](/online-payments/web-best-practices#handle-web-framework-re-renders) when you are ready to display the payment methods.

### Create your instance of Drop-in

1. Create another configuration object for Drop-in. You can add the following configuration:

   | Parameter name                  | Required                                                                                                    | Description                                                                                                                                                                                                                                                                                                                          |
   | ------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
   | `paymentMethodComponents`       | If you [imported Drop-in with individual payment methods](#import-drop-in-with-individual-payment-methods). | An array of the payment methods that you imported. For example: `[Card, PayPal, GooglePay, ApplePay, Ideal]`.                                                                                                                                                                                                                        |
   | `paymentMethodsConfiguration`   |                                                                                                             | Configuration for individual payment methods. The [payment method guide](/payment-methods) for the individual payment method shows required and optional configuration. If you include this in the configuration on your instance of `Dropin`, it overrides global payment method configuration on your instance of `AdyenCheckout`. |
   | `openFirstPaymentMethod`        |                                                                                                             | When enabled, Drop-in opens the first payment method automatically on page load. Defaults to **true**.                                                                                                                                                                                                                               |
   | `openFirstStoredPaymentMethod`  |                                                                                                             | When enabled, Drop-in opens the payment method with stored card details on page load. This option takes precedence over `openFirstPaymentMethod`. Defaults to **true**.                                                                                                                                                              |
   | `openPaymentMethod.type`        |                                                                                                             | Automatically selects the specified payment method when Drop-in renders. Set the [payment method type](/payment-methods/payment-method-types/) that you want to be automatically selected as the value.                                                                                                                              |
   | `showStoredPaymentMethods`      |                                                                                                             | Shows or hides payment methods with stored card details. Defaults to **true**.                                                                                                                                                                                                                                                       |
   | `showRemovePaymentMethodButton` |                                                                                                             | Allows the shopper to remove a stored payment method. Defaults to **false**. If using this prop, you must also implement the `onDisableStoredPaymentMethod` callback.                                                                                                                                                                |
   | `showPaymentMethods`            |                                                                                                             | Shows or hides regular (not stored) payment methods. Set to **false** if you only want to show payment methods with stored card details. Defaults to **true**.                                                                                                                                                                       |
   | `paymentMethodsConfiguration`   |                                                                                                             | Configuration for individual payment methods. The [payment method guides](/payment-methods) have configuration options specific to each payment method. If you include this in the configuration on your instance of `DropIn`, it overrides global payment method configuration on your instance of `AdyenCheckout`.                 |
   | `redirectFromTopWhenInIframe`   |                                                                                                             | If your Drop-in is inside of an [iframe element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe), set to **true** if you want redirects to be performed on the top-level window. We recommend that you do not put Component in an iframe.                                                                          |
   | `instantPaymentTypes`           |                                                                                                             | Moves payment methods to the top of the list of available payment methods. This is available for [Apple Pay](/payment-methods/apple-pay/web-drop-in#instant-payment-button-configuration) and [Google Pay](/payment-methods/google-pay/web-drop-in#instant-payment-button-configuration).                                            |
   | `disableFinalAnimation`         |                                                                                                             | When enabled, disables the final animation after a shopper completes the payment (whether successful or failed). This lets you implement your own animation. Defaults to **false**.                                                                                                                                                  |
   | `showRadioButton`               |                                                                                                             | When enabled, payment methods in the Drop-in have a [radio button](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/radio). Defaults to **false**.                                                                                                                                                                    |

2. Optionally add event handlers.

   | Event handler name                                                     |   | Description                                                                                                                                                                                                                                                                                                                                                                                                         |
   | ---------------------------------------------------------------------- | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | `onReady()`                                                            |   | Called when Drop-in is initialized and is ready for use.                                                                                                                                                                                                                                                                                                                                                            |
   | `onSelect(component)`                                                  |   | Called when the shopper selects a payment method.                                                                                                                                                                                                                                                                                                                                                                   |
   | `onDisableStoredPaymentMethod(storedPaymentMethodId, resolve, reject)` |   | Called when a shopper removes a stored payment method. To remove the selected payment method, make a **DELETE** `storedPaymentMethods` request using the `storedPaymentMethodId`. Then call either `resolve()` or `reject()`, depending on the [/storedPaymentMethods/{storedPaymentMethodId}](https://docs.adyen.com/api-explorer/Checkout/latest/delete/storedPaymentMethods/\(storedPaymentMethodId\)) response. |

   **Drop-in configuration (when importing individual payment methods)**

   ```js
   const dropinConfiguration = {
      // Required if you import individual payment methods.
      paymentMethodComponents: [Card, PayPal, GooglePay, ApplePay, Ideal],
      // Optional configuration.
      onReady: () => {},
      instantPaymentTypes: ['applepay', 'googlepay']
   };
   ```

3. For some payment methods, you must add additional configuration. You can also add optional configuration for some payment methods. For example, you can add [additional configuration for cards](/payment-methods/cards/web-drop-in/#optional-configuration).[]()

   **Payment method configuration**

   ```javascript
   const dropinConfiguration = {
     // Other Drop-in configuration...
     paymentMethodsConfiguration: {
       card: {
         // Optional configuration.
         hasHolderName: true, // Show the cardholder name field.
   	    holderNameRequired: true, // Mark the cardholder name field as required.
       }
     }
   }
   ```

   Configuration for payment methods overrides global configuration. In the following example, the `onError()` configuration for `card` overrides the global `onError()` configuration.

   **Override global configuration**

   ```js
   // The global configuration object.
   const globalConfiguration = {
     // Global configuration for onError.
     onError: () => {}
   }

   // Drop-in configuration.
   const dropInConfiguration = {
     // Configuration for individual payment methods.
     paymentMethodsConfiguration: {
       card: {
         // onError configuration for card payments. Overrides the global configuration.
         onError: () => {}
       }
     }
   };
   ```

4. Create an instance of Drop-in, passing the [instance of `AdyenCheckout`](#configure) and the Drop-in configuration object that you created. Then mount the Drop-in to the [DOM element you created](#create-container-element).

   **Create an instance of Drop-in**

   ```js
   const dropin = new Dropin(checkout, dropinConfiguration).mount('#dropin');
   ```

**

### Drop-in methods

The following methods are available on [your instance of Drop-in](#create-instance):

| Method name                  | Description                                                                                                                                                                                                                                                                                              |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mount(selector)`            | Mounts the Drop-in into the DOM returned by the `selector`. The `selector` must be either a [valid CSS selector string](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector#parameters) or an [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement) reference. |
| `unmount()`                  | Unmounts the Drop-in from the DOM. We recommend to unmount in case the payment amount changes after the initial mount.                                                                                                                                                                                   |
| `closeActivePaymentMethod()` | Closes a selected payment method, for example if you want to reset the Drop-in.                                                                                                                                                                                                                          |
| `update()`                   | Updates the properties and remounts Drop-in into the DOM, for example, if you want to change the properties of the configuration object after Drop-in is mounted.                                                                                                                                        |

### Optional Change Order Payment Methods (optional)

**

### Custom order of payment methods

In the checkout settings in your [Customer Area](https://ca-test.adyen.com/), you can enable [dynamic payment method ordering](/online-payments/checkout-settings#checkout-payment-method-ordering), or manually configure which payment methods are rendered [based on the shopper's country](/online-payments/checkout-settings#checkout-payment-method). If you want to customize rendered payment methods *for specific transactions*, you can do this on your [server](#customize-for-specific-transactions-server-side).

#### Customize for specific transactions (on your server)

When making a [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) request, you can include one of the following parameters:

* [allowedPaymentMethods](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods#request-allowedPaymentMethods): Drop-in renders only the payment methods that you specify.
* [blockedPaymentMethods](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods#request-blockedPaymentMethods): Drop-in doesn't render payment methods that you specify.

To refer to payment methods, use their `paymentMethod.type` from [Payment methods overview](/payment-methods/payment-method-types).

The following example shows how to make a request to only show iDEAL and credit cards in the payment form:

**/sessions request**

#### curl

```bash
curl https://checkout-test.adyen.com/v70/sessions \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "allowedPaymentMethods": ["ideal", "scheme"],
  "countryCode": "NL",
  "amount": {
    "currency": "EUR",
    "value": 1000
  },
  "channel": "Web",
  "shopperLocale": "NL"
}'
```

#### Java

```java
// Adyen Java API Library v27.0.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, additionally include your liveEndpointUrlPrefix.
Client client = new Client("ADYEN_API_KEY", Environment.TEST);

// Create the request object(s)
Amount amount = new Amount()
  .currency("")
  .value(1000L);

CreateCheckoutSessionRequest createCheckoutSessionRequest = new CreateCheckoutSessionRequest()
  .amount(amount)
  .merchantAccount("YOUR_MERCHANT_ACCOUNT")
  .countryCode("")
  .channel(CreateCheckoutSessionRequest.ChannelEnum.)
  .shopperLocale("")
  .allowedPaymentMethods(Arrays.asList("ideal", "scheme"));

// Send the request
PaymentsApi service = new PaymentsApi(client);
CreateCheckoutSessionResponse response = service.sessions(createCheckoutSessionRequest, new RequestOptions().idempotencyKey("UUID"));
```

#### PHP

```php
// Adyen PHP API Library v19.0.0
use Adyen\Client;
use Adyen\Environment;
use Adyen\Model\Checkout\Amount;
use Adyen\Model\Checkout\CreateCheckoutSessionRequest;
use Adyen\Service\Checkout\PaymentsApi;

$client = new Client();
$client->setXApiKey("ADYEN_API_KEY");
// For the live environment, additionally include your liveEndpointUrlPrefix.
$client->setEnvironment(Environment::TEST);


// Create the request object(s)
$amount = new Amount();
$amount
  ->setCurrency("")
  ->setValue(1000);

$createCheckoutSessionRequest = new CreateCheckoutSessionRequest();
$createCheckoutSessionRequest
  ->setAmount($amount)
  ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT")
  ->setCountryCode("")
  ->setChannel("")
  ->setShopperLocale("")
  ->setAllowedPaymentMethods(array("ideal", "scheme"));

$requestOptions['idempotencyKey'] = 'UUID';

// Send the request
$service = new PaymentsApi($client);
$response = $service->sessions($createCheckoutSessionRequest, $requestOptions);
```

#### C\#

```cs
// Adyen .net API Library v17.0.0
using Adyen;
using Environment = Adyen.Model.Environment;
using Adyen.Model;
using Adyen.Model.Checkout;
using Adyen.Service.Checkout;

// For the live environment, additionally include your liveEndpointUrlPrefix.
var config = new Config()
{
    XApiKey = "ADYEN_API_KEY",
    Environment = Environment.Test
};
var client = new Client(config);

// Create the request object(s)
Amount amount = new Amount
{
  Currency = "",
  Value = 1000
};

CreateCheckoutSessionRequest createCheckoutSessionRequest = new CreateCheckoutSessionRequest
{
  Amount = amount,
  MerchantAccount = "YOUR_MERCHANT_ACCOUNT",
  CountryCode = "",
  Channel = CreateCheckoutSessionRequest.ChannelEnum.,
  ShopperLocale = "",
  AllowedPaymentMethods = { "ideal", "scheme" }
};

// Send the request
var service = new PaymentsService(client);
var response = service.Sessions(createCheckoutSessionRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"});
```

#### NodeJS (JavaScript)

```js
// Adyen Node API Library v18.0.0
// Require the parts of the module you want to use
const { Client, CheckoutAPI } = require('@adyen/api-library');
// Initialize the client object
// For the live environment, additionally include your liveEndpointUrlPrefix.
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object(s)
const createCheckoutSessionRequest = {
  merchantAccount: "YOUR_MERCHANT_ACCOUNT",
  allowedPaymentMethods: [ "ideal", "scheme" ],
  countryCode: "",
  amount: {
    currency: "",
    value: 1000
  },
  channel: "",
  shopperLocale: ""
}

// Send the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.sessions(createCheckoutSessionRequest, { idempotencyKey: "UUID" });
```

#### Go

```go
// Adyen Go API Library v10.4.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, additionally include your liveEndpointUrlPrefix.
client := adyen.NewClient(&common.Config{
  ApiKey:      "ADYEN_API_KEY",
  Environment: common.TestEnv,
})

// Create the request object(s)
amount := checkout.Amount{
  Currency: "",
  Value: 1000,
}

createCheckoutSessionRequest := checkout.CreateCheckoutSessionRequest{
  Amount: amount,
  MerchantAccount: "YOUR_MERCHANT_ACCOUNT",
  CountryCode: common.PtrString(""),
  Channel: common.PtrString(""),
  ShopperLocale: common.PtrString(""),
  AllowedPaymentMethods: []string{
    "ideal", "scheme",
  },
}

// Send the request
service := client.Checkout()
req := service.PaymentsApi.SessionsInput().IdempotencyKey("UUID").CreateCheckoutSessionRequest(createCheckoutSessionRequest)
res, httpRes, err := service.PaymentsApi.Sessions(context.Background(), req)
```

#### Python

```py
# Adyen Python API Library v12.5.1
import Adyen

adyen = Adyen.Adyen()
adyen.client.xapikey = "ADYEN_API_KEY"
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.client.platform = "test" # The environment to use library in.

# Create the request object(s)
json_request = {
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "allowedPaymentMethods": [ "ideal", "scheme" ],
  "countryCode": "",
  "amount": {
    "currency": "",
    "value": 1000
  },
  "channel": "",
  "shopperLocale": ""
}

# Send the request
result = adyen.checkout.payments_api.sessions(request=json_request, idempotency_key="UUID")
```

#### Ruby

```rb
# Adyen Ruby API Library v9.5.1
require "adyen-ruby-api-library"

adyen = Adyen::Client.new
adyen.api_key = 'ADYEN_API_KEY'
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.env = :test # Set to "live" for live environment

# Create the request object(s)
request_body = {
  :merchantAccount => 'YOUR_MERCHANT_ACCOUNT',
  :allowedPaymentMethods => [ 'ideal', 'scheme' ],
  :countryCode => '',
  :amount => {
    :currency => '',
    :value => 1000
  },
  :channel => '',
  :shopperLocale => ''
}

# Send the request
result = adyen.checkout.payments_api.sessions(request_body, headers: { 'Idempotency-Key' => 'UUID' })
```

#### NodeJS (TypeScript)

```ts
// Adyen Node API Library v18.0.0
// Require the parts of the module you want to use
import { Client, CheckoutAPI, Types } from "@adyen/api-library";
// Initialize the client object
// For the live environment, additionally include your liveEndpointUrlPrefix.
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object(s)
const amount: Types.checkout.Amount = {
  currency: "",
  value: 1000
};

const createCheckoutSessionRequest: Types.checkout.CreateCheckoutSessionRequest = {
  amount: amount,
  merchantAccount: "YOUR_MERCHANT_ACCOUNT",
  countryCode: "",
  channel: Types.checkout.CreateCheckoutSessionRequest.ChannelEnum.,
  shopperLocale: "",
  allowedPaymentMethods: ["ideal", "scheme"]
};

// Send the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.sessions(createCheckoutSessionRequest, { idempotencyKey: "UUID" });
```

### Optional Custom Styling (optional)

**

### Custom styling

Drop-in includes a pre-styled payment form. The styling of fonts, colors, layouts, and buttons can be customized using CSS custom properties to match your website and brand.

You can customize elements that are not inside an iFrame, by overriding the CSS property styles:

1. Create a CSS file `override.css`, with the [CSS variables](https://github.com/Adyen/adyen-web/blob/main/README.md#styling) you want to style:

   **override.css**

   ```css
   :root {
     --adyen-checkout-input-wrapper-focus-border-color: #ff8888;
   }
   ```

2. Import the `override.css` file after importing the Adyen library's main CSS file:

   **Your checkout code**

   ```css
   import '@adyen/adyen-web/styles/adyen.css';
   import './override.css';
   ```

### Optional Localization (optional)

**

### Localization

#### Supported languages

We include UI localizations for some languages. The fields and text are in the [files for the included locales](https://github.com/Adyen/adyen-web/tree/main/packages/server/translations).

To use a language or localization that isn't included, [create your own](#create-localization).

#### Change the language

The language of the UI is based on the `locale` set when creating your instance of `AdyenCheckout`.

If no `locale` is set when creating an instance of `AdyenCheckout`, the language displayed matches the `shopperLocale` from your [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) request.

If neither language is set or supported, the UI language defaults to US English.

#### Customize the localization

The text displayed in each localization can be customized, allowing you to replace the default text with your own.

To customize a localization:

1. Create a `translations` object on your payments page.

2. In this object, specify the `locale` you want to customize, and add key-value pairs corresponding to any text you want to customize.

   The following example shows how to customize the US English (`en-US`) translation so that:

   * **Shipping Address** appears instead of **Delivery Address** (the default **en-US** text).
   * **State** appears instead of **State or Province** (the default **en-US** text).

   **Customize translations**

   ```js
   const translations = {
     "en-US": {
       "deliveryAddress": "Shipping Address",
       "stateOrProvince": "State"
     }
   };
   ```

3. To use the customized localization in your payment form, provide the following parameters in the [`configuration` object](#configure):

   | Parameter name | Required                                                                                                      | Description                                       |
   | -------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
   | `locale`       | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The `locale` you customized in the previous step. |
   | `translations` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Use **translations**                              |

   The following example shows how to use a customized **en-US** localization in Drop-in.

   **Example of US English localization**

   ```js
   const configuration = {
     locale: "en-US",
     translations: translations,
     ...
   };
   ```

#### Create your custom localization

To use a language or localization that we do not included, create your own.

1. Create a `translations` object on your payments page.

2. In this object, specify the `locale` you want to create. For example, you can use the locale **nl-BE** to create a Belgian Dutch localization, and add key-value pairs corresponding to text shown in the UI.

   The example below shows a `translation` object for creating a **nl-BE** localization.

   **British English translations example**

   ```js
   const translations = {
     "nl-BE": {
       "paymentMethods.moreMethodsButton": "Meer betaalmethoden",
       "payButton": "Betaal",
       "storeDetails": "Bewaar voor mijn volgende betaling",
       ...
     }
   };
   ```

   The ellipsis (...) in the `translations` object above indicates the code sample isn't complete. For missing key-value pairs in your configuration, the translation defaults to **en-US**.

3. To use your localization in your payment form, provide the following parameters in the [`configuration` object](#configure):

   | Parameter name | Required                                                                                                      | Description                                    |
   | -------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
   | `locale`       | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The `locale` you created in the previous step. |
   | `translations` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Use **translations**                           |

   The example below shows how to use a created localization for **nl-BE**.

   ```js
   const configuration = {
     locale: "nl-BE",
     translations: translations,
     ...
   };

   const checkout = await AdyenCheckout(configuration);
   ```

#### Text direction

The default text direction is left-to-right. Text direction is independent from the `locale` you set in the `configuration` object. So even if you set the locale to a right-to-left language, like Arabic, you still need to set the text direction.

To change the text direction to right-to-left, use the [HTML `dir` attribute](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dir) on the parent element for the checkout container.

### Optional Update Amount (optional)

## Optional: Update the payment amount

You must use Checkout API v72 or later for this feature.

After you create a session, the order amount can change before the shopper submits the payment. For example: the shopper adds or removes items from their cart, or applies a discount. You can update the session with the new amount so that the shopper pays the correct total.

### Update the session amount

Client website

Payment server

1. Trigger the `beforeSubmit` callback from your instance of `AdyenCheckout` to make a PATCH `/sessions/{sessionId}` request to update the session from your server, including the follow parameters:

   | Parameter                      | Required                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                          |
   | ------------------------------ | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | `sessionId` **Path parameter** | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The ID of the session to update.                                                                                                                                                                                                                                                                                                                     |
   | `sessionData`                  | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The encoded session data from the original [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) response.                                                                                                                                                                                                                  |
   | `amount.value`                 | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The updated amount in [minor units](/development-resources/currency-codes).                                                                                                                                                                                                                                                                          |
   | `amount.currency`              | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The three-character [ISO currency code](/development-resources/currency-codes).                                                                                                                                                                                                                                                                      |
   | `payable`                      |                                                                                                               | If you know that the amount in this request is the final amount, set to **true**. This indicates that the session is ready for payment. When you set this to true, you can no longer update the session. If you set to **false**, you must make another request to update the session and set to **true** before the shopper can submit the payment. |

   **Example request to update the session amount**

   ```bash
   curl https://checkout-test.adyen.com/v72/sessions/QFQTPCQ8HXSKGK82 \
   -X PATCH \
   -H 'x-api-key: ADYEN_API_KEY' \
   -H 'idempotency-key: YOUR_IDEMPOTENCY_KEY' \
   -H 'content-type: application/json' \
   -d '{
     "sessionData": "Ab02b4c...",
     "amount": {
       "value": 10000,
       "currency": "EUR"
     },
     "payable": true
   }'
   ```

   After you set `payable` to **true**, you cannot update the session again. Only set this when you confirm the final amount, and the session is ready for payment.

   The response includes the updated session data.

   **Example response with updated session data**

   ```json
   {
       "sessionData": "Ab02b4c.."
   }
   ```

2. Add the updated `sessionData` object to the `actions.resolve` method, to pass it to Drop-in.

   When you make a request to update the server-side session data, you must store and get the updated amount on your server. Do not get the updated amount from the client.

   **Example of the beforeSubmit callback to update the session**

   ```ts
   const checkout = await AdyenCheckout({ 
     beforeSubmit: async (data, component, actions) => {
       try {
         // Get the latest session data.
         const { session } = component.core.session;
         // Make an PATCH /sessions/{sessionId} request to update the session.
         const updatedSessionData = await patchSession(session);
         // Add the updated session data to actions.resolve.
         actions.resolve({ ...data, sessionData: updatedSessionData });
       } catch (error) {
         actions.reject();
       }
     },
     // ...Other configuration properties
   });
   ```

### Update the amount in Drop-in

Client website

Update the amount in Drop-in when the payment amount changes (for example, when the shopper adds or removes items from their cart). The amount can be updated multiple times without the need to update the server-side session data every time. The server-side session update is required only before the shopper can submit the payment.

#### Show the updated amount to the shopper

Client website

To show the updated amount in the payment form:

From your [instance of `AdyenCheckout`](/online-payments/build-your-integration/sessions-flow/#configure), call the `update` function and pass the new amount.

**Example to update the amount in the payment form**

```ts
// Create an amount object for the updated amount.
const amount = { value: 1000, currency: 'USD' };
// Update the amount in the payment form, specifying not to reinitialize the checkout instance.
checkout.update({ amount }, { shouldReinitializeCheckout: false });
```

## Handle the payment

Client website

When you create and mount Drop-in, the shopper interacts with the interface to complete the payment. The whole payment flow is handled by Drop-in you configured and created, except for when a redirect happens.

### Handle The Redirect Result

### Handle the redirect

Some payment methods, like iDEAL and some 3D Secure flows, will redirect the shopper back to your website. When the shopper comes back to your website, show them the payment result, based on the result code. To get the `resultCode`, you can either:

* Create an instance of `AdyenCheckout` after the redirect, as described below.
* Confirm the redirect result on your server, for which you need to [implement an extra API endpoint](/online-payments/build-your-integration).

The shopper comes back to the `returnUrl` specified when [creating the payment session](#create-payment-session). The `returnUrl` has query parameters appended to it, which you need to handle the redirect:

* `sessionId`: the unique identifier for the shopper's payment session.
* `redirectResult`: details you need to submit to handle the redirect.

If the shopper doesn't return to you website, you do not get a `redirectResult`. You do not need to do anything to handle the redirect in this case. Instead, wait for the [webhook](#get-payment-outcome) that we send to your server.

**Example return URL**

```text
// The return URL has query parameters related to the payment session.
https://your-company.example.com/?sessionId=CSD9CAC34EBAE225DD&redirectResult=X6XtfGC3!Y...
```

Extract the values from the query string parameters and create a function which handles the redirect result. The function needs to:

1. Create an instance of Adyen Checkout using the `sessionId` value you extracted.
2. Submit the `redirectResult` value you extracted from the `returnUrl`.

**handleRedirectResult**

```js
// Create an instance of AdyenCheckout to handle the shopper returning to your website.
// Configure the instance with the sessionId you extracted from the returnUrl.
const checkout = await AdyenCheckout(configuration);

// Submit the redirectResult value you extracted from the returnUrl.
checkout.submitDetails({ details: { redirectResult: redirectResult } });
```

If the shopper doesn't return to your website, do not call `submitDetails`, because the result doesn't change when you attempt the request.

After you submit the `redirectResult` value, Drop-in calls the `onPaymentCompleted(result, component)` event. Use the [result code](/online-payments/build-your-integration/payment-result-codes#final-payment-status) in `result.resultCode` to inform the shopper.

To update your order management system, wait for the [webhook](#update-your-order-management-system) that we send to your server.

### Get The Outcome

## Get the payment outcome

After Drop-in finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.

### Inform the shopper

Client website

Depending on whether the payment was successful, the `onPaymentCompleted` or `onPaymentFailed` event is triggered.

From the relevant event, you can get the [`resultCode` ](/online-payments/payment-result-codes#final-payment-status)to inform the shopper about the current payment status.

**

### Optional: Get the result of the payment session on your server

Payment server

You can also get the result of the payment session on your server.

1. Get the `id` from the [`/sessions` response](#sessions-response).

2. Get `sessionResult` from the `onPaymentCompleted` or `onPaymentFailed` event.

3. Make a **GET** `/sessions/{id}?sessionResult={sessionResult}` request including the `id` and `sessionResult`. For example:

   **Request for result of payment session**

   #### curl

   ```bash
   curl -X GET https://checkout-test.adyen.com/v70/sessions/CS12345678?sessionResult=SOME_DATA
   ```

   #### Java

   ```java
   // Adyen Java API Library v25.0.0
   import com.adyen.Client;
   import com.adyen.enums.Environment;
   import com.adyen.service.checkout.*;

   // For the live environment, additionally include your liveEndpointUrlPrefix.
   Client client = new Client("ADYEN_API_KEY", Environment.TEST);
   // Make the API call
   PaymentsApi service = new PaymentsApi(client);
   SessionResultResponse response = service.getResultOfPaymentSession("sessionId", "String", null);
   ```

   #### PHP

   ```php
   // Adyen PHP API Library v17.4.0
   use Adyen\Client;
   use Adyen\Environment;
   use Adyen\Service\Checkout\PaymentsApi;

   $client = new Client();
   $client->setXApiKey("ADYEN_API_KEY");
   // For the live environment, additionally include your liveEndpointUrlPrefix.
   $client->setEnvironment(Environment::TEST);

   $requestOptions['queryParams'] = array('sessionResult' => 'string');

   // Make the API call
   $service = new PaymentsApi($client);
   $response = $service->getResultOfPaymentSession('sessionId', $requestOptions);
   ```

   #### C\#

   ```cs
   // Adyen .net API Library v14.4.0
   using Adyen;
   using Environment = Adyen.Model.Environment;
   using Adyen.Service.Checkout;

   // For the live environment, additionally include your liveEndpointUrlPrefix.
   var config = new Config()
   {
       XApiKey = "ADYEN_API_KEY",
       Environment = Environment.Test
   };
   var client = new Client(config);

   // Make the API call
   var service = new PaymentsService(client);
   var response = service.GetResultOfPaymentSession("sessionId", sessionResult: "string");
   ```

   #### NodeJS (JavaScript)

   ```js
   // Adyen Node API Library v16.2.0
   // Require the parts of the module you want to use
   const { Client, CheckoutAPI } = require('@adyen/api-library');
   // Initialize the client object
   // For the live environment, additionally include your liveEndpointUrlPrefix.
   const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

   // Make the API call
   const checkoutAPI = new CheckoutAPI(client);
   const response = checkoutAPI.PaymentsApi.getResultOfPaymentSession("sessionId", "string");
   ```

   #### Go

   ```go
   // Adyen Go API Library v21.0.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:      "",
     Environment: common.TestEnv,
   })

   // Send the request
   service := client.Checkout()
   req := service.PaymentsApi.GetResultOfPaymentSessionInput("sessionId")
   req = req.SessionResult("string")
   res, httpRes, err := service.PaymentsApi.GetResultOfPaymentSession(context.Background(), req)
   ```

   #### Python

   ```py
   # Adyen Python API Library v13.6.0
   import Adyen

   adyen = Adyen.Adyen()
   adyen.client.xapikey = ""
   # For the LIVE environment, also include your liveEndpointUrlPrefix.
   adyen.client.platform = "test" # The environment to use library in.

   query_parameters = {
     "sessionResult" : "string"
   }

   # Send the request
   result = adyen.checkout.payments_api.get_result_of_payment_session(sessionId="sessionId", query_parameters=query_parameters)
   ```

   #### Ruby

   ```rb
   # Adyen Ruby API Library v9.3.0
   require "adyen-ruby-api-library"

   adyen = Adyen::Client.new
   adyen.api_key = 'ADYEN_API_KEY'
   # For the live environment, additionally include your liveEndpointUrlPrefix.
   adyen.env = :test # Set to "live" for live environment

   # Create the request object(s)
   query_params = {
     :sessionResult => 'string'
   }

   # Make the API call
   result = adyen.checkout.payments_api.get_result_of_payment_session('sessionId', query_params: query_params)
   ```

   #### NodeJS (TypeScript)

   ```ts
   // Adyen Node API Library v16.2.0
   // Require the parts of the module you want to use
   import { Client, CheckoutAPI, Types } from "@adyen/api-library";
   // Initialize the client object
   // For the live environment, additionally include your liveEndpointUrlPrefix.
   const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

   // Make the API call
   const checkoutAPI = new CheckoutAPI(client);
   const response = checkoutAPI.PaymentsApi.getResultOfPaymentSession("sessionId", "string");
   ```

   The response includes the result of the payment session (`status`). For example:

   **Response with result of the payment session**

   ```json
   {
     "additionalData": {
       ...
     },
     "id": "CSD9CAC34EBAE225DD",
     "payments": [{
       "amount": {
         "currency": "EUR",
         "value": 1000
       },
       "paymentMethod": {
         "brand": "visa",
         "type": "scheme"
       },
       "pspReference": "TG9SNBJJNXRKDM92",
       "resultCode": "Authorised"
     }],
     "reference": "YOUR_PAYMENT_REFERENCE",
     "status": "completed"
   }
   ```

   The [additionalData](https://docs.adyen.com/api-explorer/Checkout/latest/get/sessions/\(sessionId\)#responses-200-additionalData) attributes in the response depend on the type of payment made.

   Possible statuses:

   | `status`           | Description                                                                                                                      |
   | ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
   | **completed**      | The shopper completed the payment. This means that the payment was authorized.                                                   |
   | **paymentPending** | The shopper is in the process of making the payment. This applies to payment methods with an asynchronous flow.                  |
   | **canceled**       | The shopper canceled the payment.                                                                                                |
   | **expired**        | The session expired (default: 1 hour after session creation). Shoppers can no longer complete the payment with this `sessionId`. |

The `status` included in the response doesn't get updated. Do not make the request again to check for payment status updates. Instead, check webhooks or the **Transactions** list in your [Customer Area](https://ca-test.adyen.com/).

### Update your order management system

Webhook server

You get the outcome of each payment asynchronously, in an **AUTHORISATION** [webhook](/development-resources/webhooks). Use the `merchantReference` from the webhook to match it to your order reference.\
For a successful payment, the event contains `success`: **true**.

**Example webhook for a successful payment**

```json
{
  "live": "false",
  "notificationItems":[
    {
      "NotificationRequestItem":{
        "eventCode":"AUTHORISATION",
        "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
        "reason":"033899:1111:03/2030",
        "amount":{
          "currency":"EUR",
          "value":2500
        },
        "operations":["CANCEL","CAPTURE","REFUND"],
        "success":"true",
        "paymentMethod":"mc",
        "additionalData":{
          "expiryDate":"03/2030",
          "authCode":"033899",
          "cardBin":"411111",
          "cardSummary":"1111",
          "checkoutSessionId":"CSF46729982237A879"
        },
        "merchantReference":"YOUR_REFERENCE",
        "pspReference":"NC6HT9CRT65ZGN82",
        "eventDate":"2021-09-13T14:10:22+02:00"
      }
    }
  ]
}
```

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

**Example webhook for an unsuccessful payment**

```json
{
  "live": "false",
  "notificationItems":[
    {
      "NotificationRequestItem":{
        "eventCode":"AUTHORISATION",
        "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
        "reason":"validation 101 Invalid card number",
        "amount":{
          "currency":"EUR",
          "value":2500
        },
        "success":"false",
        "paymentMethod":"unknowncard",
        "additionalData":{
          "expiryDate":"03/2030",
          "cardBin":"411111",
          "cardSummary":"1112",
          "checkoutSessionId":"861631540104159H"
        },
        "merchantReference":"YOUR_REFERENCE",
        "pspReference":"KHQC5N7G84BLNK43",
        "eventDate":"2021-09-13T14:14:05+02:00"
      }
    }
  ]
}
```

## Test and go live

Before going live, use our list of [test cards and other payment methods](/development-resources/test-cards-and-credentials/test-card-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](https://ca-test.adyen.com/), under **Transactions** > **Payments**.

To debug or troubleshoot test payments, you can also use [API logs](/development-resources/logs-resources/api-logs) in your test environment.

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

1. [Apply for a live account](/get-started-with-adyen/application-requirements). Review the process to start accepting payments on [Get started with Adyen](/get-started-with-adyen).

2. Assess your [PCI DSS compliance](/development-resources/pci-dss-compliance-guide#online-payments) by submitting the [Self-Assessment Questionnaire-A](https://www.pcisecuritystandards.org/documents/PCI-DSS-v3_2_1-SAQ-A.pdf).

3. [Configure your live account](/online-payments/go-live-checklist). 

4. Ensure your checkout is served over HTTPS. Non-HTTPS connections can result in payment processing failures.

5. Submit a request to add payment methods in your [live Customer Area](https://ca-live.adyen.com/).

6. Switch from test to our [live endpoints](/development-resources/live-endpoints#checkout-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, for example, when authenticating with 3D Secure 2.

7. Load Drop-in from one of our live environments and set the `environment` to match your live endpoints:

   | 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**  |

### Staying up to date

After you go live, [keep your integration up-to-date](/online-payments/upgrade-your-integration#staying-up-to-date). Regular updates help you:

* Access new features as they are released.
* Improve checkout performance and accessibility for your customers.
* Update security to protect your business and your data.

## Next steps

[required](/online-payments/modify-payments)

[Modify payments](/online-payments/modify-payments)

[Find out how to cancel, refund, or capture a payment using our API.](/online-payments/modify-payments)

[Add payment methods](/payment-methods/add-payment-methods)

[Learn about payment methods and how to add them to your account.](/payment-methods/add-payment-methods)

[Tokenization](/online-payments/tokenization)

[Save shopper payment details for later payments.](/online-payments/tokenization)

[3D Secure authentication](/online-payments/3d-secure)

[Comply with regulations such as PSD2 SCA in Europe.](/online-payments/3d-secure)

## Web Components

Use our customizable UI components

### Version Update

## Introducing Web v6

### Improvements

The Web v6 library introduces the following improvements:

* Reduced bundle size through tree shaking
* Enhanced design
* Enhanced Typescript developer experience
* Better alignment of express payment methods
* Added support for 6 localizations
* Support for Apple Pay Order tracking
* Improve AVS checks for Google Pay and Apple Pay

To upgrade your existing integration, see [Upgrade to Adyen Web v6](/online-payments/upgrade-your-integration/upgrade-to-web-v6)

## How it works

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

* **Your payment server**: sends the API requests to get available payment methods, make a payment, and send additional payment details.

* **Your client website**: 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 website.

* **Your webhook server**: receives webhooks that include the outcome of each payment.

### Integration steps

To integrate Components in your web application:

1. [Install an API library](#install-api-library) on your server.
2. [Create a session](#create-payment-session) from your server.
3. [Install the Adyen Web library](#install-adyen-web) on your front end.
4. [Create a DOM element](#create-container-element) for Components.
5. [Configure and create an instance of `AdyenCheckout`](#configure).
6. [Configure and create an instance of the Component](#create-instance).
7. [Handle redirects](#handle-the-redirect).
8. [Show the payment status](#inform-the-shopper) to your shopper.
9. [Update your order management system](#update-your-order-management-system).
10. [Test your integration and go live](#test-and-go-live).

### Payment flow

The parts of your integration work together to complete the payment flow. The payment flow is the same for all payments:

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

![](/user/pages/filters/sessions-flow-integration/web/5-12-0/02.how-it-works/sessions-components.svg?decoding=auto\&fetchpriority=auto)

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

[![](/user/pages/reuse/online-payments/how-it-works-parts/servers.svg?decoding=auto\&fetchpriority=auto)](/#install-api-library)

[Payment server](/#install-api-library)

[Go to the integration steps for your server.](/#install-api-library)

[![](/user/pages/reuse/online-payments/how-it-works-parts/browser-developers.svg?decoding=auto\&fetchpriority=auto)](/#prepare-your-front-end)

[Client website](/#prepare-your-front-end)

[Go to the integration steps for your client website.](/#prepare-your-front-end)

[![](/user/pages/reuse/online-payments/how-it-works-parts/event-code.svg?decoding=auto\&fetchpriority=auto)](/#update-your-order-management-system)

[Webhook server](/#update-your-order-management-system)

[Go to the integration steps for your webhook server.](/#update-your-order-management-system)

### Before You Begin

## Requirements

Before you begin, take into account the following requirements, limitations, and preparations.

| Requirement                                                                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Integration type**                                                            | Use this information to build an online payments integration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| **[Customer Area roles](/account/user-roles)**                                  | Make sure that you have the following roles:- **Merchant admin role**
- **Manage API credentials**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| **[Adyen API credentials](/development-resources/api-credentials)**             | Make sure that you have created the following:- [API credential](/development-resources/api-credentials/#new-credential)
- [API key](/development-resources/api-credentials/#generate-api-key)
- [Client key](/development-resources/client-side-authentication/#get-your-client-key)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| **[Adyen API credential roles](/development-resources/api-credentials/roles/)** | Make sure that you have the [roles for payments](/development-resources/api-credentials/roles/#roles-for-payments) that are assigned by default.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| **[Webhooks](/development-resources/webhooks)**                                 | Subscribe to the following webhooks:- Standard webhook with [default event codes](/development-resources/webhooks/webhook-types/#default-event-codes)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| **Limitations**                                                                 | Make sure that your integration follows our recommended best practices:- **[\<iframe>](/online-payments/best-practices/#avoid-iframe-elements)**: an \<iframe> must be hosted on the same domain as the parent window to support payment flows that use redirects.
- **[WebViews](/online-payments/best-practices/#avoid-webviews)**: we do not recommend using WebViews in native apps due to security and functionality limitations. Use native equivalents instead.
- **[Server-side Rendering (SSR)](/online-payments/best-practices/#manage-server-side-rendering-ssr-)**: if you use SSR, ensure the `AdyenCheckout` instance and Components are initialized on the client side.
- **[Browser support](/online-payments/best-practices/#supported-browsers)**: we support recent versions of all major browsers.For [3D Secure 2](/online-payments/3d-secure):- A strict [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/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 specify to use the redirect flow when creating a session if you do not want to adjust your CSP. |
| **Setup steps**                                                                 | Make sure that you have done the following:- [Set up your test account](/online-payments/integration-checklist/#set-up-your-test-account).
- [Got an overview of what is required before you accept live payments](/online-payments/integration-checklist/#set-up-your-test-account).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Install Api Library

## 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.

### Tab: Java

##### Try our example integration

![](/reuse/development-resources/install-api-library/java/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-java-spring-online-payments#checkout-example).\
![](/reuse/development-resources/install-api-library/java/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-java-spring-online-payments).

#### Requirements

* Java 11 or later.

#### Installation

You can use [Maven](https://maven.apache.org), adding this dependency to your project's POM.

**Add the API library**

```xml
<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](https://github.com/Adyen/adyen-java-api-library/releases).

#### Setting up the client

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

**Set up your client**

```java
// 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);
    }
}
```

### Tab: PHP

##### Try our example integration

![](/reuse/development-resources/install-api-library/php/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-php-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/php/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-php-online-payments).

#### 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](https://getcomposer.org/). Follow the [installation instructions](https://getcomposer.org/doc/00-intro.md) if you do not already have composer installed.

**Install the API library**

```bash
composer require adyen/php-api-library
```

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

**Include the autoloader**

```php
require __DIR__ . '/vendor/autoload.php';
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-php-api-library/releases).

#### Set up the client

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

**Set up your client**

```php
use Adyen\Model\Checkout\Amount;
use Adyen\Model\Checkout\CreateCheckoutSessionRequest;
use Adyen\Service\Checkout\PaymentsApi;

// Include your idempotency key when you make an API request.
$requestOptions['idempotencyKey'] = "YOUR_IDEMPOTENCY_KEY";

// Set up the client and service.
$client = new \Adyen\Client();
$client->setXApiKey('ADYEN_API_KEY');
$client->setEnvironment(\Adyen\Environment::TEST);

$service = new PaymentsApi($client);
```

### Tab: C\#

#### 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](https://www.nuget.org/packages/Adyen/):

**Install the API library**

```bash
PM> Install-Package Adyen -Version LATEST_VERSION
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-dotnet-api-library).

#### Set up the client

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

**Set up your client**

```cs
using Adyen;
using Adyen.Model.Checkout;
using Adyen.Service.Checkout;
using Environment = Adyen.Model.Environment;

class Program
{
    static void Main()
    {
        // Set up the client and service.
        var config = new Config
        {
            XApiKey = "ADYEN_API_KEY",
            Environment = Environment.Test
        };
        var client = new Client(config);
        var checkout = new PaymentsService(client);

        // Include your idempotency key when you make an API request.
        var requestOptions = new Adyen.Model.RequestOptions { IdempotencyKey = "YOUR_IDEMPOTENCY_KEY" };
    }
}
```

### Tab: NodeJS

##### Try our example integration

![](/reuse/development-resources/install-api-library/node-js/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-node-online-payments#checkout-example).\
![](/reuse/development-resources/install-api-library/node-js/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-node-online-payments).

#### Requirements

* Node.js version 18 or later.

#### Installation

You can use [npm](https://www.npmjs.com/):

**Install the API library**

```bash
npm install --save @adyen/api-library
npm update @adyen/api-library
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-node-api-library/releases).

#### Setting up the client

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

**Set up your client**

```js
// Require the parts of the module you want to use.
const { Client, CheckoutAPI, Types} = require("@adyen/api-library");

// Set up the client and service.
const client = new Client({ apiKey: "ADYEN_API_KEY", environment: "TEST" });
const checkoutApi = new CheckoutAPI(client);

// Include your idempotency key when you make an API request.
const requestOptions = { idempotencyKey: "YOUR_IDEMPOTENCY_KEY" };
```

### Tab: Go

##### Try our example integration

![](/reuse/development-resources/install-api-library/go/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-golang-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/go/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-golang-online-payments).

#### Requirements

* Go 1.13 or later.

#### Installation

You can use [Go modules](https://github.com/golang/go/wiki/Modules):

**Install the API library**

```shell
go get github.com/adyen/adyen-go-api-library/vLATEST_VERSION
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-go-api-library).

#### Set up the client

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

**Set up your client**

```go
package main

import (
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/adyen"
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/checkout"
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/common"
)

// Create a payment object.

func main () {
	client := adyen.NewClient(&common.Config{
		ApiKey: "ADYEN_API_KEY",
		Environment: common.TestEnv,
	})
	service := client.Checkout()
```

### Tab: Python

##### Try our example integration

![](/reuse/development-resources/install-api-library/python/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-python-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/python/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-python-online-payments).

#### Requirements

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

#### Installation

You can use [pip](https://pip.pypa.io/en/stable/):

**Install the API library**

```py
pip install Adyen
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-python-api-library).

#### Set up the client

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

**Set up your client**

```py
import Adyen

# Set up the client and service.
adyen = Adyen.Adyen()
adyen.client.xapikey = "ADYEN_API_KEY"
adyen.client.platform = "test" # The environment that the library is used in.
```

### Tab: Ruby

##### Try our example integration

![](/reuse/development-resources/install-api-library/ruby/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-rails-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/ruby/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-rails-online-payments).

#### Requirements

* Ruby 2.7 or later.

#### Installation

You can use [RubyGems](https://rubygems.org/):

**Install the API library**

```bash
gem install adyen-ruby-api-library
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-ruby-api-library/releases).

Run `bundle install` to install dependencies.

#### Set up the client

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

**Set up your client**

```ruby
require 'adyen-ruby-api-library'

# Set up the client and service.
adyen = Adyen::Client.new
adyen.api_key = 'ADYEN_API_KEY'
adyen.env = :test # The environment that the library is used in.
```

## Create a 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 [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) request, including:

| Parameter name                                                                                                                                 | Required                                                                                                      | Description                                                                                                                                                                                                                                                                                                     |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `merchantAccount`                                                                                                                              | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your merchant account name.                                                                                                                                                                                                                                                                                     |
| `amount`                                                                                                                                       | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The `currency` and `value` of the payment, in [minor units](/development-resources/currency-codes). This is used to filter the list of available payment methods to your shopper.                                                                                                                               |
| `returnUrl`                                                                                                                                    | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | URL to where the shopper should be taken back to after a redirection. 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`                                                                                                                                    | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your unique reference for the payment. Minimum length: three characters.                                                                                                                                                                                                                                        |
| `countryCode`                                                                                                                                  |                                                                                                               | The shopper's country code. This is used to filter the list of available payment methods to your shopper. If not set, setting the `locale` is required in the front-end [global configuration](#configure).                                                                                                     |
| `channel`                                                                                                                                      |                                                                                                               | The platform where the payment is taking place. Use **Web**.                                                                                                                                                                                                                                                    |
| `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.                                 |
| `shopperLocale`                                                                                                                                |                                                                                                               | The language that the payment methods will appear in if the `locale` in your front-end [global configuration](#configure) isn't set. Set it to the shopper's language and country code. The default is **en-US**.                                                                                               |
| `shopperEmail`                                                                                                                                 |                                                                                                               | The shopper's email address. Strongly recommended because this field is used in a number of [risk checks](/risk-management/configure-your-risk-profile/risk-field-reference), and for 3D Secure.                                                                                                                |
| `shopperReference`                                                                                                                             |                                                                                                               | Your reference to uniquely identify this shopper. Strongly recommended because this field is used in a number of [risk checks](/risk-management/configure-your-risk-profile/risk-field-reference).                                                                                                              |
| `payable`                                                                                                                                      |                                                                                                               | Checkout API v72 or later. If you want to support [updating the amount](#update-amount) after creating the payment session, set to **false**.                                                                                                                                                                   |
| [`applicationInfo`](/development-resources/building-adyen-solutions)                                                                           |                                                                                                               | If you are building an Adyen solution for multiple merchants, include some basic identifying information, so that we can offer you better support.                                                                                                                                                              |
| [nativeThreeDS](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-authenticationData-threeDSRequestData-nativeThreeDS) |                                                                                                               | When set to **disabled**, the redirect flow is used for [3D Secure 2 authentication](/online-payments/3d-secure). This lets you use the redirect flow to avoid adjusting your [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) to load the 3D Secure 2 interfaces. |

Here is an example of how to create a session for a payment of **10** EUR:

#### curl

```bash
curl https://checkout-test.adyen.com/v71/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": "https://your-company.example.com/checkout?shopperOrder=12xy..",
  "reference": "YOUR_PAYMENT_REFERENCE",
  "countryCode": "NL"
}'
```

#### Java

```java
// Adyen Java API Library v27.0.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, additionally include your liveEndpointUrlPrefix.
Client client = new Client("ADYEN_API_KEY", Environment.TEST);

// Create the request object(s)
Amount amount = new Amount()
  .currency("EUR")
  .value(1000L);

CreateCheckoutSessionRequest createCheckoutSessionRequest = new CreateCheckoutSessionRequest()
  .reference("YOUR_PAYMENT_REFERENCE")
  .amount(amount)
  .merchantAccount("YOUR_MERCHANT_ACCOUNT")
  .countryCode("NL")
  .returnUrl("https://your-company.example.com/checkout?shopperOrder=12xy..");

// Send the request
PaymentsApi service = new PaymentsApi(client);
CreateCheckoutSessionResponse response = service.sessions(createCheckoutSessionRequest, new RequestOptions().idempotencyKey("UUID"));
```

#### PHP

```php
// Adyen PHP API Library v19.0.0
use Adyen\Client;
use Adyen\Environment;
use Adyen\Model\Checkout\Amount;
use Adyen\Model\Checkout\CreateCheckoutSessionRequest;
use Adyen\Service\Checkout\PaymentsApi;

$client = new Client();
$client->setXApiKey("ADYEN_API_KEY");
// For the live environment, additionally include your liveEndpointUrlPrefix.
$client->setEnvironment(Environment::TEST);


// Create the request object(s)
$amount = new Amount();
$amount
  ->setCurrency("EUR")
  ->setValue(1000);

$createCheckoutSessionRequest = new CreateCheckoutSessionRequest();
$createCheckoutSessionRequest
  ->setReference("YOUR_PAYMENT_REFERENCE")
  ->setAmount($amount)
  ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT")
  ->setCountryCode("NL")
  ->setReturnUrl("https://your-company.example.com/checkout?shopperOrder=12xy..");

$requestOptions['idempotencyKey'] = 'UUID';

// Send the request
$service = new PaymentsApi($client);
$response = $service->sessions($createCheckoutSessionRequest, $requestOptions);
```

#### C\#

```cs
// Adyen .net API Library v17.0.0
using Adyen;
using Environment = Adyen.Model.Environment;
using Adyen.Model;
using Adyen.Model.Checkout;
using Adyen.Service.Checkout;

// For the live environment, additionally include your liveEndpointUrlPrefix.
var config = new Config()
{
    XApiKey = "ADYEN_API_KEY",
    Environment = Environment.Test
};
var client = new Client(config);

// Create the request object(s)
Amount amount = new Amount
{
  Currency = "EUR",
  Value = 1000
};

CreateCheckoutSessionRequest createCheckoutSessionRequest = new CreateCheckoutSessionRequest
{
  Reference = "YOUR_PAYMENT_REFERENCE",
  Amount = amount,
  MerchantAccount = "YOUR_MERCHANT_ACCOUNT",
  CountryCode = "NL",
  ReturnUrl = "https://your-company.example.com/checkout?shopperOrder=12xy.."
};

// Send the request
var service = new PaymentsService(client);
var response = service.Sessions(createCheckoutSessionRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"});
```

#### Go

```go
// Adyen Go API Library v10.4.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, additionally include your liveEndpointUrlPrefix.
client := adyen.NewClient(&common.Config{
  ApiKey:      "ADYEN_API_KEY",
  Environment: common.TestEnv,
})

// Create the request object(s)
amount := checkout.Amount{
  Currency: "EUR",
  Value: 1000,
}

createCheckoutSessionRequest := checkout.CreateCheckoutSessionRequest{
  Reference: "YOUR_PAYMENT_REFERENCE",
  Amount: amount,
  MerchantAccount: "YOUR_MERCHANT_ACCOUNT",
  CountryCode: common.PtrString("NL"),
  ReturnUrl: "https://your-company.example.com/checkout?shopperOrder=12xy..",
}

// Send the request
service := client.Checkout()
req := service.PaymentsApi.SessionsInput().IdempotencyKey("UUID").CreateCheckoutSessionRequest(createCheckoutSessionRequest)
res, httpRes, err := service.PaymentsApi.Sessions(context.Background(), req)
```

#### Python

```py
# Adyen Python API Library v12.5.1
import Adyen

adyen = Adyen.Adyen()
adyen.client.xapikey = "ADYEN_API_KEY"
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.client.platform = "test" # The environment to use library in.

# Create the request object(s)
json_request = {
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "amount": {
    "value": 1000,
    "currency": "EUR"
  },
  "returnUrl": "https://your-company.example.com/checkout?shopperOrder=12xy..",
  "reference": "YOUR_PAYMENT_REFERENCE",
  "countryCode": "NL"
}

# Send the request
result = adyen.checkout.payments_api.sessions(request=json_request, idempotency_key="UUID")
```

#### Ruby

```rb
# Adyen Ruby API Library v9.5.1
require "adyen-ruby-api-library"

adyen = Adyen::Client.new
adyen.api_key = 'ADYEN_API_KEY'
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.env = :test # Set to "live" for live environment

# Create the request object(s)
request_body = {
  :merchantAccount => 'YOUR_MERCHANT_ACCOUNT',
  :amount => {
    :value => 1000,
    :currency => 'EUR'
  },
  :returnUrl => 'https://your-company.example.com/checkout?shopperOrder=12xy..',
  :reference => 'YOUR_PAYMENT_REFERENCE',
  :countryCode => 'NL'
}

# Send the request
result = adyen.checkout.payments_api.sessions(request_body, headers: { 'Idempotency-Key' => 'UUID' })
```

#### NodeJS (TypeScript)

```ts
// Adyen Node API Library v18.0.0
// Require the parts of the module you want to use
import { Client, CheckoutAPI, Types } from "@adyen/api-library";
// Initialize the client object
// For the live environment, additionally include your liveEndpointUrlPrefix.
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object(s)
const amount: Types.checkout.Amount = {
  currency: "EUR",
  value: 1000
};

const createCheckoutSessionRequest: Types.checkout.CreateCheckoutSessionRequest = {
  reference: "YOUR_PAYMENT_REFERENCE",
  amount: amount,
  merchantAccount: "YOUR_MERCHANT_ACCOUNT",
  countryCode: "NL",
  returnUrl: "https://your-company.example.com/checkout?shopperOrder=12xy.."
};

// Send the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.sessions(createCheckoutSessionRequest, { idempotencyKey: "UUID" });
```

The response contains:

* `sessionData`: the payment session data you need to pass to your front end.
* `id`: a unique identifier for the session data.
* The request body.

**HTTP 201 /sessions response body**

```json
{
    "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": "https://your-company.example.com/checkout?shopperOrder=12xy..",
    "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](/development-resources/error-codes) to troubleshoot.

### Prepare Front End

## Prepare your front end

Client website

Use a Component to show each available payment method, and to collect payment details from your shoppers.

### Get Adyen Web

### Install Adyen Web

Use the Adyen Web npm package, or embed the Adyen Web script and stylesheet into your HTML file:

### Tab: npm (recommended)

Install the [Adyen Web Node package](https://www.npmjs.com/package/@adyen/adyen-web):

```bash
npm install @adyen/adyen-web --save
```

Import Adyen Web into your application.

```js
import { AdyenCheckout, Card } from '@adyen/adyen-web';
import '@adyen/adyen-web/styles/adyen.css';
```

### Tab: Embed script and stylesheet

Use the `integrity` attribute so browsers can verify that the script and stylesheet have not been changed unexpectedly.

The value of the `integrity` attribute is the [Subresource Integrity (SRI) hash](/online-payments/web-best-practices#implement-subresource-integrity-hashes) which Adyen provides for each version of the Adyen Web JavaScript and CSS files.

Get the SRI hashes in the [release notes](/online-payments/release-notes?integration_type=web), under **Updating to this version**.

**checkout.html**

```html
<!-- Embed the Adyen Web script element above any other JavaScript in your checkout page. -->
<script src="https://checkoutshopper-test.cdn.adyen.com/sdk/VERSION/adyen.js"
   integrity="JS_INTEGRITY_HASH_FOR_YOUR_VERSION"
   crossorigin="anonymous"></script>

<!-- Embed the Adyen Web stylesheet. You can add your own styling by overriding the rules in the CSS file -->
<link rel="stylesheet" href="https://checkoutshopper-test.cdn.adyen.com/checkoutshopper/sdk/VERSION/adyen.css"
    integrity="CSS_INTEGRITY_HASH_FOR_YOUR_VERSION"
    crossorigin="anonymous">
```

Components resources are available on the `window` global variable.

### Create Dom Element

### Create a DOM element for the Component

Create a DOM container element on your checkout page where you want the Component to be rendered and give it a descriptive `id`. We strongly recommend that you do not put it in an [iframe element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe), because it may cause issues.

For example, if you are implementing the Card Component:

**Create a DOM element**

```html
<div id="card-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 do not re-render the DOM element.

### Configure And Create Instances

## Create the Component

Client website

Components consists of:

* `AdyenCheckout`: represents one payment and is linked to a payment session, environment, and amount to be paid.
* Components: represent the payment method-specific interface a shopper completes their payment with.

With the `AdyenCheckout` instance, you can create one or multiple Components.

### Create your instance of AdyenCheckout

Create a global configuration object that you use to create the instance of `AdyenCheckout`. The object contains configuration parameters and event handlers.

1. Add configuration parameters.

   | Parameter name    | Required                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
   | ----------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | `session`         | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The payment session object from your call to `/sessions`. Contains a `session.id` and `session.sessionData`.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
   | `environment`     | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Use **test**. When you are ready to accept live payments, change the value to one of our [live environments](#test-and-go-live).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
   | `amount`          | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | An object representing the amount to be displayed on the **Pay** Button. Its properties are `value` (the amount in the currencies smallest unit, for example cents for EUR) and `currency`.                                                                                                                                                                                                                                                                                                                                                                               |
   | `countryCode`     | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The shopper's country code. This is used to filter the list of available payment methods to your shopper.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
   | `locale`          | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The language used in the the Component UI. For possible values, see the [list of available languages](https://github.com/Adyen/adyen-web/tree/main/packages/server/translations). By default, this is the either the `shopperLocale` from your `/sessions` request or, if this locale is not available on Components, **en-US**.                                                                                                                                                                                                                                          |
   | `showPayButton`   |                                                                                                               | Shows or hides a **Pay** Button for each payment method. Defaults to **true**. The **Pay** button triggers the `onSubmit` event when payment details are valid. If you want to disable the button and then trigger the submit flow on your own, set this to **false** and call the `.submit()` method from your own button implementation. PayPal Smart Payment Buttons doesn't support the `.submit()` method.                                                                                                                                                           |
   | `secondaryAmount` |                                                                                                               | Shows the payment amount in an additional currency on the **Pay** button. You must do the currency conversion and set the amount. This object has properties:- `currency`: The three-character [ISO currency code](/development-resources/currency-codes).
   - `value`: The amount of the transaction, in [minor units](/development-resources/currency-codes).
   - `currencyDisplay`: Sets the [currency formatting](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#currencydisplay). Default: **symbol**.
    |
   | `donation`        |                                                                                                               | An object for configuring [donations](/online-payments/donations/integration-options/sessions-flow/) after a successful payment.                                                                                                                                                                                                                                                                                                                                                                                                                                          |

2. Add event handlers, to handle events that get triggered during the payment.

   | Event handler name                               | Required                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
   | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | `onPaymentCompleted(result, component)`          | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Create an event handler, called when the payment is completed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
   | `onPaymentFailed(result, component)`             | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Create an event handler, called when the payment failed. A failed payment has result code **Cancelled**, **Error** or **Refused**.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
   | `onError(error)`                                 |                                                                                                               | Create an event handler, called when an error occurs in Components.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
   | `beforeSubmit(data, component, actions)`         |                                                                                                               | Create an event handler, called when the shopper selects the **Pay** button. Do not use if you are implementing an [additional use case](/online-payments/build-your-integration#supported-use-cases). Allows you to add parameters to the payment request that the Component makes. For example, you can add shopper details like [`billingAddress`](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-billingAddress), [`deliveryAddress`](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-deliveryAddress), [`shopperEmail`](https://docs.adyen.com/api-explorer/Checkout/latest/payments#request-shopperEmail), or [`shopperName`](https://docs.adyen.com/api-explorer/Checkout/latest/payments#request-shopperName). When the `beforeSubmit` event is triggered, you need to continue or stop the payment flow using methods available in the event handler:- Continue the payment flow (`actions.resolve()`): You should call the `actions.resolve()` method regardless of the `resultCode`, including when the payment is unsuccessful.
   - Stop the payment flow (`actions.reject()`): Stop the payment flow only when your server-side API request to Adyen failed, or when experiencing network connection issues. |
   | `onSubmit(state, component, actions)`            |                                                                                                               | Required if you need to [update the payment amount after rendering the Component](/online-payments/build-your-integration#supported-use-cases). For this additional use case, you need to integrate additional endpoints. Creates an event handler, called when the shopper selects the **Pay** button and payment details are valid. When the `onSubmit` event is triggered, you need to continue or stop the payment flow using methods available in the event handler:- Continue the payment flow (`actions.resolve()`): You should call the `actions.resolve()` method regardless of the `resultCode`, including when the payment is unsuccessful.
   - Stop the payment flow (`actions.reject()`): Stop the payment flow only when your server-side API request to Adyen failed, or when experiencing network connection issues.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
   | []()`onActionHandled`                            |                                                                                                               | Create an event handler, called when an action, for example a QR code or 3D Secure 2 authentication screen, is shown to the shopper. The following `action.type` values trigger this callback:- `threeDS`
   - `qr`
   - `await`Returns data that contains:- `componentType`: The type of component that shows the action to the shopper.
   - `actionDescription`: A description of the action shown to the shopper.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
   | `onAdditionalDetails(state, component, actions)` |                                                                                                               | Required if you need to [confirm an additional action on your server](/online-payments/build-your-integration#supported-use-cases). For this additional use case, you need to integrate additional endpoints. Create an event handler, called when a payment method requires more details, for example for native 3D Secure 2, or native QR code payment methods.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
   | `onChange(state, component)`                     |                                                                                                               | Create an event handler, called when a change happens in the payment form.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |

   If an error occurs, the `onError` event returns an object which contains details about the error:

   | Error field     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
   | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | `error.name`    | The type of error. Use the values it returns to configure localized error messages for your shoppers:- **NETWORK\_ERROR**: a call that the Component made to the server has failed, for example because of a timeout, or if there is missing information in the request. Ask the shopper to try again.
   - **CANCEL**: the shopper canceled the payment. Only applies for payment methods that allow explicit cancellation in the UI, for example Apple Pay or PayPal.
   - **IMPLEMENTATION\_ERROR**: the method or parameter is incorrect or not supported.
   - **ERROR**: generic catch-all error. Tell the shopper something went wrong and ask them to try paying again, maybe with a different payment method. |
   | `error.message` | Gives more information for each type of error. The message is technical so you shouldn't show it to your shoppers. For `error.name`: **NETWORK\_ERROR**, the information in the `message` field depends on the environment:- **test**: you get a message with a [generic error code](/development-resources/error-codes#generic-error-codes) to help you troubleshoot.
   - **live**: the message from the response.                                                                                                                                                                                                                                                                                             |
   | `component`     | The name of the variable where you [created the instance of the Component](#create-and-mount-instance), for example **cardComponent**.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

   The `error` object may contain additional fields inherited from the [`Error()` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/Error).

   Combine the configuration parameters and event handlers into your global configuration object.

   **Create a global configuration object**

   ```js
   const globalConfiguration = {
     session: {
       id: 'CSD9CAC3...', // Unique identifier for the payment session.
       sessionData: 'Ab02b4c...' // The payment session data.
     },
     environment: 'test', // Change to 'live' for the live environment.
     amount: {
       value: 1000,
       currency: 'EUR'
     },
     locale: 'nl-NL',
     countryCode: 'NL',
     clientKey: 'test_870be2...', // Public key used for client-side authentication: https://docs.adyen.com/development-resources/client-side-authentication
     onPaymentCompleted: (result, component) => {
       console.info(result, component);
     },
     onPaymentFailed: (result, component) => {
       console.info(result, component);
     },
     onError: (error, component) => {
       console.error(error.name, error.message, error.stack, component);
     }
   };
   ```

3. Use this global configuration object to create an instance of `AdyenCheckout`.

   **Create an instance of AdyenCheckout**

   ```javascript
   // All of the resources that you imported are properties of the window.
   // In this example you imported Card.
   const { AdyenCheckout, Card } = window.AdyenWeb;

   const checkout = await AdyenCheckout(globalConfiguration);
   ```

   **Initializing in a reactive framework**\
   Modern frameworks can re-render UI components, which can cause unexpected behavior in the checkout. As a rule, [initialize `AdyenCheckout` and mount your Components only once](/online-payments/web-best-practices#handle-web-framework-re-renders) when you are ready to display the payment methods.

### Create your instance of Components

1. Optionally create another configuration object for the Component. For some payment methods, you must add additional configuration. You can also add optional configuration for some payment methods. For example, you can add [additional configuration for cards](/payment-methods/cards/web-drop-in/#optional-configurationn).[]()

   **Payment method configuration**

   ```javascript
   const cardConfiguration = {
     // Optional configuration.
     billingAddressRequired: true, // Show the billing address input fields and mark them as required.
     brandsConfiguration: {
       visa: { icon: 'https://...' } // Custom icon for Visa.
     }
   };
   ```

   Configuration for payment methods overrides global configuration. In the following example, the `onError()` configuration for `card` overrides the global `onError()` configuration.

   **Override global configuration**

   ```js
   // Global configuration object.
   const globalConfiguration = {
     // Global configuration for onError.
     onError: () => {},
   };

   // Card configuration object.
   const componentConfiguration = {
     // onError configuration for card payments. Overrides the global configuration.
     onError: () => {}
   };
   ```

2. Use the `paymentMethodsResponse` property of the `AdyenCheckout` instance to check the available payment methods.

3. If the payment method is available, create an instance of the Component and mount it to the [container element](#create-container-element) you created.

   The Component you use depends on the payment method. You can find which Component to use for which payment method on the [payment method pages](/payment-methods). For example, for cards, use `Card`.

   **checkout.js**

   ```js
   // 1. Check the available payment methods from the AdyenCheckout instance.
   console.log(checkout.paymentMethodsResponse); // => { paymentMethods: [...], storedPaymentMethods: [...] }

   // 2. Create an instance of the Component and mount it to the container you created.
   const cardComponent = new Card(checkout, cardConfiguration).mount('#card-container')
   ```

   The Github repository also includes a [Components map](https://github.com/Adyen/adyen-web/blob/main/packages/lib/src/components/components-name-map.ts) that shows which payment methods use which Components.

**

### Components methods

The following methods are available on [your instance of Components](#create-instance):

| Method name       | Description                                                                                                                                                                                                                                                                                                    |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mount(selector)` | Mounts the the Component into the DOM returned by the `selector`. The `selector` must be either a [valid CSS selector string](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector#parameters) or an [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement) reference. |
| `unmount()`       | Unmounts the the Component from the DOM. We recommend to unmount in case the payment amount changes after the initial mount.                                                                                                                                                                                   |
| `update()`        | Updates the properties and remounts the Component into the DOM, for example, if you want to change the properties of the configuration object after the Component is mounted.                                                                                                                                  |

### Optional Localization (optional)

**

### Localization

#### Supported languages

We include UI localizations for some languages. The fields and text are in the [files for the included locales](https://github.com/Adyen/adyen-web/tree/main/packages/server/translations).

To use a language or localization that isn't included, [create your own](#create-localization).

#### Change the language

The language of the UI is based on the `locale` set when creating your instance of `AdyenCheckout`.

If no `locale` is set when creating an instance of `AdyenCheckout`, the language displayed matches the `shopperLocale` from your [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) request.

If neither language is set or supported, the UI language defaults to US English.

#### Customize the localization

The text displayed in each localization can be customized, allowing you to replace the default text with your own.

To customize a localization:

1. Create a `translations` object on your payments page.

2. In this object, specify the `locale` you want to customize, and add key-value pairs corresponding to any text you want to customize.

   The following example shows how to customize the US English (`en-US`) translation so that:

   * **Shipping Address** appears instead of **Delivery Address** (the default **en-US** text).
   * **State** appears instead of **State or Province** (the default **en-US** text).

   **Customize translations**

   ```js
   const translations = {
     "en-US": {
       "deliveryAddress": "Shipping Address",
       "stateOrProvince": "State"
     }
   };
   ```

3. To use the customized localization in your payment form, provide the following parameters in the [`configuration` object](#configure):

   | Parameter name | Required                                                                                                      | Description                                       |
   | -------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
   | `locale`       | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The `locale` you customized in the previous step. |
   | `translations` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Use **translations**                              |

   The following example shows how to use a customized **en-US** localization in Drop-in.

   **Example of US English localization**

   ```js
   const configuration = {
     locale: "en-US",
     translations: translations,
     ...
   };
   ```

#### Create your custom localization

To use a language or localization that we do not included, create your own.

1. Create a `translations` object on your payments page.

2. In this object, specify the `locale` you want to create. For example, you can use the locale **nl-BE** to create a Belgian Dutch localization, and add key-value pairs corresponding to text shown in the UI.

   The example below shows a `translation` object for creating a **nl-BE** localization.

   **British English translations example**

   ```js
   const translations = {
     "nl-BE": {
       "paymentMethods.moreMethodsButton": "Meer betaalmethoden",
       "payButton": "Betaal",
       "storeDetails": "Bewaar voor mijn volgende betaling",
       ...
     }
   };
   ```

   The ellipsis (...) in the `translations` object above indicates the code sample isn't complete. For missing key-value pairs in your configuration, the translation defaults to **en-US**.

3. To use your localization in your payment form, provide the following parameters in the [`configuration` object](#configure):

   | Parameter name | Required                                                                                                      | Description                                    |
   | -------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
   | `locale`       | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The `locale` you created in the previous step. |
   | `translations` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Use **translations**                           |

   The example below shows how to use a created localization for **nl-BE**.

   ```js
   const configuration = {
     locale: "nl-BE",
     translations: translations,
     ...
   };

   const checkout = await AdyenCheckout(configuration);
   ```

#### Text direction

The default text direction is left-to-right. Text direction is independent from the `locale` you set in the `configuration` object. So even if you set the locale to a right-to-left language, like Arabic, you still need to set the text direction.

To change the text direction to right-to-left, use the [HTML `dir` attribute](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dir) on the parent element for the checkout container.

### Optional Update Amount (optional)

## Optional: Update the payment amount

You must use Checkout API v72 or later for this feature.

After you create a session, the order amount can change before the shopper submits the payment. For example: the shopper adds or removes items from their cart, or applies a discount. You can update the session with the new amount so that the shopper pays the correct total.

### Update the session amount

Client website

Payment server

1. Trigger the `beforeSubmit` callback from your instance of `AdyenCheckout` to make a PATCH `/sessions/{sessionId}` request to update the session from your server, including the follow parameters:

   | Parameter                      | Required                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                          |
   | ------------------------------ | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | `sessionId` **Path parameter** | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The ID of the session to update.                                                                                                                                                                                                                                                                                                                     |
   | `sessionData`                  | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The encoded session data from the original [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) response.                                                                                                                                                                                                                  |
   | `amount.value`                 | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The updated amount in [minor units](/development-resources/currency-codes).                                                                                                                                                                                                                                                                          |
   | `amount.currency`              | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The three-character [ISO currency code](/development-resources/currency-codes).                                                                                                                                                                                                                                                                      |
   | `payable`                      |                                                                                                               | If you know that the amount in this request is the final amount, set to **true**. This indicates that the session is ready for payment. When you set this to true, you can no longer update the session. If you set to **false**, you must make another request to update the session and set to **true** before the shopper can submit the payment. |

   **Example request to update the session amount**

   ```bash
   curl https://checkout-test.adyen.com/v72/sessions/QFQTPCQ8HXSKGK82 \
   -X PATCH \
   -H 'x-api-key: ADYEN_API_KEY' \
   -H 'idempotency-key: YOUR_IDEMPOTENCY_KEY' \
   -H 'content-type: application/json' \
   -d '{
     "sessionData": "Ab02b4c...",
     "amount": {
       "value": 10000,
       "currency": "EUR"
     },
     "payable": true
   }'
   ```

   After you set `payable` to **true**, you cannot update the session again. Only set this when you confirm the final amount, and the session is ready for payment.

   The response includes the updated session data.

   **Example response with updated session data**

   ```json
   {
       "sessionData": "Ab02b4c.."
   }
   ```

2. Add the updated `sessionData` object to the `actions.resolve` method, to pass it to the Component.

   When you make a request to update the server-side session data, you must store and get the updated amount on your server. Do not get the updated amount from the client.

   **Example of the beforeSubmit callback to update the session**

   ```ts
   const checkout = await AdyenCheckout({ 
     beforeSubmit: async (data, component, actions) => {
       try {
         // Get the latest session data.
         const { session } = component.core.session;
         // Make an PATCH /sessions/{sessionId} request to update the session.
         const updatedSessionData = await patchSession(session);
         // Add the updated session data to actions.resolve.
         actions.resolve({ ...data, sessionData: updatedSessionData });
       } catch (error) {
         actions.reject();
       }
     },
     // ...Other configuration properties
   });
   ```

### Update the amount in the Component

Client website

Update the amount in the Component when the payment amount changes (for example, when the shopper adds or removes items from their cart). The amount can be updated multiple times without the need to update the server-side session data every time. The server-side session update is required only before the shopper can submit the payment.

#### Show the updated amount to the shopper

Client website

To show the updated amount in the payment form:

From your [instance of `AdyenCheckout`](/online-payments/build-your-integration/sessions-flow/#configure), call the `update` function and pass the new amount.

**Example to update the amount in the payment form**

```ts
// Create an amount object for the updated amount.
const amount = { value: 1000, currency: 'USD' };
// Update the amount in the payment form, specifying not to reinitialize the checkout instance.
checkout.update({ amount }, { shouldReinitializeCheckout: false });
```

## Handle the payment

Client website

When you create and mount the Component, the shopper interacts with the interface to complete the payment. The whole payment flow is handled by the Component you configured and created, except for when a redirect happens.

### Handle The Redirect Result

### Handle the redirect

Some payment methods, like iDEAL and some 3D Secure flows, will redirect the shopper back to your website. When the shopper comes back to your website, show them the payment result, based on the result code. To get the `resultCode`, you can either:

* Create an instance of `AdyenCheckout` after the redirect, as described below.
* Confirm the redirect result on your server, for which you need to [implement an extra API endpoint](/online-payments/build-your-integration).

The shopper comes back to the `returnUrl` specified when [creating the payment session](#create-payment-session). The `returnUrl` has query parameters appended to it, which you need to handle the redirect:

* `sessionId`: the unique identifier for the shopper's payment session.
* `redirectResult`: details you need to submit to handle the redirect.

If the shopper doesn't return to you website, you do not get a `redirectResult`. You do not need to do anything to handle the redirect in this case. Instead, wait for the [webhook](#get-payment-outcome) that we send to your server.

**Example return URL**

```text
// The return URL has query parameters related to the payment session.
https://your-company.example.com/?sessionId=CSD9CAC34EBAE225DD&redirectResult=X6XtfGC3!Y...
```

Extract the values from the query string parameters and create a function which handles the redirect result. The function needs to:

1. Create an instance of Adyen Checkout using the `sessionId` value you extracted.
2. Submit the `redirectResult` value you extracted from the `returnUrl`.

**handleRedirectResult**

```js
// Create an instance of AdyenCheckout to handle the shopper returning to your website.
// Configure the instance with the sessionId you extracted from the returnUrl.
const checkout = await AdyenCheckout(configuration);

// Submit the redirectResult value you extracted from the returnUrl.
checkout.submitDetails({ details: { redirectResult: redirectResult } });
```

If the shopper doesn't return to your website, do not call `submitDetails`, because the result doesn't change when you attempt the request.

After you submit the `redirectResult` value, the Component calls the `onPaymentCompleted(result, component)` event. Use the [result code](/online-payments/build-your-integration/payment-result-codes#final-payment-status) in `result.resultCode` to inform the shopper.

To update your order management system, wait for the [webhook](#update-your-order-management-system) that we send to your server.

### Get The Outcome

## Get the payment outcome

After the Component finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.

### Inform the shopper

Client website

Depending on whether the payment was successful, the `onPaymentCompleted` or `onPaymentFailed` event is triggered.

From the relevant event, you can get the [`resultCode` ](/online-payments/payment-result-codes#final-payment-status)to inform the shopper about the current payment status.

**

### Optional: Get the result of the payment session on your server

Payment server

You can also get the result of the payment session on your server.

1. Get the `id` from the [`/sessions` response](#sessions-response).

2. Get `sessionResult` from the `onPaymentCompleted` or `onPaymentFailed` event.

3. Make a **GET** `/sessions/{id}?sessionResult={sessionResult}` request including the `id` and `sessionResult`. For example:

   The response includes the result of the payment session (`status`). For example:

   **Response with result of the payment session**

   ```json
   {
     "additionalData": {
       ...
     },
     "id": "CSD9CAC34EBAE225DD",
     "payments": [{
       "amount": {
         "currency": "EUR",
         "value": 1000
       },
       "paymentMethod": {
         "brand": "visa",
         "type": "scheme"
       },
       "pspReference": "TG9SNBJJNXRKDM92",
       "resultCode": "Authorised"
     }],
     "reference": "YOUR_PAYMENT_REFERENCE",
     "status": "completed"
   }
   ```

   The [additionalData](https://docs.adyen.com/api-explorer/Checkout/latest/get/sessions/\(sessionId\)#responses-200-additionalData) attributes in the response depend on the type of payment made.

   Possible statuses:

   | `status`           | Description                                                                                                                      |
   | ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
   | **completed**      | The shopper completed the payment. This means that the payment was authorized.                                                   |
   | **paymentPending** | The shopper is in the process of making the payment. This applies to payment methods with an asynchronous flow.                  |
   | **canceled**       | The shopper canceled the payment.                                                                                                |
   | **expired**        | The session expired (default: 1 hour after session creation). Shoppers can no longer complete the payment with this `sessionId`. |

The `status` included in the response doesn't get updated. Do not make the request again to check for payment status updates. Instead, check webhooks or the **Transactions** list in your [Customer Area](https://ca-test.adyen.com/).

### Update your order management system

Webhook server

You get the outcome of each payment asynchronously, in an **AUTHORISATION** [webhook](/development-resources/webhooks). Use the `merchantReference` from the webhook to match it to your order reference.\
For a successful payment, the event contains `success`: **true**.

**Example webhook for a successful payment**

```json
{
  "live": "false",
  "notificationItems":[
    {
      "NotificationRequestItem":{
        "eventCode":"AUTHORISATION",
        "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
        "reason":"033899:1111:03/2030",
        "amount":{
          "currency":"EUR",
          "value":2500
        },
        "operations":["CANCEL","CAPTURE","REFUND"],
        "success":"true",
        "paymentMethod":"mc",
        "additionalData":{
          "expiryDate":"03/2030",
          "authCode":"033899",
          "cardBin":"411111",
          "cardSummary":"1111",
          "checkoutSessionId":"CSF46729982237A879"
        },
        "merchantReference":"YOUR_REFERENCE",
        "pspReference":"NC6HT9CRT65ZGN82",
        "eventDate":"2021-09-13T14:10:22+02:00"
      }
    }
  ]
}
```

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

**Example webhook for an unsuccessful payment**

```json
{
  "live": "false",
  "notificationItems":[
    {
      "NotificationRequestItem":{
        "eventCode":"AUTHORISATION",
        "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
        "reason":"validation 101 Invalid card number",
        "amount":{
          "currency":"EUR",
          "value":2500
        },
        "success":"false",
        "paymentMethod":"unknowncard",
        "additionalData":{
          "expiryDate":"03/2030",
          "cardBin":"411111",
          "cardSummary":"1112",
          "checkoutSessionId":"861631540104159H"
        },
        "merchantReference":"YOUR_REFERENCE",
        "pspReference":"KHQC5N7G84BLNK43",
        "eventDate":"2021-09-13T14:14:05+02:00"
      }
    }
  ]
}
```

## Test and go live

Before going live, use our list of [test cards and other payment methods](/development-resources/test-cards-and-credentials/test-card-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](https://ca-test.adyen.com/), under **Transactions** > **Payments**.

To debug or troubleshoot test payments, you can also use [API logs](/development-resources/logs-resources/api-logs) in your test environment.

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

1. [Apply for a live account](/get-started-with-adyen/application-requirements). Review the process to start accepting payments on [Get started with Adyen](/get-started-with-adyen).

2. Assess your [PCI DSS compliance](/development-resources/pci-dss-compliance-guide#online-payments) by submitting the [Self-Assessment Questionnaire-A](https://www.pcisecuritystandards.org/documents/PCI-DSS-v3_2_1-SAQ-A.pdf).

3. [Configure your live account](/online-payments/go-live-checklist). 

4. Ensure your checkout is served over HTTPS. Non-HTTPS connections can result in payment processing failures.

5. Submit a request to add payment methods in your [live Customer Area](https://ca-live.adyen.com/).

6. Switch from test to our [live endpoints](/development-resources/live-endpoints#checkout-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, for example, when authenticating with 3D Secure 2.

7. Load Components from one of our live environments and set the `environment` to match your live endpoints:

   | 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**  |

### Staying up to date

After you go live, [keep your integration up-to-date](/online-payments/upgrade-your-integration#staying-up-to-date). Regular updates help you:

* Access new features as they are released.
* Improve checkout performance and accessibility for your customers.
* Update security to protect your business and your data.

## Next steps

[required](/online-payments/modify-payments)

[Modify payments](/online-payments/modify-payments)

[Find out how to cancel, refund, or capture a payment using our API.](/online-payments/modify-payments)

[Add payment methods](/payment-methods/add-payment-methods)

[Learn about payment methods and how to add them to your account.](/payment-methods/add-payment-methods)

[Tokenization](/online-payments/tokenization)

[Save shopper payment details for later payments.](/online-payments/tokenization)

[3D Secure authentication](/online-payments/3d-secure)

[Comply with regulations such as PSD2 SCA in Europe.](/online-payments/3d-secure)

## Web Hosted Checkout

Use our quick-to-integrate hosted solution

## iOS Drop-in

Use our pre-built UI for accepting payments

### Before You Begin

## Requirements

Before you begin, take into account the following requirements, limitations, and preparations.

| Requirement                                                                     | Description                                                                                                                                                                                                                                                                           |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Integration type**                                                            | Use this information to build an online payments integration.                                                                                                                                                                                                                         |
| **[Customer Area roles](/account/user-roles)**                                  | Make sure that you have the following roles:- **Merchant admin role**
- **Manage API credentials**                                                                                                                                                                                    |
| **[Adyen API credentials](/development-resources/api-credentials)**             | Make sure that you have created the following:- [API credential](/development-resources/api-credentials/#new-credential)
- [API key](/development-resources/api-credentials/#generate-api-key)
- [Client key](/development-resources/client-side-authentication/#get-your-client-key) |
| **[Adyen API credential roles](/development-resources/api-credentials/roles/)** | Make sure that you have the [roles for payments](/development-resources/api-credentials/roles/#roles-for-payments) that are assigned by default.                                                                                                                                      |
| **[Webhooks](/development-resources/webhooks)**                                 | Subscribe to the following webhooks:- Standard webhook with [default event codes](/development-resources/webhooks/webhook-types/#default-event-codes)                                                                                                                                 |
| **Setup steps**                                                                 | Make sure that you have done the following:- [Set up your test account](/online-payments/integration-checklist/#set-up-your-test-account).
- [Got an overview of what is required before you accept live payments](/online-payments/integration-checklist/#set-up-your-test-account). |

## How it works

For a Drop-in integration, you must implement the following parts:

* **Your payment server**: sends the API request to create a payment session.
* **Your client app**: shows the Drop-in UI where the shopper makes the payment. Drop-in 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:

1. The shopper goes to the checkout page.

2. Your server uses the shopper's country and currency information from your client to create a payment session.

3. Your client creates an instance of Drop-in using the session data from the server.

4. Drop-in shows the available payment methods, collects the shopper's payment details, handles additional actions, and presents the payment result to the shopper.

5. Your webhook server receives the notification containing the payment outcome.

![](/user/pages/filters/sessions-flow-integration/ios/5-0-0/02.how-it-works/drop-in-sessions.svg?decoding=auto\&fetchpriority=auto)

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

[![](/user/pages/reuse/online-payments/how-it-works-parts/servers.svg?decoding=auto\&fetchpriority=auto)](/#install-api-library)

[Payment server](/#install-api-library)

[Go to the integration steps for your server.](/#install-api-library)

[![](/user/pages/reuse/online-payments/how-it-works-parts/browser-developers.svg?decoding=auto\&fetchpriority=auto)](/#set-up)

[Client app](/#set-up)

[Go to the integration steps for your client app.](/#set-up)

[![](/user/pages/reuse/online-payments/how-it-works-parts/event-code.svg?decoding=auto\&fetchpriority=auto)](/#update-your-order-management-system)

[Webhook server](/#update-your-order-management-system)

[Go to the integration steps for your webhook server.](/#update-your-order-management-system)

### Install Api Library

## 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.

### Tab: Java

##### Try our example integration

![](/reuse/development-resources/install-api-library/java/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-java-spring-online-payments#checkout-example).\
![](/reuse/development-resources/install-api-library/java/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-java-spring-online-payments).

#### Requirements

* Java 11 or later.

#### Installation

You can use [Maven](https://maven.apache.org), adding this dependency to your project's POM.

**Add the API library**

```xml
<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](https://github.com/Adyen/adyen-java-api-library/releases).

#### Setting up the client

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

**Set up your client**

```java
// 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);
    }
}
```

### Tab: PHP

##### Try our example integration

![](/reuse/development-resources/install-api-library/php/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-php-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/php/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-php-online-payments).

#### 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](https://getcomposer.org/). Follow the [installation instructions](https://getcomposer.org/doc/00-intro.md) if you do not already have composer installed.

**Install the API library**

```bash
composer require adyen/php-api-library
```

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

**Include the autoloader**

```php
require __DIR__ . '/vendor/autoload.php';
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-php-api-library/releases).

#### Set up the client

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

**Set up your client**

```php
use Adyen\Model\Checkout\Amount;
use Adyen\Model\Checkout\CreateCheckoutSessionRequest;
use Adyen\Service\Checkout\PaymentsApi;

// Include your idempotency key when you make an API request.
$requestOptions['idempotencyKey'] = "YOUR_IDEMPOTENCY_KEY";

// Set up the client and service.
$client = new \Adyen\Client();
$client->setXApiKey('ADYEN_API_KEY');
$client->setEnvironment(\Adyen\Environment::TEST);

$service = new PaymentsApi($client);
```

### Tab: C\#

#### 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](https://www.nuget.org/packages/Adyen/):

**Install the API library**

```bash
PM> Install-Package Adyen -Version LATEST_VERSION
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-dotnet-api-library).

#### Set up the client

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

**Set up your client**

```cs
using Adyen;
using Adyen.Model.Checkout;
using Adyen.Service.Checkout;
using Environment = Adyen.Model.Environment;

class Program
{
    static void Main()
    {
        // Set up the client and service.
        var config = new Config
        {
            XApiKey = "ADYEN_API_KEY",
            Environment = Environment.Test
        };
        var client = new Client(config);
        var checkout = new PaymentsService(client);

        // Include your idempotency key when you make an API request.
        var requestOptions = new Adyen.Model.RequestOptions { IdempotencyKey = "YOUR_IDEMPOTENCY_KEY" };
    }
}
```

### Tab: NodeJS

##### Try our example integration

![](/reuse/development-resources/install-api-library/node-js/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-node-online-payments#checkout-example).\
![](/reuse/development-resources/install-api-library/node-js/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-node-online-payments).

#### Requirements

* Node.js version 18 or later.

#### Installation

You can use [npm](https://www.npmjs.com/):

**Install the API library**

```bash
npm install --save @adyen/api-library
npm update @adyen/api-library
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-node-api-library/releases).

#### Setting up the client

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

**Set up your client**

```js
// Require the parts of the module you want to use.
const { Client, CheckoutAPI, Types} = require("@adyen/api-library");

// Set up the client and service.
const client = new Client({ apiKey: "ADYEN_API_KEY", environment: "TEST" });
const checkoutApi = new CheckoutAPI(client);

// Include your idempotency key when you make an API request.
const requestOptions = { idempotencyKey: "YOUR_IDEMPOTENCY_KEY" };
```

### Tab: Go

##### Try our example integration

![](/reuse/development-resources/install-api-library/go/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-golang-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/go/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-golang-online-payments).

#### Requirements

* Go 1.13 or later.

#### Installation

You can use [Go modules](https://github.com/golang/go/wiki/Modules):

**Install the API library**

```shell
go get github.com/adyen/adyen-go-api-library/vLATEST_VERSION
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-go-api-library).

#### Set up the client

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

**Set up your client**

```go
package main

import (
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/adyen"
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/checkout"
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/common"
)

// Create a payment object.

func main () {
	client := adyen.NewClient(&common.Config{
		ApiKey: "ADYEN_API_KEY",
		Environment: common.TestEnv,
	})
	service := client.Checkout()
```

### Tab: Python

##### Try our example integration

![](/reuse/development-resources/install-api-library/python/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-python-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/python/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-python-online-payments).

#### Requirements

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

#### Installation

You can use [pip](https://pip.pypa.io/en/stable/):

**Install the API library**

```py
pip install Adyen
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-python-api-library).

#### Set up the client

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

**Set up your client**

```py
import Adyen

# Set up the client and service.
adyen = Adyen.Adyen()
adyen.client.xapikey = "ADYEN_API_KEY"
adyen.client.platform = "test" # The environment that the library is used in.
```

### Tab: Ruby

##### Try our example integration

![](/reuse/development-resources/install-api-library/ruby/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-rails-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/ruby/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-rails-online-payments).

#### Requirements

* Ruby 2.7 or later.

#### Installation

You can use [RubyGems](https://rubygems.org/):

**Install the API library**

```bash
gem install adyen-ruby-api-library
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-ruby-api-library/releases).

Run `bundle install` to install dependencies.

#### Set up the client

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

**Set up your client**

```ruby
require 'adyen-ruby-api-library'

# Set up the client and service.
adyen = Adyen::Client.new
adyen.api_key = 'ADYEN_API_KEY'
adyen.env = :test # The environment that the library is used in.
```

### Create Payment Session

## 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 [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) request, including:

| Parameter name                                                       | Required                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `merchantAccount`                                                    | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your merchant account name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `amount`                                                             | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The `currency` and `value` of the payment, in [minor units](/development-resources/currency-codes). This is used to filter the list of available payment methods to your shopper.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `returnUrl`                                                          | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The URL the shopper should be taken back to after a redirection. Use the custom URL for your app, for example, `my-app://adyen`, to take the shopper back to your app after they complete the payment outside of your app. For more information on setting a custom URL scheme, read the [Apple Developer documentation](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app). The URL can contain a maximum of 1024 characters. You can also include your own additional query parameters, for example, shopper ID or order reference number. 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`                                                          | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | 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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. Exception: **QZ** (Kosovo).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `channel`                                                            |                                                                                                               | The platform where the payment is taking place. Use **iOS**. 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 client app. 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](/risk-management/configure-standard-risk-rules/required-risk-field-reference), 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](/risk-management/configure-standard-risk-rules/required-risk-field-reference).                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| [`applicationInfo`](/development-resources/building-adyen-solutions) |                                                                                                               | 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](/development-resources/building-adyen-solutions).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

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

#### curl

```bash
curl https://checkout-test.adyen.com/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"
}'
```

#### Java

```java
// Adyen Java API Library v27.0.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, additionally include your liveEndpointUrlPrefix.
Client client = new Client("ADYEN_API_KEY", Environment.TEST);

// Create the request object(s)
Amount amount = new Amount()
  .currency("EUR")
  .value(1000L);

CreateCheckoutSessionRequest createCheckoutSessionRequest = new CreateCheckoutSessionRequest()
  .reference("YOUR_PAYMENT_REFERENCE")
  .amount(amount)
  .merchantAccount("YOUR_MERCHANT_ACCOUNT")
  .countryCode("NL")
  .returnUrl("my-app://adyen");

// Send the request
PaymentsApi service = new PaymentsApi(client);
CreateCheckoutSessionResponse response = service.sessions(createCheckoutSessionRequest, new RequestOptions().idempotencyKey("UUID"));
```

#### PHP

```php
// Adyen PHP API Library v19.0.0
use Adyen\Client;
use Adyen\Environment;
use Adyen\Model\Checkout\Amount;
use Adyen\Model\Checkout\CreateCheckoutSessionRequest;
use Adyen\Service\Checkout\PaymentsApi;

$client = new Client();
$client->setXApiKey("ADYEN_API_KEY");
// For the live environment, additionally include your liveEndpointUrlPrefix.
$client->setEnvironment(Environment::TEST);


// Create the request object(s)
$amount = new Amount();
$amount
  ->setCurrency("EUR")
  ->setValue(1000);

$createCheckoutSessionRequest = new CreateCheckoutSessionRequest();
$createCheckoutSessionRequest
  ->setReference("YOUR_PAYMENT_REFERENCE")
  ->setAmount($amount)
  ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT")
  ->setCountryCode("NL")
  ->setReturnUrl("my-app://adyen");

$requestOptions['idempotencyKey'] = 'UUID';

// Send the request
$service = new PaymentsApi($client);
$response = $service->sessions($createCheckoutSessionRequest, $requestOptions);
```

#### C\#

```cs
// Adyen .net API Library v17.0.0
using Adyen;
using Environment = Adyen.Model.Environment;
using Adyen.Model;
using Adyen.Model.Checkout;
using Adyen.Service.Checkout;

// For the live environment, additionally include your liveEndpointUrlPrefix.
var config = new Config()
{
    XApiKey = "ADYEN_API_KEY",
    Environment = Environment.Test
};
var client = new Client(config);

// Create the request object(s)
Amount amount = new Amount
{
  Currency = "EUR",
  Value = 1000
};

CreateCheckoutSessionRequest createCheckoutSessionRequest = new CreateCheckoutSessionRequest
{
  Reference = "YOUR_PAYMENT_REFERENCE",
  Amount = amount,
  MerchantAccount = "YOUR_MERCHANT_ACCOUNT",
  CountryCode = "NL",
  ReturnUrl = "my-app://adyen"
};

// Send the request
var service = new PaymentsService(client);
var response = service.Sessions(createCheckoutSessionRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"});
```

#### NodeJS (JavaScript)

```js
// Adyen Node API Library v18.0.0
// Require the parts of the module you want to use
const { Client, CheckoutAPI } = require('@adyen/api-library');
// Initialize the client object
// For the live environment, additionally include your liveEndpointUrlPrefix.
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object(s)
const createCheckoutSessionRequest = {
  merchantAccount: "YOUR_MERCHANT_ACCOUNT",
  amount: {
    value: 1000,
    currency: "EUR"
  },
  returnUrl: "my-app://adyen",
  reference: "YOUR_PAYMENT_REFERENCE",
  countryCode: "NL"
}

// Send the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.sessions(createCheckoutSessionRequest, { idempotencyKey: "UUID" });
```

#### Go

```go
// Adyen Go API Library v10.4.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, additionally include your liveEndpointUrlPrefix.
client := adyen.NewClient(&common.Config{
  ApiKey:      "ADYEN_API_KEY",
  Environment: common.TestEnv,
})

// Create the request object(s)
amount := checkout.Amount{
  Currency: "EUR",
  Value: 1000,
}

createCheckoutSessionRequest := checkout.CreateCheckoutSessionRequest{
  Reference: "YOUR_PAYMENT_REFERENCE",
  Amount: amount,
  MerchantAccount: "YOUR_MERCHANT_ACCOUNT",
  CountryCode: common.PtrString("NL"),
  ReturnUrl: "my-app://adyen",
}

// Send the request
service := client.Checkout()
req := service.PaymentsApi.SessionsInput().IdempotencyKey("UUID").CreateCheckoutSessionRequest(createCheckoutSessionRequest)
res, httpRes, err := service.PaymentsApi.Sessions(context.Background(), req)
```

#### Python

```py
# Adyen Python API Library v12.5.1
import Adyen

adyen = Adyen.Adyen()
adyen.client.xapikey = "ADYEN_API_KEY"
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.client.platform = "test" # The environment to use library in.

# Create the request object(s)
json_request = {
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "amount": {
    "value": 1000,
    "currency": "EUR"
  },
  "returnUrl": "my-app://adyen",
  "reference": "YOUR_PAYMENT_REFERENCE",
  "countryCode": "NL"
}

# Send the request
result = adyen.checkout.payments_api.sessions(request=json_request, idempotency_key="UUID")
```

#### Ruby

```rb
# Adyen Ruby API Library v9.5.1
require "adyen-ruby-api-library"

adyen = Adyen::Client.new
adyen.api_key = 'ADYEN_API_KEY'
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.env = :test # Set to "live" for live environment

# Create the request object(s)
request_body = {
  :merchantAccount => 'YOUR_MERCHANT_ACCOUNT',
  :amount => {
    :value => 1000,
    :currency => 'EUR'
  },
  :returnUrl => 'my-app://adyen',
  :reference => 'YOUR_PAYMENT_REFERENCE',
  :countryCode => 'NL'
}

# Send the request
result = adyen.checkout.payments_api.sessions(request_body, headers: { 'Idempotency-Key' => 'UUID' })
```

#### NodeJS (TypeScript)

```ts
// Adyen Node API Library v18.0.0
// Require the parts of the module you want to use
import { Client, CheckoutAPI, Types } from "@adyen/api-library";
// Initialize the client object
// For the live environment, additionally include your liveEndpointUrlPrefix.
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object(s)
const amount: Types.checkout.Amount = {
  currency: "EUR",
  value: 1000
};

const createCheckoutSessionRequest: Types.checkout.CreateCheckoutSessionRequest = {
  reference: "YOUR_PAYMENT_REFERENCE",
  amount: amount,
  merchantAccount: "YOUR_MERCHANT_ACCOUNT",
  countryCode: "NL",
  returnUrl: "my-app://adyen"
};

// Send the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.sessions(createCheckoutSessionRequest, { idempotencyKey: "UUID" });
```

The response contains:

* `sessionData`: the payment session data you need to pass to your client app.
* `id`: a unique identifier for the session data.
* The request body.

**HTTP 201 /sessions response body**

```json
{
    "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](/development-resources/error-codes) to troubleshoot.

### Get Adyen Ios

## Set up Drop-in

Client app

### 1. Get Adyen iOS

Choose how you want to install the Adyen iOS client-side library:

### Tab: Swift Package Manager

To install iOS Drop-in using Swift Package Manager, [follow the Apple guide](https://developer.apple.com/documentation/xcode/adding_package_dependencies_to_your_app) and specify:

* The repository URL as `https://github.com/Adyen/adyen-ios`.
* The Adyen iOS client-side library version to be at least **5.0.0**.

### Tab: CocoaPods

To install iOS Drop-in from CocoaPods:

1. Add `pod 'Adyen'` to your `Podfile`.
2. Run `pod install`.

### Tab: Carthage

To install iOS Drop-in from Carthage:

1. Add `github "adyen/adyen-ios"` to your `Cartfile`.
2. Run `carthage update`.
3. Link the framework with your target as described in [Carthage Readme](https://github.com/Carthage/Carthage#adding-frameworks-to-an-application).

### 2. Create the context

First, create an instance of `APIContext` that contains:

* The [client key](/development-resources/client-side-authentication#get-your-client-key).
* The [environment setting](#test-and-go-live).

Then, create an instance of `AdyenContext` that contains:

* The instance of `APIContext`.
* Payment information.

**Create the context**

```swift
// Set the client key and environment in an instance of APIContext.
let apiContext = APIContext(clientKey: clientKey, environment: Environment.test) // Set the environment to a live one when going live.
// Create the amount with the value in minor units and the currency code.
let amount = Amount(value: 1000, currencyCode: "EUR")
// Create the payment object with the amount and country code.
let payment = Payment(amount: amount, countryCode: "NL")
// Create an instance of AdyenContext, passing the instance of APIContext, and payment object.
let adyenContext = AdyenContext(apiContext: apiContext, payment:payment)
```

### 3. Create a configuration object

Use the fields from the [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) response to configure and create an instance of `AdyenSession`:

**Create a configuration object**

```swift
let configuration = AdyenSession.Configuration(sessionIdentifier: sessionId, // The id from the API response.
                                               initialSessionData: data, // The sessionData from the API response.)
```

### 4. Initialize `AdyenSession`

Call the static `initialize` function of the `AdyenSession`, setting:

* `configuration`: the configuration object you created in the previous step.
* `delegate`: your delegate object. For example, **self**.
* `presentationDelegate`: your delegate object. For example, **self**.

This asynchronously creates and returns an instance of the session.

**Initialize AdyenSession**

```swift
AdyenSession.initialize(with: configuration, delegate: self, presentationDelegate: self) { [weak self] result in
        switch result {
        case let .success(session):
            //Store the session object.
            self?.session = session
        case let .failure(error):
            //Handle the error.
        }
    }
```

### Configure Drop In

### 5. Configure Drop-in

Create a Drop-in configuration object (`DropInComponent.Configuration`). Some [payment methods](/payment-methods) require additional configuration, and you can add [optional configuration](#optional-configuration).[]()

**Configure Drop-in**

```js
let dropInConfiguration = DropInComponent.Configuration()
// Some payment methods have additional required or optional configuration.
// For example, an optional configuration to show the cardholder name field for cards.
dropInConfiguration.card.showsHolderNameField = true
```

### Initialize Drop In

### 6. Initialize the `DropInComponent` class

Set the instance of `AdyenSession` you created in the previous step as the `delegate` and, if you accept gift cards, `partialPaymentDelegate` of the `DropInComponent` instance.

**Initialize DropInComponent**

```swift
let dropInComponent = DropInComponent(paymentMethods: session.sessionContext.paymentMethods,
                                      context: adyenContext,
                                      configuration: dropInConfiguration)

// Keep the instance of Drop-in to so that it doesn't get destroyed after the function is executed.
self.dropInComponent = dropInComponent

// Set the session as the delegate.
dropInComponent.delegate = session
// If you support gift cards, set the session as the partial payment delegate.
dropInComponent.partialPaymentDelegate = session
```

### Show In App

### 7. Show Drop-in in your app

Call the `present` method, passing the configured `viewController`.

**Present Drop-in**

```swift
myCheckoutViewController.present(dropInComponent.viewController, animated: true)
```

Some payment methods require additional action from the shopper such as authenticating a payment with 3D Secure, or to switch to another app to complete the payment. Your instance of `AdyenSession` handles the actions to complete the payment.

If the `action` type is **redirect**, you need to [handle the redirect result](#handle-the-redirect).

### Handle Redirect

### 8. Handle the redirect

If the `action` field returns **redirect**, the shopper is redirected to an external site or to another application to complete the payment. You then need to inform the Drop-in when the shopper returns to your app.

The way to handle the redirect depends on if you use Custom or Universal URLs and the way you manage your app’s lifecycle events:

### Tab: UIApplicationDelegate

If you use a [Custom URL scheme](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app?language=objc), implement the following in your [`UIApplicationDelegate` ](https://developer.apple.com/documentation/uikit/uiapplicationdelegate):

**Handle the redirect for Custom URLs**

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

If you use a [Universal URL](https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app?language=objc), implement the following in your [`UIApplicationDelegate` ](https://developer.apple.com/documentation/uikit/uiapplicationdelegate)instead:

**Handle the redirect for Universal URLs**

```swift
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
            let incomingURL = userActivity.webpageURL else { return false }
    return RedirectComponent.applicationDidOpen(from: incomingURL)
}
```

### Tab: UISceneDelegate

If you use a [Custom URL scheme](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app?language=objc), implement the following in your [`UISceneDelegate` ](https://developer.apple.com/documentation/uikit/uiscenedelegate):

**Handle the redirect for Custom URLs**

```swift
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
     guard let url = URLContexts.first?.url else { return }
     RedirectComponent.applicationDidOpen(from: url)
}
```

If you use a [Universal URL](https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app?language=objc), implement the following in your [`UISceneDelegate` ](https://developer.apple.com/documentation/uikit/uiscenedelegate)instead:

**Handle the redirect for Universal URLs**

```swift
func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
        let url = userActivity.webpageURL else { return }
    RedirectComponent.applicationDidOpen(from: url)
}
```

### Handle Result

### 9. Handle the result

Drop-in handles a [result code](#result-codes) or an [error](#errors) object.

#### Result code

When the payment flow is finished, your instance of `AdyenSession` calls the `didComplete` method.

Implement the following in your [Drop-in configuration object](#drop-in-configuration-object).

**Implement didComplete**

```swift
func didComplete(with result: AdyenSessionResult, // The session result.
                 component: Component, // The Drop-in component.
                 session: AdyenSession) // Your instance of AdyenSession.
```

Use the `resultCode` to inform your shopper about the current [payment status](/account/payments-lifecycle). Possible values:

| `resultCode`         | Description                                                                                                                                             | Action to take                                                                                                                                                                                                                              |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **authorised**       | The payment was successfully authorised.                                                                                                                | Inform the shopper that the payment was successful.                                                                                                                                                                                         |
| **refused**          | The payment was refused. The response also contains a [refusal reason](/development-resources/refusal-reasons) that indicates why it was refused.       | Inform the shopper that the payment was refused.                                                                                                                                                                                            |
| **pending**          | The final status of the payment isn't available yet. This is common for payments with an asynchronous flow, such as Boleto or iDEAL.                    | Inform the shopper that you have received their order, and are waiting for them to complete the payment. When the shopper completes the payment, you [get a webhook with the updated payment status](#update-your-order-management-system). |
| **cancelled**        | The payment was cancelled (by either the shopper or your system) before processing was completed.                                                       | Inform the shopper that the payment was cancelled.                                                                                                                                                                                          |
| **error**            | An error occurred during payment processing. The response also contains an error code that gives more details about the error.                          | Inform the shopper that an error occurred during payment processing.                                                                                                                                                                        |
| **received**         | The payment request was received, but the final status of the payment isn't available yet. Some payments, like SEPA Direct Debit, take time to process. | Inform the shopper that you have received their order, and are waiting for the final payment status. When the updated payment status is available, you [get a webhook](#update-your-order-management-system).                               |
| **presentToShopper** | Show the voucher or QR code to the shopper.                                                                                                             | Inform the shopper that you have received their order, and are waiting for them to complete the payment. When the shopper completes the payment, you [get a webhook with the updated payment status](#update-your-order-management-system). |

### Errors

#### Error

If an error occurs during the payment flow, your instance of `AdyenSession` calls the `didFail` method containing the error.

Implement the following in your [Drop-in configuration object](#configure).

**Implement didFail**

```js
func didFail(with error: Error, // The error object.
             from component: Component, // The Drop-in component.
             session: AdyenSession) // Your instance of AdyenSession.
```

The error tells you the type of error and contains a message with details. Use the information to tell the shopper what happened and use the message to troubleshoot the error.

### Get-Payment-Outcome

## Get the payment outcome

After Drop-in finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.

### Inform the shopper

Client app

From the `didComplete` method, you can get the [`resultCode` ](/online-payments/payment-result-codes)to inform the shopper about the current payment status.

**

### Optional: Get the result of the payment session on your server

Payment server

You can also get the result of the payment session on your server.

1. Get the `id` from the [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) response.

2. Get `sessionResult` from the `onPaymentCompleted` event.

3. Make a **GET** `/sessions/{id}?sessionResult={sessionResult}` request including the `id` and `sessionResult`. For example:

   **Request for result of payment session**

   ```bash
   curl -X GET https://checkout-test.adyen.com/v71/sessions/CS12345678?sessionResult=SOME_DATA
   ```

   The response includes the result of the payment session (`status`). For example:

   **Response with result of the payment session**

   ```bash
   {
      "id": "CS12345678",
      "status": "completed"
   }
   ```

   Possible statuses:

   | `status`           | Description                                                                                                                      |
   | ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
   | **completed**      | The shopper completed the payment. This means that the payment was authorized.                                                   |
   | **paymentPending** | The shopper is in the process of making the payment. This applies to payment methods with an asynchronous flow.                  |
   | **canceled**       | The shopper canceled the payment.                                                                                                |
   | **expired**        | The session expired (default: 1 hour after session creation). Shoppers can no longer complete the payment with this `sessionId`. |

The `status` included in the response doesn't get updated. Do not make the request again to check for payment status updates. Instead, check webhooks or the **Transactions** list in your [Customer Area](https://ca-test.adyen.com/).

### Update your order management system

Webhook server

You get the outcome of each payment asynchronously, in an **AUTHORISATION** [webhook](/development-resources/webhooks). Use the `merchantReference` from the webhook to match it to your order reference.\
For a successful payment, the event contains `success`: **true**.

**Example webhook for a successful payment**

```json
{
  "live": "false",
  "notificationItems":[
    {
      "NotificationRequestItem":{
        "eventCode":"AUTHORISATION",
        "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
        "reason":"033899:1111:03/2030",
        "amount":{
          "currency":"EUR",
          "value":2500
        },
        "operations":["CANCEL","CAPTURE","REFUND"],
        "success":"true",
        "paymentMethod":"mc",
        "additionalData":{
          "expiryDate":"03/2030",
          "authCode":"033899",
          "cardBin":"411111",
          "cardSummary":"1111",
          "checkoutSessionId":"CSF46729982237A879"
        },
        "merchantReference":"YOUR_REFERENCE",
        "pspReference":"NC6HT9CRT65ZGN82",
        "eventDate":"2021-09-13T14:10:22+02:00"
      }
    }
  ]
}
```

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

**Example webhook for an unsuccessful payment**

```json
{
  "live": "false",
  "notificationItems":[
    {
      "NotificationRequestItem":{
        "eventCode":"AUTHORISATION",
        "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
        "reason":"validation 101 Invalid card number",
        "amount":{
          "currency":"EUR",
          "value":2500
        },
        "success":"false",
        "paymentMethod":"unknowncard",
        "additionalData":{
          "expiryDate":"03/2030",
          "cardBin":"411111",
          "cardSummary":"1112",
          "checkoutSessionId":"861631540104159H"
        },
        "merchantReference":"YOUR_REFERENCE",
        "pspReference":"KHQC5N7G84BLNK43",
        "eventDate":"2021-09-13T14:14:05+02:00"
      }
    }
  ]
}
```

## Test and go live

Before going live, use our list of [test cards and other payment methods](/development-resources/test-cards-and-credentials/test-card-numbers) to [test your integration](/development-resources/testing). 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](https://ca-test.adyen.com/), under **Transactions** > **Payments**.

To debug or troubleshoot test payments, you can also use [API logs](/development-resources/logs-resources/api-logs) in your test environment.

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

1. [Apply for a live account](/get-started-with-adyen/application-requirements). Review the process to start accepting payments on [Get started with Adyen](/get-started-with-adyen).

2. Assess your [PCI DSS compliance](/development-resources/pci-dss-compliance-guide#online-payments) by submitting the [Self-Assessment Questionnaire-A](https://www.pcisecuritystandards.org/documents/PCI-DSS-v3_2_1-SAQ-A.pdf).

3. [Configure your live account](/online-payments/go-live-checklist). 

4. Submit a request to add payment methods in your [live Customer Area](https://ca-live.adyen.com/) .

5. Switch from test to our [live endpoints](/development-resources/live-endpoints#checkout-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, for example, when authenticating with 3D Secure 2.

6. Load Drop-in from one of our live environments and set the `environment` to match your live endpoints:

   | 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**        |

### Optional Configuration Drop In (optional)

## Optional configuration

Client app

You can set additional configuration on the [Drop-in configuration](#configure).

| Parameter name                | Description                                                                                                                                             |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shopperInformation`          | Prefilled shopper information.                                                                                                                          |
| `localizationParameters`      | [Localization](#localization) parameters, like custom placeholders in other languages.                                                                  |
| `allowsSkippingPaymentList`   | If you support only one non-instant payment method, set to **true** to disable showing the list of payment methods in the app view. Default: **false**. |
| `allowPreselectedPaymentView` | Show the preselected stored payment method in the app view. Default: **true**.                                                                          |

The following example shows how to set an optional configuration parameter:

**Set optional configuration**

```js
let dropInConfiguration = DropInComponent.Configuration()

//Optional configuration to disable showing the preselected stored payment method.
dropInConfiguration.allowsSkippingPaymentList = true
```

### Localization

**

### Localization

iOS Drop-in supports the languages listed [here](https://github.com/Adyen/adyen-ios/tree/master/Adyen/Assets).

To customize a localization, add a new `localizable.strings` file for the language that you need. You can also override [existing strings](https://github.com/Adyen/adyen-ios/blob/master/Adyen/Assets/en-US.lproj/Localizable.strings) by using the same keys.

For example, to override the cardholder name field title, set the following on your `localizable.strings` file:

```swift
"adyen.card.nameItem.title" = "Your cardholder name";
```

To find localized strings, the library first checks your custom `localizable.strings` file, and then the default Adyen file.

You can use `LocalizationParameters` to customize the localization file name, bundle, or the separator for translation strings.

For example, if you store translations in `MyLocalizable.strings` files in the shared bundle `CommonBundle`:

```swift
let localizationParameters = LocalizationParameters(bundle: commonBundle, tableName: "MyLocalizable")
dropInComponent.localizationParameters = localizationParameters
```

## Next steps

[required](/online-payments/modify-payments)

[Modify payments](/online-payments/modify-payments)

[Find out how to cancel, refund, or capture a payment using our API.](/online-payments/modify-payments)

[Add payment methods](/payment-methods/add-payment-methods)

[Learn about payment methods and how to add them to your account.](/payment-methods/add-payment-methods)

[Tokenization](/online-payments/tokenization)

[Save shopper payment details for later payments.](/online-payments/tokenization)

[3D Secure authentication](/online-payments/3d-secure)

[Comply with regulations such as PSD2 SCA in Europe.](/online-payments/3d-secure)

## iOS Components

Use our customizable UI components

### Before You Begin

## Requirements

Before you begin, take into account the following requirements, limitations, and preparations.

| Requirement                                                                     | Description                                                                                                                                                                                                                                                                           |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Integration type**                                                            | Use this information to build an online payments integration.                                                                                                                                                                                                                         |
| **[Customer Area roles](/account/user-roles)**                                  | Make sure that you have the following roles:- **Merchant admin role**
- **Manage API credentials**                                                                                                                                                                                    |
| **[Adyen API credentials](/development-resources/api-credentials)**             | Make sure that you have created the following:- [API credential](/development-resources/api-credentials/#new-credential)
- [API key](/development-resources/api-credentials/#generate-api-key)
- [Client key](/development-resources/client-side-authentication/#get-your-client-key) |
| **[Adyen API credential roles](/development-resources/api-credentials/roles/)** | Make sure that you have the [roles for payments](/development-resources/api-credentials/roles/#roles-for-payments) that are assigned by default.                                                                                                                                      |
| **[Webhooks](/development-resources/webhooks)**                                 | Subscribe to the following webhooks:- Standard webhook with [default event codes](/development-resources/webhooks/webhook-types/#default-event-codes)                                                                                                                                 |
| **Setup steps**                                                                 | Make sure that you have done the following:- [Set up your test account](/online-payments/integration-checklist/#set-up-your-test-account).
- [Got an overview of what is required before you accept live payments](/online-payments/integration-checklist/#set-up-your-test-account). |

## 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:

1. The shopper goes to the checkout page.

2. Your server uses the shopper's country and currency information from your client to create a payment session.

3. Your client creates an instance of the Component using the session data from the server.

4. The Component collects the shopper's payment details, handles additional actions, and presents the payment result to the shopper.

5. Your webhook server receives the notification containing the payment outcome.

![](/user/pages/filters/sessions-flow-integration/ios/5-0-0/02.how-it-works/component-sessions.svg?decoding=auto\&fetchpriority=auto)

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

[![](/user/pages/reuse/online-payments/how-it-works-parts/servers.svg?decoding=auto\&fetchpriority=auto)](/#install-api-library)

[Payment server](/#install-api-library)

[Go to the integration steps for your server.](/#install-api-library)

[![](/user/pages/reuse/online-payments/how-it-works-parts/browser-developers.svg?decoding=auto\&fetchpriority=auto)](/#set-up)

[Client app](/#set-up)

[Go to the integration steps for your client app.](/#set-up)

[![](/user/pages/reuse/online-payments/how-it-works-parts/event-code.svg?decoding=auto\&fetchpriority=auto)](/#update-your-order-management-system)

[Webhook server](/#update-your-order-management-system)

[Go to the integration steps for your webhook server.](/#update-your-order-management-system)

### Install Api Library

## 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.

### Tab: Java

##### Try our example integration

![](/reuse/development-resources/install-api-library/java/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-java-spring-online-payments#checkout-example).\
![](/reuse/development-resources/install-api-library/java/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-java-spring-online-payments).

#### Requirements

* Java 11 or later.

#### Installation

You can use [Maven](https://maven.apache.org), adding this dependency to your project's POM.

**Add the API library**

```xml
<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](https://github.com/Adyen/adyen-java-api-library/releases).

#### Setting up the client

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

**Set up your client**

```java
// 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);
    }
}
```

### Tab: PHP

##### Try our example integration

![](/reuse/development-resources/install-api-library/php/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-php-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/php/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-php-online-payments).

#### 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](https://getcomposer.org/). Follow the [installation instructions](https://getcomposer.org/doc/00-intro.md) if you do not already have composer installed.

**Install the API library**

```bash
composer require adyen/php-api-library
```

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

**Include the autoloader**

```php
require __DIR__ . '/vendor/autoload.php';
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-php-api-library/releases).

#### Set up the client

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

**Set up your client**

```php
use Adyen\Model\Checkout\Amount;
use Adyen\Model\Checkout\CreateCheckoutSessionRequest;
use Adyen\Service\Checkout\PaymentsApi;

// Include your idempotency key when you make an API request.
$requestOptions['idempotencyKey'] = "YOUR_IDEMPOTENCY_KEY";

// Set up the client and service.
$client = new \Adyen\Client();
$client->setXApiKey('ADYEN_API_KEY');
$client->setEnvironment(\Adyen\Environment::TEST);

$service = new PaymentsApi($client);
```

### Tab: C\#

#### 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](https://www.nuget.org/packages/Adyen/):

**Install the API library**

```bash
PM> Install-Package Adyen -Version LATEST_VERSION
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-dotnet-api-library).

#### Set up the client

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

**Set up your client**

```cs
using Adyen;
using Adyen.Model.Checkout;
using Adyen.Service.Checkout;
using Environment = Adyen.Model.Environment;

class Program
{
    static void Main()
    {
        // Set up the client and service.
        var config = new Config
        {
            XApiKey = "ADYEN_API_KEY",
            Environment = Environment.Test
        };
        var client = new Client(config);
        var checkout = new PaymentsService(client);

        // Include your idempotency key when you make an API request.
        var requestOptions = new Adyen.Model.RequestOptions { IdempotencyKey = "YOUR_IDEMPOTENCY_KEY" };
    }
}
```

### Tab: NodeJS

##### Try our example integration

![](/reuse/development-resources/install-api-library/node-js/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-node-online-payments#checkout-example).\
![](/reuse/development-resources/install-api-library/node-js/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-node-online-payments).

#### Requirements

* Node.js version 18 or later.

#### Installation

You can use [npm](https://www.npmjs.com/):

**Install the API library**

```bash
npm install --save @adyen/api-library
npm update @adyen/api-library
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-node-api-library/releases).

#### Setting up the client

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

**Set up your client**

```js
// Require the parts of the module you want to use.
const { Client, CheckoutAPI, Types} = require("@adyen/api-library");

// Set up the client and service.
const client = new Client({ apiKey: "ADYEN_API_KEY", environment: "TEST" });
const checkoutApi = new CheckoutAPI(client);

// Include your idempotency key when you make an API request.
const requestOptions = { idempotencyKey: "YOUR_IDEMPOTENCY_KEY" };
```

### Tab: Go

##### Try our example integration

![](/reuse/development-resources/install-api-library/go/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-golang-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/go/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-golang-online-payments).

#### Requirements

* Go 1.13 or later.

#### Installation

You can use [Go modules](https://github.com/golang/go/wiki/Modules):

**Install the API library**

```shell
go get github.com/adyen/adyen-go-api-library/vLATEST_VERSION
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-go-api-library).

#### Set up the client

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

**Set up your client**

```go
package main

import (
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/adyen"
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/checkout"
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/common"
)

// Create a payment object.

func main () {
	client := adyen.NewClient(&common.Config{
		ApiKey: "ADYEN_API_KEY",
		Environment: common.TestEnv,
	})
	service := client.Checkout()
```

### Tab: Python

##### Try our example integration

![](/reuse/development-resources/install-api-library/python/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-python-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/python/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-python-online-payments).

#### Requirements

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

#### Installation

You can use [pip](https://pip.pypa.io/en/stable/):

**Install the API library**

```py
pip install Adyen
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-python-api-library).

#### Set up the client

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

**Set up your client**

```py
import Adyen

# Set up the client and service.
adyen = Adyen.Adyen()
adyen.client.xapikey = "ADYEN_API_KEY"
adyen.client.platform = "test" # The environment that the library is used in.
```

### Tab: Ruby

##### Try our example integration

![](/reuse/development-resources/install-api-library/ruby/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-rails-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/ruby/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-rails-online-payments).

#### Requirements

* Ruby 2.7 or later.

#### Installation

You can use [RubyGems](https://rubygems.org/):

**Install the API library**

```bash
gem install adyen-ruby-api-library
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-ruby-api-library/releases).

Run `bundle install` to install dependencies.

#### Set up the client

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

**Set up your client**

```ruby
require 'adyen-ruby-api-library'

# Set up the client and service.
adyen = Adyen::Client.new
adyen.api_key = 'ADYEN_API_KEY'
adyen.env = :test # The environment that the library is used in.
```

### Create Payment Session

## 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 [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) request, including:

| Parameter name                                                       | Required                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `merchantAccount`                                                    | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your merchant account name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `amount`                                                             | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The `currency` and `value` of the payment, in [minor units](/development-resources/currency-codes). This is used to filter the list of available payment methods to your shopper.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `returnUrl`                                                          | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The URL the shopper should be taken back to after a redirection. Use the custom URL for your app, for example, `my-app://adyen`, to take the shopper back to your app after they complete the payment outside of your app. For more information on setting a custom URL scheme, read the [Apple Developer documentation](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app). The URL can contain a maximum of 1024 characters. You can also include your own additional query parameters, for example, shopper ID or order reference number. 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`                                                          | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | 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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. Exception: **QZ** (Kosovo).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `channel`                                                            |                                                                                                               | The platform where the payment is taking place. Use **iOS**. 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 client app. 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](/risk-management/configure-standard-risk-rules/required-risk-field-reference), 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](/risk-management/configure-standard-risk-rules/required-risk-field-reference).                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| [`applicationInfo`](/development-resources/building-adyen-solutions) |                                                                                                               | 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](/development-resources/building-adyen-solutions).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

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

#### curl

```bash
curl https://checkout-test.adyen.com/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"
}'
```

#### Java

```java
// Adyen Java API Library v27.0.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, additionally include your liveEndpointUrlPrefix.
Client client = new Client("ADYEN_API_KEY", Environment.TEST);

// Create the request object(s)
Amount amount = new Amount()
  .currency("EUR")
  .value(1000L);

CreateCheckoutSessionRequest createCheckoutSessionRequest = new CreateCheckoutSessionRequest()
  .reference("YOUR_PAYMENT_REFERENCE")
  .amount(amount)
  .merchantAccount("YOUR_MERCHANT_ACCOUNT")
  .countryCode("NL")
  .returnUrl("my-app://adyen");

// Send the request
PaymentsApi service = new PaymentsApi(client);
CreateCheckoutSessionResponse response = service.sessions(createCheckoutSessionRequest, new RequestOptions().idempotencyKey("UUID"));
```

#### PHP

```php
// Adyen PHP API Library v19.0.0
use Adyen\Client;
use Adyen\Environment;
use Adyen\Model\Checkout\Amount;
use Adyen\Model\Checkout\CreateCheckoutSessionRequest;
use Adyen\Service\Checkout\PaymentsApi;

$client = new Client();
$client->setXApiKey("ADYEN_API_KEY");
// For the live environment, additionally include your liveEndpointUrlPrefix.
$client->setEnvironment(Environment::TEST);


// Create the request object(s)
$amount = new Amount();
$amount
  ->setCurrency("EUR")
  ->setValue(1000);

$createCheckoutSessionRequest = new CreateCheckoutSessionRequest();
$createCheckoutSessionRequest
  ->setReference("YOUR_PAYMENT_REFERENCE")
  ->setAmount($amount)
  ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT")
  ->setCountryCode("NL")
  ->setReturnUrl("my-app://adyen");

$requestOptions['idempotencyKey'] = 'UUID';

// Send the request
$service = new PaymentsApi($client);
$response = $service->sessions($createCheckoutSessionRequest, $requestOptions);
```

#### C\#

```cs
// Adyen .net API Library v17.0.0
using Adyen;
using Environment = Adyen.Model.Environment;
using Adyen.Model;
using Adyen.Model.Checkout;
using Adyen.Service.Checkout;

// For the live environment, additionally include your liveEndpointUrlPrefix.
var config = new Config()
{
    XApiKey = "ADYEN_API_KEY",
    Environment = Environment.Test
};
var client = new Client(config);

// Create the request object(s)
Amount amount = new Amount
{
  Currency = "EUR",
  Value = 1000
};

CreateCheckoutSessionRequest createCheckoutSessionRequest = new CreateCheckoutSessionRequest
{
  Reference = "YOUR_PAYMENT_REFERENCE",
  Amount = amount,
  MerchantAccount = "YOUR_MERCHANT_ACCOUNT",
  CountryCode = "NL",
  ReturnUrl = "my-app://adyen"
};

// Send the request
var service = new PaymentsService(client);
var response = service.Sessions(createCheckoutSessionRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"});
```

#### NodeJS (JavaScript)

```js
// Adyen Node API Library v18.0.0
// Require the parts of the module you want to use
const { Client, CheckoutAPI } = require('@adyen/api-library');
// Initialize the client object
// For the live environment, additionally include your liveEndpointUrlPrefix.
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object(s)
const createCheckoutSessionRequest = {
  merchantAccount: "YOUR_MERCHANT_ACCOUNT",
  amount: {
    value: 1000,
    currency: "EUR"
  },
  returnUrl: "my-app://adyen",
  reference: "YOUR_PAYMENT_REFERENCE",
  countryCode: "NL"
}

// Send the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.sessions(createCheckoutSessionRequest, { idempotencyKey: "UUID" });
```

#### Go

```go
// Adyen Go API Library v10.4.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, additionally include your liveEndpointUrlPrefix.
client := adyen.NewClient(&common.Config{
  ApiKey:      "ADYEN_API_KEY",
  Environment: common.TestEnv,
})

// Create the request object(s)
amount := checkout.Amount{
  Currency: "EUR",
  Value: 1000,
}

createCheckoutSessionRequest := checkout.CreateCheckoutSessionRequest{
  Reference: "YOUR_PAYMENT_REFERENCE",
  Amount: amount,
  MerchantAccount: "YOUR_MERCHANT_ACCOUNT",
  CountryCode: common.PtrString("NL"),
  ReturnUrl: "my-app://adyen",
}

// Send the request
service := client.Checkout()
req := service.PaymentsApi.SessionsInput().IdempotencyKey("UUID").CreateCheckoutSessionRequest(createCheckoutSessionRequest)
res, httpRes, err := service.PaymentsApi.Sessions(context.Background(), req)
```

#### Python

```py
# Adyen Python API Library v12.5.1
import Adyen

adyen = Adyen.Adyen()
adyen.client.xapikey = "ADYEN_API_KEY"
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.client.platform = "test" # The environment to use library in.

# Create the request object(s)
json_request = {
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "amount": {
    "value": 1000,
    "currency": "EUR"
  },
  "returnUrl": "my-app://adyen",
  "reference": "YOUR_PAYMENT_REFERENCE",
  "countryCode": "NL"
}

# Send the request
result = adyen.checkout.payments_api.sessions(request=json_request, idempotency_key="UUID")
```

#### Ruby

```rb
# Adyen Ruby API Library v9.5.1
require "adyen-ruby-api-library"

adyen = Adyen::Client.new
adyen.api_key = 'ADYEN_API_KEY'
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.env = :test # Set to "live" for live environment

# Create the request object(s)
request_body = {
  :merchantAccount => 'YOUR_MERCHANT_ACCOUNT',
  :amount => {
    :value => 1000,
    :currency => 'EUR'
  },
  :returnUrl => 'my-app://adyen',
  :reference => 'YOUR_PAYMENT_REFERENCE',
  :countryCode => 'NL'
}

# Send the request
result = adyen.checkout.payments_api.sessions(request_body, headers: { 'Idempotency-Key' => 'UUID' })
```

#### NodeJS (TypeScript)

```ts
// Adyen Node API Library v18.0.0
// Require the parts of the module you want to use
import { Client, CheckoutAPI, Types } from "@adyen/api-library";
// Initialize the client object
// For the live environment, additionally include your liveEndpointUrlPrefix.
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object(s)
const amount: Types.checkout.Amount = {
  currency: "EUR",
  value: 1000
};

const createCheckoutSessionRequest: Types.checkout.CreateCheckoutSessionRequest = {
  reference: "YOUR_PAYMENT_REFERENCE",
  amount: amount,
  merchantAccount: "YOUR_MERCHANT_ACCOUNT",
  countryCode: "NL",
  returnUrl: "my-app://adyen"
};

// Send the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.sessions(createCheckoutSessionRequest, { idempotencyKey: "UUID" });
```

The response contains:

* `sessionData`: the payment session data you need to pass to your client app.
* `id`: a unique identifier for the session data.
* The request body.

**HTTP 201 /sessions response body**

```json
{
    "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](/development-resources/error-codes) to troubleshoot.

### Get Adyen Ios

## Set up Components

Client app

### 1. Get Adyen iOS

Choose how you want to install the Adyen iOS client-side library:

### Tab: Swift Package Manager

To install iOS Components using Swift Package Manager, [follow the Apple guide](https://developer.apple.com/documentation/xcode/adding_package_dependencies_to_your_app) and specify:

* The repository URL as `https://github.com/Adyen/adyen-ios`.
* The Adyen iOS client-side library version to be at least **5.0.0**.

### Tab: CocoaPods

To install iOS Components from CocoaPods:

1. Add `pod 'Adyen'` to your `Podfile`.
2. Run `pod install`.

### Tab: Carthage

To install iOS Components from Carthage:

1. Add `github "adyen/adyen-ios"` to your `Cartfile`.
2. Run `carthage update`.
3. Link the framework with your target as described in [Carthage Readme](https://github.com/Carthage/Carthage#adding-frameworks-to-an-application).

### 2. Create the context

First, create an instance of `APIContext` that contains:

* The [client key](/development-resources/client-side-authentication#get-your-client-key).
* The [environment setting](#test-and-go-live).

Then, create an instance of `AdyenContext` that contains:

* The instance of `APIContext`.
* Payment information.

**Create the context**

```swift
// Set the client key and environment in an instance of APIContext.
let apiContext = APIContext(clientKey: clientKey, environment: Environment.test) // Set the environment to a live one when going live.
// Create the amount with the value in minor units and the currency code.
let amount = Amount(value: 1000, currencyCode: "EUR")
// Create the payment object with the amount and country code.
let payment = Payment(amount: amount, countryCode: "NL")
// Create an instance of AdyenContext, passing the instance of APIContext, and payment object.
let adyenContext = AdyenContext(apiContext: apiContext, payment:payment)
```

### 3. Create a configuration object

Use the fields from the [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) response to configure and create an instance of `AdyenSession`:

**Create a configuration object**

```swift
let configuration = AdyenSession.Configuration(sessionIdentifier: sessionId, // The id from the API response.
                                               initialSessionData: data, // The sessionData from the API response.)
```

### 4. Initialize `AdyenSession`

Call the static `initialize` function of the `AdyenSession`, setting:

* `configuration`: the configuration object you created in the previous step.
* `delegate`: your delegate object. For example, **self**.
* `presentationDelegate`: your delegate object. For example, **self**.

This asynchronously creates and returns an instance of the session.

**Initialize AdyenSession**

```swift
AdyenSession.initialize(with: configuration, delegate: self, presentationDelegate: self) { [weak self] result in
        switch result {
        case let .success(session):
            //Store the session object.
            self?.session = session
        case let .failure(error):
            //Handle the error.
        }
    }
```

### Configure Components

### 5. Configure the Component

The Component shows the UI elements such as the payment form and pay button.[]()

Create and set the following:

* A configuration object for the payment method. For example, `cardComponentConfiguration` for the Card Component. Initialize it with `CardComponent.Configuration()`.

  * Optionally, custom localization parameters.
  * Optionally, payment method specific parameters. For example, `showsHolderNameField` for the Card Component.[]()

* Other [optional configuration](#optional-configuration).

**Configure the Component**

```swift
var cardComponentConfiguration = CardComponent.Configuration()
cardComponentConfiguration.localizationParameters = // Optional custom localization parameters.
cardComponentConfiguration.showsHolderNameField = true // Optional configuration for Card Component.
... // Other required or optional payment method configuration.
```

### Initialize Components

### 6. Initialize the Component

When the shopper selects a payment method, initialize the matching payment method Component.

1. Create the Component, passing the following configurations:

   * `paymentMethod`: the payment method object that you created.
   * `context`: the `AdyenContext` that you created.
   * `configuration`: the configuration object that you created.

2. Set the instance of `AdyenSession` you created in the previous step as the delegate.

   The following example shows how to create the Card Component and set the instance of `AdyenSession` you created as the `delegate`:

   **Create the Card Component**

   ```swift
   // Check that the payment method is supported before showing the Component.
   guard let paymentMethods = self.session?.sessionContext.paymentMethods,
   let paymentMethod = paymentMethods.paymentMethod(ofType: CardPaymentMethod.self) else { return nil }

   let cardComponent = CardComponent(paymentMethod: paymentMethod,
                                     context: adyenContext,
                                     configuration: cardComponentConfiguration)

   // Set the session as the delegate.
   cardComponent.delegate = session
   ```

### Show In App

### 7. Show the Component in your app

Call the `present` method, passing the configured `viewController`.

The following example shows how to present the Card Component:

**Present the Card Component**

```swift
present(cardComponent.viewController)
```

Some payment methods require additional action from the shopper such as authenticating a payment with 3D Secure, or to switch to another app to complete the payment. Your instance of `AdyenSession` handles the actions to complete the payment.

If the `action` type is **redirect**, you need to [handle the redirect result](#handle-the-redirect).

### Handle Redirect

### 8. Handle the redirect

If the `action` field returns **redirect**, the shopper is redirected to an external site or to another application to complete the payment. You then need to inform the Component when the shopper returns to your app.

The way to handle the redirect depends on if you use Custom or Universal URLs and the way you manage your app’s lifecycle events:

### Tab: UIApplicationDelegate

If you use a [Custom URL scheme](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app?language=objc), implement the following in your [`UIApplicationDelegate` ](https://developer.apple.com/documentation/uikit/uiapplicationdelegate):

**Handle the redirect for Custom URLs**

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

If you use a [Universal URL](https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app?language=objc), implement the following in your [`UIApplicationDelegate` ](https://developer.apple.com/documentation/uikit/uiapplicationdelegate)instead:

**Handle the redirect for Universal URLs**

```swift
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
            let incomingURL = userActivity.webpageURL else { return false }
    return RedirectComponent.applicationDidOpen(from: incomingURL)
}
```

### Tab: UISceneDelegate

If you use a [Custom URL scheme](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app?language=objc), implement the following in your [`UISceneDelegate` ](https://developer.apple.com/documentation/uikit/uiscenedelegate):

**Handle the redirect for Custom URLs**

```swift
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
     guard let url = URLContexts.first?.url else { return }
     RedirectComponent.applicationDidOpen(from: url)
}
```

If you use a [Universal URL](https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app?language=objc), implement the following in your [`UISceneDelegate` ](https://developer.apple.com/documentation/uikit/uiscenedelegate)instead:

**Handle the redirect for Universal URLs**

```swift
func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
        let url = userActivity.webpageURL else { return }
    RedirectComponent.applicationDidOpen(from: url)
}
```

### Handle Result

### 9. Handle the result

The Component handles a [result code](#result-codes) or an [error](#errors) object.

#### Result code

When the payment flow is finished, your instance of `AdyenSession` calls the `didComplete` method.

Implement the following in your [Component configuration object](#configure).

**Implement didComplete in Component configuration**

```swift
func didComplete(with result: AdyenSessionResult, // The session result.
                 component: Component, // Your instance of Component.
                 session: AdyenSession) // Your instance of AdyenSession.
```

Use the `resultCode` to inform your shopper about the current [payment status](/account/payments-lifecycle). Possible values:

| `resultCode`         | Description                                                                                                                                             | Action to take                                                                                                                                                                                                                              |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **authorised**       | The payment was successfully authorised.                                                                                                                | Inform the shopper that the payment was successful.                                                                                                                                                                                         |
| **refused**          | The payment was refused. The response also contains a [refusal reason](/development-resources/refusal-reasons) that indicates why it was refused.       | Inform the shopper that the payment was refused.                                                                                                                                                                                            |
| **pending**          | The final status of the payment isn't available yet. This is common for payments with an asynchronous flow, such as Boleto or iDEAL.                    | Inform the shopper that you have received their order, and are waiting for them to complete the payment. When the shopper completes the payment, you [get a webhook with the updated payment status](#update-your-order-management-system). |
| **cancelled**        | The payment was cancelled (by either the shopper or your system) before processing was completed.                                                       | Inform the shopper that the payment was cancelled.                                                                                                                                                                                          |
| **error**            | An error occurred during payment processing. The response also contains an error code that gives more details about the error.                          | Inform the shopper that an error occurred during payment processing.                                                                                                                                                                        |
| **received**         | The payment request was received, but the final status of the payment isn't available yet. Some payments, like SEPA Direct Debit, take time to process. | Inform the shopper that you have received their order, and are waiting for the final payment status. When the updated payment status is available, you [get a webhook](#update-your-order-management-system).                               |
| **presentToShopper** | Show the voucher or QR code to the shopper.                                                                                                             | Inform the shopper that you have received their order, and are waiting for them to complete the payment. When the shopper completes the payment, you [get a webhook with the updated payment status](#update-your-order-management-system). |

### Errors

#### Error

If an error occurs during the payment flow, your instance of `AdyenSession` calls the `didFail` method containing the error.

Implement the following in your [Component configuration object](#configure).

**Implement didFail in Component configuration**

```js
func didFail(with error: Error, // The error object.
             from component: Component, // Your instance of the Component.
             session: AdyenSession) // Your instance of AdyenSession.
```

The error tells you the type of error and contains a message with details. Use the information to tell the shopper what happened and use the message to troubleshoot the error.

### Get-Payment-Outcome

## Get the payment outcome

After the Component finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.

### Inform the shopper

Client app

From the `didComplete` method, you can get the [`resultCode`](/online-payments/payment-result-codes) to inform the shopper about the current payment status.

**

### Optional: Get the result of the payment session on your server

Payment server

You can also get the result of the payment session on your server.

1. Get the `id` from the [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) response.

2. Get `sessionResult` from the `onPaymentCompleted` event.

3. Make a **GET** `/sessions/{id}?sessionResult={sessionResult}` request including the `id` and `sessionResult`. For example:

   **Request for result of payment session**

   ```bash
   curl -X GET https://checkout-test.adyen.com/v71/sessions/CS12345678?sessionResult=SOME_DATA
   ```

   The response includes the result of the payment session (`status`). For example:

   **Response with result of the payment session**

   ```bash
   {
      "id": "CS12345678",
      "status": "completed"
   }
   ```

   Possible statuses:

   | `status`           | Description                                                                                                                      |
   | ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
   | **completed**      | The shopper completed the payment. This means that the payment was authorized.                                                   |
   | **paymentPending** | The shopper is in the process of making the payment. This applies to payment methods with an asynchronous flow.                  |
   | **canceled**       | The shopper canceled the payment.                                                                                                |
   | **expired**        | The session expired (default: 1 hour after session creation). Shoppers can no longer complete the payment with this `sessionId`. |

The `status` included in the response doesn't get updated. Do not make the request again to check for payment status updates. Instead, check webhooks or the **Transactions** list in your [Customer Area](https://ca-test.adyen.com/).

### Update your order management system

Webhook server

You get the outcome of each payment asynchronously, in an **AUTHORISATION** [webhook](/development-resources/webhooks). Use the `merchantReference` from the webhook to match it to your order reference.\
For a successful payment, the event contains `success`: **true**.

**Example webhook for a successful payment**

```json
{
  "live": "false",
  "notificationItems":[
    {
      "NotificationRequestItem":{
        "eventCode":"AUTHORISATION",
        "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
        "reason":"033899:1111:03/2030",
        "amount":{
          "currency":"EUR",
          "value":2500
        },
        "operations":["CANCEL","CAPTURE","REFUND"],
        "success":"true",
        "paymentMethod":"mc",
        "additionalData":{
          "expiryDate":"03/2030",
          "authCode":"033899",
          "cardBin":"411111",
          "cardSummary":"1111",
          "checkoutSessionId":"CSF46729982237A879"
        },
        "merchantReference":"YOUR_REFERENCE",
        "pspReference":"NC6HT9CRT65ZGN82",
        "eventDate":"2021-09-13T14:10:22+02:00"
      }
    }
  ]
}
```

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

**Example webhook for an unsuccessful payment**

```json
{
  "live": "false",
  "notificationItems":[
    {
      "NotificationRequestItem":{
        "eventCode":"AUTHORISATION",
        "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
        "reason":"validation 101 Invalid card number",
        "amount":{
          "currency":"EUR",
          "value":2500
        },
        "success":"false",
        "paymentMethod":"unknowncard",
        "additionalData":{
          "expiryDate":"03/2030",
          "cardBin":"411111",
          "cardSummary":"1112",
          "checkoutSessionId":"861631540104159H"
        },
        "merchantReference":"YOUR_REFERENCE",
        "pspReference":"KHQC5N7G84BLNK43",
        "eventDate":"2021-09-13T14:14:05+02:00"
      }
    }
  ]
}
```

## Test and go live

Before going live, use our list of [test cards and other payment methods](/development-resources/test-cards-and-credentials/test-card-numbers) to [test your integration](/development-resources/testing). 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](https://ca-test.adyen.com/), under **Transactions** > **Payments**.

To debug or troubleshoot test payments, you can also use [API logs](/development-resources/logs-resources/api-logs) in your test environment.

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

1. [Apply for a live account](/get-started-with-adyen/application-requirements). Review the process to start accepting payments on [Get started with Adyen](/get-started-with-adyen).

2. Assess your [PCI DSS compliance](/development-resources/pci-dss-compliance-guide#online-payments) by submitting the [Self-Assessment Questionnaire-A](https://www.pcisecuritystandards.org/documents/PCI-DSS-v3_2_1-SAQ-A.pdf).

3. [Configure your live account](/online-payments/go-live-checklist). 

4. Submit a request to add payment methods in your [live Customer Area](https://ca-live.adyen.com/) .

5. Switch from test to our [live endpoints](/development-resources/live-endpoints#checkout-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, for example, when authenticating with 3D Secure 2.

6. Load Components from one of our live environments and set the `environment` to match your live endpoints:

   | 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**        |

### Optional Configuration Components (optional)

## Optional configuration

Client app

You can set additional configuration on the [Component configuration](#configure).

| Parameter name           | Description                                                                                                                                  |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `showsSubmitButton`      | Set to **false** to hide the default pay button, so that you can [implement a custom button](#custom-pay-button) instead. Default: **true**. |
| `shopperInformation`     | Prefilled shopper information.                                                                                                               |
| `localizationParameters` | [Localization](#localization) parameters, like custom placeholders in other languages.                                                       |
| `style`                  | Custom styling of the UI.                                                                                                                    |

The following example shows how to set optional configuration parameters on the Card Component.

**Set optional configuration parameters**

```js
// Create a configuration object for the Component.
let cardComponentConfiguration = CardComponent.Configuration()

// Optional: create a configuration object for styling.
let style = FormComponentStyle()
// Set the background color.
style.backgroundColor = .darkGray

// Set the style on the configuration object.
cardComponentConfiguration.style = style
```

### Implement a custom pay button

To implement a custom pay button, hide the default one and use the included functions to validate and submit payment data.

This is not supported for [Apple Pay](/filters/sessions-flow-integration/ios/5-14-0/components/optional-components-configuration/payment-methods/apple-pay) and [BACS Direct Debit](/payment-methods/bacs).

1. When you [create the configuration object](#configure), set `showsSubmitButton` to **false**.
2. [Initialize](#initialize) the Component.
3. You can optionally show a confirmation page to the shopper, where payment data is validated.
4. Create and show your custom button.

You can use the following functions.

| Function     | Required                                                                                                      | Description                                                                                                                |
| ------------ | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `validate()` |                                                                                                               | Validates the payment data.                                                                                                |
| `submit()`   | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Makes a [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request to submit the payment data. |

The following example shows the Card Component with a custom pay button.

**Card Component with a custom pay button**

```swift
class CardPaymentViewController: UIViewController {

    // The instance of CardComponent for handling card payments.
    var cardComponent: CardComponent?

    // The function to configure and initialize an instance of CardComponent.
    func setupCardComponent() {
        // 1. Hide the default submit button in the CardComponent configuration.
        var cardComponentConfiguration = CardComponent.Configuration(showsSubmitButton: false)

        // 2. Check if the card payment method is available.
        guard let paymentMethods = self.session?.sessionContext.paymentMethods,
              let paymentMethod = paymentMethods.paymentMethod(ofType: CardPaymentMethod.self) else {
            // If no valid payment method is found, exit setup.
            return
        }

        // 3. Initialize the CardComponent with the payment method, context, and configuration.
        cardComponent = CardComponent(paymentMethod: paymentMethod,
                                       context: adyenContext,
                                       configuration: cardComponentConfiguration)

        // 4. Set the delegate to handle CardComponent callbacks.
        cardComponent?.delegate = session
    }

    override func viewDidLoad() {
        super.viewDidLoad()

        // 5. Create your custom button for starting the payment.
        let customSubmitButton = UIButton(frame: .zero)
        customSubmitButton.setTitle("Pay Now", for: .normal)
        customSubmitButton.backgroundColor = .systemBlue
        customSubmitButton.layer.cornerRadius = 8
        customSubmitButton.addTarget(self, action: #selector(startPayment), for: .touchUpInside)

        // 6. Configure and initialize an instance of CardComponent.
        setupCardComponent()

        // 7. If the instance of CardComponent successfully initialized, add its view to the view hierarchy.
        if let cardView = cardComponent?.viewController.view {
            view.addSubview(cardView)
            // Optional: set constraints or position cardView.
        }

        // 8. Add your custom pay button to the view hierarchy.
        view.addSubview(customSubmitButton)
      
        // 9. Optional: set constraints or change the position of your custom submit button.

        // 10. Optional: configure additional UI elements or the layout.
        view.backgroundColor = .white
    }

    // The action that is triggered when the shopper selects your custom button.
    @objc func startPayment() {
        // 11. Validate the payment details that the shopper entered.
        if cardComponent?.validate() == true {
            // 12. If validation is successful, submit the payment.
            cardComponent?.submit()
        } else {
            // 13. If validation is unsuccessful, handle validation errors. For example, show an error message to the user.
            print("Validation failed. Please check your card details.")
        }
    }
}
```

### Localization

**

### Localization

iOS Components support the languages listed [here](https://github.com/Adyen/adyen-ios/tree/master/Adyen/Assets).

To customize a localization, add a new `localizable.strings` file for the language that you need. You can also override [existing strings](https://github.com/Adyen/adyen-ios/blob/master/Adyen/Assets/en-US.lproj/Localizable.strings) by using the same keys.

For example, to override the cardholder name field title, set the following on your `localizable.strings` file:

```swift
"adyen.card.nameItem.title" = "Your cardholder name";
```

For more information on iOS Components classes, see our [reference documentation](https://adyen.github.io/adyen-ios/5.0.0/documentation/adyen/) page.

To find localized strings, the library first checks your custom `localizable.strings` file, and then the default Adyen file.

You can use `LocalizationParameters` to customize the localization file name, bundle, or the separator for translation strings.

For example, if you store translations in `MyLocalizable.strings` files in the shared bundle `CommonBundle`:

```swift
let localizationParameters = LocalizationParameters(bundle: commonBundle, tableName: "MyLocalizable")
cardComponentConfiguration.localizationParameters = localizationParameters
```

## Next steps

[required](/online-payments/modify-payments)

[Modify payments](/online-payments/modify-payments)

[Find out how to cancel, refund, or capture a payment using our API.](/online-payments/modify-payments)

[Add payment methods](/payment-methods/add-payment-methods)

[Learn about payment methods and how to add them to your account.](/payment-methods/add-payment-methods)

[Tokenization](/online-payments/tokenization)

[Save shopper payment details for later payments.](/online-payments/tokenization)

[3D Secure authentication](/online-payments/3d-secure)

[Comply with regulations such as PSD2 SCA in Europe.](/online-payments/3d-secure)

## Android Drop-in

Use our pre-built UI for accepting payments

### Before You Begin

## Requirements

Before you begin to integrate, make sure you have followed the [Get started with Adyen guide](/get-started-with-adyen) 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](/development-resources/api-credentials#generate-api-key).
* [Get your client key](/development-resources/client-side-authentication#get-your-client-key).
* [Set up webhooks](/development-resources/webhooks) to know the payment outcome.

## How it works

For a Drop-in integration, you must implement the following parts:

* **Your payment server**: sends the API request to create a payment session.
* **Your client app**: shows the Drop-in UI where the shopper makes the payment. Drop-in 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:

1. The shopper goes to the checkout page.

2. Your server uses the shopper's country or region and currency information from your client to create a payment session.

3. Your client creates an instance of Drop-in using the session data from the server.

4. Drop-in shows the available payment methods, collects the shopper's payment details, handles additional actions, and presents the payment result to the shopper.

5. Your webhook server receives the event containing the payment outcome.

[![](/user/pages/filters/sessions-flow-integration/android/5-0-0/drop-in/01.how-it-works-sessions/drop-in-sessions.svg)](/user/pages/filters/sessions-flow-integration/android/5-0-0/drop-in/01.how-it-works-sessions/drop-in-sessions.svg)

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

[![](/user/pages/reuse/online-payments/how-it-works-parts/servers.svg?decoding=auto\&fetchpriority=auto)](/#install-api-library)

[Payment server](/#install-api-library)

[Go to the integration steps for your server.](/#install-api-library)

[![](/user/pages/reuse/online-payments/how-it-works-parts/browser-developers.svg?decoding=auto\&fetchpriority=auto)](/#set-up)

[Client app](/#set-up)

[Go to the integration steps for your client app.](/#set-up)

[![](/user/pages/reuse/online-payments/how-it-works-parts/event-code.svg?decoding=auto\&fetchpriority=auto)](/#update-your-order-management-system)

[Webhook server](/#update-your-order-management-system)

[Go to the integration steps for your webhook server.](/#update-your-order-management-system)

### Install Api Library

## 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.

### Tab: Java

##### Try our example integration

![](/reuse/development-resources/install-api-library/java/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-java-spring-online-payments#checkout-example).\
![](/reuse/development-resources/install-api-library/java/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-java-spring-online-payments).

#### Requirements

* Java 11 or later.

#### Installation

You can use [Maven](https://maven.apache.org), adding this dependency to your project's POM.

**Add the API library**

```xml
<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](https://github.com/Adyen/adyen-java-api-library/releases).

#### Setting up the client

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

**Set up your client**

```java
// 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);
    }
}
```

### Tab: PHP

##### Try our example integration

![](/reuse/development-resources/install-api-library/php/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-php-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/php/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-php-online-payments).

#### 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](https://getcomposer.org/). Follow the [installation instructions](https://getcomposer.org/doc/00-intro.md) if you do not already have composer installed.

**Install the API library**

```bash
composer require adyen/php-api-library
```

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

**Include the autoloader**

```php
require __DIR__ . '/vendor/autoload.php';
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-php-api-library/releases).

#### Set up the client

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

**Set up your client**

```php
use Adyen\Model\Checkout\Amount;
use Adyen\Model\Checkout\CreateCheckoutSessionRequest;
use Adyen\Service\Checkout\PaymentsApi;

// Include your idempotency key when you make an API request.
$requestOptions['idempotencyKey'] = "YOUR_IDEMPOTENCY_KEY";

// Set up the client and service.
$client = new \Adyen\Client();
$client->setXApiKey('ADYEN_API_KEY');
$client->setEnvironment(\Adyen\Environment::TEST);

$service = new PaymentsApi($client);
```

### Tab: C\#

#### 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](https://www.nuget.org/packages/Adyen/):

**Install the API library**

```bash
PM> Install-Package Adyen -Version LATEST_VERSION
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-dotnet-api-library).

#### Set up the client

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

**Set up your client**

```cs
using Adyen;
using Adyen.Model.Checkout;
using Adyen.Service.Checkout;
using Environment = Adyen.Model.Environment;

class Program
{
    static void Main()
    {
        // Set up the client and service.
        var config = new Config
        {
            XApiKey = "ADYEN_API_KEY",
            Environment = Environment.Test
        };
        var client = new Client(config);
        var checkout = new PaymentsService(client);

        // Include your idempotency key when you make an API request.
        var requestOptions = new Adyen.Model.RequestOptions { IdempotencyKey = "YOUR_IDEMPOTENCY_KEY" };
    }
}
```

### Tab: NodeJS

##### Try our example integration

![](/reuse/development-resources/install-api-library/node-js/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-node-online-payments#checkout-example).\
![](/reuse/development-resources/install-api-library/node-js/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-node-online-payments).

#### Requirements

* Node.js version 18 or later.

#### Installation

You can use [npm](https://www.npmjs.com/):

**Install the API library**

```bash
npm install --save @adyen/api-library
npm update @adyen/api-library
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-node-api-library/releases).

#### Setting up the client

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

**Set up your client**

```js
// Require the parts of the module you want to use.
const { Client, CheckoutAPI, Types} = require("@adyen/api-library");

// Set up the client and service.
const client = new Client({ apiKey: "ADYEN_API_KEY", environment: "TEST" });
const checkoutApi = new CheckoutAPI(client);

// Include your idempotency key when you make an API request.
const requestOptions = { idempotencyKey: "YOUR_IDEMPOTENCY_KEY" };
```

### Tab: Go

##### Try our example integration

![](/reuse/development-resources/install-api-library/go/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-golang-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/go/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-golang-online-payments).

#### Requirements

* Go 1.13 or later.

#### Installation

You can use [Go modules](https://github.com/golang/go/wiki/Modules):

**Install the API library**

```shell
go get github.com/adyen/adyen-go-api-library/vLATEST_VERSION
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-go-api-library).

#### Set up the client

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

**Set up your client**

```go
package main

import (
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/adyen"
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/checkout"
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/common"
)

// Create a payment object.

func main () {
	client := adyen.NewClient(&common.Config{
		ApiKey: "ADYEN_API_KEY",
		Environment: common.TestEnv,
	})
	service := client.Checkout()
```

### Tab: Python

##### Try our example integration

![](/reuse/development-resources/install-api-library/python/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-python-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/python/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-python-online-payments).

#### Requirements

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

#### Installation

You can use [pip](https://pip.pypa.io/en/stable/):

**Install the API library**

```py
pip install Adyen
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-python-api-library).

#### Set up the client

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

**Set up your client**

```py
import Adyen

# Set up the client and service.
adyen = Adyen.Adyen()
adyen.client.xapikey = "ADYEN_API_KEY"
adyen.client.platform = "test" # The environment that the library is used in.
```

### Tab: Ruby

##### Try our example integration

![](/reuse/development-resources/install-api-library/ruby/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-rails-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/ruby/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-rails-online-payments).

#### Requirements

* Ruby 2.7 or later.

#### Installation

You can use [RubyGems](https://rubygems.org/):

**Install the API library**

```bash
gem install adyen-ruby-api-library
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-ruby-api-library/releases).

Run `bundle install` to install dependencies.

#### Set up the client

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

**Set up your client**

```ruby
require 'adyen-ruby-api-library'

# Set up the client and service.
adyen = Adyen::Client.new
adyen.api_key = 'ADYEN_API_KEY'
adyen.env = :test # The environment that the library is used in.
```

## 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 [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) request, including:

| Parameter name                                                       | Required                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `merchantAccount`                                                    | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your merchant account name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `amount`                                                             | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The `currency` and `value` of the payment, in [minor units](/development-resources/currency-codes). This is used to filter the list of available payment methods to your shopper.                                                                                                                                                                                                                                                                                                                                                |
| `returnUrl`                                                          | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | URL to where the shopper should be taken back to after a redirection. The URL can contain a maximum of 1024 characters. You can include your own additional query parameters, for example, shopper ID or order reference number. Get this URL from Drop-in in the `RedirectComponent.getReturnUrl(context)`. 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`                                                          | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | 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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. Exception: **QZ** (Kosovo).                                                                                                                                                                                                                                                                              |
| `channel`                                                            |                                                                                                               | The platform where the payment is taking place. Use **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 client app. 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](/risk-management/configure-standard-risk-rules/required-risk-field-reference), and for 3D Secure.                                                                                                                                                                                                                                                                                                                      |
| `shopperReference`                                                   |                                                                                                               | Your reference to uniquely identify this shopper. Strongly recommended because this field is used in a number of [risk checks](/risk-management/configure-standard-risk-rules/required-risk-field-reference).                                                                                                                                                                                                                                                                                                                    |
| [`applicationInfo`](/development-resources/building-adyen-solutions) |                                                                                                               | 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](/development-resources/building-adyen-solutions).                                                                                                                                                                                                                                                                   |

Here is an example of how to create a session for a payment of **10** EUR:

#### curl

```bash
curl https://checkout-test.adyen.com/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": "adyencheckout://your.package.name",
  "reference": "YOUR_PAYMENT_REFERENCE",
  "countryCode": "NL"
}'
```

#### Java

```java
// Adyen Java API Library v27.0.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, additionally include your liveEndpointUrlPrefix.
Client client = new Client("ADYEN_API_KEY", Environment.TEST);

// Create the request object(s)
Amount amount = new Amount()
  .currency("EUR")
  .value(1000L);

CreateCheckoutSessionRequest createCheckoutSessionRequest = new CreateCheckoutSessionRequest()
  .reference("YOUR_PAYMENT_REFERENCE")
  .amount(amount)
  .merchantAccount("YOUR_MERCHANT_ACCOUNT")
  .countryCode("NL")
  .returnUrl("adyencheckout://your.package.name");

// Send the request
PaymentsApi service = new PaymentsApi(client);
CreateCheckoutSessionResponse response = service.sessions(createCheckoutSessionRequest, new RequestOptions().idempotencyKey("UUID"));
```

#### PHP

```php
// Adyen PHP API Library v19.0.0
use Adyen\Client;
use Adyen\Environment;
use Adyen\Model\Checkout\Amount;
use Adyen\Model\Checkout\CreateCheckoutSessionRequest;
use Adyen\Service\Checkout\PaymentsApi;

$client = new Client();
$client->setXApiKey("ADYEN_API_KEY");
// For the live environment, additionally include your liveEndpointUrlPrefix.
$client->setEnvironment(Environment::TEST);


// Create the request object(s)
$amount = new Amount();
$amount
  ->setCurrency("EUR")
  ->setValue(1000);

$createCheckoutSessionRequest = new CreateCheckoutSessionRequest();
$createCheckoutSessionRequest
  ->setReference("YOUR_PAYMENT_REFERENCE")
  ->setAmount($amount)
  ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT")
  ->setCountryCode("NL")
  ->setReturnUrl("adyencheckout://your.package.name");

$requestOptions['idempotencyKey'] = 'UUID';

// Send the request
$service = new PaymentsApi($client);
$response = $service->sessions($createCheckoutSessionRequest, $requestOptions);
```

#### C\#

```cs
// Adyen .net API Library v17.0.0
using Adyen;
using Environment = Adyen.Model.Environment;
using Adyen.Model;
using Adyen.Model.Checkout;
using Adyen.Service.Checkout;

// For the live environment, additionally include your liveEndpointUrlPrefix.
var config = new Config()
{
    XApiKey = "ADYEN_API_KEY",
    Environment = Environment.Test
};
var client = new Client(config);

// Create the request object(s)
Amount amount = new Amount
{
  Currency = "EUR",
  Value = 1000
};

CreateCheckoutSessionRequest createCheckoutSessionRequest = new CreateCheckoutSessionRequest
{
  Reference = "YOUR_PAYMENT_REFERENCE",
  Amount = amount,
  MerchantAccount = "YOUR_MERCHANT_ACCOUNT",
  CountryCode = "NL",
  ReturnUrl = "adyencheckout://your.package.name"
};

// Send the request
var service = new PaymentsService(client);
var response = service.Sessions(createCheckoutSessionRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"});
```

#### NodeJS (JavaScript)

```js
// Adyen Node API Library v18.0.0
// Require the parts of the module you want to use
const { Client, CheckoutAPI } = require('@adyen/api-library');
// Initialize the client object
// For the live environment, additionally include your liveEndpointUrlPrefix.
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object(s)
const createCheckoutSessionRequest = {
  merchantAccount: "YOUR_MERCHANT_ACCOUNT",
  amount: {
    value: 1000,
    currency: "EUR"
  },
  returnUrl: "adyencheckout://your.package.name",
  reference: "YOUR_PAYMENT_REFERENCE",
  countryCode: "NL"
}

// Send the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.sessions(createCheckoutSessionRequest, { idempotencyKey: "UUID" });
```

#### Go

```go
// Adyen Go API Library v10.4.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, additionally include your liveEndpointUrlPrefix.
client := adyen.NewClient(&common.Config{
  ApiKey:      "ADYEN_API_KEY",
  Environment: common.TestEnv,
})

// Create the request object(s)
amount := checkout.Amount{
  Currency: "EUR",
  Value: 1000,
}

createCheckoutSessionRequest := checkout.CreateCheckoutSessionRequest{
  Reference: "YOUR_PAYMENT_REFERENCE",
  Amount: amount,
  MerchantAccount: "YOUR_MERCHANT_ACCOUNT",
  CountryCode: common.PtrString("NL"),
  ReturnUrl: "adyencheckout://your.package.name",
}

// Send the request
service := client.Checkout()
req := service.PaymentsApi.SessionsInput().IdempotencyKey("UUID").CreateCheckoutSessionRequest(createCheckoutSessionRequest)
res, httpRes, err := service.PaymentsApi.Sessions(context.Background(), req)
```

#### Python

```py
# Adyen Python API Library v12.5.1
import Adyen

adyen = Adyen.Adyen()
adyen.client.xapikey = "ADYEN_API_KEY"
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.client.platform = "test" # The environment to use library in.

# Create the request object(s)
json_request = {
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "amount": {
    "value": 1000,
    "currency": "EUR"
  },
  "returnUrl": "adyencheckout://your.package.name",
  "reference": "YOUR_PAYMENT_REFERENCE",
  "countryCode": "NL"
}

# Send the request
result = adyen.checkout.payments_api.sessions(request=json_request, idempotency_key="UUID")
```

#### Ruby

```rb
# Adyen Ruby API Library v9.5.1
require "adyen-ruby-api-library"

adyen = Adyen::Client.new
adyen.api_key = 'ADYEN_API_KEY'
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.env = :test # Set to "live" for live environment

# Create the request object(s)
request_body = {
  :merchantAccount => 'YOUR_MERCHANT_ACCOUNT',
  :amount => {
    :value => 1000,
    :currency => 'EUR'
  },
  :returnUrl => 'adyencheckout://your.package.name',
  :reference => 'YOUR_PAYMENT_REFERENCE',
  :countryCode => 'NL'
}

# Send the request
result = adyen.checkout.payments_api.sessions(request_body, headers: { 'Idempotency-Key' => 'UUID' })
```

#### NodeJS (TypeScript)

```ts
// Adyen Node API Library v18.0.0
// Require the parts of the module you want to use
import { Client, CheckoutAPI, Types } from "@adyen/api-library";
// Initialize the client object
// For the live environment, additionally include your liveEndpointUrlPrefix.
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object(s)
const amount: Types.checkout.Amount = {
  currency: "EUR",
  value: 1000
};

const createCheckoutSessionRequest: Types.checkout.CreateCheckoutSessionRequest = {
  reference: "YOUR_PAYMENT_REFERENCE",
  amount: amount,
  merchantAccount: "YOUR_MERCHANT_ACCOUNT",
  countryCode: "NL",
  returnUrl: "adyencheckout://your.package.name"
};

// Send the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.sessions(createCheckoutSessionRequest, { idempotencyKey: "UUID" });
```

The response contains:

* `sessionData`: the payment session data you need to pass to your client app.
* `id`: a unique identifier for the session data.
* The request body.

**HTTP 201 /sessions response body**

```json
{
    "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": "adyencheckout://your.package.name",
    "sessionData": "Ab02b4c.."
}
```

You must pass the response to your client app to [create the checkout session](#create-the-checkout-session).

### API error handling

If you do not get an HTTP 201 response, use the `errorCode` field and the list of [API error codes](/development-resources/error-codes) to troubleshoot.

## Set up Drop-in

Client app

### 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:

### Tab: With Jetpack Compose

**Import the module with Compose**

```groovy
implementation "com.adyen.checkout:drop-in-compose:YOUR_VERSION"
```

### Tab: Without Jetpack Compose

**Import the module without Compose**

```groovy
implementation "com.adyen.checkout:drop-in:YOUR_VERSION"
```

### Create Checkout Session

### 2: Create the checkout session

1. Deserialize the [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) response to a `SessionsModel` object:

   **Deserialize the API response**

   ```java
   val sessionModel = SessionModel.SERIALIZER.deserialize(sessionsResponseJSON)
   ```

2. Call the `CheckoutSessionProvider.createSession` suspending function, passing:

   | Parameter                       | Required                                                                                                      | Description                                      |
   | ------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
   | `sessionModel`                  | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The deserialized `SessionsModel` object.         |
   | `dropInConfiguration` (Example) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The configuration object for the payment method. |

   For example:

   **Create the checkout session**

   ```java
   // Create an object for the checkout session.
   val result = CheckoutSessionProvider.createSession(sessionModel, dropInConfiguration)

   // If the payment session is successful, handle the result.
   // If the payment session encounters an error, handle the error.
   when (result) {
       is CheckoutSessionResult.Success -> handleCheckoutSession(result.checkoutSession)
       is CheckoutSessionResult.Error -> handleError(result.exception)
   }
   ```

**

### 3. (Optional) Add a configuration object

Create a configuration object, setting the following properties:[]()

| Property        | Required                                                                                                      | Description                                                                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `environment`   | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The same `environment` that you set when you created the session.                                                                                                              |
| `clientKey`     | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The same `clientKey` that you set when you created the session.                                                                                                                |
| `shopperLocale` |                                                                                                               | The shopper's locale. By default, this matches the `shopperLocale` you included in the [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) request. |

**Optionally create a configuration object**

```kotlin
// Create a configuration object.
val checkoutConfiguration = CheckoutConfiguration(
    environment = environment,
    clientKey = clientKey,
    shopperLocale = shopperLocale, // Optional
) {
    // Optional: add Drop-in configuration.
    dropIn {
        setEnableRemovingStoredPaymentMethods(true)
    }

    // Optional: add or change default configuration for the card payment method.
    card {
        setHolderNameRequired(true)
        setShopperReference("...")
    }

    // Optional: change configuration for 3D Secure 2.
    adyen3DS2 {
        setThreeDSRequestorAppURL("...")
    }
}
```

### Launch And Show Drop In

### 4: Launch and show Drop-in

### Tab: With Jetpack Compose

1. Implement `SessionDropInCallback` to get the result of the session.

   **Get the result**

   ```java
   override fun onDropInResult(sessionDropInResult: SessionDropInResult?) {
      when (sessionDropInResult) {
         // The payment finishes with a result.
         is SessionDropInResult.Finished -> handleResult(sessionDropInResult.result)
         // The shopper dismisses Drop-in.
         is SessionDropInResult.CancelledByUser ->
         // Drop-in encounters an error.
         is SessionDropInResult.Error -> handleError(sessionDropInResult.reason)
         // Drop-in encounters an unexpected state.
         null ->
      }
   }
   ```

2. Create the Drop-in launcher and call `DropIn.startPayment`, passing:

   | Parameter             | Description                                     |
   | --------------------- | ----------------------------------------------- |
   | `dropInLauncher`      | The Drop-in launcher you created.               |
   | `checkoutSession`     | The font-end checkout session that you created. |
   | `dropInConfiguration` | The Drop-in configuration that you created.     |

   For example:

   **Start Drop-in**

   ```java
   import com.adyen.checkout.dropin.compose.startPayment
   import com.adyen.checkout.dropin.compose.rememberLauncherForDropInResult

   @Composable
   private fun ComposableDropIn() {
       val dropInLauncher = rememberLauncherForDropInResult(sessionDropInCallback)

       DropIn.startPayment(dropInLauncher, checkoutSession, dropInConfiguration)
   }
   ```

### Tab: Without Jetpack Compose

1. Implement `SessionDropInCallback` to get the result of the session.

   **Get the result**

   ```java
   override fun onDropInResult(sessionDropInResult: SessionDropInResult?) {
      when (sessionDropInResult) {
         // The payment finishes with a result.
         is SessionDropInResult.Finished -> handleResult(sessionDropInResult.result)
         // The shopper dismisses Drop-in.
         is SessionDropInResult.CancelledByUser ->
         // Drop-in encounters an error.
         is SessionDropInResult.Error -> handleError(sessionDropInResult.reason)
         // Drop-in encounters an unexpected state.
         null ->
      }
   }
   ```

2. Register your `Activity` or `Fragment` with the [Activity Result API](https://developer.android.com/training/basics/intents/result) by calling `DropIn.registerForDropInResult`.

   **Register your Activity or Fragment**

   ```java
   // Declare this as a field in your Activity or Fragment.
   private val dropInLauncher = DropIn.registerForDropInResult(this, sessionDropInCallback)
   ```

3. Call `DropIn.startPayment`, passing:

   | Parameter             | Description                                                         |
   | --------------------- | ------------------------------------------------------------------- |
   | `context`             | Your context.                                                       |
   | `dropInLauncher`      | The Drop-in launcher you declared in your `Activity` or `Fragment`. |
   | `checkoutSession`     | The font-end checkout session that you created.                     |
   | `dropInConfiguration` | The Drop-in configuration that you created.                         |

   For example:

   **Start Drop-in**

   ```java
   DropIn.startPayment(
       context,
       dropInLauncher,
       checkoutSession,
       dropInConfiguration,
   )
   ```

Your app shows Drop-in, and it handles the whole payment flow.

## Get the payment outcome

After Drop-in finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.

### Inform the shopper

Client app

From the `onDropInResult` function, you can get the [`resultCode` ](/online-payments/payment-result-codes)to inform the shopper about the current payment status.

**

### Optional: Get the result of the payment session on your server

Payment server

You can also get the result of the payment session on your server.

1. Get the `id` from the [`/sessions` response](#sessions-response).

2. Get `sessionResult` from the `onDropInResult` function.

3. Make a **GET** `/sessions/{id}?sessionResult={sessionResult}` request including the `id` and `sessionResult`. For example:

   **Request for result of payment session**

   #### curl

   ```bash
   curl -X GET https://checkout-test.adyen.com/v70/sessions/CS12345678?sessionResult=SOME_DATA
   ```

   #### Java

   ```java
   // Adyen Java API Library v39.3.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.service.checkout.*;

   // For the LIVE environment, also include your liveEndpointUrlPrefix.
   Client client = new Client("", Environment.TEST);
   // Send the request
   PaymentsApi service = new PaymentsApi(client);
   SessionResultResponse response = service.getResultOfPaymentSession("sessionId", "String", null);
   ```

   #### PHP

   ```php
   <?php
   // Adyen PHP API Library v28.2.0
   use Adyen\Client;
   use Adyen\Environment;
   use Adyen\Service\Checkout\PaymentsApi;

   $client = new Client();
   $client->setXApiKey("");
   // For the LIVE environment, also include your liveEndpointUrlPrefix.
   $client->setEnvironment(Environment::TEST);

   $requestOptions['queryParams'] = array('sessionResult' => 'string');

   // Send the request
   $service = new PaymentsApi($client);
   $response = $service->getResultOfPaymentSession('sessionId', $requestOptions);
   ```

   #### C\#

   ```cs
   // Adyen .net API Library v32.1.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 = "",
       Environment = Environment.Test
   };
   var client = new Client(config);

   // Send the request
   var service = new PaymentsService(client);
   var response = service.GetResultOfPaymentSession("sessionId", sessionResult: "string");
   ```

   #### NodeJS (JavaScript)

   ```js
   // Adyen Node API Library v29.0.0
   const { Client, CheckoutAPI } = require('@adyen/api-library');

   // For the LIVE environment, also include your liveEndpointUrlPrefix.
   const config = new Config({
     apiKey: "",
     environment: EnvironmentEnum.TEST
   });

   const client = new Client(config);

   // Send the request
   const checkoutAPI = new CheckoutAPI(client);
   const response = checkoutAPI.PaymentsApi.getResultOfPaymentSession("sessionId", "string");
   ```

   #### Go

   ```go
   // Adyen Go API Library v21.0.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:      "",
     Environment: common.TestEnv,
   })

   // Send the request
   service := client.Checkout()
   req := service.PaymentsApi.GetResultOfPaymentSessionInput("sessionId")
   req = req.SessionResult("string")
   res, httpRes, err := service.PaymentsApi.GetResultOfPaymentSession(context.Background(), req)
   ```

   #### Python

   ```py
   # Adyen Python API Library v13.6.0
   import Adyen

   adyen = Adyen.Adyen()
   adyen.client.xapikey = ""
   # For the LIVE environment, also include your liveEndpointUrlPrefix.
   adyen.client.platform = "test" # The environment to use library in.

   query_parameters = {
     "sessionResult" : "string"
   }

   # Send the request
   result = adyen.checkout.payments_api.get_result_of_payment_session(sessionId="sessionId", query_parameters=query_parameters)
   ```

   #### Ruby

   ```rb
   # Adyen Ruby API Library v10.4.0
   require "adyen-ruby-api-library"

   adyen = Adyen::Client.new
   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)
   query_params = {
     :sessionResult => 'string'
   }

   # Send the request
   result = adyen.checkout.payments_api.get_result_of_payment_session('sessionId', query_params: query_params)
   ```

   #### NodeJS (TypeScript)

   ```ts
   // Adyen Node API Library v29.0.0
   import { Client, CheckoutAPI, Types } from "@adyen/api-library";

   // For the LIVE environment, also include your liveEndpointUrlPrefix.
   const config = new Config({
     apiKey: "",
     environment: EnvironmentEnum.TEST
   });

   const client = new Client(config);

   // Send the request
   const checkoutAPI = new CheckoutAPI(client);
   const response = checkoutAPI.PaymentsApi.getResultOfPaymentSession("sessionId", "string");
   ```

   The response includes the result of the payment session (`status`). For example:

   **Response with result of the payment session**

   ```bash
   {
      "id": "CS12345678",
      "status": "completed"
   }
   ```

   Possible statuses:

   | `status`           | Description                                                                                                                      |
   | ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
   | **completed**      | The shopper completed the payment. This means that the payment was authorized.                                                   |
   | **paymentPending** | The shopper is in the process of making the payment. This applies to payment methods with an asynchronous flow.                  |
   | **canceled**       | The shopper canceled the payment.                                                                                                |
   | **expired**        | The session expired (default: 1 hour after session creation). Shoppers can no longer complete the payment with this `sessionId`. |

The `status` included in the response doesn't get updated. Do not make the request again to check for payment status updates. Instead, check webhooks or the **Transactions** list in your [Customer Area](https://ca-test.adyen.com/).

### Update your order management system

Webhook server

You get the outcome of each payment asynchronously, in an **AUTHORISATION** [webhook](/development-resources/webhooks). Use the `merchantReference` from the webhook to match it to your order reference.\
For a successful payment, the event contains `success`: **true**.

**Example webhook for a successful payment**

```json
{
  "live": "false",
  "notificationItems":[
    {
      "NotificationRequestItem":{
        "eventCode":"AUTHORISATION",
        "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
        "reason":"033899:1111:03/2030",
        "amount":{
          "currency":"EUR",
          "value":2500
        },
        "operations":["CANCEL","CAPTURE","REFUND"],
        "success":"true",
        "paymentMethod":"mc",
        "additionalData":{
          "expiryDate":"03/2030",
          "authCode":"033899",
          "cardBin":"411111",
          "cardSummary":"1111",
          "checkoutSessionId":"CSF46729982237A879"
        },
        "merchantReference":"YOUR_REFERENCE",
        "pspReference":"NC6HT9CRT65ZGN82",
        "eventDate":"2021-09-13T14:10:22+02:00"
      }
    }
  ]
}
```

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

**Example webhook for an unsuccessful payment**

```json
{
  "live": "false",
  "notificationItems":[
    {
      "NotificationRequestItem":{
        "eventCode":"AUTHORISATION",
        "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
        "reason":"validation 101 Invalid card number",
        "amount":{
          "currency":"EUR",
          "value":2500
        },
        "success":"false",
        "paymentMethod":"unknowncard",
        "additionalData":{
          "expiryDate":"03/2030",
          "cardBin":"411111",
          "cardSummary":"1112",
          "checkoutSessionId":"861631540104159H"
        },
        "merchantReference":"YOUR_REFERENCE",
        "pspReference":"KHQC5N7G84BLNK43",
        "eventDate":"2021-09-13T14:14:05+02:00"
      }
    }
  ]
}
```

## Test and go live

Before going live, use our list of [test cards and other payment methods](/development-resources/test-cards-and-credentials/test-card-numbers) to [test your integration](/development-resources/testing). Use the [Adyen Android test cards app](/development-resources/test-cards-and-credentials/test-card-numbers#android-test-cards-app) to access, copy, and autofill card details from within your Android device. 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](https://ca-test.adyen.com/), under **Payments** > **Payment list**.

To debug or troubleshoot test payments, you can also use [API logs](/development-resources/logs-resources/api-logs) in your test environment.

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

1. [Apply for a live account](/get-started-with-adyen/application-requirements). Review the process to start accepting payments on [Get started with Adyen](/get-started-with-adyen).

2. Assess your [PCI DSS compliance](/development-resources/pci-dss-compliance-guide#online-payments) by submitting the [Self-Assessment Questionnaire-A](https://www.pcisecuritystandards.org/documents/PCI-DSS-v3_2_1-SAQ-A.pdf).

3. [Configure your live account](/online-payments/go-live-checklist). 

4. Submit a request to add payment methods in your [live Customer Area](https://ca-live.adyen.com/) .

5. Switch from test to our [live endpoints](/development-resources/live-endpoints#checkout-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, for example, when authenticating with 3D Secure 2.

6. Load from one of our live environments and set the `environment` to match your live endpoints:

   | 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**          |

## Next steps

[required](/online-payments/modify-payments)

[Modify payments](/online-payments/modify-payments)

[Find out how to cancel, refund, or capture a payment using our API.](/online-payments/modify-payments)

[Add payment methods](/payment-methods/add-payment-methods)

[Learn about payment methods and how to add them to your account.](/payment-methods/add-payment-methods)

[Tokenization](/online-payments/tokenization)

[Save shopper payment details for later payments.](/online-payments/tokenization)

[3D Secure authentication](/online-payments/3d-secure)

[Comply with regulations such as PSD2 SCA in Europe.](/online-payments/3d-secure)

## Android Components

Use our customizable UI components

### Before You Begin

## Requirements

Before you begin to integrate, make sure you have followed the [Get started with Adyen guide](/get-started-with-adyen) 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](/development-resources/api-credentials#generate-api-key).
* [Get your client key](/development-resources/client-side-authentication#get-your-client-key).
* [Set up webhooks](/development-resources/webhooks) to know the payment outcome.

## 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 Redirect 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:

1. The shopper goes to the checkout page.

2. Your server uses the shopper's country or region and currency information from your client to create a payment session.

3. Your client creates an instance of Redirect using the session data from the server.

4. The Component collects the shopper's payment details, handles additional actions, and presents the payment result to the shopper.

5. Your webhook server receives the event containing the payment outcome.

[![](/user/pages/filters/sessions-flow-integration/android/5-0-0/components/02.how-it-works-sessions/component-sessions.svg)](/user/pages/filters/sessions-flow-integration/android/5-0-0/components/02.how-it-works-sessions/component-sessions.svg)

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

[![](/user/pages/reuse/online-payments/how-it-works-parts/servers.svg?decoding=auto\&fetchpriority=auto)](/#install-api-library)

[Payment server](/#install-api-library)

[Go to the integration steps for your server.](/#install-api-library)

[![](/user/pages/reuse/online-payments/how-it-works-parts/browser-developers.svg?decoding=auto\&fetchpriority=auto)](/#set-up)

[Client app](/#set-up)

[Go to the integration steps for your client app.](/#set-up)

[![](/user/pages/reuse/online-payments/how-it-works-parts/event-code.svg?decoding=auto\&fetchpriority=auto)](/#update-your-order-management-system)

[Webhook server](/#update-your-order-management-system)

[Go to the integration steps for your webhook server.](/#update-your-order-management-system)

### Install Api Library

## 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.

### Tab: Java

##### Try our example integration

![](/reuse/development-resources/install-api-library/java/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-java-spring-online-payments#checkout-example).\
![](/reuse/development-resources/install-api-library/java/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-java-spring-online-payments).

#### Requirements

* Java 11 or later.

#### Installation

You can use [Maven](https://maven.apache.org), adding this dependency to your project's POM.

**Add the API library**

```xml
<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](https://github.com/Adyen/adyen-java-api-library/releases).

#### Setting up the client

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

**Set up your client**

```java
// 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);
    }
}
```

### Tab: PHP

##### Try our example integration

![](/reuse/development-resources/install-api-library/php/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-php-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/php/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-php-online-payments).

#### 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](https://getcomposer.org/). Follow the [installation instructions](https://getcomposer.org/doc/00-intro.md) if you do not already have composer installed.

**Install the API library**

```bash
composer require adyen/php-api-library
```

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

**Include the autoloader**

```php
require __DIR__ . '/vendor/autoload.php';
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-php-api-library/releases).

#### Set up the client

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

**Set up your client**

```php
use Adyen\Model\Checkout\Amount;
use Adyen\Model\Checkout\CreateCheckoutSessionRequest;
use Adyen\Service\Checkout\PaymentsApi;

// Include your idempotency key when you make an API request.
$requestOptions['idempotencyKey'] = "YOUR_IDEMPOTENCY_KEY";

// Set up the client and service.
$client = new \Adyen\Client();
$client->setXApiKey('ADYEN_API_KEY');
$client->setEnvironment(\Adyen\Environment::TEST);

$service = new PaymentsApi($client);
```

### Tab: C\#

#### 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](https://www.nuget.org/packages/Adyen/):

**Install the API library**

```bash
PM> Install-Package Adyen -Version LATEST_VERSION
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-dotnet-api-library).

#### Set up the client

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

**Set up your client**

```cs
using Adyen;
using Adyen.Model.Checkout;
using Adyen.Service.Checkout;
using Environment = Adyen.Model.Environment;

class Program
{
    static void Main()
    {
        // Set up the client and service.
        var config = new Config
        {
            XApiKey = "ADYEN_API_KEY",
            Environment = Environment.Test
        };
        var client = new Client(config);
        var checkout = new PaymentsService(client);

        // Include your idempotency key when you make an API request.
        var requestOptions = new Adyen.Model.RequestOptions { IdempotencyKey = "YOUR_IDEMPOTENCY_KEY" };
    }
}
```

### Tab: NodeJS

##### Try our example integration

![](/reuse/development-resources/install-api-library/node-js/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-node-online-payments#checkout-example).\
![](/reuse/development-resources/install-api-library/node-js/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-node-online-payments).

#### Requirements

* Node.js version 18 or later.

#### Installation

You can use [npm](https://www.npmjs.com/):

**Install the API library**

```bash
npm install --save @adyen/api-library
npm update @adyen/api-library
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-node-api-library/releases).

#### Setting up the client

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

**Set up your client**

```js
// Require the parts of the module you want to use.
const { Client, CheckoutAPI, Types} = require("@adyen/api-library");

// Set up the client and service.
const client = new Client({ apiKey: "ADYEN_API_KEY", environment: "TEST" });
const checkoutApi = new CheckoutAPI(client);

// Include your idempotency key when you make an API request.
const requestOptions = { idempotencyKey: "YOUR_IDEMPOTENCY_KEY" };
```

### Tab: Go

##### Try our example integration

![](/reuse/development-resources/install-api-library/go/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-golang-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/go/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-golang-online-payments).

#### Requirements

* Go 1.13 or later.

#### Installation

You can use [Go modules](https://github.com/golang/go/wiki/Modules):

**Install the API library**

```shell
go get github.com/adyen/adyen-go-api-library/vLATEST_VERSION
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-go-api-library).

#### Set up the client

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

**Set up your client**

```go
package main

import (
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/adyen"
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/checkout"
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/common"
)

// Create a payment object.

func main () {
	client := adyen.NewClient(&common.Config{
		ApiKey: "ADYEN_API_KEY",
		Environment: common.TestEnv,
	})
	service := client.Checkout()
```

### Tab: Python

##### Try our example integration

![](/reuse/development-resources/install-api-library/python/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-python-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/python/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-python-online-payments).

#### Requirements

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

#### Installation

You can use [pip](https://pip.pypa.io/en/stable/):

**Install the API library**

```py
pip install Adyen
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-python-api-library).

#### Set up the client

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

**Set up your client**

```py
import Adyen

# Set up the client and service.
adyen = Adyen.Adyen()
adyen.client.xapikey = "ADYEN_API_KEY"
adyen.client.platform = "test" # The environment that the library is used in.
```

### Tab: Ruby

##### Try our example integration

![](/reuse/development-resources/install-api-library/ruby/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-rails-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/ruby/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-rails-online-payments).

#### Requirements

* Ruby 2.7 or later.

#### Installation

You can use [RubyGems](https://rubygems.org/):

**Install the API library**

```bash
gem install adyen-ruby-api-library
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-ruby-api-library/releases).

Run `bundle install` to install dependencies.

#### Set up the client

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

**Set up your client**

```ruby
require 'adyen-ruby-api-library'

# Set up the client and service.
adyen = Adyen::Client.new
adyen.api_key = 'ADYEN_API_KEY'
adyen.env = :test # The environment that the library is used in.
```

## 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 [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) request, including:

| Parameter name                                                       | Required                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `merchantAccount`                                                    | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your merchant account name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `amount`                                                             | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The `currency` and `value` of the payment, in [minor units](/development-resources/currency-codes). This is used to filter the list of available payment methods to your shopper.                                                                                                                                                                                                                                                                                                                                     |
| `returnUrl`                                                          | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | URL to where the shopper should be taken back to after a redirection. The URL can contain a maximum of 1024 characters. You can include your own additional query parameters, for example, shopper ID or order reference number. Get this URL from the `RedirectComponent.getReturnUrl(context)`. 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`                                                          | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | 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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. Exception: **QZ** (Kosovo).                                                                                                                                                                                                                                                                   |
| `channel`                                                            |                                                                                                               | The platform where the payment is taking place. Use **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 client app. 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](/risk-management/configure-standard-risk-rules/required-risk-field-reference), and for 3D Secure.                                                                                                                                                                                                                                                                                                           |
| `shopperReference`                                                   |                                                                                                               | Your reference to uniquely identify this shopper. Strongly recommended because this field is used in a number of [risk checks](/risk-management/configure-standard-risk-rules/required-risk-field-reference).                                                                                                                                                                                                                                                                                                         |
| [`applicationInfo`](/development-resources/building-adyen-solutions) |                                                                                                               | 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](/development-resources/building-adyen-solutions).                                                                                                                                                                                                                                                        |

Here is an example of how to create a session for a payment of **10** EUR:

#### curl

```bash
curl https://checkout-test.adyen.com/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": "adyencheckout://your.package.name",
  "reference": "YOUR_PAYMENT_REFERENCE",
  "countryCode": "NL"
}'
```

#### Java

```java
// Adyen Java API Library v27.0.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, additionally include your liveEndpointUrlPrefix.
Client client = new Client("ADYEN_API_KEY", Environment.TEST);

// Create the request object(s)
Amount amount = new Amount()
  .currency("EUR")
  .value(1000L);

CreateCheckoutSessionRequest createCheckoutSessionRequest = new CreateCheckoutSessionRequest()
  .reference("YOUR_PAYMENT_REFERENCE")
  .amount(amount)
  .merchantAccount("YOUR_MERCHANT_ACCOUNT")
  .countryCode("NL")
  .returnUrl("adyencheckout://your.package.name");

// Send the request
PaymentsApi service = new PaymentsApi(client);
CreateCheckoutSessionResponse response = service.sessions(createCheckoutSessionRequest, new RequestOptions().idempotencyKey("UUID"));
```

#### PHP

```php
// Adyen PHP API Library v19.0.0
use Adyen\Client;
use Adyen\Environment;
use Adyen\Model\Checkout\Amount;
use Adyen\Model\Checkout\CreateCheckoutSessionRequest;
use Adyen\Service\Checkout\PaymentsApi;

$client = new Client();
$client->setXApiKey("ADYEN_API_KEY");
// For the live environment, additionally include your liveEndpointUrlPrefix.
$client->setEnvironment(Environment::TEST);


// Create the request object(s)
$amount = new Amount();
$amount
  ->setCurrency("EUR")
  ->setValue(1000);

$createCheckoutSessionRequest = new CreateCheckoutSessionRequest();
$createCheckoutSessionRequest
  ->setReference("YOUR_PAYMENT_REFERENCE")
  ->setAmount($amount)
  ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT")
  ->setCountryCode("NL")
  ->setReturnUrl("adyencheckout://your.package.name");

$requestOptions['idempotencyKey'] = 'UUID';

// Send the request
$service = new PaymentsApi($client);
$response = $service->sessions($createCheckoutSessionRequest, $requestOptions);
```

#### C\#

```cs
// Adyen .net API Library v17.0.0
using Adyen;
using Environment = Adyen.Model.Environment;
using Adyen.Model;
using Adyen.Model.Checkout;
using Adyen.Service.Checkout;

// For the live environment, additionally include your liveEndpointUrlPrefix.
var config = new Config()
{
    XApiKey = "ADYEN_API_KEY",
    Environment = Environment.Test
};
var client = new Client(config);

// Create the request object(s)
Amount amount = new Amount
{
  Currency = "EUR",
  Value = 1000
};

CreateCheckoutSessionRequest createCheckoutSessionRequest = new CreateCheckoutSessionRequest
{
  Reference = "YOUR_PAYMENT_REFERENCE",
  Amount = amount,
  MerchantAccount = "YOUR_MERCHANT_ACCOUNT",
  CountryCode = "NL",
  ReturnUrl = "adyencheckout://your.package.name"
};

// Send the request
var service = new PaymentsService(client);
var response = service.Sessions(createCheckoutSessionRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"});
```

#### NodeJS (JavaScript)

```js
// Adyen Node API Library v18.0.0
// Require the parts of the module you want to use
const { Client, CheckoutAPI } = require('@adyen/api-library');
// Initialize the client object
// For the live environment, additionally include your liveEndpointUrlPrefix.
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object(s)
const createCheckoutSessionRequest = {
  merchantAccount: "YOUR_MERCHANT_ACCOUNT",
  amount: {
    value: 1000,
    currency: "EUR"
  },
  returnUrl: "adyencheckout://your.package.name",
  reference: "YOUR_PAYMENT_REFERENCE",
  countryCode: "NL"
}

// Send the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.sessions(createCheckoutSessionRequest, { idempotencyKey: "UUID" });
```

#### Go

```go
// Adyen Go API Library v10.4.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, additionally include your liveEndpointUrlPrefix.
client := adyen.NewClient(&common.Config{
  ApiKey:      "ADYEN_API_KEY",
  Environment: common.TestEnv,
})

// Create the request object(s)
amount := checkout.Amount{
  Currency: "EUR",
  Value: 1000,
}

createCheckoutSessionRequest := checkout.CreateCheckoutSessionRequest{
  Reference: "YOUR_PAYMENT_REFERENCE",
  Amount: amount,
  MerchantAccount: "YOUR_MERCHANT_ACCOUNT",
  CountryCode: common.PtrString("NL"),
  ReturnUrl: "adyencheckout://your.package.name",
}

// Send the request
service := client.Checkout()
req := service.PaymentsApi.SessionsInput().IdempotencyKey("UUID").CreateCheckoutSessionRequest(createCheckoutSessionRequest)
res, httpRes, err := service.PaymentsApi.Sessions(context.Background(), req)
```

#### Python

```py
# Adyen Python API Library v12.5.1
import Adyen

adyen = Adyen.Adyen()
adyen.client.xapikey = "ADYEN_API_KEY"
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.client.platform = "test" # The environment to use library in.

# Create the request object(s)
json_request = {
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "amount": {
    "value": 1000,
    "currency": "EUR"
  },
  "returnUrl": "adyencheckout://your.package.name",
  "reference": "YOUR_PAYMENT_REFERENCE",
  "countryCode": "NL"
}

# Send the request
result = adyen.checkout.payments_api.sessions(request=json_request, idempotency_key="UUID")
```

#### Ruby

```rb
# Adyen Ruby API Library v9.5.1
require "adyen-ruby-api-library"

adyen = Adyen::Client.new
adyen.api_key = 'ADYEN_API_KEY'
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.env = :test # Set to "live" for live environment

# Create the request object(s)
request_body = {
  :merchantAccount => 'YOUR_MERCHANT_ACCOUNT',
  :amount => {
    :value => 1000,
    :currency => 'EUR'
  },
  :returnUrl => 'adyencheckout://your.package.name',
  :reference => 'YOUR_PAYMENT_REFERENCE',
  :countryCode => 'NL'
}

# Send the request
result = adyen.checkout.payments_api.sessions(request_body, headers: { 'Idempotency-Key' => 'UUID' })
```

#### NodeJS (TypeScript)

```ts
// Adyen Node API Library v18.0.0
// Require the parts of the module you want to use
import { Client, CheckoutAPI, Types } from "@adyen/api-library";
// Initialize the client object
// For the live environment, additionally include your liveEndpointUrlPrefix.
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object(s)
const amount: Types.checkout.Amount = {
  currency: "EUR",
  value: 1000
};

const createCheckoutSessionRequest: Types.checkout.CreateCheckoutSessionRequest = {
  reference: "YOUR_PAYMENT_REFERENCE",
  amount: amount,
  merchantAccount: "YOUR_MERCHANT_ACCOUNT",
  countryCode: "NL",
  returnUrl: "adyencheckout://your.package.name"
};

// Send the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.sessions(createCheckoutSessionRequest, { idempotencyKey: "UUID" });
```

The response contains:

* `sessionData`: the payment session data you need to pass to your client app.
* `id`: a unique identifier for the session data.
* The request body.

**HTTP 201 /sessions response body**

```json
{
    "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": "adyencheckout://your.package.name",
    "sessionData": "Ab02b4c.."
}
```

You must pass the response to your client app to [create the checkout session](#create-the-checkout-session).

### API error handling

If you do not get an HTTP 201 response, use the `errorCode` field and the list of [API error codes](/development-resources/error-codes) to troubleshoot.

### Set Up Drop In

## Set up Components

Client app

### 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. For example, to import the Card Component:

### Tab: With Jetpack Compose

**Import the module with Compose**

```groovy
implementation "com.adyen.checkout:card:YOUR_VERSION"
implementation "com.adyen.checkout:components-compose:YOUR_VERSION"
```

### Tab: Without Jetpack Compose

**Import the module without Compose**

```groovy
implementation "com.adyen.checkout:card:YOUR_VERSION"
```

You can find the module to import for each payment method on the corresponding [payment method](/payment-methods/) page.

### Create Checkout Session

### 2: Create the checkout session

1. Deserialize the [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) response to a `SessionsModel` object:

   **Deserialize the API response**

   ```kotlin
   val sessionModel = SessionModel.SERIALIZER.deserialize(sessionsResponseJSON)
   ```

2. Call the `CheckoutSessionProvider.createSession` suspending function, passing:

   | Parameter      | Required                                                                                                      | Description                                                                            |
   | -------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
   | `sessionModel` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The deserialized `SessionsModel` object.                                               |
   | `environment`  | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Use `Environment.TEST` for testing. When going live, use one of our live environments. |
   | `clientKey`    | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your client key.                                                                       |

   For example:

   **Create the checkout session**

   ```kotlin
   // Create an object for the checkout session.
   val result = CheckoutSessionProvider.createSession(sessionModel, environment, clientKey)

   // If the payment session is successful, handle the result.
   // If the payment session encounters an error, handle the error.
   when (result) {
       is CheckoutSessionResult.Success -> handleCheckoutSession(result.checkoutSession)
       is CheckoutSessionResult.Error -> handleError(result.exception)
   }
   ```

**

### 3. (Optional) Add a configuration object

Create a configuration object, setting the following properties:[]()

| Property        | Required                                                                                                      | Description                                                                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `environment`   | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The same `environment` that you set when you created the session.                                                                                                              |
| `clientKey`     | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The same `clientKey` that you set when you created the session.                                                                                                                |
| `shopperLocale` |                                                                                                               | The shopper's locale. By default, this matches the `shopperLocale` you included in the [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) request. |

**Optionally create a configuration object**

```kotlin
// Create a configuration object.
val checkoutConfiguration = CheckoutConfiguration(
    environment = environment,
    clientKey = clientKey,
    shopperLocale = shopperLocale, // Optional
) {
    // Optional: configuration for the card payment method.
    card {
        setHolderNameRequired(true)
        setShopperReference("...")
    }

    // Optional: change configuration for 3D Secure 2.
    adyen3DS2 {
        setThreeDSRequestorAppURL("...")
    }
}
```

### Launch And Show Drop In

### 4: Launch and show the Component

### Tab: With Jetpack Compose

1. Implement the `SessionComponentCallback` class to handle additional actions and receive the result of the session.

   **Add handlers**

   ```kotlin
   override fun onFinished(result: SessionPaymentResult) {
       // The payment finishes with a result.
   }
   override fun onAction(action: Action) {
       // An additional action needs to be handled. Forward the action to the Component.
       cardComponent.handleAction(action, activity)
   }
   override fun onError(componentError: ComponentError) {
       // The Component encounters an error.
   }
   ```

2. Create the Component and attach it to a view. For example:

   **Create the Component**

   ```kotlin
   import com.adyen.checkout.components.compose.get

   // Get the payment method.
   val paymentMethod = checkoutSession.getPaymentMethod(PaymentMethodTypes.SCHEME)

   @Composable
   private fun ComposableCardComponent() {
      // Keep a reference to this Component in case you need to access it later.
      val cardComponent = CardComponent.PROVIDER.get(
          checkoutSession = checkoutSession,
          paymentMethod = paymentMethod,
          configuration = checkoutConfiguration, //Optional: pass this if you added a configuration object in the previous step.
          componentCallback = callback,
          // This key is required to ensure a new Component gets created for each different screen or payment session.
          // Generate a new value for this key every time you need to reset the Component.
          key = "YOUR_UNIQUE_KEY_FOR_THIS_COMPONENT",
      )

      // This is your composable, a wrapper around our xml view.
      AdyenComponent(
         component = cardComponent,
         modifier = YOUR_MODIFIER,
      )
   }
   ```

### Tab: Without Jetpack Compose

1. Add `AdyenComponentView` to your `xml` file:

   **Add the view**

   ```xml
   <com.adyen.checkout.ui.core.AdyenComponentView
       android:id="@+id/YOUR_COMPONENT_VIEW_ID"
       .../>
   ```

2. Implement the `SessionComponentCallback` class to handle additional actions and receive the result of the session.

   **Add handlers**

   ```kotlin
   override fun onFinished(result: SessionPaymentResult) {
       // The payment finishes with a result.
   }
   override fun onAction(action: Action) {
       // An additional action needs to be handled. Forward the action to the Component.
       cardComponent.handleAction(action, activity)
   }
   override fun onError(componentError: ComponentError) {
       // The Component encounters an error.
   }
   ```

Create the Component by calling `PROVIDER.get` from your Component class, passing:

| Parameter                          | Required                                                                                                      | Description                                         |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `activity` or `fragment` (Example) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your `Activity` or `Fragment`.                      |
| `checkoutSession`                  | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The checkout session that you created.              |
| `componentCallback`                | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The callback for the functions you implemented.     |
| `checkoutConfiguration`            |                                                                                                               | The checkout configuration object that you created. |

**Start the Component**

```kotlin
// Get the payment method.
val paymentMethod = checkoutSession.getPaymentMethod(PaymentMethodTypes.SCHEME)

val cardComponent = CardComponent.PROVIDER.get(
    activity, // Your activity or fragment.
    checkoutSession,
    paymentMethod,
    checkoutConfiguration, // Optional: pass this if you created a configuration object in the previous step.
    componentCallback
)
```

3. Attach your Component to your `Activity` or `Fragment`. For example to attach your Component to your view with the identifier `cardView`:

   **Attach your Component to the view**

   ```kotlin
   binding.cardView.attach(cardComponent, activity) // Your activity or fragment.
   ```

Your app shows the Component, and the Component handles the whole payment flow.

### Handle a redirect

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

1. Add an `IntentFilter` to your `Activity` that handles redirects. The

**Add handling for redirects**

```xml
<activity
  android:name="YOUR_ACTIVITY"
  android:exported="true">
  <intent-filter>
     <action android:name="android.intent.action.VIEW"/>
     <category android:name="android.intent.category.DEFAULT"/>
     <category android:name="android.intent.category.BROWSABLE"/>
     <data android:host="YOUR_APPLICATION_ID" android:scheme="adyencheckout"/>
  </intent-filter>
</activity>
```

The `android:host` value is your package name at build time. This must match the `returnUrl` from the [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) request. To get your `returnUrl`, you can use the `RedirectComponent.getReturnUrl(context)` function.

2. 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`.

**Handle the intent**

```java
private fun handleIntent(intent: Intent?) {
  if (intent.data?.toString().orEmpty().startsWith(RedirectComponent.REDIRECT_RESULT_SCHEME)) {
      cardComponent?.handleIntent(intent)
  }
}
```

## Get the payment outcome

After Redirect finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.

### Inform the shopper

Client app

From the `onFinished` function, you can get the [`resultCode` ](/online-payments/payment-result-codes)to inform the shopper about the current payment status.

**

### Optional: Get the result of the payment session on your server

Payment server

You can also get the result of the payment session on your server.

1. Get the `id` from the [`/sessions` response](#sessions-response).

2. Get `sessionResult` from the `onFinished` function.

3. Make a **GET** `/sessions/{id}?sessionResult={sessionResult}` request including the `id` and `sessionResult`. For example:

   **Request for result of payment session**

   #### curl

   ```bash
   curl -X GET https://checkout-test.adyen.com/v70/sessions/CS12345678?sessionResult=SOME_DATA
   ```

   #### Java

   ```java
   // Adyen Java API Library v39.3.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.service.checkout.*;

   // For the LIVE environment, also include your liveEndpointUrlPrefix.
   Client client = new Client("", Environment.TEST);
   // Send the request
   PaymentsApi service = new PaymentsApi(client);
   SessionResultResponse response = service.getResultOfPaymentSession("sessionId", "String", null);
   ```

   #### PHP

   ```php
   <?php
   // Adyen PHP API Library v28.2.0
   use Adyen\Client;
   use Adyen\Environment;
   use Adyen\Service\Checkout\PaymentsApi;

   $client = new Client();
   $client->setXApiKey("");
   // For the LIVE environment, also include your liveEndpointUrlPrefix.
   $client->setEnvironment(Environment::TEST);

   $requestOptions['queryParams'] = array('sessionResult' => 'string');

   // Send the request
   $service = new PaymentsApi($client);
   $response = $service->getResultOfPaymentSession('sessionId', $requestOptions);
   ```

   #### C\#

   ```cs
   // Adyen .net API Library v32.1.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 = "",
       Environment = Environment.Test
   };
   var client = new Client(config);

   // Send the request
   var service = new PaymentsService(client);
   var response = service.GetResultOfPaymentSession("sessionId", sessionResult: "string");
   ```

   #### NodeJS (JavaScript)

   ```js
   // Adyen Node API Library v29.0.0
   const { Client, CheckoutAPI } = require('@adyen/api-library');

   // For the LIVE environment, also include your liveEndpointUrlPrefix.
   const config = new Config({
     apiKey: "",
     environment: EnvironmentEnum.TEST
   });

   const client = new Client(config);

   // Send the request
   const checkoutAPI = new CheckoutAPI(client);
   const response = checkoutAPI.PaymentsApi.getResultOfPaymentSession("sessionId", "string");
   ```

   #### Go

   ```go
   // Adyen Go API Library v21.0.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:      "",
     Environment: common.TestEnv,
   })

   // Send the request
   service := client.Checkout()
   req := service.PaymentsApi.GetResultOfPaymentSessionInput("sessionId")
   req = req.SessionResult("string")
   res, httpRes, err := service.PaymentsApi.GetResultOfPaymentSession(context.Background(), req)
   ```

   #### Python

   ```py
   # Adyen Python API Library v13.6.0
   import Adyen

   adyen = Adyen.Adyen()
   adyen.client.xapikey = ""
   # For the LIVE environment, also include your liveEndpointUrlPrefix.
   adyen.client.platform = "test" # The environment to use library in.

   query_parameters = {
     "sessionResult" : "string"
   }

   # Send the request
   result = adyen.checkout.payments_api.get_result_of_payment_session(sessionId="sessionId", query_parameters=query_parameters)
   ```

   #### Ruby

   ```rb
   # Adyen Ruby API Library v10.4.0
   require "adyen-ruby-api-library"

   adyen = Adyen::Client.new
   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)
   query_params = {
     :sessionResult => 'string'
   }

   # Send the request
   result = adyen.checkout.payments_api.get_result_of_payment_session('sessionId', query_params: query_params)
   ```

   #### NodeJS (TypeScript)

   ```ts
   // Adyen Node API Library v29.0.0
   import { Client, CheckoutAPI, Types } from "@adyen/api-library";

   // For the LIVE environment, also include your liveEndpointUrlPrefix.
   const config = new Config({
     apiKey: "",
     environment: EnvironmentEnum.TEST
   });

   const client = new Client(config);

   // Send the request
   const checkoutAPI = new CheckoutAPI(client);
   const response = checkoutAPI.PaymentsApi.getResultOfPaymentSession("sessionId", "string");
   ```

   The response includes the result of the payment session (`status`). For example:

   **Response with result of the payment session**

   ```bash
   {
      "id": "CS12345678",
      "status": "completed"
   }
   ```

   Possible statuses:

   | `status`           | Description                                                                                                                      |
   | ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
   | **completed**      | The shopper completed the payment. This means that the payment was authorized.                                                   |
   | **paymentPending** | The shopper is in the process of making the payment. This applies to payment methods with an asynchronous flow.                  |
   | **canceled**       | The shopper canceled the payment.                                                                                                |
   | **expired**        | The session expired (default: 1 hour after session creation). Shoppers can no longer complete the payment with this `sessionId`. |

The `status` included in the response doesn't get updated. Do not make the request again to check for payment status updates. Instead, check webhooks or the **Transactions** list in your [Customer Area](https://ca-test.adyen.com/).

### Update your order management system

Webhook server

You get the outcome of each payment asynchronously, in an **AUTHORISATION** [webhook](/development-resources/webhooks). Use the `merchantReference` from the webhook to match it to your order reference.\
For a successful payment, the event contains `success`: **true**.

**Example webhook for a successful payment**

```json
{
  "live": "false",
  "notificationItems":[
    {
      "NotificationRequestItem":{
        "eventCode":"AUTHORISATION",
        "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
        "reason":"033899:1111:03/2030",
        "amount":{
          "currency":"EUR",
          "value":2500
        },
        "operations":["CANCEL","CAPTURE","REFUND"],
        "success":"true",
        "paymentMethod":"mc",
        "additionalData":{
          "expiryDate":"03/2030",
          "authCode":"033899",
          "cardBin":"411111",
          "cardSummary":"1111",
          "checkoutSessionId":"CSF46729982237A879"
        },
        "merchantReference":"YOUR_REFERENCE",
        "pspReference":"NC6HT9CRT65ZGN82",
        "eventDate":"2021-09-13T14:10:22+02:00"
      }
    }
  ]
}
```

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

**Example webhook for an unsuccessful payment**

```json
{
  "live": "false",
  "notificationItems":[
    {
      "NotificationRequestItem":{
        "eventCode":"AUTHORISATION",
        "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
        "reason":"validation 101 Invalid card number",
        "amount":{
          "currency":"EUR",
          "value":2500
        },
        "success":"false",
        "paymentMethod":"unknowncard",
        "additionalData":{
          "expiryDate":"03/2030",
          "cardBin":"411111",
          "cardSummary":"1112",
          "checkoutSessionId":"861631540104159H"
        },
        "merchantReference":"YOUR_REFERENCE",
        "pspReference":"KHQC5N7G84BLNK43",
        "eventDate":"2021-09-13T14:14:05+02:00"
      }
    }
  ]
}
```

## Test and go live

Before going live, use our list of [test cards and other payment methods](/development-resources/test-cards-and-credentials/test-card-numbers) to [test your integration](/development-resources/testing). Use the [Adyen Android test cards app](/development-resources/test-cards-and-credentials/test-card-numbers#android-test-cards-app) to access, copy, and autofill card details from within your Android device. 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](https://ca-test.adyen.com/), under **Payments** > **Payment list**.

To debug or troubleshoot test payments, you can also use [API logs](/development-resources/logs-resources/api-logs) in your test environment.

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

1. [Apply for a live account](/get-started-with-adyen/application-requirements). Review the process to start accepting payments on [Get started with Adyen](/get-started-with-adyen).

2. Assess your [PCI DSS compliance](/development-resources/pci-dss-compliance-guide#online-payments) by submitting the [Self-Assessment Questionnaire-A](https://www.pcisecuritystandards.org/documents/PCI-DSS-v3_2_1-SAQ-A.pdf).

3. [Configure your live account](/online-payments/go-live-checklist). 

4. Submit a request to add payment methods in your [live Customer Area](https://ca-live.adyen.com/) .

5. Switch from test to our [live endpoints](/development-resources/live-endpoints#checkout-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, for example, when authenticating with 3D Secure 2.

6. Load from one of our live environments and set the `environment` to match your live endpoints:

   | 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**          |

## Next steps

[required](/online-payments/modify-payments)

[Modify payments](/online-payments/modify-payments)

[Find out how to cancel, refund, or capture a payment using our API.](/online-payments/modify-payments)

[Add payment methods](/payment-methods/add-payment-methods)

[Learn about payment methods and how to add them to your account.](/payment-methods/add-payment-methods)

[Tokenization](/online-payments/tokenization)

[Save shopper payment details for later payments.](/online-payments/tokenization)

[3D Secure authentication](/online-payments/3d-secure)

[Comply with regulations such as PSD2 SCA in Europe.](/online-payments/3d-secure)

## React Native Drop-in

Use our pre-built UI for accepting payments

### Intro

Drop-in is our pre-built UI solution for accepting payments in your app. Drop-in shows all payment methods as a list, in the same block. Your server makes one API request to the [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) endpoint.

React Native Drop-in v1, Components v1, and Components v2 only support [Advanced flow](/online-payments/build-your-integration/advanced-flow) integrations.

### Before You Begin

## Requirements

Before you begin to integrate, make sure you have followed the [Get started with Adyen guide](/get-started-with-adyen) 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](/development-resources/api-credentials#generate-api-key).
* [Get your client key](/development-resources/client-side-authentication#get-your-client-key).
* [Set up webhooks](/development-resources/webhooks) to know the payment outcome.

## How it works

For a Drop-in integration, you must implement the following parts:

* **Your payment server**: sends the API request to create a payment session.
* **Your client app**: shows the Drop-in UI where the shopper makes the payment. Drop-in 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:

1. The shopper goes to the checkout page.
2. Your server uses the shopper's country and currency information from your client to create a payment session.
3. Your client creates an instance of Drop-in using the session data from the server.
4. Drop-in shows the available payment methods, collects the shopper's payment details, handles additional actions, and presents the payment result to the shopper.
5. Your webhook server receives the notification containing the payment outcome.

![](/user/pages/filters/sessions-flow-integration/react-native/2-0-0/02.how-it-works/drop-in-sessions.svg?decoding=auto\&fetchpriority=auto)

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

[![](/user/pages/reuse/online-payments/how-it-works-parts/servers.svg?decoding=auto\&fetchpriority=auto)](/#install-api-library)

[Payment server](/#install-api-library)

[Go to the integration steps for your server.](/#install-api-library)

[![](/user/pages/reuse/online-payments/how-it-works-parts/browser-developers.svg?decoding=auto\&fetchpriority=auto)](/#add)

[Client app](/#add)

[Go to the integration steps for your client app.](/#add)

[![](/user/pages/reuse/online-payments/how-it-works-parts/event-code.svg?decoding=auto\&fetchpriority=auto)](/#update-your-order-management-system)

[Webhook server](/#update-your-order-management-system)

[Go to the integration steps for your webhook server.](/#update-your-order-management-system)

### Install Api Library

## 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.

### Tab: Java

##### Try our example integration

![](/reuse/development-resources/install-api-library/java/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-java-spring-online-payments#checkout-example).\
![](/reuse/development-resources/install-api-library/java/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-java-spring-online-payments).

#### Requirements

* Java 11 or later.

#### Installation

You can use [Maven](https://maven.apache.org), adding this dependency to your project's POM.

**Add the API library**

```xml
<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](https://github.com/Adyen/adyen-java-api-library/releases).

#### Setting up the client

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

**Set up your client**

```java
// 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);
    }
}
```

### Tab: PHP

##### Try our example integration

![](/reuse/development-resources/install-api-library/php/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-php-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/php/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-php-online-payments).

#### 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](https://getcomposer.org/). Follow the [installation instructions](https://getcomposer.org/doc/00-intro.md) if you do not already have composer installed.

**Install the API library**

```bash
composer require adyen/php-api-library
```

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

**Include the autoloader**

```php
require __DIR__ . '/vendor/autoload.php';
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-php-api-library/releases).

#### Set up the client

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

**Set up your client**

```php
use Adyen\Model\Checkout\Amount;
use Adyen\Model\Checkout\CreateCheckoutSessionRequest;
use Adyen\Service\Checkout\PaymentsApi;

// Include your idempotency key when you make an API request.
$requestOptions['idempotencyKey'] = "YOUR_IDEMPOTENCY_KEY";

// Set up the client and service.
$client = new \Adyen\Client();
$client->setXApiKey('ADYEN_API_KEY');
$client->setEnvironment(\Adyen\Environment::TEST);

$service = new PaymentsApi($client);
```

### Tab: C\#

#### 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](https://www.nuget.org/packages/Adyen/):

**Install the API library**

```bash
PM> Install-Package Adyen -Version LATEST_VERSION
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-dotnet-api-library).

#### Set up the client

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

**Set up your client**

```cs
using Adyen;
using Adyen.Model.Checkout;
using Adyen.Service.Checkout;
using Environment = Adyen.Model.Environment;

class Program
{
    static void Main()
    {
        // Set up the client and service.
        var config = new Config
        {
            XApiKey = "ADYEN_API_KEY",
            Environment = Environment.Test
        };
        var client = new Client(config);
        var checkout = new PaymentsService(client);

        // Include your idempotency key when you make an API request.
        var requestOptions = new Adyen.Model.RequestOptions { IdempotencyKey = "YOUR_IDEMPOTENCY_KEY" };
    }
}
```

### Tab: NodeJS

##### Try our example integration

![](/reuse/development-resources/install-api-library/node-js/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-node-online-payments#checkout-example).\
![](/reuse/development-resources/install-api-library/node-js/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-node-online-payments).

#### Requirements

* Node.js version 18 or later.

#### Installation

You can use [npm](https://www.npmjs.com/):

**Install the API library**

```bash
npm install --save @adyen/api-library
npm update @adyen/api-library
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-node-api-library/releases).

#### Setting up the client

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

**Set up your client**

```js
// Require the parts of the module you want to use.
const { Client, CheckoutAPI, Types} = require("@adyen/api-library");

// Set up the client and service.
const client = new Client({ apiKey: "ADYEN_API_KEY", environment: "TEST" });
const checkoutApi = new CheckoutAPI(client);

// Include your idempotency key when you make an API request.
const requestOptions = { idempotencyKey: "YOUR_IDEMPOTENCY_KEY" };
```

### Tab: Go

##### Try our example integration

![](/reuse/development-resources/install-api-library/go/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-golang-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/go/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-golang-online-payments).

#### Requirements

* Go 1.13 or later.

#### Installation

You can use [Go modules](https://github.com/golang/go/wiki/Modules):

**Install the API library**

```shell
go get github.com/adyen/adyen-go-api-library/vLATEST_VERSION
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-go-api-library).

#### Set up the client

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

**Set up your client**

```go
package main

import (
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/adyen"
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/checkout"
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/common"
)

// Create a payment object.

func main () {
	client := adyen.NewClient(&common.Config{
		ApiKey: "ADYEN_API_KEY",
		Environment: common.TestEnv,
	})
	service := client.Checkout()
```

### Tab: Python

##### Try our example integration

![](/reuse/development-resources/install-api-library/python/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-python-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/python/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-python-online-payments).

#### Requirements

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

#### Installation

You can use [pip](https://pip.pypa.io/en/stable/):

**Install the API library**

```py
pip install Adyen
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-python-api-library).

#### Set up the client

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

**Set up your client**

```py
import Adyen

# Set up the client and service.
adyen = Adyen.Adyen()
adyen.client.xapikey = "ADYEN_API_KEY"
adyen.client.platform = "test" # The environment that the library is used in.
```

### Tab: Ruby

##### Try our example integration

![](/reuse/development-resources/install-api-library/ruby/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-rails-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/ruby/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-rails-online-payments).

#### Requirements

* Ruby 2.7 or later.

#### Installation

You can use [RubyGems](https://rubygems.org/):

**Install the API library**

```bash
gem install adyen-ruby-api-library
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-ruby-api-library/releases).

Run `bundle install` to install dependencies.

#### Set up the client

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

**Set up your client**

```ruby
require 'adyen-ruby-api-library'

# Set up the client and service.
adyen = Adyen::Client.new
adyen.api_key = 'ADYEN_API_KEY'
adyen.env = :test # The environment that the library is used in.
```

## 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 [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) request, including:

| Parameter name                                                       | Required                                                                                                                                                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `merchantAccount`                                                    | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto)                                                                         | Your merchant account name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `amount`                                                             | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto)                                                                         | The `currency` and `value` of the payment, in [minor units](/development-resources/currency-codes). This is used to filter the list of available payment methods to your shopper.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `returnUrl`                                                          | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) For Android, this value is automatically overridden by `AdyenCheckout`. | The URL the shopper should be taken back to after a redirection. Maximum length: 1024 characters. For iOS, use the custom URL for your app, for example, `my-app://adyen`, to take the shopper back to your app after they complete the payment outside of your app. For more information on setting a custom URL scheme, read the [Apple Developer documentation](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app). You can also include your own additional query parameters, for example, shopper ID or order reference number. 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`                                                          | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto)                                                                         | 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](https://en.wikipedia.org/wiki/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 client app. 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](/risk-management/configure-standard-risk-rules/required-risk-field-reference), 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](/risk-management/configure-standard-risk-rules/required-risk-field-reference).                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [`applicationInfo`](/development-resources/building-adyen-solutions) |                                                                                                                                                                                       | 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](/development-resources/building-adyen-solutions).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |

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

#### curl

```bash
curl https://checkout-test.adyen.com/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"
}'
```

#### Java

```java
// Adyen Java API Library v27.0.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, additionally include your liveEndpointUrlPrefix.
Client client = new Client("ADYEN_API_KEY", Environment.TEST);

// Create the request object(s)
Amount amount = new Amount()
  .currency("EUR")
  .value(1000L);

CreateCheckoutSessionRequest createCheckoutSessionRequest = new CreateCheckoutSessionRequest()
  .reference("YOUR_PAYMENT_REFERENCE")
  .amount(amount)
  .merchantAccount("YOUR_MERCHANT_ACCOUNT")
  .countryCode("NL")
  .returnUrl("my-app://adyen");

// Send the request
PaymentsApi service = new PaymentsApi(client);
CreateCheckoutSessionResponse response = service.sessions(createCheckoutSessionRequest, new RequestOptions().idempotencyKey("UUID"));
```

#### PHP

```php
// Adyen PHP API Library v19.0.0
use Adyen\Client;
use Adyen\Environment;
use Adyen\Model\Checkout\Amount;
use Adyen\Model\Checkout\CreateCheckoutSessionRequest;
use Adyen\Service\Checkout\PaymentsApi;

$client = new Client();
$client->setXApiKey("ADYEN_API_KEY");
// For the live environment, additionally include your liveEndpointUrlPrefix.
$client->setEnvironment(Environment::TEST);


// Create the request object(s)
$amount = new Amount();
$amount
  ->setCurrency("EUR")
  ->setValue(1000);

$createCheckoutSessionRequest = new CreateCheckoutSessionRequest();
$createCheckoutSessionRequest
  ->setReference("YOUR_PAYMENT_REFERENCE")
  ->setAmount($amount)
  ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT")
  ->setCountryCode("NL")
  ->setReturnUrl("my-app://adyen");

$requestOptions['idempotencyKey'] = 'UUID';

// Send the request
$service = new PaymentsApi($client);
$response = $service->sessions($createCheckoutSessionRequest, $requestOptions);
```

#### C\#

```cs
// Adyen .net API Library v17.0.0
using Adyen;
using Environment = Adyen.Model.Environment;
using Adyen.Model;
using Adyen.Model.Checkout;
using Adyen.Service.Checkout;

// For the live environment, additionally include your liveEndpointUrlPrefix.
var config = new Config()
{
    XApiKey = "ADYEN_API_KEY",
    Environment = Environment.Test
};
var client = new Client(config);

// Create the request object(s)
Amount amount = new Amount
{
  Currency = "EUR",
  Value = 1000
};

CreateCheckoutSessionRequest createCheckoutSessionRequest = new CreateCheckoutSessionRequest
{
  Reference = "YOUR_PAYMENT_REFERENCE",
  Amount = amount,
  MerchantAccount = "YOUR_MERCHANT_ACCOUNT",
  CountryCode = "NL",
  ReturnUrl = "my-app://adyen"
};

// Send the request
var service = new PaymentsService(client);
var response = service.Sessions(createCheckoutSessionRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"});
```

#### NodeJS (JavaScript)

```js
// Adyen Node API Library v18.0.0
// Require the parts of the module you want to use
const { Client, CheckoutAPI } = require('@adyen/api-library');
// Initialize the client object
// For the live environment, additionally include your liveEndpointUrlPrefix.
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object(s)
const createCheckoutSessionRequest = {
  merchantAccount: "YOUR_MERCHANT_ACCOUNT",
  amount: {
    value: 1000,
    currency: "EUR"
  },
  returnUrl: "my-app://adyen",
  reference: "YOUR_PAYMENT_REFERENCE",
  countryCode: "NL"
}

// Send the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.sessions(createCheckoutSessionRequest, { idempotencyKey: "UUID" });
```

#### Go

```go
// Adyen Go API Library v10.4.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, additionally include your liveEndpointUrlPrefix.
client := adyen.NewClient(&common.Config{
  ApiKey:      "ADYEN_API_KEY",
  Environment: common.TestEnv,
})

// Create the request object(s)
amount := checkout.Amount{
  Currency: "EUR",
  Value: 1000,
}

createCheckoutSessionRequest := checkout.CreateCheckoutSessionRequest{
  Reference: "YOUR_PAYMENT_REFERENCE",
  Amount: amount,
  MerchantAccount: "YOUR_MERCHANT_ACCOUNT",
  CountryCode: common.PtrString("NL"),
  ReturnUrl: "my-app://adyen",
}

// Send the request
service := client.Checkout()
req := service.PaymentsApi.SessionsInput().IdempotencyKey("UUID").CreateCheckoutSessionRequest(createCheckoutSessionRequest)
res, httpRes, err := service.PaymentsApi.Sessions(context.Background(), req)
```

#### Python

```py
# Adyen Python API Library v12.5.1
import Adyen

adyen = Adyen.Adyen()
adyen.client.xapikey = "ADYEN_API_KEY"
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.client.platform = "test" # The environment to use library in.

# Create the request object(s)
json_request = {
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "amount": {
    "value": 1000,
    "currency": "EUR"
  },
  "returnUrl": "my-app://adyen",
  "reference": "YOUR_PAYMENT_REFERENCE",
  "countryCode": "NL"
}

# Send the request
result = adyen.checkout.payments_api.sessions(request=json_request, idempotency_key="UUID")
```

#### Ruby

```rb
# Adyen Ruby API Library v9.5.1
require "adyen-ruby-api-library"

adyen = Adyen::Client.new
adyen.api_key = 'ADYEN_API_KEY'
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.env = :test # Set to "live" for live environment

# Create the request object(s)
request_body = {
  :merchantAccount => 'YOUR_MERCHANT_ACCOUNT',
  :amount => {
    :value => 1000,
    :currency => 'EUR'
  },
  :returnUrl => 'my-app://adyen',
  :reference => 'YOUR_PAYMENT_REFERENCE',
  :countryCode => 'NL'
}

# Send the request
result = adyen.checkout.payments_api.sessions(request_body, headers: { 'Idempotency-Key' => 'UUID' })
```

#### NodeJS (TypeScript)

```ts
// Adyen Node API Library v18.0.0
// Require the parts of the module you want to use
import { Client, CheckoutAPI, Types } from "@adyen/api-library";
// Initialize the client object
// For the live environment, additionally include your liveEndpointUrlPrefix.
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object(s)
const amount: Types.checkout.Amount = {
  currency: "EUR",
  value: 1000
};

const createCheckoutSessionRequest: Types.checkout.CreateCheckoutSessionRequest = {
  reference: "YOUR_PAYMENT_REFERENCE",
  amount: amount,
  merchantAccount: "YOUR_MERCHANT_ACCOUNT",
  countryCode: "NL",
  returnUrl: "my-app://adyen"
};

// Send the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.sessions(createCheckoutSessionRequest, { idempotencyKey: "UUID" });
```

The response contains:

* `sessionData`: the payment session data you need to pass to your client app.
* `id`: a unique identifier for the session data.
* The request body.

**HTTP 201 /sessions response body**

```json
{
    "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](/development-resources/error-codes) to troubleshoot.

### Add Adyen To Your App

## Add Adyen Drop-in to your app

Client app

### 1. Add Adyen React Native to your project

**Add Adyen React Native**

```js
$ yarn add @adyen/react-native
```

### 2. Install

### Tab: iOS

1. Run `pod install`.

2. In your `AppDelegate.m` file, add a return URL handler for handling redirects from other apps. For example:

   **iOS return URL handler**

   ```js
   import <adyen-react-native/ADYRedirectComponent.h>

   {
   ...
   - (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
     return [ADYRedirectComponent applicationDidOpenURL:url];
   }
   ```

   If you use `RCTLinkingManager` or other ways of deep linking, use `ADYRedirectComponent.applicationDidOpenURL` first:

   **Return URL handler with deep linking**

   ```js
   import <adyen-react-native/ADYRedirectComponent.h>

   {
   ...
   - (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
     return [ADYRedirectComponent applicationDidOpenURL:url] || [super application:application openURL:url options:options] || [RCTLinkingManager application:application openURL:url options:options];
   }
   ```

   If you want to [support universal links in your app](https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app), add the following return URL handler instead:

   **Return handler with universal link support**

   ```js
   import <adyen-react-native/ADYRedirectComponent.h>

   {
   ...
   - (BOOL)application:(UIApplication *)application continueUserActivity:(nonnull NSUserActivity *)userActivity restorationHandler:(nonnull void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {
     if ([[userActivity activityType] isEqualToString:NSUserActivityTypeBrowsingWeb]) {
      NSURL *url = [userActivity webpageURL];
       if (![url isEqual:[NSNull null]] && [ADYRedirectComponent applicationDidOpenURL:url]) {
         return YES;
       }
     }
     BOOL result = [RCTLinkingManager application:application continueUserActivity:userActivity restorationHandler:restorationHandler];
     return [super application:application continueUserActivity:userActivity restorationHandler:restorationHandler] || result;
   }
   ```

If your `Podfile` has `use_frameworks!`, import the redirect component using underscores (**\_**) instead of hyphens(**-**):

```js
#import <adyen_react_native/ADYRedirectComponent.h>
```

### Tab: Android

1. Provide your checkout [activity](https://developer.android.com/guide/components/activities/intro-activities) to `AdyenCheckout`.

   **Provide checkout activity to AdyenCheckout**

   ```kotlin
   @Override
   protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       AdyenCheckout.setLauncherActivity(this);
   }
   ```

2. To enable standalone redirect components, return the URL handler to your Checkout activity `onNewIntent`.

   **Return URL handler to onNewIntent**

   ```kotlin
   @Override
   public void onNewIntent(Intent intent) {
        super.onNewIntent(intent);
        AdyenCheckout.handle(intent);
   }
   ```

### Tab: Expo

The library is not compatible with ExpoGo and is only available with the Expo managed workflow.

1. Add the Adyen React Native plugin to your `app.json`.

   **Add Adyen React Native**

   ```js
   {
     "expo": {
       "plugins": ["@adyen/react-native"]
     }
   }
   ```

### Create A Configuration Object

### 3. Create a configuration object

Create a configuration object with the following properties:

| Parameter     | Required                                                                                                      | Description                                                                                                                                                                                                                                        |
| ------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `environment` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Use **test**. When you're ready to accept live payments, change the value to one of our [live environments](/online-payments//online-payments/build-your-integration/sessions-flow?platform=React%2BNative\&integration=Drop-in#test-and-go-live). |
| `clientKey`   | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | A public key linked to your API credential, used for [client-side authentication](/development-resources/client-side-authentication).                                                                                                              |

For example:

**Create a configuration object**

```js
import { Configuration } from '@adyen/react-native';

const configuration: Configuration = {
  environment: 'test', // When you're ready to accept real payments, change the value to a suitable live environment.
  clientKey: '{YOUR_CLIENT_KEY}',
};
```

To add configuration for specific payment methods, add these in a payment method specific configuration object. For example, for Apple Pay:[]()

**Add configuration for Apple Pay**

```js
import { Configuration } from '@adyen/react-native';

const configuration: Configuration = {
  environment: 'test', // When you're ready to accept real payments, change the value to a suitable live environment.
  clientKey: 'YOUR_CLIENT_KEY',
  applepay: {
    merchantID: 'APPLE_PAY_MERCHANT_ID',
    merchantName: 'APPLE_PAY_MERCHANT_NAME'
  }
};
```

#### Optional configuration

Optionally, you can configure the following properties for Drop-in.

| Parameter                            | Description                                                                                                                         |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `showPreselectedStoredPaymentMethod` | When enabled, shows the preselected stored payment method view. Defaults to **true**.                                               |
| `skipListWhenSinglePaymentMethod`    | Set to **true** to skip the payment methods list step when only one non-instant payment method is available. Defaults to **false**. |
| `title` Only for iOS                 | Set a custom title for the pre-selected stored payment view. By default, the app's name is used.                                    |
| `showRemovePaymentMethodButton`      | Allows the shopper to remove a stored payment method. Defaults to **false**.                                                        |

For example:

**Add optional configuration for Drop-in**

```js
import { Configuration } from '@adyen/react-native';

const configuration: Configuration = {
    environment: 'test', // When you're ready to accept real payments, change the value to a suitable live environment.
    clientKey: 'YOUR_CLIENT_KEY',
    dropin: {
        skipListWhenSinglePaymentMethod: true,
        showPreselectedStoredPaymentMethod: false
    }
};
```

### Initialize

### 4. Initialize Drop-in

Configure `AdyenCheckout`, setting the following:

| Parameter    | Required                                                                                                      | Description                                                                                                         |
| ------------ | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `config`     | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your [configuration object](#configure).                                                                            |
| `session`    | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The full response from the [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) endpoint. |
| `onComplete` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Calls the `onComplete` function for returning the result code when the payment flow is complete.                    |
| `onError`    | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Calls the `onError` function for returning errors.                                                                  |

In your `onComplete` and `onError` callbacks, you must call `component.hide(result)` to dismiss the payment UI when the API request is completed and the payment result is known.

**Configure AdyenCheckout**

```js
import { AdyenCheckout } from '@adyen/react-native';
import { useCallback } from 'react';

  const onComplete = useCallback( (result, nativeComponent ) => {
    // When this callback is executed, you must call `component.hide(true | false)` to dismiss the payment UI.
  }, [some, dependency]);
  const onError = useCallback( (error, component) => {
    // Handle errors or termination by shopper.
    // When this callback is executed, you must now call `component.hide(false)` to dismiss the payment UI.
  }, []);

<AdyenCheckout
  config={configuration}
  session={session}
  onComplete={onComplete}
  onError={onError}
>
  <MyCheckoutView />
</AdyenCheckout>;
```

### 5. Show Drop-in in your app

1. Set `AdyenCheckout` as the [context](https://reactjs.org/docs/context.html) for your [`View` ](https://reactnative.dev/docs/view).
2. Create a way, like a button, for `AdyenCheckout` to call the `start` function.

For example:

**Create a way to start Drop-in**

```js
// Import useAdyenCheckout.
import { useAdyenCheckout } from '@adyen/react-native';

// Set your View to use AdyenCheckout as the context.
const YourCheckoutView = () => {
    const { start } = useAdyenCheckout();

    return (
    // Create a way, like a checkout button, that starts Drop-in.
        <Button
            title="Checkout"
            // Use dropIn to show the full list of available payment methods.
            onPress={() => { start('dropIn'); }} />
    );
};
```

The context starts Adyen's [Native Component](https://reactnative.dev/docs/intro-react-native-components#native-components) for Drop-in.

### Handle Result

### 6. Handle the result

When the payment flow is completed, you get a result object from the `onComplete` callback.

The [`resultCode` ](/online-payments/build-your-integration/payment-result-codes#final-payment-status)indicates the [payment status](/account/payments-lifecycle/).

### Errors

If an error occurs during the payment flow, your `AdyenCheckout` calls the `onError` method. You get an error object with one of the following error codes:

| Error code                | Description                                                   | Action to take                                                                |
| ------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| **canceledByShopper**     | The shopper canceled the payment.                             | Take the shopper back to the checkout page.                                   |
| **notSupported**          | The payment method isn't supported by the shopper's device.   | Tell the shopper that the payment method isn't supported by their device.     |
| **noClientKey**           | No `clientKey` configured.                                    | Tell the shopper that an error occurred.                                      |
| **noPayment**             | No `payment` information configured.                          | Tell the shopper that an error occurred.                                      |
| **invalidPaymentMethods** | Cannot parse the `paymentMethods` list, or the list is empty. | Tell the shopper that an error occurred.                                      |
| **invalidAction**         | Cannot parse the action.                                      | Tell the shopper that an error occurred.                                      |
| **noPaymentMethod**       | Cannot find the selected payment method.                      | Tell the shopper that their selected payment method is currently unavailable. |
| **sessionError**          | An error occurred while creating a new session.               | Tell the shopper that an error occurred.                                      |

### Show Payment Result

## Get the payment outcome

After Drop-in finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.

### Inform the shopper

Client app

Use the [`resultCode` ](/online-payments/payment-result-codes#final-payment-status)to show the shopper the [current payment status](/account/payments-lifecycle). 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](#update-your-order-management-system).

**

### Optional: Get the result of the payment session on your server

Payment server

You can also get the result of the payment session on your server.

1. Get the `id` from the [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) response.

2. Get `sessionResult` from the `onPaymentCompleted` event.

3. Make a **GET** `/sessions/{id}?sessionResult={sessionResult}` request including the `id` and `sessionResult`. For example:

   **Request for result of payment session**

   ```bash
   curl -X GET https://checkout-test.adyen.com/v70/sessions/CS12345678?sessionResult=SOME_DATA
   ```

   The response includes the result of the payment session (`status`). For example:

   **Response with result of the payment session**

   ```bash
   {
      "id": "CS12345678",
      "status": "completed"
   }
   ```

   Possible statuses:

   | `status`           | Description                                                                                                                      |
   | ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
   | **completed**      | The shopper completed the payment. This means that the payment was authorized.                                                   |
   | **paymentPending** | The shopper is in the process of making the payment. This applies to payment methods with an asynchronous flow.                  |
   | **canceled**       | The shopper canceled the payment.                                                                                                |
   | **expired**        | The session expired (default: 1 hour after session creation). Shoppers can no longer complete the payment with this `sessionId`. |

The `status` included in the response doesn't get updated. Do not make the request again to check for payment status updates. Instead, check webhooks or the **Transactions** list in your [Customer Area](https://ca-test.adyen.com/).

### Update your order management system

Webhook server

You get the outcome of each payment asynchronously, in an **AUTHORISATION** [webhook](/development-resources/webhooks). Use the `merchantReference` from the webhook to match it to your order reference.\
For a successful payment, the event contains `success`: **true**.

**Example webhook for a successful payment**

```json
{
  "live": "false",
  "notificationItems":[
    {
      "NotificationRequestItem":{
        "eventCode":"AUTHORISATION",
        "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
        "reason":"033899:1111:03/2030",
        "amount":{
          "currency":"EUR",
          "value":2500
        },
        "operations":["CANCEL","CAPTURE","REFUND"],
        "success":"true",
        "paymentMethod":"mc",
        "additionalData":{
          "expiryDate":"03/2030",
          "authCode":"033899",
          "cardBin":"411111",
          "cardSummary":"1111",
          "checkoutSessionId":"CSF46729982237A879"
        },
        "merchantReference":"YOUR_REFERENCE",
        "pspReference":"NC6HT9CRT65ZGN82",
        "eventDate":"2021-09-13T14:10:22+02:00"
      }
    }
  ]
}
```

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

**Example webhook for an unsuccessful payment**

```json
{
  "live": "false",
  "notificationItems":[
    {
      "NotificationRequestItem":{
        "eventCode":"AUTHORISATION",
        "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
        "reason":"validation 101 Invalid card number",
        "amount":{
          "currency":"EUR",
          "value":2500
        },
        "success":"false",
        "paymentMethod":"unknowncard",
        "additionalData":{
          "expiryDate":"03/2030",
          "cardBin":"411111",
          "cardSummary":"1112",
          "checkoutSessionId":"861631540104159H"
        },
        "merchantReference":"YOUR_REFERENCE",
        "pspReference":"KHQC5N7G84BLNK43",
        "eventDate":"2021-09-13T14:14:05+02:00"
      }
    }
  ]
}
```

## Test and go live

Before going live, use our list of [test cards and other payment methods](/development-resources/test-cards-and-credentials/test-card-numbers) to [test your integration](/development-resources/testing). 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](https://ca-test.adyen.com/), under **Transactions** > **Payments**.

To debug or troubleshoot test payments, you can also use [API logs](/development-resources/logs-resources/api-logs) in your test environment.

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

1. [Apply for a live account](/get-started-with-adyen/application-requirements). Review the process to start accepting payments on [Get started with Adyen](/get-started-with-adyen).

2. Assess your [PCI DSS compliance](/development-resources/pci-dss-compliance-guide#online-payments) by submitting the [Self-Assessment Questionnaire-A](https://www.pcisecuritystandards.org/documents/PCI-DSS-v3_2_1-SAQ-A.pdf).

3. [Configure your live account](/online-payments/go-live-checklist). 

4. Submit a request to add payment methods in your [live Customer Area](https://ca-live.adyen.com/) .

5. Switch from test to our [live endpoints](/development-resources/live-endpoints#checkout-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, for example, when authenticating with 3D Secure 2.

6. Load Drop-in from one of our live environments and set the `environment` to match your live endpoints:

   | 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**  |

## Next steps

[required](/online-payments/modify-payments)

[Modify payments](/online-payments/modify-payments)

[Find out how to cancel, refund, or capture a payment using our API.](/online-payments/modify-payments)

[Add payment methods](/payment-methods/add-payment-methods)

[Learn about payment methods and how to add them to your account.](/payment-methods/add-payment-methods)

[Tokenization](/online-payments/tokenization)

[Save shopper payment details for later payments.](/online-payments/tokenization)

[3D Secure authentication](/online-payments/3d-secure)

[Comply with regulations such as PSD2 SCA in Europe.](/online-payments/3d-secure)

## Flutter Drop-in

Use our pre-built UI for accepting payments

### Intro

Drop-in is our pre-built UI solution for accepting payments in your app. Drop-in shows all payment methods as a list, in the same block. Your server makes one API request to the [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) endpoint.

### Before You Begin

## Requirements

Before you begin to integrate, make sure you have followed the [Get started with Adyen guide](/get-started-with-adyen) 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](/development-resources/api-credentials#generate-api-key).
* [Get your client key](/development-resources/client-side-authentication#get-your-client-key).
* [Set up webhooks](/development-resources/webhooks) to know the payment outcome.

Required versions:

* [iOS 12](https://support.apple.com/en-us/118387) or later.
* [Android 5.0](https://www.android.com/versions/lollipop-5-0/) or later.
* [Kotlin 1.8](https://kotlinlang.org/docs/whatsnew18.html) or later.
* Gradle v8 or later.

## How it works

For a Drop-in integration, you must implement the following parts:

* **Your payment server**: sends the API request to create a payment session.
* **Your client app**: shows the Drop-in UI where the shopper makes the payment. Drop-in 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:

1. The shopper goes to the checkout page.
2. Your server uses the shopper's country and currency information from your client to create a payment session.
3. Your client creates an instance of Drop-in using the session data from the server.
4. Drop-in shows the available payment methods, collects the shopper's payment details, handles additional actions, and presents the payment result to the shopper.
5. Your webhook server receives the notification containing the payment outcome.

![](/user/pages/filters/sessions-flow-integration/flutter/1-0-0/02.how-it-works/drop-in-sessions.svg?decoding=auto\&fetchpriority=auto)

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

[![](/user/pages/reuse/online-payments/how-it-works-parts/servers.svg?decoding=auto\&fetchpriority=auto)](/#install-api-library)

[Payment server](/#install-api-library)

[Go to the integration steps for your server.](/#install-api-library)

[![](/user/pages/reuse/online-payments/how-it-works-parts/browser-developers.svg?decoding=auto\&fetchpriority=auto)](/#add)

[Client](/#add)

[Go to the integration steps for your client app.](/#add)

[![](/user/pages/reuse/online-payments/how-it-works-parts/event-code.svg?decoding=auto\&fetchpriority=auto)](/#update-your-order-management-system)

[Webhook server](/#update-your-order-management-system)

[Go to the integration steps for your webhook server.](/#update-your-order-management-system)

### Install Api Library

## 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.

### Tab: Java

##### Try our example integration

![](/reuse/development-resources/install-api-library/java/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-java-spring-online-payments#checkout-example).\
![](/reuse/development-resources/install-api-library/java/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-java-spring-online-payments).

#### Requirements

* Java 11 or later.

#### Installation

You can use [Maven](https://maven.apache.org), adding this dependency to your project's POM.

**Add the API library**

```xml
<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](https://github.com/Adyen/adyen-java-api-library/releases).

#### Setting up the client

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

**Set up your client**

```java
// 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);
    }
}
```

### Tab: PHP

##### Try our example integration

![](/reuse/development-resources/install-api-library/php/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-php-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/php/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-php-online-payments).

#### 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](https://getcomposer.org/). Follow the [installation instructions](https://getcomposer.org/doc/00-intro.md) if you do not already have composer installed.

**Install the API library**

```bash
composer require adyen/php-api-library
```

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

**Include the autoloader**

```php
require __DIR__ . '/vendor/autoload.php';
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-php-api-library/releases).

#### Set up the client

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

**Set up your client**

```php
use Adyen\Model\Checkout\Amount;
use Adyen\Model\Checkout\CreateCheckoutSessionRequest;
use Adyen\Service\Checkout\PaymentsApi;

// Include your idempotency key when you make an API request.
$requestOptions['idempotencyKey'] = "YOUR_IDEMPOTENCY_KEY";

// Set up the client and service.
$client = new \Adyen\Client();
$client->setXApiKey('ADYEN_API_KEY');
$client->setEnvironment(\Adyen\Environment::TEST);

$service = new PaymentsApi($client);
```

### Tab: C\#

#### 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](https://www.nuget.org/packages/Adyen/):

**Install the API library**

```bash
PM> Install-Package Adyen -Version LATEST_VERSION
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-dotnet-api-library).

#### Set up the client

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

**Set up your client**

```cs
using Adyen;
using Adyen.Model.Checkout;
using Adyen.Service.Checkout;
using Environment = Adyen.Model.Environment;

class Program
{
    static void Main()
    {
        // Set up the client and service.
        var config = new Config
        {
            XApiKey = "ADYEN_API_KEY",
            Environment = Environment.Test
        };
        var client = new Client(config);
        var checkout = new PaymentsService(client);

        // Include your idempotency key when you make an API request.
        var requestOptions = new Adyen.Model.RequestOptions { IdempotencyKey = "YOUR_IDEMPOTENCY_KEY" };
    }
}
```

### Tab: NodeJS

##### Try our example integration

![](/reuse/development-resources/install-api-library/node-js/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-node-online-payments#checkout-example).\
![](/reuse/development-resources/install-api-library/node-js/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-node-online-payments).

#### Requirements

* Node.js version 18 or later.

#### Installation

You can use [npm](https://www.npmjs.com/):

**Install the API library**

```bash
npm install --save @adyen/api-library
npm update @adyen/api-library
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-node-api-library/releases).

#### Setting up the client

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

**Set up your client**

```js
// Require the parts of the module you want to use.
const { Client, CheckoutAPI, Types} = require("@adyen/api-library");

// Set up the client and service.
const client = new Client({ apiKey: "ADYEN_API_KEY", environment: "TEST" });
const checkoutApi = new CheckoutAPI(client);

// Include your idempotency key when you make an API request.
const requestOptions = { idempotencyKey: "YOUR_IDEMPOTENCY_KEY" };
```

### Tab: Go

##### Try our example integration

![](/reuse/development-resources/install-api-library/go/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-golang-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/go/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-golang-online-payments).

#### Requirements

* Go 1.13 or later.

#### Installation

You can use [Go modules](https://github.com/golang/go/wiki/Modules):

**Install the API library**

```shell
go get github.com/adyen/adyen-go-api-library/vLATEST_VERSION
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-go-api-library).

#### Set up the client

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

**Set up your client**

```go
package main

import (
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/adyen"
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/checkout"
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/common"
)

// Create a payment object.

func main () {
	client := adyen.NewClient(&common.Config{
		ApiKey: "ADYEN_API_KEY",
		Environment: common.TestEnv,
	})
	service := client.Checkout()
```

### Tab: Python

##### Try our example integration

![](/reuse/development-resources/install-api-library/python/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-python-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/python/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-python-online-payments).

#### Requirements

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

#### Installation

You can use [pip](https://pip.pypa.io/en/stable/):

**Install the API library**

```py
pip install Adyen
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-python-api-library).

#### Set up the client

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

**Set up your client**

```py
import Adyen

# Set up the client and service.
adyen = Adyen.Adyen()
adyen.client.xapikey = "ADYEN_API_KEY"
adyen.client.platform = "test" # The environment that the library is used in.
```

### Tab: Ruby

##### Try our example integration

![](/reuse/development-resources/install-api-library/ruby/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-rails-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/ruby/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-rails-online-payments).

#### Requirements

* Ruby 2.7 or later.

#### Installation

You can use [RubyGems](https://rubygems.org/):

**Install the API library**

```bash
gem install adyen-ruby-api-library
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-ruby-api-library/releases).

Run `bundle install` to install dependencies.

#### Set up the client

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

**Set up your client**

```ruby
require 'adyen-ruby-api-library'

# Set up the client and service.
adyen = Adyen::Client.new
adyen.api_key = 'ADYEN_API_KEY'
adyen.env = :test # The environment that the library is used in.
```

## 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](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) request, including:

| Parameter name                                                       | Required                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `merchantAccount`                                                    | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your merchant account name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `amount`                                                             | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The `currency` and `value` of the payment, in [minor units](/development-resources/currency-codes). This is used to filter the list of available payment methods to your shopper.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `returnUrl`                                                          | ![Required](/user/pages/reuse/image-library/01.icons/required/required.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. |
| `reference`                                                          | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | 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](https://en.wikipedia.org/wiki/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**. Drop-in 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](/risk-management/configure-standard-risk-rules/required-risk-field-reference), 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](/risk-management/configure-standard-risk-rules/required-risk-field-reference).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [`applicationInfo`](/development-resources/building-adyen-solutions) |                                                                                                               | 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](/development-resources/building-adyen-solutions).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

**Example request to create a session for a 10 EUR payment with iOS**

#### curl

```bash
curl https://checkout-test.adyen.com/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"
}'
```

#### Java

```java
// Adyen Java API Library v27.0.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, additionally include your liveEndpointUrlPrefix.
Client client = new Client("ADYEN_API_KEY", Environment.TEST);

// Create the request object(s)
Amount amount = new Amount()
  .currency("EUR")
  .value(1000L);

CreateCheckoutSessionRequest createCheckoutSessionRequest = new CreateCheckoutSessionRequest()
  .reference("YOUR_PAYMENT_REFERENCE")
  .amount(amount)
  .merchantAccount("YOUR_MERCHANT_ACCOUNT")
  .countryCode("NL")
  .returnUrl("my-app://adyen");

// Send the request
PaymentsApi service = new PaymentsApi(client);
CreateCheckoutSessionResponse response = service.sessions(createCheckoutSessionRequest, new RequestOptions().idempotencyKey("UUID"));
```

#### PHP

```php
// Adyen PHP API Library v19.0.0
use Adyen\Client;
use Adyen\Environment;
use Adyen\Model\Checkout\Amount;
use Adyen\Model\Checkout\CreateCheckoutSessionRequest;
use Adyen\Service\Checkout\PaymentsApi;

$client = new Client();
$client->setXApiKey("ADYEN_API_KEY");
// For the live environment, additionally include your liveEndpointUrlPrefix.
$client->setEnvironment(Environment::TEST);


// Create the request object(s)
$amount = new Amount();
$amount
  ->setCurrency("EUR")
  ->setValue(1000);

$createCheckoutSessionRequest = new CreateCheckoutSessionRequest();
$createCheckoutSessionRequest
  ->setReference("YOUR_PAYMENT_REFERENCE")
  ->setAmount($amount)
  ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT")
  ->setCountryCode("NL")
  ->setReturnUrl("my-app://adyen");

$requestOptions['idempotencyKey'] = 'UUID';

// Send the request
$service = new PaymentsApi($client);
$response = $service->sessions($createCheckoutSessionRequest, $requestOptions);
```

#### C\#

```cs
// Adyen .net API Library v17.0.0
using Adyen;
using Environment = Adyen.Model.Environment;
using Adyen.Model;
using Adyen.Model.Checkout;
using Adyen.Service.Checkout;

// For the live environment, additionally include your liveEndpointUrlPrefix.
var config = new Config()
{
    XApiKey = "ADYEN_API_KEY",
    Environment = Environment.Test
};
var client = new Client(config);

// Create the request object(s)
Amount amount = new Amount
{
  Currency = "EUR",
  Value = 1000
};

CreateCheckoutSessionRequest createCheckoutSessionRequest = new CreateCheckoutSessionRequest
{
  Reference = "YOUR_PAYMENT_REFERENCE",
  Amount = amount,
  MerchantAccount = "YOUR_MERCHANT_ACCOUNT",
  CountryCode = "NL",
  ReturnUrl = "my-app://adyen"
};

// Send the request
var service = new PaymentsService(client);
var response = service.Sessions(createCheckoutSessionRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"});
```

#### NodeJS (JavaScript)

```js
// Adyen Node API Library v18.0.0
// Require the parts of the module you want to use
const { Client, CheckoutAPI } = require('@adyen/api-library');
// Initialize the client object
// For the live environment, additionally include your liveEndpointUrlPrefix.
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object(s)
const createCheckoutSessionRequest = {
  merchantAccount: "YOUR_MERCHANT_ACCOUNT",
  amount: {
    value: 1000,
    currency: "EUR"
  },
  returnUrl: "my-app://adyen",
  reference: "YOUR_PAYMENT_REFERENCE",
  countryCode: "NL"
}

// Send the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.sessions(createCheckoutSessionRequest, { idempotencyKey: "UUID" });
```

#### Go

```go
// Adyen Go API Library v10.4.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, additionally include your liveEndpointUrlPrefix.
client := adyen.NewClient(&common.Config{
  ApiKey:      "ADYEN_API_KEY",
  Environment: common.TestEnv,
})

// Create the request object(s)
amount := checkout.Amount{
  Currency: "EUR",
  Value: 1000,
}

createCheckoutSessionRequest := checkout.CreateCheckoutSessionRequest{
  Reference: "YOUR_PAYMENT_REFERENCE",
  Amount: amount,
  MerchantAccount: "YOUR_MERCHANT_ACCOUNT",
  CountryCode: common.PtrString("NL"),
  ReturnUrl: "my-app://adyen",
}

// Send the request
service := client.Checkout()
req := service.PaymentsApi.SessionsInput().IdempotencyKey("UUID").CreateCheckoutSessionRequest(createCheckoutSessionRequest)
res, httpRes, err := service.PaymentsApi.Sessions(context.Background(), req)
```

#### Python

```py
# Adyen Python API Library v12.5.1
import Adyen

adyen = Adyen.Adyen()
adyen.client.xapikey = "ADYEN_API_KEY"
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.client.platform = "test" # The environment to use library in.

# Create the request object(s)
json_request = {
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "amount": {
    "value": 1000,
    "currency": "EUR"
  },
  "returnUrl": "my-app://adyen",
  "reference": "YOUR_PAYMENT_REFERENCE",
  "countryCode": "NL"
}

# Send the request
result = adyen.checkout.payments_api.sessions(request=json_request, idempotency_key="UUID")
```

#### Ruby

```rb
# Adyen Ruby API Library v9.5.1
require "adyen-ruby-api-library"

adyen = Adyen::Client.new
adyen.api_key = 'ADYEN_API_KEY'
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.env = :test # Set to "live" for live environment

# Create the request object(s)
request_body = {
  :merchantAccount => 'YOUR_MERCHANT_ACCOUNT',
  :amount => {
    :value => 1000,
    :currency => 'EUR'
  },
  :returnUrl => 'my-app://adyen',
  :reference => 'YOUR_PAYMENT_REFERENCE',
  :countryCode => 'NL'
}

# Send the request
result = adyen.checkout.payments_api.sessions(request_body, headers: { 'Idempotency-Key' => 'UUID' })
```

#### NodeJS (TypeScript)

```ts
// Adyen Node API Library v18.0.0
// Require the parts of the module you want to use
import { Client, CheckoutAPI, Types } from "@adyen/api-library";
// Initialize the client object
// For the live environment, additionally include your liveEndpointUrlPrefix.
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object(s)
const amount: Types.checkout.Amount = {
  currency: "EUR",
  value: 1000
};

const createCheckoutSessionRequest: Types.checkout.CreateCheckoutSessionRequest = {
  reference: "YOUR_PAYMENT_REFERENCE",
  amount: amount,
  merchantAccount: "YOUR_MERCHANT_ACCOUNT",
  countryCode: "NL",
  returnUrl: "my-app://adyen"
};

// Send the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.sessions(createCheckoutSessionRequest, { idempotencyKey: "UUID" });
```

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**

```json
{
    "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](/development-resources/error-codes) to troubleshoot.

### Add Adyen To Your App

## Add Drop-in to your app

Client app

Add different configurations for iOS and Android, 'Drop-in', and some payment methods.

### 1. Add platform-specific configurations

### Tab: iOS

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

   **Add return URL handler**

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

2. In your app, add a [custom URL scheme](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app) that matches the `returnUrl` you use when [creating the payment session](#create-payment-session).

3. For voucher payment methods, add photo library usage descriptions to the `Info.plist` file.

4. For Apple Pay, do the following:

   * Complete the steps to [set up Apple Pay with your own certificate](/payment-methods/apple-pay/apple-pay-certificate/ios).
   * In your Runner target, add Apple Pay as a capability.
   * In your Runner target, enter your merchant ID.

### Tab: Android

Set your activity to inherit from `FlutterFragmentActivity`:

**Inherit from FlutterFragmentActivity**

```kotlin
import io.flutter.embedding.android.FlutterFragmentActivity

class MainActivity: FlutterFragmentActivity() {
   // ...
}
```

### Create A Configuration Object

### 2. Create a configuration object

Create a configuration object with the following properties:

| Parameter       | Required                                                                                                      | Description                                                                                                                                                                                                                                                               |
| --------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `environment`   | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Use **test**. When you are ready to accept live payments, change the value to one of our [live environments](#test-and-go-live).                                                                                                                                          |
| `clientKey`     | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | A public key linked to your API credential, used for [client-side authentication](/development-resources/client-side-authentication).                                                                                                                                     |
| `countryCode`   | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | 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](https://en.wikipedia.org/wiki/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](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) request, Drop-in uses that one. |
| `amount`        |                                                                                                               | The `currency` and `value` of the payment, in [minor units](/development-resources/currency-codes). This is used to filter the list of available payment methods to your shopper.                                                                                         |

For example:[]()

**Create a configuration object**

```js
final DropInConfiguration dropInConfiguration = DropInConfiguration(
  // 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.
  // Configuration for specific payment methods. For example, Apple Pay.
  applePayConfiguration: applePayConfiguration
);
```

To add configuration for specific payment methods, create an additional configuration object. For example, for Apple Pay:

**Create a configuration object**

```js
final ApplePayConfiguration applePayConfiguration = ApplePayConfiguration(
  merchantId: MERCHANT_ID,
  merchantName: MERCHANT_NAME,
);
```

### Optional configuration

| Parameter name                                | Description                                                                                                   |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `preselectedPaymentMethodTitle` Only for iOS. | When you have a preselected payment method, sets the title of the Drop-in overlay.                            |
| `paymentMethodNames`                          | If you want to use custom names when displaying payment methods, set the name to use for each payment method. |

**Add optional configuration**

```js
final DropInConfiguration dropInConfiguration = DropInConfiguration(
  // 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.
  // Configuration for specific payment methods. For example, Apple Pay.
  applePayConfiguration: applePayConfiguration
  // Optional Drop-in configuration.
  paymentMethodNames: {
      "scheme": "Credit Card",
  },
);
```

### Initialize

### 3. Initialize Drop-in

Call the `create` method, passing the following:

| Parameter       | Required                                                                                                      | Description                                                                                                                        |
| --------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `sessionId`     | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | `sessionResponse.id`: the `id` from the [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) response.   |
| `sessionData`   | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | `sessionData`: the `sessionData` from the [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) response. |
| `configuration` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The configuration object you created.                                                                                              |

**Call the create method**

```js
final SessionCheckout sessionCheckout = await AdyenCheckout.session.create(
   sessionId: sessionResponse.id,
   sessionData: sessionResponse.sessionData,
   configuration: dropInConfiguration,
);
```

### Show

### 4. Show Drop-in in your app

Call `startDropin` to show the Drop-in, passing the following:

| Parameter             | Required                                                                                                      | Description                           |
| --------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `dropInConfiguration` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The configuration object you created. |
| `checkout`            | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The `sessionCheckout` you created.    |

**Show Drop-in**

```js
final PaymentResult paymentResult =  await AdyenCheckout.session.startDropIn(
  dropInConfiguration: dropInConfiguration,
  checkout: sessionCheckout,
);
```

Drop-in handles the payment flow.

### 5. Dismiss Drop-in (optional)

Client app

You can optionally implement the method to dismiss Drop-in, if this is required for your app. For example, if you want to stop showing the Drop-in UI when the shopper abandons your payment page for an extended period of time.

Use the global `AdyenCheckout.sessions.stopDropIn();` method to dismiss Drop-in. If you do not implement this method, Drop-in is automatically dismissed when the payment flow ends.

If the shopper has been redirected to a third-party app, for example to authorize the payment on an issuer-hosted website, they can still complete the payment even after you dismiss the Drop-in UI.

### Handle Result

### 5. Handle the result

When the payment flow is completed, you get one of the following objects:

| Object                   | Description                                                                                     |
| ------------------------ | ----------------------------------------------------------------------------------------------- |
| `PaymentSessionFinished` | The payment was successfully submitted. Contains a `resultCode` with the status of the payment. |
| `PaymentCancelledByUser` | The payment was canceled by the user.                                                           |
| `PaymentError`           | The payment encountered an error.                                                               |

Handle the object and [inform the shopper](#inform-the-shopper).

### Get Payment Outcome

## Get the payment outcome

After Drop-in finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.

### Inform the shopper

Client app

Use the [`resultCode` ](/online-payments/payment-result-codes#final-payment-status)to show the shopper the [current payment status](/account/payments-lifecycle). 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](#update-your-order-management-system).

**

### Optional: Get the result of the payment session on your server

Payment server

You can also get the result of the payment session on your server.

1. Get the `id` from the [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) response.

2. Get `sessionResult` from the `onPaymentCompleted` event.

3. Make a **GET** `/sessions/{id}?sessionResult={sessionResult}` request including the `id` and `sessionResult`. For example:

   **Request for result of payment session**

   ```bash
   curl -X GET https://checkout-test.adyen.com/v71/sessions/CS12345678?sessionResult=SOME_DATA
   ```

   The response includes the result of the payment session (`status`). For example:

   **Response with result of the payment session**

   ```bash
   {
      "id": "CS12345678",
      "status": "completed"
   }
   ```

   Possible statuses:

   | `status`           | Description                                                                                                                      |
   | ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
   | **completed**      | The shopper completed the payment. This means that the payment was authorized.                                                   |
   | **paymentPending** | The shopper is in the process of making the payment. This applies to payment methods with an asynchronous flow.                  |
   | **canceled**       | The shopper canceled the payment.                                                                                                |
   | **expired**        | The session expired (default: 1 hour after session creation). Shoppers can no longer complete the payment with this `sessionId`. |

The `status` included in the response doesn't get updated. Do not make the request again to check for payment status updates. Instead, check webhooks or the **Transactions** list in your [Customer Area](https://ca-test.adyen.com/).

### Update your order management system

Webhook server

You get the outcome of each payment asynchronously, in an **AUTHORISATION** [webhook](/development-resources/webhooks). Use the `merchantReference` from the webhook to match it to your order reference.\
For a successful payment, the event contains `success`: **true**.

**Example webhook for a successful payment**

```json
{
  "live": "false",
  "notificationItems":[
    {
      "NotificationRequestItem":{
        "eventCode":"AUTHORISATION",
        "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
        "reason":"033899:1111:03/2030",
        "amount":{
          "currency":"EUR",
          "value":2500
        },
        "operations":["CANCEL","CAPTURE","REFUND"],
        "success":"true",
        "paymentMethod":"mc",
        "additionalData":{
          "expiryDate":"03/2030",
          "authCode":"033899",
          "cardBin":"411111",
          "cardSummary":"1111",
          "checkoutSessionId":"CSF46729982237A879"
        },
        "merchantReference":"YOUR_REFERENCE",
        "pspReference":"NC6HT9CRT65ZGN82",
        "eventDate":"2021-09-13T14:10:22+02:00"
      }
    }
  ]
}
```

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

**Example webhook for an unsuccessful payment**

```json
{
  "live": "false",
  "notificationItems":[
    {
      "NotificationRequestItem":{
        "eventCode":"AUTHORISATION",
        "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
        "reason":"validation 101 Invalid card number",
        "amount":{
          "currency":"EUR",
          "value":2500
        },
        "success":"false",
        "paymentMethod":"unknowncard",
        "additionalData":{
          "expiryDate":"03/2030",
          "cardBin":"411111",
          "cardSummary":"1112",
          "checkoutSessionId":"861631540104159H"
        },
        "merchantReference":"YOUR_REFERENCE",
        "pspReference":"KHQC5N7G84BLNK43",
        "eventDate":"2021-09-13T14:14:05+02:00"
      }
    }
  ]
}
```

## Test and go live

Before going live, use our list of [test cards and other payment methods](/development-resources/test-cards-and-credentials/test-card-numbers) to [test your integration](/development-resources/testing). 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](https://ca-test.adyen.com/), under **Transactions** > **Payments**.

To debug or troubleshoot test payments, you can also use [API logs](/development-resources/logs-resources/api-logs) in your test environment.

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

1. [Apply for a live account](/get-started-with-adyen/application-requirements). Review the process to start accepting payments on [Get started with Adyen](/get-started-with-adyen).

2. Assess your [PCI DSS compliance](/development-resources/pci-dss-compliance-guide#online-payments) by submitting the [Self-Assessment Questionnaire-A](https://www.pcisecuritystandards.org/documents/PCI-DSS-v3_2_1-SAQ-A.pdf).

3. [Configure your live account](/online-payments/go-live-checklist). 

4. Submit a request to add payment methods in your [live Customer Area](https://ca-live.adyen.com/) .

5. Switch from test to our [live endpoints](/development-resources/live-endpoints#checkout-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, for example, when authenticating with 3D Secure 2.

6. Load Drop-in from one of our live environments and set the `environment` to match your live endpoints:

   | 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**        |

## Next steps

[required](/online-payments/modify-payments)

[Modify payments](/online-payments/modify-payments)

[Find out how to cancel, refund, or capture a payment using our API.](/online-payments/modify-payments)

[Add payment methods](/payment-methods/add-payment-methods)

[Learn about payment methods and how to add them to your account.](/payment-methods/add-payment-methods)

[Tokenization](/online-payments/tokenization)

[Save shopper payment details for later payments.](/online-payments/tokenization)

[3D Secure authentication](/online-payments/3d-secure)

[Comply with regulations such as PSD2 SCA in Europe.](/online-payments/3d-secure)

## Flutter Components

Use our customizable UI components

### Intro

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](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) endpoint.

### Before You Begin

## Requirements

Before you begin to integrate, make sure you have followed the [Get started with Adyen guide](/get-started-with-adyen) 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](/development-resources/api-credentials#generate-api-key).
* [Get your client key](/development-resources/client-side-authentication#get-your-client-key).
* [Set up webhooks](/development-resources/webhooks) to know the payment outcome.

Required versions:

* [iOS 12](https://support.apple.com/en-us/118387) or later.
* [Android 5.0](https://www.android.com/versions/lollipop-5-0/) or later.
* [Kotlin 1.8](https://kotlinlang.org/docs/whatsnew18.html) 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:

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

![](/user/pages/filters/sessions-flow-integration/flutter/1-0-0/02.how-it-works/component-sessions.svg?decoding=auto\&fetchpriority=auto)

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

[![](/user/pages/reuse/online-payments/how-it-works-parts/servers.svg?decoding=auto\&fetchpriority=auto)](/#install-api-library)

[Payment server](/#install-api-library)

[Go to the integration steps for your server.](/#install-api-library)

[![](/user/pages/reuse/online-payments/how-it-works-parts/browser-developers.svg?decoding=auto\&fetchpriority=auto)](/#add)

[Client](/#add)

[Go to the integration steps for your client app.](/#add)

[![](/user/pages/reuse/online-payments/how-it-works-parts/event-code.svg?decoding=auto\&fetchpriority=auto)](/#update-your-order-management-system)

[Webhook server](/#update-your-order-management-system)

[Go to the integration steps for your webhook server.](/#update-your-order-management-system)

### Install Api Library

## 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.

### Tab: Java

##### Try our example integration

![](/reuse/development-resources/install-api-library/java/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-java-spring-online-payments#checkout-example).\
![](/reuse/development-resources/install-api-library/java/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-java-spring-online-payments).

#### Requirements

* Java 11 or later.

#### Installation

You can use [Maven](https://maven.apache.org), adding this dependency to your project's POM.

**Add the API library**

```xml
<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](https://github.com/Adyen/adyen-java-api-library/releases).

#### Setting up the client

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

**Set up your client**

```java
// 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);
    }
}
```

### Tab: PHP

##### Try our example integration

![](/reuse/development-resources/install-api-library/php/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-php-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/php/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-php-online-payments).

#### 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](https://getcomposer.org/). Follow the [installation instructions](https://getcomposer.org/doc/00-intro.md) if you do not already have composer installed.

**Install the API library**

```bash
composer require adyen/php-api-library
```

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

**Include the autoloader**

```php
require __DIR__ . '/vendor/autoload.php';
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-php-api-library/releases).

#### Set up the client

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

**Set up your client**

```php
use Adyen\Model\Checkout\Amount;
use Adyen\Model\Checkout\CreateCheckoutSessionRequest;
use Adyen\Service\Checkout\PaymentsApi;

// Include your idempotency key when you make an API request.
$requestOptions['idempotencyKey'] = "YOUR_IDEMPOTENCY_KEY";

// Set up the client and service.
$client = new \Adyen\Client();
$client->setXApiKey('ADYEN_API_KEY');
$client->setEnvironment(\Adyen\Environment::TEST);

$service = new PaymentsApi($client);
```

### Tab: C\#

#### 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](https://www.nuget.org/packages/Adyen/):

**Install the API library**

```bash
PM> Install-Package Adyen -Version LATEST_VERSION
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-dotnet-api-library).

#### Set up the client

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

**Set up your client**

```cs
using Adyen;
using Adyen.Model.Checkout;
using Adyen.Service.Checkout;
using Environment = Adyen.Model.Environment;

class Program
{
    static void Main()
    {
        // Set up the client and service.
        var config = new Config
        {
            XApiKey = "ADYEN_API_KEY",
            Environment = Environment.Test
        };
        var client = new Client(config);
        var checkout = new PaymentsService(client);

        // Include your idempotency key when you make an API request.
        var requestOptions = new Adyen.Model.RequestOptions { IdempotencyKey = "YOUR_IDEMPOTENCY_KEY" };
    }
}
```

### Tab: NodeJS

##### Try our example integration

![](/reuse/development-resources/install-api-library/node-js/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-node-online-payments#checkout-example).\
![](/reuse/development-resources/install-api-library/node-js/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-node-online-payments).

#### Requirements

* Node.js version 18 or later.

#### Installation

You can use [npm](https://www.npmjs.com/):

**Install the API library**

```bash
npm install --save @adyen/api-library
npm update @adyen/api-library
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-node-api-library/releases).

#### Setting up the client

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

**Set up your client**

```js
// Require the parts of the module you want to use.
const { Client, CheckoutAPI, Types} = require("@adyen/api-library");

// Set up the client and service.
const client = new Client({ apiKey: "ADYEN_API_KEY", environment: "TEST" });
const checkoutApi = new CheckoutAPI(client);

// Include your idempotency key when you make an API request.
const requestOptions = { idempotencyKey: "YOUR_IDEMPOTENCY_KEY" };
```

### Tab: Go

##### Try our example integration

![](/reuse/development-resources/install-api-library/go/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-golang-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/go/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-golang-online-payments).

#### Requirements

* Go 1.13 or later.

#### Installation

You can use [Go modules](https://github.com/golang/go/wiki/Modules):

**Install the API library**

```shell
go get github.com/adyen/adyen-go-api-library/vLATEST_VERSION
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-go-api-library).

#### Set up the client

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

**Set up your client**

```go
package main

import (
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/adyen"
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/checkout"
	"github.com/adyen/adyen-go-api-library/vLATEST_VERSION/src/common"
)

// Create a payment object.

func main () {
	client := adyen.NewClient(&common.Config{
		ApiKey: "ADYEN_API_KEY",
		Environment: common.TestEnv,
	})
	service := client.Checkout()
```

### Tab: Python

##### Try our example integration

![](/reuse/development-resources/install-api-library/python/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-python-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/python/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-python-online-payments).

#### Requirements

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

#### Installation

You can use [pip](https://pip.pypa.io/en/stable/):

**Install the API library**

```py
pip install Adyen
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-python-api-library).

#### Set up the client

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

**Set up your client**

```py
import Adyen

# Set up the client and service.
adyen = Adyen.Adyen()
adyen.client.xapikey = "ADYEN_API_KEY"
adyen.client.platform = "test" # The environment that the library is used in.
```

### Tab: Ruby

##### Try our example integration

![](/reuse/development-resources/install-api-library/ruby/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-rails-online-payments#run-this-integration-in-seconds-using-gitpod).\
![](/reuse/development-resources/install-api-library/ruby/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-rails-online-payments).

#### Requirements

* Ruby 2.7 or later.

#### Installation

You can use [RubyGems](https://rubygems.org/):

**Install the API library**

```bash
gem install adyen-ruby-api-library
```

Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-ruby-api-library/releases).

Run `bundle install` to install dependencies.

#### Set up the client

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

**Set up your client**

```ruby
require 'adyen-ruby-api-library'

# Set up the client and service.
adyen = Adyen::Client.new
adyen.api_key = 'ADYEN_API_KEY'
adyen.env = :test # The environment that the library is used in.
```

## 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](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) request, including:

| Parameter name                                                       | Required                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `merchantAccount`                                                    | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your merchant account name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `amount`                                                             | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The `currency` and `value` of the payment, in [minor units](/development-resources/currency-codes). This is used to filter the list of available payment methods to your shopper.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `returnUrl`                                                          | ![Required](/user/pages/reuse/image-library/01.icons/required/required.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. |
| `reference`                                                          | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | 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](https://en.wikipedia.org/wiki/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](/risk-management/configure-standard-risk-rules/required-risk-field-reference), 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](/risk-management/configure-standard-risk-rules/required-risk-field-reference).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| [`applicationInfo`](/development-resources/building-adyen-solutions) |                                                                                                               | 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](/development-resources/building-adyen-solutions).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

**Example request to create a session for a 10 EUR payment with iOS**

#### curl

```bash
curl https://checkout-test.adyen.com/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"
}'
```

#### Java

```java
// Adyen Java API Library v27.0.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, additionally include your liveEndpointUrlPrefix.
Client client = new Client("ADYEN_API_KEY", Environment.TEST);

// Create the request object(s)
Amount amount = new Amount()
  .currency("EUR")
  .value(1000L);

CreateCheckoutSessionRequest createCheckoutSessionRequest = new CreateCheckoutSessionRequest()
  .reference("YOUR_PAYMENT_REFERENCE")
  .amount(amount)
  .merchantAccount("YOUR_MERCHANT_ACCOUNT")
  .countryCode("NL")
  .returnUrl("my-app://adyen");

// Send the request
PaymentsApi service = new PaymentsApi(client);
CreateCheckoutSessionResponse response = service.sessions(createCheckoutSessionRequest, new RequestOptions().idempotencyKey("UUID"));
```

#### PHP

```php
// Adyen PHP API Library v19.0.0
use Adyen\Client;
use Adyen\Environment;
use Adyen\Model\Checkout\Amount;
use Adyen\Model\Checkout\CreateCheckoutSessionRequest;
use Adyen\Service\Checkout\PaymentsApi;

$client = new Client();
$client->setXApiKey("ADYEN_API_KEY");
// For the live environment, additionally include your liveEndpointUrlPrefix.
$client->setEnvironment(Environment::TEST);


// Create the request object(s)
$amount = new Amount();
$amount
  ->setCurrency("EUR")
  ->setValue(1000);

$createCheckoutSessionRequest = new CreateCheckoutSessionRequest();
$createCheckoutSessionRequest
  ->setReference("YOUR_PAYMENT_REFERENCE")
  ->setAmount($amount)
  ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT")
  ->setCountryCode("NL")
  ->setReturnUrl("my-app://adyen");

$requestOptions['idempotencyKey'] = 'UUID';

// Send the request
$service = new PaymentsApi($client);
$response = $service->sessions($createCheckoutSessionRequest, $requestOptions);
```

#### C\#

```cs
// Adyen .net API Library v17.0.0
using Adyen;
using Environment = Adyen.Model.Environment;
using Adyen.Model;
using Adyen.Model.Checkout;
using Adyen.Service.Checkout;

// For the live environment, additionally include your liveEndpointUrlPrefix.
var config = new Config()
{
    XApiKey = "ADYEN_API_KEY",
    Environment = Environment.Test
};
var client = new Client(config);

// Create the request object(s)
Amount amount = new Amount
{
  Currency = "EUR",
  Value = 1000
};

CreateCheckoutSessionRequest createCheckoutSessionRequest = new CreateCheckoutSessionRequest
{
  Reference = "YOUR_PAYMENT_REFERENCE",
  Amount = amount,
  MerchantAccount = "YOUR_MERCHANT_ACCOUNT",
  CountryCode = "NL",
  ReturnUrl = "my-app://adyen"
};

// Send the request
var service = new PaymentsService(client);
var response = service.Sessions(createCheckoutSessionRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"});
```

#### NodeJS (JavaScript)

```js
// Adyen Node API Library v18.0.0
// Require the parts of the module you want to use
const { Client, CheckoutAPI } = require('@adyen/api-library');
// Initialize the client object
// For the live environment, additionally include your liveEndpointUrlPrefix.
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object(s)
const createCheckoutSessionRequest = {
  merchantAccount: "YOUR_MERCHANT_ACCOUNT",
  amount: {
    value: 1000,
    currency: "EUR"
  },
  returnUrl: "my-app://adyen",
  reference: "YOUR_PAYMENT_REFERENCE",
  countryCode: "NL"
}

// Send the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.sessions(createCheckoutSessionRequest, { idempotencyKey: "UUID" });
```

#### Go

```go
// Adyen Go API Library v10.4.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, additionally include your liveEndpointUrlPrefix.
client := adyen.NewClient(&common.Config{
  ApiKey:      "ADYEN_API_KEY",
  Environment: common.TestEnv,
})

// Create the request object(s)
amount := checkout.Amount{
  Currency: "EUR",
  Value: 1000,
}

createCheckoutSessionRequest := checkout.CreateCheckoutSessionRequest{
  Reference: "YOUR_PAYMENT_REFERENCE",
  Amount: amount,
  MerchantAccount: "YOUR_MERCHANT_ACCOUNT",
  CountryCode: common.PtrString("NL"),
  ReturnUrl: "my-app://adyen",
}

// Send the request
service := client.Checkout()
req := service.PaymentsApi.SessionsInput().IdempotencyKey("UUID").CreateCheckoutSessionRequest(createCheckoutSessionRequest)
res, httpRes, err := service.PaymentsApi.Sessions(context.Background(), req)
```

#### Python

```py
# Adyen Python API Library v12.5.1
import Adyen

adyen = Adyen.Adyen()
adyen.client.xapikey = "ADYEN_API_KEY"
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.client.platform = "test" # The environment to use library in.

# Create the request object(s)
json_request = {
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "amount": {
    "value": 1000,
    "currency": "EUR"
  },
  "returnUrl": "my-app://adyen",
  "reference": "YOUR_PAYMENT_REFERENCE",
  "countryCode": "NL"
}

# Send the request
result = adyen.checkout.payments_api.sessions(request=json_request, idempotency_key="UUID")
```

#### Ruby

```rb
# Adyen Ruby API Library v9.5.1
require "adyen-ruby-api-library"

adyen = Adyen::Client.new
adyen.api_key = 'ADYEN_API_KEY'
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.env = :test # Set to "live" for live environment

# Create the request object(s)
request_body = {
  :merchantAccount => 'YOUR_MERCHANT_ACCOUNT',
  :amount => {
    :value => 1000,
    :currency => 'EUR'
  },
  :returnUrl => 'my-app://adyen',
  :reference => 'YOUR_PAYMENT_REFERENCE',
  :countryCode => 'NL'
}

# Send the request
result = adyen.checkout.payments_api.sessions(request_body, headers: { 'Idempotency-Key' => 'UUID' })
```

#### NodeJS (TypeScript)

```ts
// Adyen Node API Library v18.0.0
// Require the parts of the module you want to use
import { Client, CheckoutAPI, Types } from "@adyen/api-library";
// Initialize the client object
// For the live environment, additionally include your liveEndpointUrlPrefix.
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object(s)
const amount: Types.checkout.Amount = {
  currency: "EUR",
  value: 1000
};

const createCheckoutSessionRequest: Types.checkout.CreateCheckoutSessionRequest = {
  reference: "YOUR_PAYMENT_REFERENCE",
  amount: amount,
  merchantAccount: "YOUR_MERCHANT_ACCOUNT",
  countryCode: "NL",
  returnUrl: "my-app://adyen"
};

// Send the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.sessions(createCheckoutSessionRequest, { idempotencyKey: "UUID" });
```

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**

```json
{
    "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](/development-resources/error-codes) to troubleshoot.

### Add Adyen To Your App

## 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

### Tab: iOS

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

   **Add return URL handler**

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

2. In your app, add a [custom URL scheme](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app) that matches the return URL.

3. For Apple Pay, do the following:

   * Complete the steps to [set up Apple Pay with your own certificate](/payment-methods/apple-pay/apple-pay-certificate/ios).
   * In your Runner target, add Apple Pay as a capability.
   * In your Runner target, enter your merchant ID.

### Tab: Android

1. Set your activity to inherit from `FlutterFragmentActivity`:

   **Inherit from FlutterFragmentActivity**

   ```kotlin
   import io.flutter.embedding.android.FlutterFragmentActivity

   class MainActivity: FlutterFragmentActivity() {
       // ...
   }
   ```

2. Declare the intent filter in your `AndroidManifest.xml` file:

   **Configure your manifest file**

   ```xml
   <intent-filter>
     <action android:name="android.intent.action.VIEW" />
     <category android:name="android.intent.category.DEFAULT" />
     <category android:name="android.intent.category.BROWSABLE" />
     <data
         android:host="YOUR_APPLICATION_ID" <!-- For example: com.adyen.checkout.flutter.your-app -->
         android:path="YOUR_CUSTOM_PATH" <!-- For example: /adyenPayment -->
         android:scheme="adyencheckout" />
   </intent-filter>
   }
   ```

### Create A Configuration Object

### 2. Create a configuration object

Create a configuration object with the following properties:

| Parameter       | Required                                                                                                      | Description                                                                                                                                                                                                                                                                     |
| --------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `environment`   | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Use **test**. When you are ready to accept live payments, change the value to one of our [live environments](#test-and-go-live).                                                                                                                                                |
| `clientKey`     | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | A public key linked to your API credential, used for [client-side authentication](/development-resources/client-side-authentication).                                                                                                                                           |
| `countryCode`   | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | 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](https://en.wikipedia.org/wiki/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](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) request, the Component uses that one. |
| `amount`        |                                                                                                               | The `currency` and `value` of the payment, in [minor units](/development-resources/currency-codes). 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](https://github.com/Adyen/adyen-flutter/tree/main/lib/src/common/model/payment_method_configurations).

### Tab: InstantComponent

Create an `InstantComponentConfiguration` object:

**Create the configuration object**

```js
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.
);
```

### Tab: Other Component

The following example shows the configuration object for cards:

**Create a configuration object for the Card Component**

```js
final CardComponentConfiguration cardComponentConfiguration = CardComponentConfiguration(
  // 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.
);
```

### Initialize

### 3. Initialize Components

Call the `create` method, passing the following:

| Parameter       | Required                                                                                                      | Description                                                                                                                        |
| --------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `sessionId`     | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | `sessionResponse.id`: the `id` from the [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) response.   |
| `sessionData`   | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | `sessionData`: the `sessionData` from the [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) response. |
| `configuration` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The configuration object you created.                                                                                              |

**Call the create method**

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

### Show

### 4. Show Components in your app

Make sure that the selected payment method is available in your `sessionCheckout.paymentMethods` object.

1. From the list of payment methods, find the one you want to use and put it in an object of the type `Map<String, dynamic>`:

   **Find the payment method**

   ```js
   final Map<String, dynamic> paymentMethod =
     sessionCheckout.paymentMethods["paymentMethods"].firstWhere(
     (paymentMethod) => paymentMethod["type"] == "PAYMENT_METHOD_TYPE", // For example, paypal.
     orElse: () => throw Exception("Payment method not found"),
   );
   ```

   ### Tab: InstantComponent

   2. Call `startInstantComponent` to show the Component, passing the following:

   | Parameter       | Required                                                                                                      | Description                                                                                                                                                                   |
   | --------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | `configuration` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The configuration object you created.                                                                                                                                         |
   | `paymentMethod` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The payment method from the [/paymentMethods](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods) response, in an object of type `Map<String, dynamic>`. |
   | `checkout`      | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The `sessionCheckout` that you created.                                                                                                                                       |

   **Show the Component**

   ```js
   final PaymentResult paymentResult = await AdyenCheckout.advanced.startInstantComponent(
     configuration: instantComponentConfiguration,
     paymentMethod: paymentMethod,
     checkout: sessionCheckout,
   );
   ```

   ### Tab: Other Component

   2. Create the widget for your Component with the required parameters. For example, for the Card Component:

   | Parameter         | Required                                                                                                      | Description                                      |
   | ----------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
   | `configuration`   | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The configuration object you created.            |
   | `paymentMethod`   | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The `sessionCheckout` you created.               |
   | `checkout`        | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The `sessionCheckout` you created.               |
   | `onPaymentResult` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Create a handler for the `paymentResult` object. |

   **Show the Component**

   ```js
   AdyenCardComponent(
     configuration: cardComponentConfiguration,
     paymentMethod: paymentMethod,
     checkout: sessionCheckout,
     onPaymentResult: (paymentResult) async {
       // Handle the `paymentResult` that you get when the shopper completes the payment.
     },
   );
   ```

The Component handles the payment flow.

### Handle Result

### 5. Handle the result

When the payment flow is completed, you get one of the following objects:

| Object                   | Description                                                                                     |
| ------------------------ | ----------------------------------------------------------------------------------------------- |
| `PaymentSessionFinished` | The payment was successfully submitted. Contains a `resultCode` with the status of the payment. |
| `PaymentCancelledByUser` | The payment was canceled by the user.                                                           |
| `PaymentError`           | The payment encountered an error.                                                               |

Handle the object and [inform the shopper](#inform-the-shopper).

### Get Payment Outcome

## Get the payment outcome

After the Component finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.

### Inform the shopper

Client app

Use the [`resultCode`](/online-payments/payment-result-codes#final-payment-status) to show the shopper the [current payment status](/account/payments-lifecycle). 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](#update-your-order-management-system).

**

### Optional: Get the result of the payment session on your server

Payment server

You can also get the result of the payment session on your server.

1. Get the `id` from the [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) response.

2. Get `sessionResult` from the `onPaymentCompleted` event.

3. Make a **GET** `/sessions/{id}?sessionResult={sessionResult}` request including the `id` and `sessionResult`. For example:

   **Request for result of payment session**

   ```bash
   curl -X GET https://checkout-test.adyen.com/v71/sessions/CS12345678?sessionResult=SOME_DATA
   ```

   The response includes the result of the payment session (`status`). For example:

   **Response with result of the payment session**

   ```bash
   {
      "id": "CS12345678",
      "status": "completed"
   }
   ```

   Possible statuses:

   | `status`           | Description                                                                                                                      |
   | ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
   | **completed**      | The shopper completed the payment. This means that the payment was authorized.                                                   |
   | **paymentPending** | The shopper is in the process of making the payment. This applies to payment methods with an asynchronous flow.                  |
   | **canceled**       | The shopper canceled the payment.                                                                                                |
   | **expired**        | The session expired (default: 1 hour after session creation). Shoppers can no longer complete the payment with this `sessionId`. |

The `status` included in the response doesn't get updated. Do not make the request again to check for payment status updates. Instead, check webhooks or the **Transactions** list in your [Customer Area](https://ca-test.adyen.com/).

### Update your order management system

Webhook server

You get the outcome of each payment asynchronously, in an **AUTHORISATION** [webhook](/development-resources/webhooks). Use the `merchantReference` from the webhook to match it to your order reference.\
For a successful payment, the event contains `success`: **true**.

**Example webhook for a successful payment**

```json
{
  "live": "false",
  "notificationItems":[
    {
      "NotificationRequestItem":{
        "eventCode":"AUTHORISATION",
        "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
        "reason":"033899:1111:03/2030",
        "amount":{
          "currency":"EUR",
          "value":2500
        },
        "operations":["CANCEL","CAPTURE","REFUND"],
        "success":"true",
        "paymentMethod":"mc",
        "additionalData":{
          "expiryDate":"03/2030",
          "authCode":"033899",
          "cardBin":"411111",
          "cardSummary":"1111",
          "checkoutSessionId":"CSF46729982237A879"
        },
        "merchantReference":"YOUR_REFERENCE",
        "pspReference":"NC6HT9CRT65ZGN82",
        "eventDate":"2021-09-13T14:10:22+02:00"
      }
    }
  ]
}
```

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

**Example webhook for an unsuccessful payment**

```json
{
  "live": "false",
  "notificationItems":[
    {
      "NotificationRequestItem":{
        "eventCode":"AUTHORISATION",
        "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
        "reason":"validation 101 Invalid card number",
        "amount":{
          "currency":"EUR",
          "value":2500
        },
        "success":"false",
        "paymentMethod":"unknowncard",
        "additionalData":{
          "expiryDate":"03/2030",
          "cardBin":"411111",
          "cardSummary":"1112",
          "checkoutSessionId":"861631540104159H"
        },
        "merchantReference":"YOUR_REFERENCE",
        "pspReference":"KHQC5N7G84BLNK43",
        "eventDate":"2021-09-13T14:14:05+02:00"
      }
    }
  ]
}
```

## Test and go live

Before going live, use our list of [test cards and other payment methods](/development-resources/test-cards-and-credentials/test-card-numbers) to [test your integration](/development-resources/testing). 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](https://ca-test.adyen.com/), under **Transactions** > **Payments**.

To debug or troubleshoot test payments, you can also use [API logs](/development-resources/logs-resources/api-logs) in your test environment.

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

1. [Apply for a live account](/get-started-with-adyen/application-requirements). Review the process to start accepting payments on [Get started with Adyen](/get-started-with-adyen).

2. Assess your [PCI DSS compliance](/development-resources/pci-dss-compliance-guide#online-payments) by submitting the [Self-Assessment Questionnaire-A](https://www.pcisecuritystandards.org/documents/PCI-DSS-v3_2_1-SAQ-A.pdf).

3. [Configure your live account](/online-payments/go-live-checklist). 

4. Submit a request to add payment methods in your [live Customer Area](https://ca-live.adyen.com/) .

5. Switch from test to our [live endpoints](/development-resources/live-endpoints#checkout-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, for example, when authenticating with 3D Secure 2.

6. Load Components from one of our live environments and set the `environment` to match your live endpoints:

   | 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**        |

## Next steps

[required](/online-payments/modify-payments)

[Modify payments](/online-payments/modify-payments)

[Find out how to cancel, refund, or capture a payment using our API.](/online-payments/modify-payments)

[Add payment methods](/payment-methods/add-payment-methods)

[Learn about payment methods and how to add them to your account.](/payment-methods/add-payment-methods)

[Tokenization](/online-payments/tokenization)

[Save shopper payment details for later payments.](/online-payments/tokenization)

[3D Secure authentication](/online-payments/3d-secure)

[Comply with regulations such as PSD2 SCA in Europe.](/online-payments/3d-secure)

![](/user/pages/filters/sessions-flow-integration/web/dropin/visual/web-v6-drop-in.png) ![](/user/pages/filters/sessions-flow-integration/web/github/github-mark.png) ![](/user/pages/filters/advanced-flow-integration/web/components/visual/web-v6-components.png) ![](/user/pages/filters/advanced-flow-integration/web/github/github-mark.png) ![](/user/pages/filters/sessions-flow-integration/hosted-checkout/visual/hosted_checkout.png) ![](/user/pages/filters/sessions-flow-integration/ios/dropin/visual/ios-dropin.svg) ![](/user/pages/filters/sessions-flow-integration/ios/github/github-mark.png) ![](/user/pages/filters/sessions-flow-integration/ios/components/visual/ios-components.svg) ![](/user/pages/filters/sessions-flow-integration/ios/github/github-mark.png) ![](/user/pages/filters/sessions-flow-integration/android/dropin/visual/android-dropin.svg) ![](/user/pages/filters/sessions-flow-integration/android/github/github-mark.png) ![](/user/pages/filters/sessions-flow-integration/android/components/visual/android-components.svg) ![](/user/pages/filters/sessions-flow-integration/android/github/github-mark.png) ![](/user/pages/filters/sessions-flow-integration/react-native/dropin/visual/react-dropin.svg) ![](/user/pages/filters/sessions-flow-integration/react-native/github/github-mark.png) ![](/user/pages/filters/sessions-flow-integration/flutter/dropin/visual/flutter-dropin.svg) ![](/user/pages/filters/sessions-flow-integration/flutter/github/github-mark.png) ![](/user/pages/filters/sessions-flow-integration/flutter/components/visual/flutter-components.svg) ![](/user/pages/filters/sessions-flow-integration/flutter/github/github-mark.png)