canonical: https://jentic.com/apis/adyen.com/adyen-checkout

# Adyen Checkout API

The Adyen Checkout API is Adyen's primary surface for initiating and authorising online payments - cards (including 3D Secure), mobile wallets, local payment methods, and recurring billing. The 26 endpoints in v70 cover the full payment lifecycle: list available payment methods for a session, create payments, post payment details for redirects and 3DS challenges, capture and cancel authorisations, refund, manage payment links, handle Apple Pay sessions, support recurring stored details, and process orders for partial-method splits and donations.

## For AI agents

Initiate and authorise online payments across cards, wallets, and local methods, plus refunds, captures, payment links, and recurring billing.

## Scope

Does not handle balance platform configuration, BIN lookup, settlement reporting, or in-person POS terminals - use for online payment authorisation, modifications, and recurring tokens only.

## Capabilities

- Initiate a payment via POST /payments with card, wallet, or local payment method details
- Submit additional payment details (3DS challenge results, redirect returns) via POST /payments/details
- Capture, cancel, refund, or reverse an authorised payment using the modifications endpoints
- Generate hosted payment links via POST /paymentLinks for invoicing and async checkout flows
- Create Apple Pay merchant sessions via POST /applePay/sessions for in-app and web Apple Pay checkouts
- Use POST /sessions to launch a Drop-in or Components session that handles payment method selection client-side
- Manage stored payment details and recurring tokens for subscription billing

## Use cases

### Card Checkout with 3D Secure

The classic card-payment flow uses POST /sessions to launch a Drop-in or Components session, then POST /payments and POST /payments/details to handle the 3DS2 round-trip. Adyen returns the resultCode (Authorised, ChallengeShopper, RedirectShopper) and the front end follows the prescribed step. The API handles 135+ payment methods and 100+ currencies with the same surface.

Example prompt: Call POST /payments with paymentMethod.type=scheme, encryptedCardNumber, amount, and merchantAccount, then if resultCode=ChallengeShopper post the 3DS challenge result to POST /payments/details

### Hosted Payment Links for Invoicing

When a payment cannot be collected synchronously - invoicing a customer, sending a quote - POST /paymentLinks generates a hosted Adyen-branded URL that the customer can open from email or SMS. The link supports the same 135+ methods, returns a webhook on completion, and can be voided with PATCH /paymentLinks/{linkId} if the invoice is cancelled.

Example prompt: Call POST /paymentLinks with amount, reference, expiresAt, and shopperEmail, then email the returned link.url to the customer

### Recurring Subscription Billing

Subscription products tokenize a card on the first payment and reuse the recurringDetailReference for renewals. POST /payments with recurringProcessingModel=Subscription captures the token; subsequent renewals call POST /payments referencing the stored token, with no shopper interaction required. Stored details can be revoked via DELETE on the storedPaymentMethods resource.

Example prompt: Call POST /payments with shopperReference, recurringProcessingModel=Subscription, and storePaymentMethod=true on the first charge, then renewals call POST /payments referencing storedPaymentMethodId

### Refunds and Modifications

Operational tools need to capture an authorisation, partially refund a settled payment, or reverse a pending one. The modifications endpoints - POST /payments/{paymentPspReference}/captures, /refunds, /reversals, /cancels - accept a pspReference and an amount, and Adyen handles the corresponding webhook acknowledgement asynchronously.

Example prompt: Call POST /payments/{paymentPspReference}/refunds with the original pspReference and the amount to refund, then track the refund webhook for confirmation

### Agent-Driven Checkout via Jentic

A commerce agent can use Jentic to discover the right Checkout operation across 26 endpoints - payments, payment links, captures, refunds, sessions - and execute it with X-API-Key managed in your Jentic One instance. This is the highest-value surface in the Adyen catalogue for agent-driven workflows because of the breadth of operations and the criticality of the credentials.

