canonical: https://jentic.com/apis/adyen.com/adyen-transfers-v3 # Adyen Transfers API The Adyen Transfers API v3 is the Balance Platform interface for moving money between balance accounts, third-party bank accounts, and capital grants. The nine endpoints initiate transfers, approve or cancel pending transfers, return a settled transfer, list and inspect transactions, and request or look up Adyen Capital grants. It is the modern replacement for the deprecated classic Payout API and supports instant payouts, third-party bank transfers, and dual-control approval where required. ## For AI agents Move funds between balance accounts and third-party banks, approve or cancel transfers, return settled transfers, and request capital grants on Adyen's Balance Platform. ## Scope Does not authorise card payments, manage balance account configuration, or onboard legal entities - use only for moving funds, approving transfers, and requesting capital grants on Adyen's Balance Platform. ## Capabilities - Initiate a transfer from a balance account to a third party or another balance account via POST /transfers - Approve a queued, dual-control transfer via POST /transfers/approve and cancel one via POST /transfers/cancel - Return a previously settled transfer to its source via POST /transfers/{transferId}/returns - List or look up transactions on the Balance Platform via GET /transactions and GET /transactions/{id} - Request a capital grant payout via POST /grants and inspect grants via GET /grants and GET /grants/{id} - Authenticate using API key (X-API-Key), basic auth, or a clientKey scheme as declared in the spec ## Use cases ### Marketplace Seller Settlement Marketplaces on Adyen's Balance Platform call POST /transfers to move daily proceeds from the platform's holding balance account to each seller's connected bank account. The Transfers API supports instant rails where the receiving country and bank allow, and falls back to standard rails otherwise. GET /transactions reconciles the resulting movements against the platform's expected ledger. Example prompt: Call POST /transfers with category=bank, amount.value, amount.currency, counterparty.bankAccount, and balanceAccountId for the seller, then GET /transactions for reconciliation ### Dual-Control Transfer Approval Regulated payout flows require segregation of duties. POST /transfers initiated under a dual-control config returns a transferId in a pending state; a separate user with approval rights calls POST /transfers/approve with the transferId, or POST /transfers/cancel to reject. The classic Payout API equivalent required two distinct API credentials; on the Balance Platform the same control is enforced via Balance Platform users and roles. Example prompt: Call POST /transfers/approve with the transferId returned from the original POST /transfers call to release the queued transfer for execution ### Capital Grant Payouts Adyen Capital lets eligible merchants take a financing grant repaid from future card receipts. POST /grants requests a grant payout to the merchant's balance account, GET /grants/{id} returns the grant's status and outstanding repayment, and GET /grants lists the merchant's capital account history. This is the integration surface for marketplaces and platforms offering Capital to their sellers. Example prompt: Call POST /grants with grantOfferId and counterparty.balanceAccount.balanceAccountId to request a Capital grant payout for the merchant ### AI Agent Payout Operations via Jentic An ops agent that processes a daily settlement run searches Jentic for 'send Adyen transfer to bank account', loads the schema for /transfers, and executes per seller from the day's settlement file. Jentic injects X-API-Key from the encrypted vault and the agent never holds the raw secret. The returned transferId is recorded in the operations ledger, and a separate reviewer agent or human approves via /transfers/approve where dual control is configured. Example prompt: Search Jentic for 'send an Adyen transfer to a bank account', load the transfers schema, then execute one call per seller in the daily settlement file ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /transfers | Initiate a transfer | | POST | /transfers/approve | Approve queued transfers | | POST | /transfers/cancel | Cancel queued transfers | | POST | /transfers/{transferId}/returns | Return a settled transfer | | GET | /transactions | List transactions | | GET | /transactions/{id} | Get a transaction by ID | | POST | /grants | Request a capital grant payout | | GET | /grants/{id} | Get a grant by ID | ## Key resources - **Transfers** — Initiate, approve, cancel, and return transfers between balance accounts and third-party banks - **Transactions** — List and inspect transactions on the Balance Platform - **Grants** — Request Adyen Capital grant payouts and inspect grant accounts ## Why Jentic - **Setup:** Wiring the Adyen Transfers API by hand means handling its multiple credential types (an API key, basic-auth, and a clientKey), pointing at the Balance Platform host, and coding your own retry logic around fund movements. Through Jentic you install once, import the Adyen Transfers API from the API Directory, store the credentials once, and your agent calls it. - **Permission scoping:** This API creates and approves transfers and grants through body-driven operations, so scope the agent to the operations it needs, such as requesting a transfer or reading a transaction, rather than to a single account. You choose which operations are in the allowed set, so approving or cancelling transfers is not included unless you add it. - **Credential handling:** Your Adyen API key, basic-auth credential, and clientKey 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 'send a transfer to a bank account' or 'request a capital grant', and Jentic returns the matching Balance Platform operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Adyen Transfers API v4** — Latest major version of the Transfers API - **Adyen Payout API (deprecated)** — Classic-platform payout surface that Transfers API replaces - **Adyen Balance Platform Configuration API** — Configures balance accounts referenced by Transfers API - **Adyen Legal Entity API** — Onboards the legal entities that own the balance accounts ## FAQ ### What authentication does the Adyen Transfers API v3 use? The spec declares ApiKeyAuth (X-API-Key header), BasicAuth, and a clientKey scheme. In production the X-API-Key model is the standard server-side choice; the clientKey is used for client-side flows where applicable. Through Jentic, credentials are stored encrypted in the vault and only a scoped execution token is exposed to the agent. ### Can I send a transfer to a third-party bank account with the Transfers API? Yes. POST /transfers accepts a counterparty.bankAccount object describing the destination IBAN or account number, plus amount, balanceAccountId, and category. Adyen routes the transfer over the appropriate rail (instant where supported, standard otherwise) and returns a transferId for tracking. ### How do I approve or cancel a pending transfer? When dual control is configured, POST /transfers returns a transferId in a pending state. A reviewer with the right role calls POST /transfers/approve with that transferId to release the transfer, or POST /transfers/cancel to reject it. Both endpoints accept a list of transferIds for batch approval or rejection. ### How do I send a transfer with the Adyen Transfers API through Jentic? Search Jentic for 'send an Adyen transfer to a bank account', load the transfers schema, then execute with category=bank, amount, counterparty.bankAccount, and balanceAccountId. Jentic injects X-API-Key from the encrypted vault. Get an account through Jentic One, the self-hosted execution layer. ### What are the rate limits for the Adyen Transfers API? Adyen does not publish a fixed numeric rate limit in the spec; throughput is provisioned per balance platform and risk profile. If 429 responses appear in production, contact Adyen support to review the platform's transfer quota. ### Should I use Transfers v3 or v4 for new integrations? Adyen recommends the latest major version for new integrations; v4 adds GET /transfers list and GET /transfers/{id} alongside refinements to existing endpoints. Use v3 only when an existing integration is already on it; new integrations should target v4. ### Can I limit what my agent is allowed to do with the Adyen Transfers API? Yes. Because you self-host Jentic One, your own rules decide which of this API's operations the agent may call, so you can allow only what a task needs, such as requesting a transfer with POST /transfers or reading movements with GET /transactions. Approving or cancelling transfers via POST /transfers/approve and POST /transfers/cancel is not in the allowed set unless you add it, which keeps dual-control review out of a single agent's reach. Your Adyen credentials stay under your instance and are injected only for the operations you have permitted.