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.

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. Install the Adyen Web Node package or use a <script> tag.

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

3. Create a DOM element on your checkout page, placing it where you want Drop-in to be rendered on the page.

   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.

4. Create a configuration object with the following parameters:

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.
environment		Use test. When you are ready to accept live payments, change the value to one of our live environments.
onSubmit(state, dropin)		Create an event handler, called when the shopper selects the Pay button and payment details are valid.
onChange(state, dropin)		Create an event handler, called when the shopper provides the required payment details.
onAdditionalDetails(state, dropin)		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.
onError(error)		Create an event handler, called when an error occurs in Drop-in.
paymentMethodsConfiguration		Required or optional configuration for specific payment methods. For more information, refer to our payment method guides.
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' }.
analytics.enabled		Indicates if you are sending analytics data to Adyen. Default: true.

Copy code
 const configuration = {
     paymentMethodsResponse: paymentMethodsResponse, // The `/paymentMethods` response from the server.
     clientKey: "YOUR_CLIENT_KEY", // Web Drop-in versions before 3.10.1 use originKey instead of clientKey.
     locale: "en-US",
     environment: "test",
     analytics: {
       enabled: true // Set to false to not send analytics data to Adyen.
     },
     onSubmit: (state, dropin) => {
         // Global configuration for onSubmit
         // Your function calling your server to make the `/payments` request
         makePayment(state.data)
           .then(response => {
             if (response.action) {
               // Drop-in handles the action object from the /payments response
               dropin.handleAction(response.action);
             } else {
               // Your function to show the final result to the shopper
               showFinalResult(response);
             }
           })
           .catch(error => {
             throw Error(error);
           });
       },
     onAdditionalDetails: (state, dropin) => {
       // Your function calling your server to make a `/payments/details` request
       makeDetailsCall(state.data)
         .then(response => {
           if (response.action) {
             // Drop-in handles the action object from the /payments response
             dropin.handleAction(response.action);
           } else {
             // Your function to show the final result to the shopper
             showFinalResult(response);
           }
         })
         .catch(error => {
           throw Error(error);
         });
     },
     paymentMethodsConfiguration: {
       card: { // Example optional configuration for Cards
         hasHolderName: true,
         holderNameRequired: true,
         enableStoreDetails: true,
         hideCVC: false, // Change this to true to hide the CVC field for stored cards
         name: 'Credit or debit card',
         onSubmit: () => {}, // onSubmit configuration for card payments. Overrides the global configuration.
       }
     }
 };

5. Use the configuration object to create an instance of AdyenCheckout:

const checkout = await AdyenCheckout(configuration);

6. Use the returned value to create and mount an instance of Drop-in. Drop-in also accepts props related to itself.

   Copy code
   const dropin = checkout
     .create('dropin', {
     // Starting from version 4.0.0, Drop-in configuration only accepts props related to itself and cannot contain generic configuration like the onSubmit event.
         openFirstPaymentMethod:false
     })
    .mount('#dropin-container');

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.

7. Pass the state.data to your server.

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

Configuring Drop-in

Drop-in accepts the following props.

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"
}'

Your next steps depend on if the /payments response contains an action object. Choose your API version:

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

To handle these additional front-end actions, Drop-in uses the dropin.handleAction function depending on the action.type. You should also use the action.type to determine your next steps.

Copy code
GET /?shopperOrder=12xy..&&redirectResult=X6XtfGC3%21Y... HTTP/1.1
Host: www.your-company.com/checkout

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.

{
  "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 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"
      }
    }
  ]
}

Alternatively, you can use the dropin.setStatus to show a customized message. For example:

Copy code
  // Show a success message
  dropin.setStatus('success');
  dropin.setStatus('success', { message: 'Payment successful!' });
 
  // Show an error message
  dropin.setStatus('error');
  dropin.setStatus('error', { message: 'Something went wrong.'});
 
  // Set a loading state
  dropin.setStatus('loading'); // start the loading state
  dropin.setStatus('ready'); // set back to the initial state

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.

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

1. Apply for a live account.
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:

See also

Next steps