Search

Are you looking for test card numbers?

Would you like to contact support?

Online-payment icon

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 and you'll 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 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) and then pass the responses to your client.

  • POST /paymentMethods request to get a list of all the payment methods available for a shopper.
  • POST /payments request to submit a payment request containing data from Drop-in.
  • POST /payments/details request to submit additional payment details containing data from Drop-in.

These APIs are used across other integrations. If in the future you decide to change your client-side integration from Drop-in to the more modular Components integration, you will use the same APIs and will only have to change your client-side implementation.

To illustrate, see sample codes using our existing libraries below.

Get a list of available payment methods

Submit a /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

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 provided by Drop-in and submit it in your /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']

Submit additional details to complete the payment

If additional actions are required to complete the payment (for example, 3D Secure authentication), Drop-in handles performing additional actions in the client app and then provides data after completing the action. Use the data from Drop-in and submit it in your /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->paymentDetails($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']

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",
  originKey: "YOUR_ORIGIN_KEY",
  paymentMethodsResponse: paymentMethodsResponse
};
const checkout = new AdyenCheckout(configuration);

Next, you need to create functions to handle the events invoked by Drop-in and then pass the data from Drop-in to your server. If the response contains an action object, use handleAction to trigger Drop-in to perform additional actions (for example, 3D Secure authentication) 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 needed to create a payment session using the /paymentSession call. You would then pass on the paymentSession received in the response to initiate 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 or from the /payments/details response if additional payment details were required.

Next steps