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:
- Adyen JS version 3.0.0 and later
- Adyen iOS version 3.0.0 and later
- Adyen Android version 3.0.0 and later
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
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']
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']
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.