Tl;DR : Starting with version 5.0.0 of our Drop-in and Components, a single API call will be enough to create an integration. No action is required for existing merchants.

At Adyen, we make online payments easy for merchants while providing many methods of payment. Starting with version 5.0.0 of our Drop-in and Components, the number of API calls needed when integrating will be reduced from three to only one.

To achieve this, we introduce the concept of payment sessions, that are used by the web client to render the checkout for the shopper and to make all the required API requests (to internal endpoints) to complete the payment flow. This is what we will dive into in detail in this blog.

Introducing the /sessions endpoint

Version 5.0.0 of the Drop-in and Component UI elements (and their corresponding release 68 of the Checkout API ) come with an additional orchestration layer that will massively simplify your integration efforts. From your application server, only one API call will now be required : a POST request to the /sessions endpoint with payment information. All the complexity will be handled directly by the Adyen frontend components for you.

This is how the checkout flow looks like :

A sequence diagram of Adyen's checkout flow

Highlights of an example integration

Let's dive into the key elements needed to create an integration using the simplified checkout and the Drop-in interface. This is not a complete guide, but rather a highlight of the important parts of the process. You can find the complete documentation for integrations here. We also offer multiple examples of complete example integration for many languages on GitHub.

Prerequisites : We'll need our API Key and Merchant account on our server side, as well as our client key on our client side. We'll also need a return URL, which will be used to return payload once it has been processed. so that the API response can come back to us once everything has been processed properly.

The first thing we do is pass the customer's preliminary data and initiate the payment session on the backend. As a curl request, it could look like this for a payment of 5€.

Of course, those requests are usually embedded inside the back-end of your application. Here is the same example using the latest release of our Java library.

Our Checkout API will initiate a session, and return important information. It is formatted like this:

Two key piece of information are visible here :

  • The unique Id for that session
  • The sessionData, which contains all the payload of the checkout in an encrypted form

We'll pass those two pieces of information in the frontend to initiate and load the Drop-in. It looks like this:

And mount it so our Drop-in gets initiated as well :

Once that is done, the checkout workflow can proceed just as usual. The customer can enjoy their payment experience, using the method of their choice.

Our Drop-in, loaded onto a webpage

A quick glance under the hood

These snippets may look underwhelming, and they should. We strive to make integrations for our merchants as effortless as possible. But as simple as this may seem, a lot happens in the background!

Indeed, a few things have to happen before processing a payment request! Under the hood, 3 API calls are actually necessary in order to process a payment:

  • Getting the list of available payment methods (POST /paymentMethods)
  • Make the actual payment (POST to /payments)
  • Finally process payment details (usually two factor verification, 3D Secure, ...) (POST to /payments/details)

Additionally, Drop-in and components also perform a lot of heavy lifting. They validate and collect shopper details securely, make the payment request, and handle any additional actions like 3D Secure or rendering QR codes (and more). But this is a story for another blog post.

No migration required for existing merchants

As mentioned at the beginning of this post, the /sessions release is only an orchestration layer on top of existing functionalities. This means that the complete checkout experience is still available and existing merchants will not have to change anything to their existing workflow. In fact, the 3 step /paymentMethods, /payments, /payments/details is still the way to go for anyone deciding not to use our integrated Drop-in or Components, or for some more complex user flows.

Your turn to try it out!

Our documentation pages for Drop-in and Components have been updated to include the new /sessions endpoint. For a complete reference, you can also dive into the API Explorer for a complete reference of the endpoint.

Our API libraries have also been updated to add support for simplified checkout. A complete list of our API libraries for various languages is available on our GitHub.

Over the coming weeks, we will be updating all of our example integrations and publish updated versions of the libraries, so stay tuned for more information. In the meantime, any technical questions are welcome on Stack Overflow or on our forum. We will be monitoring those closely for any issues or feedback.

We hope you're as excited as us to make integrations easier and faster! Till soon

TechChoosing a mobile payments system

August 26, 20215 Minutes

TechDesign to Duty: The Accounting and Reporting Systems at Adyen

August 23, 202112 Minutes

TechDesign to Duty: How we make architecture decisions at Adyen

July 28, 20219 Minutes

See all
Sign up for the newsletter

By submitting this form, you acknowledge that you have reviewed the terms of our Privacy Statement and consent to the use of data in accordance therewith.


  • Original document
  • Permalink


Adyen NV published this content on 05 October 2021 and is solely responsible for the information contained therein. Distributed by Public, unedited and unaltered, on 07 October 2021 13:56:05 UTC.