Create an AccountHolder via POST /accountholders in the Adyen Balance Platform API; provide legalEntityId (created separately via the Legal Entity Management API) and set capabilities such as receivePayments and sendToTransferInstrument
Create a BalanceAccount linked to the AccountHolder via POST /balanceaccounts; specify accountHolderId and the defaultCurrencyCode for the account
Monitor AccountHolder capability verification status via webhook notifications (accountHolder.created, accountHolder.updated) — capabilities may be in Pending, Valid, or Invalid status pending KYC verification
Create a TransferInstrument for the payout bank account via POST /transferinstruments; provide the AccountHolder's legalEntityId and the bank account details
Configure a Sweep on the BalanceAccount via POST /balanceaccounts/{id}/sweeps; set counterparty.transferInstrumentId, currency, schedule (e.g., daily), and triggerAmount or schedule.type to automate payouts when balance exceeds a threshold
Test the sweep configuration in the Adyen test environment and verify that sweep events fire correctly by checking transferInstrument status and sweep execution via GET /balanceaccounts/{id}/sweeps
Known gotchas
Adyen's KYC verification for AccountHolders is asynchronous — capabilities like sendToTransferInstrument may remain in Pending status for hours or days pending document review; build your onboarding flow to handle this asynchronous state and notify sellers when they become active
TransferInstrument bank accounts must also pass verification before sweeps can execute — Adyen may perform micro-deposit verification or document-based verification depending on the country and bank; check current verification requirements per geography
Sweep schedules and trigger amounts interact — if you set both a schedule and a triggerAmount, consult the current Adyen docs carefully to understand when sweeps execute, as behavior may differ from a purely time-based or purely threshold-based sweep
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp