Advanced flow integration guide

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 API requests to the /paymentMethods, /payments, and /payments/details endpoints.

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 Components integration, you must implement the following parts:

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

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 get available payment methods.
3. The Component collects the shopper's payment details, handles additional actions, and shows the payment result to the shopper.
4. Your webhook server receives the notification containing the payment outcome.

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

Get available payment methods

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

From your server, make a POST /paymentMethods request, providing the following parameters. While most parameters are optional, we recommend that you include them because Adyen uses these to tailor the list of payment methods for your shopper.

Parameter name	Required	Description
merchantAccount		Your merchant account name.
amount		The currency of the payment and its value in minor units.
channel		The platform where the payment is taking place. For example, when you set this to iOS, Adyen returns only the payment methods available for iOS.
countryCode		The shopper's country/region. Adyen returns only the payment methods available in this country. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).
shopperLocale		By default, the shopperlocale is set to en-US. To change the language, set this to the shopper's language and country code. The front end also uses this locale.

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

curl https://checkout-test.adyen.com/checkout/v70/paymentMethods \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
  "merchantAccount": "ADYEN_MERCHANT_ACCOUNT",
  "countryCode": "NL",
  "amount": {
    "currency": "EUR",
    "value": 1000
  },
  "channel": "Android",
  "shopperLocale": "nl-NL"
}'

The response includes the list of available paymentMethods:

{
 "paymentMethods":[
  {
    "details":[...],
    "name":"Cards",
    "type":"scheme"
    ...
  },
  {
    "details":[...],
    "name":"SEPA Direct Debit",
    "type":"sepadirectdebit"
  },
  ...
  ]
}

Pass the response to your client app. Use this in the next step to show available payment methods to the shopper.

Add Adyen Components to your app

1. Add Adyen React Native to your project

Copy code
$ 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.
returnUrl		For iOS, this is the URL to your app, where the shopper should return, after a redirection. Maximum of 1024 characters. For more information on setting a custom URL scheme for your app, read the Apple Developer documentation. For Android, this value is automatically overridden by AdyenCheckout.
countryCode	If you want to show the amount on the Pay button.	The shopper's country/region. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).
amount	If you want to show the amount on the Pay button.	The currency and value of the payment, in minor units.

For example:

const configuration = {
    // When you're ready to accept live payments, change the value to one of our live environments.
    environment: 'test',
    clientKey: 'YOUR_CLIENT_KEY',
    // For iOS, this is the URL to your app. For Android, this is automatically overridden by AdyenCheckout.
    returnUrl: 'your-app://',
    // Must be included to show the amount on the Pay button.
    countryCode: 'NL',
    amount: { currency: 'EUR', value: 1000 }
};

To add configuration for specific payment methods, add these in a payment method specific configuration object. For example, for Apple Pay:

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',
  returnUrl: 'your-app://',
  countryCode: 'NL',
  amount: {
      currency: 'EUR',
      value: 1000
  },
  applepay: {
    merchantID: 'APPLE_PAY_MERCHANT_ID',
    merchantName: 'APPLE_PAY_MERCHANT_NAME'
  }
};

4. Initialize Components

1. Configure AdyenCheckout, setting the following:

In your onSubmit, onAdditionalDetails, 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.

2. Set AdyenCheckout as the context for your View.

For example:

// Import AdyenCheckout.
import { AdyenCheckout } from '@adyen/react-native';
import { useCallback } from 'react';
 
const submitHandler = useCallback(
    (data, component, extra) => {
        // Make a /payments request.
        // When this callback is executed, you must call `component.hide(true | false)` to dismiss the payment UI.
    },
    [...],
);
 
const errorHandler = useCallback(
    (error, component) => {
        // Handle errors or termination by shopper.
        // When this callback is executed, you must call `component.hide(false)` to dismiss the payment UI.
    },
    [...],
);
 
const additionalDetailsHandler = useCallback(
    (data, component) => {
        // Make a /payments/details request.
        // When this callback is executed, you must call `component.hide(true | false)` to dismiss the payment UI.
    },
    [...],
);
 
<AdyenCheckout
    config={configuration}
    paymentMethods={paymentMethods}
    onSubmit={submitHandler}
    onError={errorHandler}
    onAdditionalDetails={additionalDetailsHandler}
>
    <YourCheckoutView/>
</AdyenCheckout>

3. Create a way, like a button, for AdyenCheckout to call the start function.

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 the Component.
        <Button
            title="Checkout"
            // The paymentMethod is the paymentMethod.type from the /paymentMethods response.
            onPress={() => { start('paymentMethod'); }} />
    );
};

The context starts Adyen's Native Component for the corresponding payment method.

Make a payment

When the shopper selects the Pay button or chooses to pay with a payment method that requires a redirection, the Native Component calls onSubmit, and you make a payment request to Adyen.

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

Parameter name	Required	Description
merchantAccount		Your merchant account name.
amount		The currency of the payment and its value in minor units.
reference		Your unique reference for this payment.
paymentMethod		The payment method from the payload of the onSubmit event from your client app.
returnUrl	For Android, this value is automatically overridden by AdyenCheckout.	For iOS, this is the URL to your app, where the shopper should return, after a redirection. Maximum of 1024 characters. For more information on setting a custom URL scheme for your app, read the Apple Developer documentation. 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.
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 make a payment request for EUR 10:

curl https://checkout-test.adyen.com/checkout/v70/payments \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
  "amount":{
    "currency":"EUR",
    "value":1000
  },
  "reference":"YOUR_ORDER_NUMBER",
  "paymentMethod":STATE_DATApaymentMethod field of an object passed from your client app,
  "returnUrl":"my-app://adyen",
  "merchantAccount":"ADYEN_MERCHANT_ACCOUNT"
}'

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

The following example shows the /payments response for iDEAL, a redirect payment method.

{
  "resultCode": "RedirectShopper",
  "action": {
    "paymentMethodType": "ideal",
    "url": "https://checkoutshopper-test.adyen.com/checkoutshopper/checkoutPaymentRedirect?redirectData=X6Xtf...",
    "method": "GET",
    "type": "redirect"
  }
}

Errors

If an error occurs, you get an error object from the onError callback with one of the following error codes:

Handle the additional action

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

To handle these additional front-end actions, the AdyenCheckout provides a handle function to perform the next step depending on the action.type.

Call handle from one of Adyen's Native Components and pass the action to. For example:

// Call the handle function from the Native Component corresponding to the payment method.
nativeComponent.handle(action)

Handle the redirect result

If you receive an action.type redirect, The Component redirects your shopper to another website to complete the payment.

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

GET /?shopperOrder=12xy..&&redirectResult=X6XtfGC3%21Y... HTTP/1.1
Host: your-app://checkout

1. URL-decode the redirectResult and pass it to your server.
2. Send additional payment details.

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

Send additional payment details

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

From your server, make a POST /payments/details request with the data from the didProvide method from your client app.

curl https://checkout-test.adyen.com/checkout/v70/payments/details \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d 'STATE_DATAobject passed from your client app'

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

The response includes:

• pspReference: Adyen's unique identifier for the transaction.
• resultCode: Indicates the current status of the payment.

{
  "pspReference": "NC6HT9CRT65ZGN82",
  "resultCode": "Authorised"
}

{
  "pspReference": "KHQC5N7G84BLNK43",
  "refusalReason": "Not enough balance",
  "resultCode": "Refused"
}

Get the payment outcome

After 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

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"
        },
        "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"
        },
        "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 Components from one of our live environments and set the environment to match your live endpoints:

Next steps