Example prompt: Use Jentic to search 'process credit card payment adyen', load POST /payments, and execute it for the requested amount and card details

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /payments | Initiate a payment |
| POST | /payments/details | Submit 3DS or redirect details |
| POST | /sessions | Create a Drop-in/Components checkout session |
| POST | /paymentLinks | Create a hosted payment link |
| POST | /cancels | Cancel a pending authorisation |
| POST | /applePay/sessions | Create an Apple Pay merchant session |
| POST | /orders | Create a multi-method order |
| POST | /donations | Process a donation alongside a payment |

## Key resources

- **Payments** — POST /payments and /payments/details for card, wallet, and local payments
- **Payment links** — Hosted Adyen-branded payment URLs
- **Modifications** — Captures, refunds, reversals, and cancels
- **Sessions** — Drop-in and Components session creation
- **Apple Pay** — Apple Pay merchant session generation
- **Recurring** — Stored payment methods and subscription tokens
- **Orders** — Multi-method orders and donation flows

## Why Jentic

- **Setup:** Wiring the Adyen Checkout API by hand means handling its X-API-Key or basic auth, targeting the v70 checkout host, and assembling amount, paymentMethod, and reference fields for each payment. Through Jentic you install once, import the Checkout API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** This Checkout version takes the payment target in the request body for payments, cancels, and orders rather than a resource id in the URL path, so you limit the agent to the operations it needs, such as processing a payment or creating a payment link. Because you pick the operations, cancels and donations stay out unless you include them.
- **Credential handling:** Your Adyen X-API-Key and basic auth credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'process a credit card payment' or 'create a payment link', and Jentic returns the matching Checkout operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Adyen BIN Lookup API** — Pre-checkout 3DS routing and cost estimate that informs the Checkout request
- **Stripe** — Stripe Payment Intents covers an equivalent card, wallet, and recurring surface
- **Braintree** — Braintree's Transactions API offers a comparable card and wallet surface from PayPal

## FAQ

### What authentication does the Adyen Checkout API use?

The API supports an apiKey scheme using the X-API-Key header and HTTP basic auth with Customer Area credentials. Through Jentic, the X-API-Key is stored encrypted in the vault and injected at request time, so agents calling POST /payments never hold the raw key.

### Can I process refunds with the Adyen Checkout API?

Yes. POST /payments/{paymentPspReference}/refunds accepts the original payment's pspReference and the amount to refund (full or partial). Adyen confirms the refund asynchronously via the corresponding webhook.

### What are the rate limits for the Adyen Checkout API?

The OpenAPI spec does not declare programmatic rate limits. Adyen documents per-merchant-account throughput limits in their developer portal - coordinate large surge events with your Adyen account manager and use idempotency keys on POST /payments and modifications.

### How do I create a hosted payment link through Jentic?

Search Jentic for 'create adyen payment link', load the POST /paymentLinks operation, and execute it with amount, reference, expiresAt, and the shopperEmail. Jentic returns the structured response containing the link.url.

### Can I tokenize a card for subscription billing?

Yes. On the first POST /payments call, set storePaymentMethod=true and pass shopperReference plus recurringProcessingModel=Subscription. Subsequent renewals POST /payments referencing the storedPaymentMethodId without shopper interaction.

### How do I capture an authorisation and not just authorise it?

By default, set captureDelayHours appropriately on POST /payments, or call POST /payments/{paymentPspReference}/captures with the amount to capture. Auto-capture and manual-capture behaviour is controlled per merchant account in the Customer Area.

### Can I limit what my agent is allowed to do with the Adyen Checkout API?

Yes. Jentic One is self-hosted by you, so your own rules decide which of the 26 Checkout operations and which credentials the agent may use. You can allow only the operations it needs, such as POST /payments to process a payment or POST /paymentLinks to create a hosted payment link, while keeping others like POST /cancels and POST /donations out of reach. Because this Checkout version takes the payment target in the request body rather than a resource id in the URL path, you scope access at the operation level and the agent can only call what you have granted.