canonical: https://jentic.com/apis/adyen.com/adyen-configuration # Adyen Configuration API The Adyen Configuration API is the core REST surface for Adyen for Platforms. It manages account holders, balance accounts, payment instruments, payment instrument groups, transaction rules, sweeps, network tokens, and grant accounts across a balance platform. The 56 endpoints cover creation, read, update, and lifecycle operations for every structural object Adyen for Platforms exposes - from posting a new accountHolder to retrieving the platform configuration to managing card-level transaction rules. ## For AI agents Manage account holders, balance accounts, payment instruments, sweeps, and transaction rules across an Adyen for Platforms balance platform. ## Scope Does not handle card payment processing, BIN lookup, settlement, or report generation - use for Adyen for Platforms structural configuration only. ## Capabilities - Create and update account holders, including capabilities and KYC association via POST /accountHolders and PATCH /accountHolders/{id} - Provision balance accounts with currencies, default sweeps, and association to an account holder - Issue and manage payment instruments - physical and virtual cards, bank accounts - under POST /paymentInstruments - Configure automated sweeps that move funds between balance accounts on schedule or trigger - Define transaction rules at the account holder, balance account, payment instrument, or instrument group level to control which transactions are allowed - Inspect platform-level configuration via GET /platforms/{id} and manage grant accounts and network tokens ## Use cases ### Onboarding a Platform User End to End When a marketplace or fintech onboards a new seller, freelancer, or sub-merchant, the Configuration API creates the structural objects that represent them in Adyen for Platforms. POST /accountHolders creates the entity, POST /balanceAccounts provisions a balance, and POST /paymentInstruments issues a card or bank account. Each object is updatable as KYC and capabilities evolve. Example prompt: Call POST /accountHolders with legalEntityId, then POST /balanceAccounts referencing that accountHolderId, then POST /paymentInstruments to issue a virtual card on the new balance account ### Dynamic Transaction Rule Management Compliance and risk teams need to apply rules at multiple levels - block international transactions on cards, cap monthly volume on a balance account, or enforce MCC restrictions on a group of instruments. The Configuration API exposes transaction rules at account holder, balance account, payment instrument, and instrument group scope, so an agent or admin tool can adjust rules at the right level on the fly. Example prompt: Call POST /transactionRules with entityType=paymentInstrument, scope to a specific paymentInstrumentId, and a ruleRestrictions block that blocks transactions outside the EU ### Treasury Sweeps Between Balance Accounts Treasury teams use automated sweeps to consolidate funds, fund operating accounts, or enforce minimum balances. The Configuration API's sweep endpoints under /balanceAccounts/{balanceAccountId}/sweeps create, read, update, and delete sweep configurations. Combined with the Transfer webhooks, this gives a closed loop: configure the sweep, then react to its events. Example prompt: Call POST /balanceAccounts/{balanceAccountId}/sweeps with type=push, schedule.type=daily, and counterparty referencing the consolidation balance account ### Agent-Driven Platform Operations via Jentic An ops or fintech-engineering agent can use Jentic to discover and call the right Configuration API operation across 56 endpoints without scraping the Adyen developer portal. The agent searches by intent, loads the operation schema, and executes the call with X-API-Key managed in your Jentic One instance. Example prompt: Use Jentic to search 'create adyen balance account' and execute POST /balanceAccounts with the accountHolderId and currency for a new platform user ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /accountHolders | Create an account holder | | GET | /accountHolders/{id} | Retrieve an account holder by id | | PATCH | /accountHolders/{id} | Update an account holder | | POST | /balanceAccounts | Create a balance account | | GET | /balanceAccounts/{balanceAccountId}/sweeps | List sweeps on a balance account | | POST | /paymentInstruments | Issue a payment instrument (card or bank account) | | POST | /transactionRules | Create a transaction rule | ## Key resources - **Account holders** — Create, read, and update account holders and their capabilities - **Balance accounts** — Provision balance accounts and link them to account holders - **Payment instruments** — Issue and manage cards and bank accounts as payment instruments - **Transaction rules** — Create rules at account holder, balance account, instrument, or group scope - **Sweeps** — Configure automated movement of funds between balance accounts - **Platform** — Read platform-level configuration and grant accounts ## Why Jentic - **Setup:** Wiring the Adyen Configuration API by hand means handling its X-API-Key, basic, and clientKey auth, targeting the balance platform test host, and mapping structural operations across a large surface. Through Jentic you install once, import the Configuration API from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** The Configuration API puts the account holder id in the URL path (/accountHolders/{id}), so a rule can pin your agent to one account holder: it can read and patch that holder and nothing else. You choose the operations it may call, so card issuance and transaction rule writes stay out unless you add them. - **Credential handling:** Your Adyen X-API-Key, basic auth, and clientKey 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 'create an adyen balance account' or 'add a transaction rule', and Jentic returns the matching Configuration API operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Adyen Configuration webhooks** — Webhook events that fire on the same mutations this REST API performs - **Adyen Transfer webhooks** — Receives transfer events triggered by sweeps configured here - **Stripe** — Stripe Connect and Issuing offer a comparable platform-management surface ## FAQ ### What authentication does the Adyen Configuration API use? The API supports an apiKey scheme using the X-API-Key header, HTTP basic auth, and a clientKey query parameter for client-side flows. Through Jentic, the X-API-Key is stored in the encrypted vault so agents call any of the 56 endpoints without holding the raw credential. ### Can I issue cards through the Adyen Configuration API? Yes. POST /paymentInstruments with type=card creates a card under a balance account, and PATCH /paymentInstruments/{id} updates its status. Card-level transaction rules are managed via POST /transactionRules with entityType=paymentInstrument. ### What are the rate limits for the Adyen Configuration API? The OpenAPI spec does not declare programmatic rate limits. Adyen documents per-merchant-account throughput limits in their developer portal - coordinate large onboarding batches with your Adyen account manager and prefer paginated reads where available. ### How do I create a balance account through Jentic? Search Jentic for 'create adyen balance account', load the POST /balanceAccounts operation, and execute it with the accountHolderId and currency. Jentic returns the structured response including the new balanceAccountId for use in downstream calls. ### Does this API send webhook notifications for balance account changes? No - this is the REST surface for mutations. Webhook notifications for the same events are delivered by the BalancePlatformConfigurationNotification webhook spec, which fires balancePlatform.balanceAccount.created and similar events when a mutation here completes. ### Can I list every balance account owned by an account holder? Yes. GET /accountHolders/{id}/balanceAccounts returns the balance accounts belonging to the given account holder. Pair with /accountHolders/{id}/transactionRules to inspect rules attached at the account holder level. ### Can I limit what my agent is allowed to do with the Adyen Configuration API? Yes. Jentic One is self-hosted, so your own rules decide which Configuration API operations and credentials your agent may use. Because the account holder id sits in the URL path (/accountHolders/{id}), you can pin the agent to a single account holder and let it read and patch only that holder. You also pick the exact operations it may call, so card issuance via POST /paymentInstruments and rule writes via POST /transactionRules stay off limits unless you grant them.