Adyen

Access and limits

Authentication

Adyen API key

Plans and access

An Adyen merchant account with an API credential that has the Checkout webservice role; Management API roles for account, store, terminal and webhook reads; a Balance Platform API credential for Adyen for Platforms data. Payment links need the Checkout webservice role; stored payment methods need recurring permissions; Management reads need the matching Management API roles. Live calls use your account's assigned live prefix.

Test environment

Adyen test Customer Area with checkout-test.adyen.com; Management and Balance Platform calls then go to management-test.adyen.com and balanceplatform-api-test.adyen.com.

Rate limits

Adyen returns HTTP 429 when limits are exceeded. Nexra honours Retry-After and retries reads and Idempotency-Key writes within bounds.

Pagination

Checkout endpoints return a single page. Management lists page with pageNumber/pageSize (max 100); Configuration API lists use offset/limit with hasNext; Transfers lists follow _links.next cursors.

Provider events

Adyen standard webhooks (AUTHORISATION, PAYMENT_LINK status, CAPTURE, REFUND) are configured in the Customer Area. Flows can start the moment something happens: when a payment succeeds; when a payment is refused; when a payment is captured; when a refund is processed.

Before you build a flow

• Intentional exclusions: /payments, captures, cancels, refunds, reversals, amount updates, donations, gift-card orders, expiring payment links (PATCH), deleting stored payment methods and storing new ones; Transfers API fund transfers, approvals, cancellations, returns, cashouts and grants; creating or changing sweeps, payout settings and schedules, transfer limits, split configurations and payment instruments; card reveal and PINs; /cardDetails and /paymentMethods/balance (they take card data); terminal orders, reassignments and scheduled terminal actions; webhook creation, tests and HMAC generation as operations (the flow trigger registers its own standard webhook and keeps its HMAC key in secure storage); API key and client key generation.
• Management writes are limited to stores (create, update to active or inactive). Closing a store is permanent and is not offered. Merchant accounts, API credentials, users, webhooks, terminal settings and terminal orders are read-only or not exposed; API credential keys, HMAC keys and webhook passwords are never returned; only a flow trigger generates an HMAC key, for the webhook it registers, and that key goes straight to secure storage.
• Management and Balance Platform calls use the environment of the connection's Checkout origin (checkout-test.adyen.com means test; an assigned live prefix means live).
• Balance Platform operations need a separate Balance Platform API key (optional credential) and, for listing account holders, the balance platform ID. Account holder contact details and transfer counterparty bank or card details are not returned.
• Adyen does not document idempotency keys for the Management API, so store creation is not retried after an uncertain response.
• Adyen has no transaction search in the Checkout API; payment status comes from webhooks or reports, not from this connector.
• Stored payment methods return brand, last four and expiry only; BIN, IBAN, holder and owner names are omitted.
• Disputes API: only retrieveApplicableDefenseReasons (read) is offered. Adyen has no dispute list or search endpoint (List chargebacks reads chargebacks booked on Adyen for Platforms balance accounts from transfers); dispute notifications arrive by webhook (CHARGEBACK, NOTIFICATION_OF_CHARGEBACK). Accepting or defending disputes and supplying or deleting defense documents are intentional exclusions. Disputes calls use ca-test.adyen.com or ca-live.adyen.com per the connection's environment and need the API dispute management role.
• Further Management reads (users, API credentials, allowed origins, billing entities, shipping locations, terminal models, products, orders and actions, Android apps and certificates, split configurations, payout settings, Apple Pay domains) are read-only. User emails and names, API and client keys, IP allow-lists, billing-entity email and tax ID, and shipping contact details are never mapped. Terminal settings and logos are not exposed because they contain terminal passcodes and Wi-Fi credentials.
• Balance Platform reads added: balance platform, sweeps, transaction rules, payment instruments (brand, last four, expiry only; never PAN, BIN, CVC, cardholder name or IBAN), payment instrument groups and transfer limits. Card reveal, PINs, network tokens, mandates, tax forms, grants, payout schedules and every Balance Platform write remain excluded.
• Adyen reports (settlement details, payment accounting, Balance Platform accounting) are CSV files and are not downloaded by this connector; payment status comes from webhooks or Balance Platform transfers.
• Reconciliation (payouts, fees, refunds, chargebacks) is read from Balance Platform transfers and needs Adyen for Platforms with the Balance Platform API key. Adyen's API has no payout, fee, refund or settlement list for a classic merchant account: those figures are only in the settlement details and payment accounting reports, which are CSV downloads this connector does not fetch.
• Payout lines: Adyen's API does not link balance transactions to the payout that paid them out, so there is no per-payout transaction list; List balance transactions returns the booked lines for a time window instead.
• Terminal products, actions, Android apps and certificates, and shipping locations end paging on a short page because Adyen returns no total for these lists.

Developer reference