Default icon

Drop-in

Build your standard integration with Drop-in.

View source

Our pre-built Drop-in includes the UI and client-side logic to show available payment methods to your shopper, collect their payment information, and handle the complete payment flow.

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 Make sure that you have the following roles:
  • Merchant admin role
  • Manage API credentials
Adyen API credentials Make sure that you have created the following:
  • API credential
  • API key
  • Client key
Adyen API credential roles Make sure that you have the roles for payments that are assigned by default.
Webhooks Subscribe to the following webhooks:
  • standard webhook with default event codes
Limitations Make sure that your integration follows our recommended best practices:
  • <iframe>: an <iframe> must be hosted on the same domain as the parent window to support payment flows that use redirects.
  • WebViews: we do not recommend using WebViews in native apps due to security and functionality limitations. Use native equivalents instead.
  • Server-side Rendering (SSR): if you use SSR, ensure the AdyenCheckout instance and Drop-in are initialized on the client side.
  • Browser support: we support recent versions of all major browsers.
For 3D Secure 2:
  • A strict Content Security Policy (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.
  • Got an overview of what is required before you accept live payments.

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: Listens for webhook messages that include the outcome of each payment.

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 client website triggers a request to your payment server to create a payment session.
  3. Your server uses the shopper's country and currency information from your client to make a POST /sessions request to create a payment session. Adyen returns session data (session.id, session.sessionData).
  4. Your server passes the session data to your client website.
  5. Your client website creates an instance of AdyenCheckout using the session data, initializes Drop-in, and shows the payment UI to the shopper.
  6. The shopper selects the payment method, enters payment details, and submits the payment.
  7. Drop-in handles the payment flow and sends payment data. Adyen returns the result of the payment session to Drop-in.
  8. Your client website shows the result of the payment session to the shopper.
  9. Your webhook server receives a webhook message with the payment outcome.
CnNlcXVlbmNlRGlhZ3JhbQogICAgcGFydGljaXBhbnQgU2hvcHBlcgogICAgcGFydGljaXBhbnQgQ2xpZW50IGFzIFlvdXIgY2xpZW50IHdlYnNpdGUKICAgIHBhcnRpY2lwYW50IFNlcnZlciBhcyBZb3VyIHBheW1lbnQgc2VydmVyCiAgICBwYXJ0aWNpcGFudCBBZHllbgogICAgcGFydGljaXBhbnQgV2ViaG9vayBhcyBZb3VyIHdlYmhvb2sgc2VydmVyCgogICAgU2hvcHBlci0+PkNsaWVudDogMS4gR28gdG8gY2hlY2tvdXQgcGFnZQogICAgQ2xpZW50LT4+U2VydmVyOiAyLiBUcmlnZ2VyIHJlcXVlc3QgZm9yIHBheW1lbnQgc2Vzc2lvbgogICAgU2VydmVyLT4+QWR5ZW46IDMuIFJlcXVlc3QgdG8gY3JlYXRlIHBheW1lbnQgc2Vzc2lvbiAoUE9TVCAvc2Vzc2lvbnMpCiAgICBBZHllbi0tPj5TZXJ2ZXI6IFNlc3Npb24gZGF0YSAoc2Vzc2lvbi5pZCwgc2Vzc2lvbi5zZXNzaW9uRGF0YSkKICAgIFNlcnZlci0+PkNsaWVudDogNC4gUGFzcyBzZXNzaW9uIGRhdGEKICAgIENsaWVudC0+PkNsaWVudDogNS4gQ3JlYXRlIGluc3RhbmNlIG9mIGBBZHllbkNoZWNrb3V0YCBhbmQgaW5pdGlhbGl6ZSBEcm9wLWluCiAgICBDbGllbnQtPj5TaG9wcGVyOiBTaG93IHBheW1lbnQgVUkgdG8gc2hvcHBlcgogICAgU2hvcHBlci0+PkNsaWVudDogNi4gU3VibWl0IHRoZSBwYXltZW50CiAgICBDbGllbnQtPj5BZHllbjogNy4gRHJvcC1pbiBoYW5kbGVzIHRoZSBwYXltZW50IGZsb3cgYW5kIHNlbmRzIHBheW1lbnQgZGF0YQogICAgQWR5ZW4tLT4+Q2xpZW50OiBSZXN1bHQgb2YgdGhlIHBheW1lbnQgc2Vzc2lvbiB0byBEcm9wLWluCiAgICBDbGllbnQtPj5TaG9wcGVyOiA4LiBTaG93IHJlc3VsdCBvZiBwYXltZW50IHNlc3Npb24KICAgIEFkeWVuLT4+V2ViaG9vazogOS4gV2ViaG9vayBtZXNzYWdlIHdpdGggcGF5bWVudCBvdXRjb21lCg==

Implementation overview

This guide is organized by each part of the integration that you must implement:

Payment server

This section covers all the server-side implementation required for your Sessions flow integration. Complete these steps to set up your payment server.

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.

Create a 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:

Request headers:

Header Required Description
x-api-key Required Your Adyen API key for authentication.
idempotency-key Required A unique identifier for the request. This is used to prevent duplicate requests from being processed.
content-type Required The content type of the request. Set to application/json.

Request body:

Parameter name Required Description
merchantAccount Required Your merchant account name.
amount Required 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 Required 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 Your unique reference for the payment. Minimum length: three characters.
countryCode Required 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.
shopperEmail Required The shopper's email address. Strongly recommended because this field is used in a number of risk checks, and for 3D Secure.
shopperReference Required Your unique reference for the shopper. Do not include personally identifiable information (PII), such as name or email address.
Format:
  • Minimum length: 3 characters.
  • Case-sensitive.
This field is used for the following:
  • Risk checks.
  • When storing the shopper's payment details: associating the token with the shopper.
channel Required The platform where the payment is taking place. Use Web.

For a request that uses tokenization, you must include additional parameters.

The response includes the following information that you need for the next steps.

Parameter Description
sessionData The payment session data you need to pass to your front end.
id A unique identifier for the session data.

Next step: Pass the id and sessionData values to your front end. You will use these values when creating the AdyenCheckout instance on your client website.

Handling API errors

If your /sessions request does not get a HTTP 201 response, use the errorCode field and the list of API error codes to troubleshoot.

Client website

This section covers all the client-side implementation required for your Drop-in integration. Complete these steps to set up your client website.

Prerequisite: Before starting this section, make sure you have completed the Payment server setup and have the id and sessionData values from the /sessions response.

Install Adyen Web

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

Create a container element

Create a Document Object Model (DOM) container element in your HTML where you want the Drop-in UI to appear.

Create Drop-in

Drop-in consists of the following:

  • AdyenCheckout: represents one payment session.
  • Dropin: represents the interface that the shopper interacts with to make a 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 global configuration parameters and event handlers.

  1. Add configuration parameters.

    Parameter name Required Description
    session Required The payment session object from the /sessions response. It includes session.id and session.sessionData.
    environment Required Use test. When you are ready to accept live payments, change the value to one of our live environments. 
    amount Required 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 The shopper's country code. This is used to filter the list of available payment methods to your shopper.
    locale Required The language used in the Drop-in UI. For possible values, see the list of available languages.
    By default, this is the either the shopperLocale from your /sessions request or, if this locale is not available on Drop-in, en-US.


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

    Event handler name Required Description
    onPaymentCompleted(result, component) Required Create an event handler, called when the payment is completed.
    onPaymentFailed(result, component) Required Create an event handler, called when the payment failed. A failed payment has result code Cancelled, Error or Refused.
    onError(error) Required Create an event handler, called when an error occurs in Drop-in.

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


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

    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 when you are ready to display the payment methods.

Create your instance of Drop-in

  1. (Optional) Add configuration that is specific to Drop-in. This configuration is a different object than the global configuration. You pass this specific Drop-in configuration object when you create your instance of Dropin.

  2. Create an instance of Drop-in, passing the following:

    Argument Required Description
    AdyenCheckout object Required The instance of AdyenCheckout that you configured and created.
    Drop-in configuration object The Drop-in configuration object that you created.


  1. Mount the Drop-in to the DOM element that you created.

    You can call the following methods from your instance of Drop-in:

    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 or an 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.

Handle the payment

After you create and mount Drop-in, the shopper interacts with the interface to choose a payment method, enter their details in the payment form, and submit the payment.

What you must handle depends on the payment:

  • If the payment does not require a redirect, Drop-in handles the complete payment flow. You can get the payment outcome.
  • If the payment requires a redirect, you must handle it.

Handle the redirect

Some payment methods or flows (for example: iDEAL and redirect 3D Secure 2 authentication) redirect the shopper to another website to complete the payment.

When the shopper completes the payment on the other website, they get redirected back to your website (the returnUrl you specified when you created the payment session) with query parameters appended to it.

If the shopper does not return to your website, you do not get the return URL with parameters appended to it. You do not need to handle the redirect. Instead, wait for the webhook message that we send to your server.

  1. Extract the following query parameters:

    Query parameter Description
    sessionId The unique identifier for the shopper's payment session.
    redirectResult Details you need to submit to handle the redirect.

  2. Create a configuration object with the sessionId.

  3. Create instance of AdyenCheckout, passing the configuration object that you created.

  4. Call submitDetails(details), passing the redirectResult value that you extracted from the return URL.

  5. Get the payment outcome.

Get the payment outcome

After Drop-in finishes the payment flow, you can inform the shopper about the current payment status. Adyen sends a webhook message with the outcome of the payment to your webhook server.

Inform the shopper

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

From the relevant event, you can get the resultCode to inform the shopper about the current payment status.

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

Handling Drop-in errors

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 to help you troubleshoot.
  • live: the message from the response.
component The name of the variable where you created the instance of Drop-in, for example yourDropin.

The error object can contain additional fields inherited from the JavaScript Error() constructor.

Webhook server

This section covers your webhook server. It includes information about the webhook messages that you receive about payment outcomes.

Prerequisite: Make sure that you have set up webhook in your Customer Area and subscribed to the standard webhook with default event codes.

Update your order management system

Update your order management system when you get the outcome in a webhook message with eventCode: AUTHORISATION. Use the merchantReference from the webhook to match it to your order reference.

The merchantReference corresponds to the reference you provided when creating the payment session on your payment server.

For a successful payment, the event contains success: true.

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

Next steps