A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Adyen API is how an app or AI agent takes a payment, captures or refunds it, removes a shopper's saved card, sends a payout, or configures a merchant account. Access is granted through an API key whose credential carries a set of roles, and those roles, together with the origins the key is allowed to call from, set the boundary of what it can do. Many payment outcomes are confirmed asynchronously, so the result of an authorisation, capture, or refund arrives as a standard event sent to a registered endpoint.
How an app or AI agent connects to Adyen determines what it can reach. There is a route for taking and changing payments, a route for managing the account itself, a route for receiving events, and a local server that exposes Adyen tools to agents, and each is governed by the API key behind it and the roles and allowed origins set on that key.
Adyen is a set of separate REST APIs, each versioned in its own request path: Checkout for payments at https://checkout-live.adyenpayments.com, the classic Payments and Payouts APIs at the pal host, and the Management and Balance Platform APIs at their own hosts. A call sends JSON and authenticates with an API key in the X-API-Key header, or with HTTP Basic auth for older endpoints. The live host carries a company-specific prefix.
Adyen POSTs standard notifications to an endpoint registered through the Management API or the Customer Area. A payload carries a notificationItems array of NotificationRequestItem objects, each with an eventCode like AUTHORISATION or REFUND, a success flag, and a pspReference. The receiver verifies an HMAC signature, sent inside additionalData for payment webhooks, to confirm the request came from Adyen, and must return [accepted] to acknowledge it.
Adyen publishes a first-party Model Context Protocol server, written in TypeScript and run locally (for example through npx), that exposes Adyen tools to AI agents and LLM clients. The alpha release covers an initial set of Checkout and Management API endpoints, like creating payment sessions, managing payment links, and processing cancellations and refunds. It authenticates with an Adyen API key supplied when the server starts.
An API key authenticates a request through the X-API-Key header. Each key belongs to an API credential that carries a set of roles, which decide which APIs and operations the key can use, and a list of allowed origins for client-side calls. There is no per-endpoint OAuth scope; access is shaped entirely by the credential's roles. A key belongs to one environment, either test or live.
Older endpoints accept HTTP Basic authentication using the username and password of a web-service user. The same roles on the underlying API credential govern what the user can do. Adyen recommends the API key over basic auth for new integrations.
A client key is a public key safe to use in front-end code, paired with the Web and mobile SDKs (Drop-in and Components). It is restricted to client-side operations and to the origins listed on the credential, and cannot make server-side API calls or move money on its own.
The Adyen API is split into areas an agent can act on, like taking a payment, capturing or refunding it, sending a payout, managing stored cards, and configuring merchant accounts. Each area is a separate API with its own version, and writes in the payment areas move real money.
Methods for taking a payment, from listing payment methods to starting and completing a transaction.
Methods that change an existing payment: capture the funds, refund them, or cancel the authorisation.
Methods for listing and removing the tokens that stand in for a shopper's saved card or account.
Methods for configuring the account: merchant accounts, stores, API credentials, and webhooks.
Methods for sending funds out to a third party's bank account or wallet, submitted then confirmed.
Methods for the embedded-finance platform: the account holders and balance accounts that hold funds.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Checkout (payments)Methods for taking a payment, from listing payment methods to starting and completing a transaction.6 | ||||||
| POST | /v71/paymentMethods | Get the list of payment methods available for a transaction, based on amount, country, and currency. | read | Checkout: read | Current | |
Read-only; access is governed by the API key's role and allowed origins, not a per-endpoint scope. Acts onpaymentMethod Permission (capability) Checkout: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v71/sessions | Create a payment session, the single request that powers the prebuilt Drop-in and Components checkout. | write | Checkout: write | Current | |
Starts a checkout flow; the eventual result arrives by webhook. Acts onsession Permission (capability) Checkout: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v71/sessions/{sessionId} | Get the result of a payment session, including its current status. | read | Checkout: read | Current | |
Read-only. Acts onsession Permission (capability) Checkout: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v71/payments | Start a transaction, sending the amount and collected shopper details to attempt a payment. | write | Checkout: write | Current | |
The authorisation outcome is often confirmed asynchronously by the AUTHORISATION webhook. Acts onpayment Permission (capability) Checkout: writeVersionAvailable since the API’s base version Webhook event AUTHORISATIONRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v71/payments/details | Submit additional details for a payment, used to complete flows like 3D Secure or redirects. | write | Checkout: write | Current | |
Continues a payment that required an extra shopper action. Acts onpayment Permission (capability) Checkout: writeVersionAvailable since the API’s base version Webhook event AUTHORISATIONRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v71/storedPaymentMethods | Get the tokens that represent a shopper's stored payment details. | read | Checkout: read | Current | |
Read-only; returns the recurring tokens saved for a shopper. Acts onstoredPaymentMethod Permission (capability) Checkout: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Modifications (capture, refund, cancel)Methods that change an existing payment: capture the funds, refund them, or cancel the authorisation.6 | ||||||
| POST | /v71/payments/{paymentPspReference}/captures | Capture an authorised payment, collecting the funds that were held at authorisation. | write | Checkout: write | Current | |
The request is accepted synchronously; the CAPTURE webhook confirms whether it succeeded. Acts oncapture Permission (capability) Checkout: writeVersionAvailable since the API’s base version Webhook event CAPTURERate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v71/payments/{paymentPspReference}/refunds | Refund a captured payment, fully or partially, returning money to the shopper. | write | Checkout: write | Current | |
The REFUND webhook confirms the outcome; REFUND_FAILED signals a scheme rejection. Acts onrefund Permission (capability) Checkout: writeVersionAvailable since the API’s base version Webhook event REFUNDRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v71/payments/{paymentPspReference}/cancels | Cancel an authorised payment that has not been captured, releasing the held funds. | write | Checkout: write | Current | |
Only works before capture; the CANCELLATION webhook confirms the result. Acts oncancel Permission (capability) Checkout: writeVersionAvailable since the API’s base version Webhook event CANCELLATIONRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v71/cancels | Cancel an authorised payment by reference, without needing its PSP reference in the path. | write | Checkout: write | Current | |
Identifies the payment by paymentReference instead of the path. Acts oncancel Permission (capability) Checkout: writeVersionAvailable since the API’s base version Webhook event CANCELLATIONRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v71/payments/{paymentPspReference}/amountUpdates | Update the authorised amount of a payment, for example to add a tip or adjust an order. | write | Checkout: write | Current | |
Changes the amount held before capture; supported for select payment methods. Acts onamountUpdate Permission (capability) Checkout: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v71/payments/{paymentPspReference}/reversals | Reverse a payment, cancelling it if uncaptured or refunding it if already captured. | write | Checkout: write | Current | |
A single call that does the right thing whether the payment is captured or not. Acts onreversal Permission (capability) Checkout: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Recurring (stored payment details)Methods for listing and removing the tokens that stand in for a shopper's saved card or account.2 | ||||||
| POST | /Recurring/v68/listRecurringDetails | Get the stored payment details (tokens) saved for a shopper under a merchant account. | read | Recurring: read | Current | |
Read-only; the Checkout storedPaymentMethods endpoint is the modern equivalent. Acts onrecurringDetail Permission (capability) Recurring: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /Recurring/v68/disable | Disable stored payment details so a saved token can no longer be used. | write | Recurring: write | Current | |
Removes a token permanently for that shopper. Acts onrecurringDetail Permission (capability) Recurring: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Management (account configuration)Methods for configuring the account: merchant accounts, stores, API credentials, and webhooks.6 | ||||||
| GET | /v3/merchants | List the merchant accounts the API credential can access. | read | Management: read | Current | |
Read-only; the Management API is governed by management roles on the credential, separate from payment roles. Acts onmerchant Permission (capability) Management: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/merchants/{merchantId} | Get a single merchant account by its identifier. | read | Management: read | Current | |
Read-only. Acts onmerchant Permission (capability) Management: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/merchants/{merchantId}/stores | Create a store under a merchant account, used to group physical or online points of sale. | write | Management: write | Current | |
Changes account configuration; needs the Management API write role. Acts onstore Permission (capability) Management: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/merchants/{merchantId}/apiCredentials | List the API credentials configured for a merchant account. | read | Management: read | Current | |
Read-only; lists the keys, not their secret values. Acts onapiCredential Permission (capability) Management: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/merchants/{merchantId}/apiCredentials | Create a new API credential for a merchant account, returning its key and roles. | write | Management: write | Current | |
Mints a new credential that can call other APIs; the secret is returned once at creation. Acts onapiCredential Permission (capability) Management: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/merchants/{merchantId}/webhooks | Set up a webhook for a merchant account, registering the endpoint that receives event notifications. | write | Management: write | Current | |
Registers where Adyen sends events; an HMAC key is generated separately to secure it. Acts onwebhook Permission (capability) Management: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
PayoutsMethods for sending funds out to a third party's bank account or wallet, submitted then confirmed.3 | ||||||
| POST | /Payout/v68/storeDetailAndSubmitThirdParty | Store a payee's details and submit a payout, which then waits for confirmation. | write | Payout: write | Current | |
The classic Payout API is deprecated; new integrations use the Transfers API. A submitted payout must be confirmed or declined. Acts onpayout Permission (capability) Payout: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /Payout/v68/confirmThirdParty | Confirm a previously submitted payout so the money is sent. | write | Payout: write | Current | |
Releases the payout; requires the separate payout review credential. Acts onpayout Permission (capability) Payout: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /Payout/v68/declineThirdParty | Cancel a previously submitted payout so the money is not sent. | write | Payout: write | Current | |
Stops a payout that was submitted but not yet confirmed. Acts onpayout Permission (capability) Payout: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Balance Platform (Configuration)Methods for the embedded-finance platform: the account holders and balance accounts that hold funds.2 | ||||||
| POST | /bcl/v2/accountHolders | Create an account holder in the Balance Platform, the entity that owns balance accounts and can hold funds. | write | Balance Platform: write | Current | |
Embedded-finance only; the Configuration API has its own credential and roles. Acts onaccountHolder Permission (capability) Balance Platform: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /bcl/v2/accountHolders/{id}/balanceAccounts | Get all balance accounts belonging to an account holder. | read | Balance Platform: read | Current | |
Read-only. Acts onbalanceAccount Permission (capability) Balance Platform: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Adyen reports the outcome of a payment by sending a standard webhook to a registered endpoint. Many payment results are confirmed asynchronously, so the authorisation, capture, or refund result arrives as an event rather than in the original response, and an integration relies on these events to learn what happened.
| Event | What it signals | Triggered by |
|---|---|---|
AUTHORISATION | Reports whether a payment was authorised. Because many payments are confirmed asynchronously, this event, not the API response, is the definitive result of an authorisation. | /v71/payments/v71/payments/details |
CAPTURE | Reports the outcome of a capture request. A CAPTURE_FAILED event signals that the card scheme rejected the capture after it was accepted. | /v71/payments/{paymentPspReference}/captures |
REFUND | Reports the outcome of a refund request. A REFUND_FAILED event signals that the refund was rejected by the scheme after being accepted. | /v71/payments/{paymentPspReference}/refunds |
CANCELLATION | Reports the outcome of cancelling an authorised, uncaptured payment. | /v71/payments/{paymentPspReference}/cancels/v71/cancels |
Adyen limits how fast an app can call each API, measured as a number of requests over a short window, and the limit differs by API and between the test and live environments.
Adyen limits how fast each API can be called, set per API rather than by a per-method cost, and the limit differs between the test and live environments. Limits are expressed as a number of requests over a short window, for example the Legal Entity Management API allows 700 requests per 5 seconds in live and 200 per 5 seconds in test, while some APIs like the Referrals API are far tighter. Going over returns HTTP 429, and the request should be retried after a short back-off.
List endpoints that can return many items page through results, commonly with a pageNumber and pageSize on the Management and Balance Platform APIs. The payment APIs mostly return a single object per call rather than long lists, so pagination applies chiefly to the configuration and platform APIs.
An idempotency key can be sent on a write to make a retry safe to repeat; Adyen stores the first result and replays it for any repeat with the same key. A standard webhook can batch several NotificationRequestItem objects in one notificationItems array, and the receiver must return [accepted] to acknowledge the whole batch.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | validation | The request was malformed or missing a required field. The body includes an errorType of validation, an Adyen errorCode like 14_002, a message, and a pspReference where applicable. | Read errorCode and message, fix the request, and resend. The call is not retryable as-is. |
| 401 | security (unauthorized) | Authentication failed: no valid API key or web-service user was provided. | Confirm a valid key for the right environment is sent in X-API-Key, and rotate it if compromised. |
| 403 | security (forbidden) | The credential is valid but its roles do not allow this operation, or the call comes from an origin not on the allowed list. | Grant the needed role on the API credential, or add the calling origin to the allowed origins. |
| 422 | validation (unprocessable) | The request was well-formed but semantically incorrect, for example a payment refusal or a configuration problem like errorCode 905_1, payment method not configured. | Inspect errorCode and refusalReason, adjust the request or account configuration, and do not blindly retry. |
| 429 | too many requests | The request rate exceeded the limit for that API and environment. | Back off and retry with exponential backoff, and smooth the request rate. |
| 500 | internal | An error on Adyen's side, returned with an errorType of internal. It is rare. | Retry idempotently with backoff using the same idempotency key, and contact Adyen support if it persists. |
Adyen versions each API independently in the request path, so the Checkout, Payments, Recurring, Management, and Balance Platform APIs each carry their own version number, and an integration upgrades one without affecting the others.
Adyen versions each API in its own path. Checkout v71 is widely used and fully supported, while v72 is the latest Checkout version. The other APIs version on their own timelines: the classic Payments and Payouts APIs at v68, Recurring at v68, Management at v3, and the Balance Platform Configuration API at v2.
The Management API reached v3, used to configure merchant accounts, stores, API credentials, and webhooks, including generating an HMAC key per webhook endpoint.
The classic Payout API remains at v68 but is deprecated. New integrations are directed to the Transfers API on the Balance Platform; existing users migrate with Adyen's help.
The Configuration API for embedded finance reached v2, managing account holders, balance accounts, and the payment instruments linked to them.
Each API moves at its own pace; pin the version per API and upgrade one at a time.
Adyen release notes ↗Bollard AI sits between a team's AI agents and Adyen. Grant each agent exactly the access it needs, read or write, action by action, and every call is checked and logged.