Migrating from SDK to Drop-in

Learn about the advantages of switching to the new Drop-in solution.

We replaced our Checkout SDKs with a more adaptable and flexible Drop-in solution. With Drop-in, you are in control of the payment flow and you have the freedom to decide when to make the payments.

On this page we talk about how Drop-in compares to your current SDK integration and we describe the implementation changes to help you switch to Drop-in.

Drop-in is supported for Web, iOS, and Android from:

Why you should move to Drop-in

To understand how the integration will change when you move to Drop-in, first you should know the key advantages of Drop-in over SDK:

Checkout SDK	Drop-in	Advantage of using Drop-in
- Handles fetching available payment methods.	- You submit a request to get a list of payment methods.	Gives you more visibility on the available payment methods for your shopper.
- Handles shopper interaction and submits the payment request.	- Only handles shopper interaction. - You submit the payment request from your server.	Provides more flexibility, you decide when to submit the payment request.
- Limited upgrade path for customizations.	- You have the option to switch to Components, a more modular implementation.	Uses the same API calls as Components, so you can switch to Components if you require more customization.

We will continue to support Checkout SDKs. However, we recommend that you switch your integration to Drop-in. With the new integration, you'll get the most out of the benefits listed above. You will also be able to use new functionality that we'll only release for Drop-in.

See How Drop-in works for a more detailed explanation of the checkout flow.

What you need to do

To move your integration from our Checkout SDKs to Drop-in, you need to:

Server-side : Change your API calls. You need to use three new endpoints for Drop-in.
Client-side : Use Adyen version 3.0.0 and later for web, iOS, or Android.

Server-side changes

You no longer need the endpoints you used for the SDKs.

With Drop-in, you need to change your backend implementation to use the following new endpoints (version 49 and later):

POST /paymentMethods: Get a list of all the payment methods available for a shopper.
POST /payments: Make a payment containing data from Drop-in.
POST /payments/details: Submit additional payment details containing data from Drop-in or check the payment result.

These APIs are used across other integrations. This means that if you decide to change your client-side integration from Drop-in to the more modular Components integration, you will use the same APIs. You will only need to change your client-side implementation.

See sample codes using our existing libraries below.

Get a list of available payment methods

Submit a POST /paymentMethods request and then pass the response to Drop-in.

# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen::Client.new
adyen.env = :test
adyen.api_key = "YOUR_X-API-KEY"

response = adyen.checkout.payment_methods({
  :merchantAccount => 'YOUR_MERCHANT_ACCOUNT',
  :countryCode => 'NL',
  :amount => {
    :currency => 'EUR',
    :value => 1000
  },
  :channel => 'Web'
})
# Pass the response to your front end

// Set your X-API-KEY with the API key from the Customer Area.
$client = new \Adyen\Client();
$client->setXApiKey("YOUR_X-API-KEY");
$service = new \Adyen\Service\Checkout($client);

$params = array(
  "merchantAccount" => "YOUR_MERCHANT_ACCOUNT",
  "countryCode" => "NL",
  "amount" => array(
    "currency" => "EUR",
    "value" => 1000
  ),
  "channel" => "Web"
);

$result = $service->paymentMethods($params);
// Pass the paymentMethodsResponse to your front end

# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen.Adyen()
adyen.client.xapikey = 'YOUR_X-API-KEY'

request = {
  'merchantAccount': 'YOUR_MERCHANT_ACCOUNT',
  'countryCode': 'NL',
  'amount': {
    'value': 1000,
    'currency': 'EUR'
  },
  'channel': 'Web'
}

response = adyen.checkout.payment_methods(request)
# Pass the response to your front end

https://docs.adyen.com/online-payments/classic-integrations/checkout-sdks/migrating-to-drop-in#3126635238

Submit a payment request

Drop-in then renders a list of payment methods available for the shopper, and collects your shopper's payment details. Use the data from Drop-in and submit it in a POST /payments request.

# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen::Client.new
adyen.env = :test
adyen.api_key = "YOUR_X-API-KEY"

paymentMethod = "DROPIN_DATA"
# Data object passed from onSubmit event of the front end, parsed from JSON to a Hash

response = adyen.checkout.payments({
  :amount => {
    :currency => "EUR",
    :value => 1000
  },
  :reference => "YOUR_ORDER_NUMBER",
  :paymentMethod => paymentMethod,
  :returnUrl => "https://your-company.com/checkout/",
  :merchantAccount => "YOUR_MERCHANT_ACCOUNT"
})

# Check if further action is needed.
if response.body.has_key(:action)
   # Pass the action object to your front end
   # response.body[:action]
else
   # No further action needed, pass the resultCode object to your front end
   # response.body[:resultCode]

// Set your X-API-KEY with the API key from the Customer Area.
$client = new \Adyen\Client();
$client->setXApiKey("YOUR_X-API-KEY");
$service = new \Adyen\Service\Checkout($client);

$paymentMethod = "DROPIN_DATA";
// Data object passed from onSubmit event of the front end parsed from JSON to an array

$params = array(
  "amount" => array(
    "currency" => "EUR",
    "value" => 1000
  ),
  "reference" => "YOUR_ORDER_NUMBER",
  "paymentMethod" => $paymentMethod,
  "returnUrl" => "https://your-company.com/checkout/",
  "merchantAccount" => "YOUR_MERCHANT_ACCOUNT"
);

$result = $service->payments($params);

// Check if further action is needed.
if (array_key_exists("action", $result)){
   // Pass the action object to your frontend.
   // $result["action"]
}
else {
   // No further action needed, pass the resultCode to your front end
   // $result['resultCode']
}

# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen.Adyen()
adyen.client.xapikey = 'YOUR_X-API-KEY'

paymentMethod = "DROPIN_DATA"
# Data object passed from onSubmit event of the front end, parsed from JSON to a dictionary

result = adyen.checkout.payments({
   'amount': {
      'value': 1000,
      'currency': 'EUR'
   },
   'reference': 'YOUR_ORDER_NUMBER',
   'paymentMethod': paymentMethod,
   'returnUrl': 'https://your-company.com/...',
   'merchantAccount': 'YOUR_MERCHANT_ACCOUNT'
})

# Check if further action is needed
if 'action' in result.message:
   # Pass the action object to your front end
   # result.message['action']
else:
   # No further action needed, pass the resultCode to your front end
   # result.message['resultCode']

https://docs.adyen.com/online-payments/classic-integrations/checkout-sdks/migrating-to-drop-in#9645442939

Submit additional details to complete the payment or check payment result

If the shopper is required to do additional actions to complete the payment, Drop-in handles presenting additional actions in the client app. After the shopper completes the payment, Drop-in provides the data. You use the data from Drop-in and submit it in a POST /payments/details request.

# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen::Client.new
adyen.env = :test
adyen.api_key = "YOUR_X-API-KEY"

request = "DROPIN_DATA"
# Data object passed from onSubmit event of the front end, parsed from JSON to a Hash

response = adyen.checkout.payments.details(request)

# Check if further action is needed
if response.body.has_key(:action)
   # Pass the action object to your front end
   puts response.body[:action]
else
   # No further action needed, pass the resultCode to your front end
   puts response.body[:resultCode]
end

// Set your X-API-KEY with the API key from the Customer Area.
$client = new \Adyen\Client();
$client->setXApiKey("YOUR_X-API-KEY");
$service = new \Adyen\Service\Checkout($client);

$params = "DROPIN_DATA";
// Data object passed from onSubmit event of the front end parsed from JSON to an array

$result = $service->paymentsDetails($params);

// Check if further action is needed
if (array_key_exists("action", $result)){
   // Pass the action object to your front end
   // $result["action"]
}
else {
   // No further action needed, pass the resultCode to your front end
   // $result['resultCode']
}

#Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen.Adyen()
adyen.client.xapikey = 'YOUR_X-API-KEY'

request = "DROPIN_DATA"
# Data object passed from onSubmit event of the front end, parsed from JSON to a dictionary

result = adyen.checkout.payments_details(request)

# Check if further action is needed
if 'action' in result.message:
   # Pass the action object to your front end
   # result.message['action']
else:
   # No further action needed, pass the resultCode to your front end
   # result.message['resultCode']

https://docs.adyen.com/online-payments/classic-integrations/checkout-sdks/migrating-to-drop-in#8916230954

Client-side changes

With the SDK, you handled passing the payment session and the payload between your server and the SDK. Similarly, with a Drop-in integration you need to handle passing data between your server and Drop-in.

Let's take for example a Web Drop-in implementation. In the example for server-side code, your server passes the payment method response to your front end. In your front end, you will need to instantiate the Web Drop-in with the paymentMethodsResponse.

const configuration = {
  locale: "en_US",
  environment: "test",
  clientKey: "YOUR_CLIENT_KEY",
  paymentMethodsResponse: paymentMethodsResponse
};
const checkout = new AdyenCheckout(configuration);

Next, you need to handle the events and then pass the data from Drop-in to your server. If the response contains an action object, use handleAction to enable Drop-in to perform additional actions in your front end.

function makePayment(state.data) {
  if (state.isValid){
      // Submit Drop-in data to your server
    }).then(res => {
      // Handle result from server
    })
} }

function makeDetailsCall(state.data) {
      // Send Drop-in data to server
    }).then(res => {
      // Handle result from server
    })

const dropin = checkout
.create('dropin', {
  paymentMethodsConfiguration: {
    card: { //Example optional configuration for Cards
      hasHolderName: true,
      holderNameRequired: true,
      enableStoreDetails: true,
      name: 'Credit or debit card'
    }
  },
  onSubmit: (state, component) => {
    makePayment(state.data)
      // Submits the state.data to your server
      .then(action => {
        dropin.handleAction(action);
        // Drop-in handlex the action object from the POST /payments response
      })
      .catch(error => {
        throw Error(error);
      });
    },
  onAdditionalDetails: (state, dropin) => {
    makeDetailsCall(state.data)
      // Submits the state.data to your server
      .then(action => {
        dropin.handleAction(action);
        // Drop-in handlex the action object from the POST /payments/details response
      })
      .catch(error => {
        throw Error(error);
      });
    }
})
.mount('#dropin');

SDK vs Drop-in integration steps

In this section we compare the main SDK integration steps with the integration steps for Drop-in.

Creating a payment session

With the SDK, you need to create a payment session using the /paymentSession call. You then pass the paymentSession you received in the response to the SDK.

With Drop-in, you no longer need to create a payment session.

Making a payment

With the SDK, the entire process is handled by the SDK: get the available payment methods for the shopper, collect the shopper's payment details, and then submit the payment to Adyen.

With Drop-in, you need to:

From your server, get the available payment methods with a POST /paymentMethods request.
Pass the response to Drop-in. Drop-in handles presenting the available payment methods, collecting shopper's payment details, and then provides the data that you will need in your next API request.
From your server, submit a POST /payments request with the Drop-in data.
Pass the response to Drop-in. If any additional actions are required to complete the payment (for example, redirect), Drop-in will handle the corresponding action flow and then provide the data that you will need in your next API request.
From your server, submit a POST /payments/details request with the Drop-in data.

Verifying payment result

With the SDK, you needed to make a POST /payments/result request to verify the payment result.

With Drop-in, you already get the payment result in the /payments response. For payment methods that require additional action from the shopper, you get the payment result from the /payments/details response.

Next steps

Web Drop-in

Start integrating Drop-in to your website.

iOS Drop-in

Start integrating Drop-in to your iOS app.

Android Drop-in

Start integrating Drop-in to your Android app.