What we do
Tools
Industries
Department
How we workLet's talk →
Home/Adyen/Adyen API Explorer
Adyen

Using the Adyen API Explorer, and Choosing the Layer You'll Build On

You want to see exactly what a /payments request expects before anyone writes the code for it. Adyen's API Explorer, at docs.adyen.com/api-explorer, is the reference for every Adyen API and webhook, one version at a time, with example requests and the option to send your own against a test account. It tells you what a call looks like. Whether your checkout should sit on Drop-in, Components, the API on its own or the Terminal API is a separate choice, and it's the one that costs the most to undo.

Getting around the Explorer

Pick the API, then the version. The version is part of the URL you'll call, and Checkout's newest is v72. Match the version your code or library actually uses, not just the newest one.

API Explorer Checkout API v72

Open the endpoint. Each one lists its fields, marks the required ones, such as merchantAccount, amount and reference, and shows sample requests and responses.

Send it with a test key. Use an API key from your test Customer Area at ca-test.adyen.com. Test and live keys are never interchangeable.

Webhooks are listed too. Each webhook set has its own entry with the payload your handler will receive.

Drop-in, Components, the bare API or the Terminal API

Each layer sits on the Checkout or Terminal API underneath. What changes is how much of the payment page Adyen draws for you.

What you need Build on What it costs you later
A standard online checkout, live quickly Drop-in: one prebuilt component that shows every payment method you have enabled Little control over layout and step order. A custom field check or an unusual flow can mean replacing it rather than adjusting it.
Your own checkout design, with card data kept off your servers Components: one element per payment method, styled to your page, with card fields inside Adyen's secured fields More front-end code, and every payment method you add is another component to wire up and test.
A flow no front-end library fits: server-led, in-app or headless The Checkout API called directly You handle each redirect and extra step yourself, and collecting raw card data on your side widens your PCI scope.
Card readers at a counter or on the shop floor The Terminal API, from your POS to the terminal It's a separate integration from online checkout, tested on its own, even though the payments land in the same Adyen account.
Terminals, webhooks or account settings managed in bulk The Management API Its credential needs the matching roles. A key set up for Checkout alone will be refused.

Turning an Explorer example into code that behaves the same

  1. 1

    Write down the version you tested

    The Explorer shows one API version at a time. A library or an older part of your integration may call a different one, and fields are added, renamed or retired between versions.

    Watch for: the version comparison in Adyen's docs. It lists what changed from one version to the next.

  2. 2

    Send the example with your own merchant account

    Swap the sample merchantAccount for your test merchant account name and use a payment method that's set up on it. A perfectly formed request still fails for a method the account doesn't have.

  3. 3

    Move the request into your server code

    Adyen's server libraries for Node, Java, PHP, Python, .NET and other languages wrap the same fields as typed objects. Each library release targets particular API versions, so check its release notes against the version from step one.

  4. 4

    Build the webhook handler from the listed payload

    Take the webhook's payload from its Explorer entry and parse that, then let a real test payment send you one so you see the actual event, not the sample.

  5. 5

    Repeat the setup in live

    Nothing created in test carries over. Live credentials, webhooks and the prefixed live URL all come from the live Customer Area.

When the Explorer says yes and your code says no

Your code calls a different version

How you'll know: A field that worked in the Explorer is ignored or rejected when your server sends it.

Fix: Set the version explicitly in the URL or the library config, and make it the one you tested against.

The credential doesn't have the role for that API

How you'll know: Checkout calls succeed, while a Management or platform call is refused as forbidden.

Fix: Add the role to the credential in the Customer Area, or give that API its own credential with only the roles it needs.

The sample payload was the only test

How you'll know: The handler breaks on its first real webhook, because a field the sample left out turns up, or one it showed is missing.

Fix: Treat optional fields as optional, log any event you couldn't process, and replay it once the handler's fixed.

A live payment method was never added

How you'll know: A method you tried in test doesn't appear for live shoppers.

Fix: Payment methods are enabled per account and environment. Request them on the live account too before launch.

Adyen API Explorer and integration questions

What's Adyen's API Explorer?

Adyen's interactive API reference at docs.adyen.com/api-explorer. It covers Checkout, Terminal, Management, platform and other APIs, plus their webhooks, version by version, with example requests and responses. Adyen built it on its OpenAPI specs so you can try requests as well as read them.

Does Adyen provide SDKs, or do I call the API directly?

You can do either. Adyen publishes server libraries in languages including Node, Java, PHP, Python and .NET, and the REST API works from any language that can send HTTPS requests. Front-end checkout comes from the Adyen Web library, which holds Drop-in and Components.

What's the Terminal API for?

Taking in-person payments on Adyen terminals. Your POS sends the terminal a payment request and gets the result back, either over the local network or through Adyen's cloud. It has its own section in the API Explorer, apart from the Checkout API that online payments use.

Where do I get Adyen API credentials?

From the Customer Area: test at ca-test.adyen.com, live at ca-live.adyen.com, under Developers and then API credentials. Each credential holds a server-side API key, a client key for the browser, and the roles that decide which APIs it can call.

Is there a sandbox for testing the API before going live?

Yes. Adyen's test environment has its own Customer Area, credentials and endpoints, and no real money moves. Adyen also publishes Postman collections, which suit teams that would rather script their test calls than send them from the browser.

Who builds the parts of an Adyen integration the Explorer leaves out?

n-frames writes the server side once the request shape is known: the webhook handler that sets each order's real status, refunds and disputes passed back to your order system, and settlement data posted to your accounting system. It also moves a checkout from Drop-in to Components when the design outgrows it.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.