canonical: https://jentic.com/apis/adyen.com/adyen-transfer-webhooks # Adyen Transfer webhooks Adyen Balance Platform Transfer Webhooks (v3) deliver the current accounting webhook surface for incoming and outgoing transfers across an Adyen for Platforms balance platform. The OpenAPI document defines balancePlatform.transfer.created and balancePlatform.transfer.updated events with a typed TransferNotificationRequest payload covering counterparty data, merchant metadata, validation facts, and amount. This is the surface that supersedes the deprecated Payment webhooks v1 - new integrations should target this version. ## For AI agents Receive current Adyen Balance Platform transfer events with typed counterparty, validation, and amount data - the surface that replaced the deprecated payment webhooks. ## Scope Does not handle outbound REST transfers, configuration events, report events, or deprecated v1 payment events - use for current accounting transfer notification schemas only. ## Capabilities - Parse balancePlatform.transfer.created events for newly initiated transfers - Handle balancePlatform.transfer.updated events for status transitions on existing transfers - Read counterparty details - bank account, IBAN, or another balance account - from TransferNotificationCounterParty - Inspect merchant metadata and validation facts attached to a transfer for AML and reconciliation logic - Validate webhook delivery using HTTP basic auth credentials configured in the Adyen Customer Area ## Use cases ### Reconcile Outgoing Payouts in Real Time Platforms running Adyen for Platforms need to know the moment a payout to a connected bank account moves from initiated to booked, authorised, or failed. The balancePlatform.transfer.updated event delivers each status change with the transfer id, status, and counterparty details, so a reconciliation system can update its internal payout record within seconds rather than waiting for a daily report. Example prompt: On a balancePlatform.transfer.updated event with status=booked, mark the matching payout row as settled using transferId from the payload ### Detect Incoming Funding Events When funds arrive at a balance account - whether from a card capture, a manual top-up, or another platform - a balancePlatform.transfer.created event with direction=incoming fires. Treasury systems use this to update available balance projections immediately, instead of polling the balance endpoint. Example prompt: On a balancePlatform.transfer.created event with direction=incoming, increment the projected available balance for balanceAccountId by the amount in the payload ### AML and Validation Fact Routing Each TransferNotificationRequest includes validation facts - sanctions check status, name match score, and similar - that an AML system needs to react to. A receiver can route any transfer with a non-clean validation fact into a manual review queue without waiting for end-of-day batch processing. Example prompt: If TransferNotificationValidationFact.result is not 'success' for any check, post the transferId and counterparty IBAN to the AML manual review queue ### Agent-Driven Transfer Operations via Jentic An ops agent watching transfers can use Jentic to load TransferNotificationRequest, validate inbound webhooks, and chain follow-up REST calls - all with credentials Jentic stores in its vault. The agent reasons about typed counterparty and validation data rather than free-form JSON. Example prompt: Use Jentic to load TransferNotificationRequest, validate the inbound webhook, and on a failed validation fact post a follow-up alert with the transferId and counterparty ## Key resources - **Transfer events** — balancePlatform.transfer.created and updated - **Counterparty data** — Bank account, IBAN, or balance account on the other side of the transfer - **Validation facts** — Per-transfer compliance and validation results ## Why Jentic - **Setup:** Wiring Adyen Transfer webhooks by hand means validating inbound calls with basic auth and parsing accounting transfer JSON that can drive AML and ledger decisions. Through Jentic you install once, import the Transfer webhooks from the API Directory, store the basic auth credential once, and your agent validates payloads against typed schemas. - **Permission scoping:** These are inbound event schemas rather than outbound calls with a resource id in the URL, so you limit the agent to the operations it needs, such as validating a payout-updated or incoming-transfer event. Because you pick the operations, the agent only parses the event types you include. - **Credential handling:** The basic auth credential that validates these webhook calls is stored once, encrypted, by your own Jentic One instance and injected at validation time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'adyen payout updated webhook' or 'incoming transfer webhook', and Jentic returns the matching event with its TransferNotificationRequest schema for typed parsing without browsing the reference docs. ## Related APIs - **Adyen Payment Webhooks (deprecated)** — The deprecated v1 surface this spec replaces - **Adyen Configuration webhooks** — Structural change events for account holders, balance accounts, and instruments - **Adyen Balance Platform Configuration API** — REST API to fetch full transfer or account state when a webhook arrives with only an id ## FAQ ### What authentication does the Transfer webhooks use? Adyen authenticates outbound webhook calls to your server using HTTP basic auth credentials configured in the Adyen Customer Area. Your endpoint must validate the username/password before trusting the payload. Through Jentic, those validation credentials live in your Jentic One instance rather than in handler code. ### Which events does the Transfer webhooks fire? Two event types: balancePlatform.transfer.created and balancePlatform.transfer.updated. Each delivers a typed TransferNotificationRequest payload covering counterparty data (TransferNotificationCounterParty), merchant data, validation facts, and amount. ### Should I use this spec or the deprecated Payment webhooks v1? Use this spec for any new integration. Adyen has deprecated BalancePlatformPaymentNotification-v1; the Transfer webhooks v3 are the current accounting webhook surface and cover both incoming and outgoing transfers with richer counterparty and validation data. ### How do I reconcile a payout to a connected bank account? Subscribe to balancePlatform.transfer.updated and key on the transferId in the payload. Each status change (booked, failed, returned) is delivered as a discrete event, so the receiver can step the payout through your internal state machine in real time. ### How do I parse a Transfer webhook through Jentic? Search Jentic for 'parse adyen transfer webhook', load the TransferNotificationRequest schema, and validate the inbound body before dispatching to your handler. Jentic returns the typed schema so the agent reasons about counterparty and validation data directly. ### Can I limit what my agent is allowed to do with the Adyen Transfer Webhooks? Yes. Because you run Jentic One yourself and set the rules, you decide which of these inbound events your agent can parse, so you can grant only balancePlatform.transfer.updated for payout reconciliation while withholding balancePlatform.transfer.created, or the reverse. These are event schemas the agent validates rather than outbound calls, so scoping the included operations directly limits which TransferNotificationRequest payloads it can read. The basic auth credential that validates the webhook is held and injected by your own instance, so the agent never sees it and only handles the event types you allow.