Advanced flow integration guide

Drop-in is our pre-built UI solution for accepting payments on your website. Drop-in shows all payment methods as a list, in the same block. This integration requires you to make API requests to /paymentMethods, /payments, and /payments/details endpoints.

Adding new payment methods usually doesn't require more development work. Drop-in supports cards, wallets, and most local payment methods.

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 update your existing integration, see Migrate to Adyen Web v6.

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:

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. From your server, submit a request to get a list of payment methods available to the shopper.
2. Create an instance of Drop-in on your payments form.
3. From your server, submit a payment request with data you receive from Drop-in.
4. Determine from the response if you need to perform additional actions on your client website.
5. From your server, submit additional payment details with data you receive from Drop-in.
6. Present the payment result to the shopper.

When you have completed the integration, proceed to test your integration.

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 /paymentMethods request, specifying:

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.
channel		The platform of the shopper's device; use Web. This is used to filter the list of available payment methods to your shopper.
countryCode		The shopper's country/region. This is used to filter the list of available payment methods to your shopper. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).
shopperLocale		By default, the shopperlocale is set to en-US. To change the language, set this to the shopper's language and country code. You also need to set the same locale within your Drop-in configuration.

You can also include other optional parameters, for example allowedPaymentMethods or blockedPaymentMethods to customize which payment methods will be shown to the shopper.

The following example shows how 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/v71/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": "Web",
  "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 website. You'll use this in the next step to show which payment methods are available for the shopper.

Add Drop-in to your payments form

Next, use Drop-in to show the available payment methods, and to collect payment details from your shopper.

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

npm install @adyen/adyen-web --save

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

npm install @adyen/adyen-web --save

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

   You can add your own styling by overriding the rules in this CSS file.

After you have imported the Adyen Web library, do the following:

1. Create a Document Object Model (DOM) element on your checkout page and put it where you want Drop-in to render on the page.

   Expand view

   Copy link to code block

   Copy code

   Copy code

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

2. Create a global configuration object with the following parameters and events:

   Parameter name	Required	Description
   paymentMethodsResponse		The full /paymentMethods response returned when you get available payment methods.
   clientKey		A public key linked to your API credential, used for client-side authentication. Web Drop-in versions before 3.10.1 use originKey instead. Find out how to migrate from using originKey to clientKey.
   locale		The shopper's locale. This is used to set the language rendered in the UI. For a list of supported locales, see Language and localization.
   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).
   environment		Use test. When you are ready to accept live payments, change the value to one of our live environments.
   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. value: The amount of the transaction, in minor units. currencyDisplay: Sets the currency formatting. Default: symbol.
   showPayButton		Shows or hides a Pay Button for each payment method. Defaults to true. When set to false, you must override it in paymentMethodsConfiguration . 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.
   amount		Amount to be displayed on the Pay Button. It expects an object with the value and currency properties. For example, { value: 1000, currency: 'USD' }.

   Event name	Required	Description
   onSubmit(state, dropin, actions)		Create an event handler for this event, which is called when the shopper selects the Pay button, and the details are valid. This applies if the showPayButton configuration parameter is set to true. Makes a POST /payments request. If the /payments request from your server is successful, you must call actions.resolve(), passing resultCode, action, and order objects (if available) from the API response. You must call it even if the payment is unsuccessful. If the /payments request from your server fails, or if an unexpected error occurs, call actions.reject().
   onAdditionalDetails(state, dropin, actions)		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. Makes a POST /payments/details request. If the /payments/details request from your server is successful, you must call actions.resolve(), passing resultCode, action, and order objects (if available) from the API response. You must call it even if the payment is unsuccessful. If the /payments/details request from your server fails, or if an unexpected error occurs, call actions.reject.
   onPaymentCompleted(result, component)		Create an event handler, called when the payment is completed.
   onPaymentFailed(result, component)		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.
   onChange(state, dropin)		Create an event handler, called when the shopper provides the required payment details.
   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.

   Create a configuration object

   Expand view

   Copy link to code block

   Copy code

   Copy code

   const configuration = {
     clientKey: "YOUR_CLIENT_KEY",
     environment: "test",
     amount: {
       value: 1000,
       currency: 'EUR'
     },
     locale: 'nl-NL',
     countryCode: 'NL',
     // The full /paymentMethods response object from your server. Contains the payment methods configured in your account.
     paymentMethodsResponse: paymentMethodsResponse,
     onSubmit: async (state, component, actions) => {
       try {
    
         // Make a POST /payments request from your server.
         const result = await makePaymentsCall(state.data, countryCode, locale, amount);
    
         // If the /payments request from your server fails, or if an unexpected error occurs.
         if (!result.resultCode) {
           actions.reject();
           return;
         }
    
         const {
           resultCode,
           action,
           order,
           donationToken
         } = result;
    
         // If the /payments request request form your server is successful, you must call this to resolve whichever of the listed objects are available.
         // You must call this, even if the result of the payment is unsuccessful.
         actions.resolve({
           resultCode,
           action,
           order,
           donationToken,
         });
       } catch (error) {
         console.error("onSubmit", error);
         actions.reject();
       }
     },
     onAdditionalDetails: async (state, component, actions) => {
       try {
    
         // Make a POST /payments/details request from your server.
         const result = await makeDetailsCall(state.data);
    
         // If the /payments/details request from your server fails, or if an unexpected error occurs.
         if (!result.resultCode) {
           actions.reject();
           return;
         }
    
         const {
           resultCode,
           action,
           order,
           donationToken
         } = result;
    
         // If the /payments/details request request from your server is successful, you must call this to resolve whichever of the listed objects are available.
         // You must call this, even if the result of the payment is unsuccessful.
         actions.resolve({
           resultCode,
           action,
           order,
           donationToken,
         });
       } catch (error) {
         console.error("onSubmit", error);
         actions.reject();
       }
     },
     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. Create an instance of AdyenCheckout, passing the global configuration object you created:

   Expand view

   Copy link to code block

   Copy code

   Copy code

   const checkout = await AdyenCheckout(configuration);

4. Create and mount an instance of Dropin, passing the instance of AdyenCheckout you created. You can add optional Drop-in configuration your instance of Dropin. How you create it depends on if you import resources for all payment methods or individual payment methods.

   All payment methodsIndividual payment methodsAll payment methodsIndividual payment methods

   checkout.js

   Expand view

   Copy link to code block

   Copy code

   Copy code

   // Create an instance of Drop-in and mount it to the container you created.
   const dropin = new Dropin(checkout).mount('#dropin');

   When the shopper selects the Pay button, Drop-in calls the onSubmit event, which contains a state.data. These are the shopper details that you need to make the payment.

5. Pass the state.data to your server.

   Sample state from onSubmit event for a card payment

   Expand view

   Copy link to code block

   Copy code

   Copy code

   {
       isValid: true,
       data: {
         paymentMethod: {
           type: "scheme",
           encryptedCardNumber: "adyenjs_0_1_18$k7s65M5V0KdPxTErhBIPoMPI8HlC..",
           encryptedExpiryMonth: "adyenjs_0_1_18$p2OZxW2XmwAA8C1Avxm3G9UB6e4..",
           encryptedExpiryYear: "adyenjs_0_1_18$CkCOLYZsdqpxGjrALWHj3QoGHqe+..",
           encryptedSecurityCode: "adyenjs_0_1_18$XUyMJyHebrra/TpSda9fha978+.."
           holderName: "S. Hopper"
         }
       }
   }

Optional Drop-in configuration

You can add the following configuration parameters to the Dropin configuration:

Events

Use the following events to include additional logic on your checkout page:

Methods

Drop-in supports the following methods:

Make a payment

After the shopper selects the Pay button or chooses to pay with a payment method that requires a redirection, you need to make a payment request to Adyen.

From your server, make a /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 state.data.paymentMethod from the onSubmit event from your client website.
returnUrl		URL to where the shopper should be taken back to after a redirection. The URL can contain a maximum of 1024 characters and should include the protocol: http:// or https://. 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.
riskData		Device characteristics and other data that we use to detect fraudulent payment activity, and mitigate fraud.
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.
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.

The following example shows how to make a payment request for EUR 10:

curl https://checkout-test.adyen.com/checkout/v71/payments \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
  "amount": {
    "currency": "EUR",
    "value": 1000
  },
  "reference": "YOUR_ORDER_NUMBER",
  "paymentMethod":{
	    "type": "scheme",
	    "encryptedCardNumber": "test_4111111111111111",
	    "encryptedExpiryMonth": "test_03",
	    "encryptedExpiryYear": "test_2030",
	    "encryptedSecurityCode": "test_737"
	},
  "returnUrl": "https://your-company.com/checkout?shopperOrder=12xy..",
  "riskData": {
	   "clientData": "eyJ0cmFuc1N0YXR1cy...I6IlkifQ=="
	},
  "merchantAccount": "ADYEN_MERCHANT_ACCOUNT"
}'

Next, implement logic to handle /payments responses with and without 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"
  }
}

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.

Drop-in handles these additional front-end actions based on the action object and resultCode that you pass to the onSubmit actions.resolve() function.

The action.type determines your next steps:

Handle the redirect result

If you receive an action.type redirect, Drop-in 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:

Copy code
GET /?shopperOrder=12xy..&&redirectResult=X6XtfGC3%21Y... HTTP/1.1
Host: www.your-company.com/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, you need to submit additional payment details to either complete the payment, or to check the payment result.

Make a /payments/details request, and include:

• For action.type: redirect, pass in your request:
  • details: Object that contains the URL-decoded redirectResult.
• For action.type: qrCode, await, sdk, or threeDS2, pass in your request the state.data from the onAdditionalDetails event.

The following example shows how to submit additional payment details in case of a redirect.

curl https://checkout-test.adyen.com/checkout/v70/payments/details \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
     "details": {
       "redirectResult": "eyJ0cmFuc1N0YXR1cyI6IlkifQ=="
   }
}'

The response includes:

• pspReference: Our unique identifier for the transaction.
• resultCode: Indicates the status of the payment.

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

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

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 from the onPaymentCompleted or onPaymentFailed event 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"
      }
    }
  ]
}

Error handling

In case you encounter errors in your integration, refer to the following:

• API error codes: If you receive a non-HTTP 200 response, use the errorCode to troubleshoot and modify your request.
• Payment refusals: If you receive an HTTP 200 response with an Error or Refused resultCode, check the refusal reason and, if possible, modify your request.

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	Value
   Europe (EU) live	live
   United States (US) live	live-us
   Australia (AU) live	live-au
   Asia Pacific & Southeast (APSE) live	live-apse
   India (IN) live	live-in

See also

Next steps