--- title: "Top-up webhooks" description: "Stay updated about changes to the recurring top-ups on your platform." url: "https://docs.adyen.com/issuing/add-manage-funds/top-ups/top-up-webhooks" source_url: "https://docs.adyen.com/issuing/add-manage-funds/top-ups/top-up-webhooks.md" canonical: "https://docs.adyen.com/issuing/add-manage-funds/top-ups/top-up-webhooks" last_modified: "2020-09-11T17:20:00+02:00" language: "en" --- # Top-up webhooks Stay updated about changes to the recurring top-ups on your platform. [View source](/issuing/add-manage-funds/top-ups/top-up-webhooks.md) Managing recurring top-ups using the Top-up API is an asynchronous process. A successful API response does not necessarily indicate that a recurring top-up is successfully created, updated, or deleted. To stay up to date about changes to the recurring top-ups in your platform, we recommend that you subscribe to [Configuration webhooks](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/overview). To stay up to date about the direct debit triggered by the recurring top-up, we recommend that you subscribe to [Transfer webhooks](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/overview) and [Transaction webhooks](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/overview). ## Requirements | Requirement | Description | | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | Adyen Issuing integration. | | **[Webhooks](/development-resources/webhooks)** | Subscribe to the following webhook(s):- **[Configuration webhooks](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/overview)**: to stay updated about changes to recurring top-ups in your platform. - **[Transfer webhooks](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/overview)**: to stay updated about status changes to the direct debit triggered by the recurring top-up. - **[Transaction webhooks](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/overview)**: to stay updated about the movement of funds as a result of a triggered direct debit top-up. | | **Setup steps** | Before you begin:- Make sure that your server can [receive and accept webhooks](/issuing/set-up-webhooks). | ## Configuration webhooks To stay updated about changes to recurring top-ups in your balance platform, you can listen to the following webhooks: * `balancePlatform.balanceAccount.recurringTopUp.created`: sent when a new recurring top-up is successfully created. * `balancePlatform.balanceAccount.recurringTopUp.updated`: sent when an existing recurring top-up is successfully updated. * `balancePlatform.balanceAccount.recurringTopUp.deleted`: sent when an existing recurring top-up is successfully deleted. In these webhooks, pay attention to the following fields: | Parameter | Description | | --------------------------- | ------------------------------------------------------------------------------------------- | | `accountId` | The unique identifier of the balance account on which the recurring top-up is configured. | | `webhookTopUpConfiguration` | An object that contains the details of the recurring top-up. | | `type` | The type of webhook, indicating whether a recurring top-up is created, updated, or deleted. | ### Examples ** #### Recurring top-up created ```json { "data": { "accountId": "BA00000000000000000000001", "balancePlatform": "YOUR_BALANCE_PLATFORM", "webhookTopUpConfiguration": { "id": "TU0000000000000000000000000001", "status": "inactive", "trigger": { "threshold": { "value": 5000, "currency": "EUR" } }, "description": "Testing recurring top up", "topUpAmount": { "fixedAmount": { "value": 1000, "currency": "EUR" } }, "counterparty": { "transferInstrumentId": "TI00000000000000000000001" } } }, "type": "balancePlatform.balanceAccount.recurringTopUp.created", "timestamp": "2026-02-26T09:39:14.25Z", "environment": "test" } ``` ** #### Recurring top-up updated ```json { "data": { "accountId": "BA00000000000000000000001, "balancePlatform": "YOUR_BALANCE_PLATFORM", "webhookTopUpConfiguration": { "id": "TU0000000000000000000000000001", "status": "inactive", "trigger": { "threshold": { "value": 5000, "currency": "EUR" } }, "description": "Updating description", "topUpAmount": { "fixedAmount": { "value": 1000, "currency": "EUR" } }, "counterparty": { "transferInstrumentId": "TI00000000000000000000001" } } }, "type": "balancePlatform.balanceAccount.recurringTopUp.updated", "timestamp": "2026-02-26T09:43:02.401Z", "environment": "test" } ``` ** #### Recurring top-up deleted ```json { "data": { "accountId": "BA00000000000000000000001", "balancePlatform": "YOUR_BALANCE_PLATFORM", "webhookTopUpConfiguration": { "id": "TU0000000000000000000000000001", "status": "inactive", "trigger": { "threshold": { "value": 5000, "currency": "EUR" } }, "description": "Testing recurring top up", "topUpAmount": { "fixedAmount": { "value": 1000, "currency": "EUR" } }, "counterparty": { "transferInstrumentId": "TI00000000000000000000001" } } }, "type": "balancePlatform.balanceAccount.recurringTopUp.deleted", "timestamp": "2026-02-26T09:34:03.894Z", "environment": "test" } ``` ## Transfer webhooks When a top-up is triggered on your balance platform, Adyen sends the following transfer webhooks: * [balancePlatform.transfer.created](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created): which informs your server that an outgoing direct debit request is initiated from a balance account in your balance platform. * [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated): which informs your server of the transfer status changes. ### Identify top-up related transfer webhooks You can identify transfer webhooks triggered by payout-related events by looking at the following values: | Parameter | Description | Value | | ---------- | ----------------------------------- | ------------------- | | `category` | The category of the transfer. | **bank** | | `type` | Specifies the type of the transfer. | **bankDirectDebit** | ### Examples ** #### Top-up initiated ```bash { "data": { "accountHolder": { "id": "AH00000000000000000000001" }, "amount": { "currency": "EUR", "value": 100000 }, "balanceAccount": { "id": "BA00000000000000000000001" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "currency": "EUR", "received": 100000 } ], "category": "bank", "categoryData": { "priority": "regular", "type": "bank" }, "counterparty": { "transferInstrumentId": "SE00000000000000000000001" }, "creationDate": "2023-02-28T13:30:05+02:00", "direction": "outgoing", "directDebitInformation": { "dateOfSignature": "2023-01-01T01:00:00+01:00", "dueDate": "2024-08-23T02:00:00+02:00", "mandateId": "EBAClearing-MANDAT001", "sequenceType": "FRST" }, "events": [ { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000001", "mutations": [ { "currency": "EUR", "received": 100000 } ], "status": "received", "type": "accounting" } ], "id": "JN4227222422265", "reason": "approved", "sequenceNumber": 1, "status": "received", "transactionRulesResult": { "allHardBlockRulesPassed": true }, "type": "bankDirectDebit", "ultimateParty": { "type": "unknown", "fullName": "***", "useAsParty": false } }, "environment": "test", "type": "balancePlatform.transfer.created" } ``` ** #### Top-up authorized ```bash { "data": { "accountHolder": { "id": "AH00000000000000000000001" }, "amount": { "currency": "EUR", "value": 100000 }, "balanceAccount": { "id": "BA00000000000000000000001" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "currency": "EUR", "received": 0, "reserved": 100000 } ], "category": "bank", "categoryData": { "priority": "regular", "type": "bank" }, "counterparty": { "transferInstrumentId": "SE00000000000000000000001" }, "creationDate": "2023-02-28T13:30:05+02:00", "direction": "outgoing", "directDebitInformation": { "dateOfSignature": "2023-01-01T01:00:00+01:00", "dueDate": "2024-08-23T02:00:00+02:00", "mandateId": "EBAClearing-MANDAT001", "sequenceType": "FRST" }, "events": [ { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000001", "mutations": [ { "currency": "EUR", "received": 100000 } ], "status": "received", "type": "accounting" }, { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000002", "mutations": [ { "currency": "EUR", "received": -100000, "reserved": 100000 } ], "status": "authorised", "type": "accounting" } ], "id": "JN4227222422265", "reason": "approved", "sequenceNumber": 2, "status": "authorised", "transactionRulesResult": { "allHardBlockRulesPassed": true }, "type": "bankDirectDebit", "ultimateParty": { "type": "unknown", "fullName": "***", "useAsParty": false } }, "environment": "test", "type": "balancePlatform.transfer.updated" } ``` ** #### Top-up booked ```bash { "data": { "accountHolder": { "id": "AH00000000000000000000001" }, "amount": { "currency": "EUR", "value": 100000 }, "balanceAccount": { "id": "BA00000000000000000000001" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "balance": 100000, "currency": "EUR", "received": 0, "reserved": 0 } ], "category": "bank", "categoryData": { "priority": "regular", "type": "bank" }, "counterparty": { "transferInstrumentId": "SE00000000000000000000001" }, "creationDate": "2023-02-28T13:30:05+02:00", "direction": "incoming", "events": [ { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000001", "mutations": [ { "currency": "EUR", "received": 100000 } ], "status": "received", "type": "accounting" }, { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000002", "mutations": [ { "currency": "EUR", "received": -100000, "reserved": 100000 } ], "status": "authorised", "type": "accounting" }, { "bookingDate": "2023-02-28T13:30:20+02:00", "id": "EVJN00000000000000000000000003", "mutations": [ { "balance": 100000, "currency": "EUR", "received": 0, "reserved": -100000 } ], "status": "booked", "transactionId": "EVJN42272224222B5JB8BRC84N686ZEUR", "type": "accounting", "valueDate": "2023-03-01T00:00:00+02:00" } ], "id": "JN4227222422265", "reason": "approved", "sequenceNumber": 3, "status": "booked", "type": "bankDirectDebit" }, "environment": "test", "type": "balancePlatform.transfer.updated" } ``` ## Transfer failure examples A transfer can fail during processing even if the initial API request is accepted. When a transfer cannot be completed, the status of the transfer is updated, and a `balancePlatform.transfer.updated` notification is sent. Use the following examples to identify the reasons for these failures. In the following example, a transfer is rejected if it fails internal validation or transaction rules before it can be finalized. **Rejected** ```json { "data": { "accountHolder": { "description": "Your description of the account holder", "id": "AH00000000000000000000002", "reference": "Your reference for the account holder" }, "amount": { "currency": "EUR", "value": 1000 }, "balanceAccount": { "description": "Your description of the target balance account", "id": "BA00000000000000000000002" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "balance": -1000, "currency": "EUR", "received": 0, "reserved": 0 } ], "category": "bank", "categoryData": { "type": "bank" }, "counterparty": { "bankAccount": { "accountHolder": { "fullName": "John Smith", "type": "unknown" }, "accountIdentification": { "iban": "FR0000000000000000000000117", "type": "iban" } } }, "creationDate": "2024-08-28T13:30:05+02:00", "directDebitInformation": { "dateOfSignature": "2023-01-01T01:00:00+01:00", "dueDate": "2024-08-23T02:00:00+02:00", "mandateId": "EBAClearing-MANDAT001", "sequenceType": "FRST" }, "direction": "incoming", "events": [ { "bookingDate": "2024-08-28T13:30:18+02:00", "id": "JDRF00000000000000000000000001", "mutations": [ { "currency": "EUR", "received": -1000 } ], "status": "received", "type": "accounting" }, { "bookingDate": "2024-08-28T13:30:18+02:00", "id": "JDRF00000000000000000000000002", "mutations": [ { "currency": "EUR", "received": 1000, "reserved": -1000 } ], "status": "authorised", "type": "accounting" }, { "bookingDate": "2024-08-28T13:30:18+02:00", "id": "JDRF00000000000000000000000003", "mutations": [ { "balance": -1000, "currency": "EUR", "received": 0, "reserved": 1000 } ], "status": "booked", "transactionId": "JDRF00000000000000000000000MEUR", "type": "accounting", "valueDate": "2024-08-28T14:00:00+02:00" }, { "bookingDate": "2024-09-12T10:25:12+02:00", "id": "JDRF00000000000000000000000004", "mutations": [ { "balance": 1000, "currency": "EUR", "received": 0, "reserved": -1000 } ], "status": "rejected", "transactionId": "JDRF00000000000000000000000MEUR", "type": "accounting", "valueDate": "2024-09-12T14:00:00+02:00" } ], "id": "2WT1N05XXY7P9XH9", "paymentInstrument": { "description": "Your reference for the payment instrument", "id": "PI00000000000000000000001" }, "reason": "approved", "reference": "Your reference for the transfer", "referenceForBeneficiary": "The sender's reference for the beneficiary", "sequenceNumber": 3, "status": "rejected", "transactionRulesResult": { "allHardBlockRulesPassed": true }, "type": "bankDirectDebit" }, "environment": "test", "timestamp": "2024-08-28T13:27:05+02:00", "type": "balancePlatform.transfer.updated" } ``` In the following example, a transfer is marked as returned when the funds reach the destination bank but are sent back, usually due to a closed account or incorrect beneficiary details. **Returned** ```json { "data": { "accountHolder": { "description": "Your description of the account holder", "id": "AH00000000000000000000002", "reference": "Your reference for the account holder" }, "amount": { "currency": "EUR", "value": 1000 }, "balanceAccount": { "description": "Your description of the target balance account", "id": "BA00000000000000000000002" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "balance": -1000, "currency": "EUR", "received": 0, "reserved": 0 } ], "category": "bank", "categoryData": { "type": "bank" }, "counterparty": { "bankAccount": { "accountHolder": { "fullName": "John Smith", "type": "unknown" }, "accountIdentification": { "iban": "FR0000000000000000000000117", "type": "iban" } } }, "creationDate": "2024-08-28T13:30:05+02:00", "directDebitInformation": { "dateOfSignature": "2023-01-01T01:00:00+01:00", "dueDate": "2024-08-23T02:00:00+02:00", "mandateId": "EBAClearing-MANDAT001", "sequenceType": "FRST" }, "direction": "incoming", "events": [ { "bookingDate": "2024-08-28T13:30:18+02:00", "id": "JDRF00000000000000000000000001", "mutations": [ { "currency": "EUR", "received": -1000 } ], "status": "received", "type": "accounting" }, { "bookingDate": "2024-08-28T13:30:18+02:00", "id": "JDRF00000000000000000000000002", "mutations": [ { "currency": "EUR", "received": 1000, "reserved": -1000 } ], "status": "authorised", "type": "accounting" }, { "bookingDate": "2024-08-28T13:30:18+02:00", "id": "JDRF00000000000000000000000003", "mutations": [ { "balance": -1000, "currency": "EUR", "received": 0, "reserved": 1000 } ], "status": "booked", "transactionId": "JDRF00000000000000000000000MEUR", "type": "accounting", "valueDate": "2024-08-28T14:00:00+02:00" }, { "bookingDate": "2024-09-12T10:25:12+02:00", "id": "JDRF00000000000000000000000004", "mutations": [ { "balance": 1000, "currency": "EUR", "received": 0, "reserved": -1000 } ], "status": "returned", "transactionId": "JDRF00000000000000000000000MEUR", "type": "accounting", "valueDate": "2024-09-12T14:00:00+02:00" } ], "id": "2WT1N05XXY7P9XH9", "paymentInstrument": { "description": "Your reference for the payment instrument", "id": "PI00000000000000000000001" }, "reason": "approved", "reference": "Your reference for the transfer", "referenceForBeneficiary": "The sender's reference for the beneficiary", "sequenceNumber": 3, "status": "returned", "transactionRulesResult": { "allHardBlockRulesPassed": true }, "type": "bankDirectDebit" }, "environment": "test", "timestamp": "2024-08-28T13:27:05+02:00", "type": "balancePlatform.transfer.updated" } ``` ## Transaction webhooks The transaction webhook [balancePlatform.transaction.created](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created) informs your server that Adyen has credited funds to your balance account. [Transaction webhooks](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/overview) can be used in combination with [Transfer webhooks](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/overview) to stay fully up to date about the status of your transfers. While a transfer webhook is sent for every status change, transaction webhooks are only sent when the funds from the transfer are credited to the balance account. Here is an example of a transaction webhook you receive when a top-up is credited to your balance account: **Transaction created for top-up** ```bash { "data": { "id": "EVJN00000000000000000000000002EUR", "amount": { "value": 100000, "currency": "EUR" }, "status": "booked", "transfer": { "categoryData": { "priority": "regular", "type": "bank" }, "id": "3JNC3O5ZVFLLGV4B", "reference": "automatically-generated-reference" }, "valueDate": "2023-08-11T16:19:35+02:00", "bookingDate": "2023-08-11T16:19:45+02:00", "creationDate": "2023-08-11T16:19:35+02:00", "accountHolder": { "id": "AH00000000000000000000001", "description": "Your description for the account holder", "reference": "Your reference for the account holder" }, "balanceAccount": { "id": "BA00000000000000000000001", "description": "Your description for the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM" }, "type": "balancePlatform.transaction.created", "environment": "test" ``` ## See also ###### [Funds transfers](/issuing/add-manage-funds/funds-transfers) [Transfer funds internally to balance accounts.](/issuing/add-manage-funds/funds-transfers) ###### [Split payments](/issuing/add-manage-funds/split-payments) [Process payments and split the funds between your balance accounts.](/issuing/add-manage-funds/split-payments)