Sessions flow integration guide

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

React Native Drop-in v1, Components v1, and Components v2 only support Advanced flow integrations.

Requirements

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

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

After you have created your test account:

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

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.

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

Install an API library

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

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

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

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

Create a payment session

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 request, including:

Parameter name	Required	Description
merchantAccount		Your merchant account name.
amount		The currency and value of the payment, in minor units. This is used to filter the list of available payment methods to your shopper.
returnUrl	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. 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		Your unique reference for the payment. Minimum length: three characters.
expiresAt		The session expiry date in ISO8601 format, for example 2023-11-23T12:25:28Z, or 2023-05-27T20:25:28+08:00. When not specified, the expiry date is set to 1 hour after session creation. You cannot set the session expiry to more than 24 hours after session creation.
countryCode		The shopper's country/region. This is used to filter the list of available payment methods to your shopper. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).
channel		The platform where the payment is taking place. Use iOS or Android. Strongly recommended because this field is used for 3D Secure.
shopperLocale		The language that the payment methods will appear in. Set it to the shopper's language and country code. The default is en-US. The 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, and for 3D Secure.
shopperReference		Your reference to uniquely identify this shopper. Minimum length: three characters. Do not include personally identifiable information, for example name or email address. Strongly recommended because this field is used in a number of risk checks.
applicationInfo		If you are building an Adyen solution for multiple merchants, include some basic identifying information, so that we can offer you better support. For more information, refer to Building Adyen solutions.

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

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

The response contains:

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

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

API error handling

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

Add Adyen Drop-in to your app

1. Add Adyen React Native to your project

$ yarn add @adyen/react-native

2. Install

Copy code
#import <adyen_react_native/ADYRedirectComponent.h>

3. Create a configuration object

Create a configuration object with the following properties:

Parameter	Required	Description
environment		Use test. When you're ready to accept live payments, change the value to one of our live environments.
clientKey		A public key linked to your API credential, used for client-side authentication.

For example:

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:

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.

For example:

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
    }
};

4. Initialize Drop-in

Configure AdyenCheckout, setting the following:

Parameter	Required	Description
config		Your configuration object.
session		The full response from the /sessions endpoint.
onComplete		Calls the onComplete function for returning the result code when the payment flow is complete.
onError		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.

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 for your View .
2. Create a way, like a button, for AdyenCheckout to call the start function.

For example:

// 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 for Drop-in.

6. Handle the result

When the payment flow is completed, you get a result object from the onComplete callback.

The resultCode indicates the payment status.

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:

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

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

Update your order management system

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

{
  "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.

{
  "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 to test your integration. We recommend testing each payment method that you intend to offer to your shoppers.

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

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

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

1. Apply for a live account. Review the process to start accepting payments on Get started with Adyen.
2. Assess your PCI DSS compliance by submitting the Self-Assessment Questionnaire-A.
3. Configure your live account. 
4. Submit a request to add payment methods in your live Customer Area .
5. Switch from test to our live endpoints.

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

   Endpoint region	iOS	Android
   EU	liveEurope	EUROPE
   APSE	liveApse	APSE
   AU	liveAustralia	AUSTRALIA
   US	liveUnitedStates	UNITED_STATES
   IN	liveIndia	INDIA

Next steps