--- title: "Refund with split instructions" description: "Split a refund between the balance accounts in your platform." url: "https://docs.adyen.com/platforms/in-person-payments/split-transactions/split-refunds/refund-split-instructions" source_url: "https://docs.adyen.com/platforms/in-person-payments/split-transactions/split-refunds/refund-split-instructions.md" canonical: "https://docs.adyen.com/platforms/in-person-payments/split-transactions/split-refunds/refund-split-instructions" last_modified: "2024-01-24T11:14:00+01:00" language: "en" --- # Refund with split instructions Split a refund between the balance accounts in your platform. [View source](/platforms/in-person-payments/split-transactions/split-refunds/refund-split-instructions.md) You can always be in control of funds movements in your platform if you provide split instructions in your refund requests, and you can support different refund scenarios, such as partial and multiple partial refunds. You can split a refund into: * The sale amount that is refunded * Your platform's commission that is now refunded * The [transaction fees](/platforms/in-person-payments/transaction-fees) incurred by the refund ## Requirements In addition to the [general requirements](/platforms/in-person-payments#requirements) for in-person payments with an Adyen for Platforms integration, take into account the following information. | Requirement | Description | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Integration type** | A [Terminal API](/point-of-sale/design-your-integration/terminal-api) integration with [payment terminals](/point-of-sale/what-we-support/select-your-terminals) or with a [Mobile solution](/point-of-sale/ipp-mobile).The standalone solution does not support adding split instructions to individual referenced refund requests. | | **[Webhooks](/development-resources/webhooks)** | Listen to the following webhook events:- [**CANCEL\_OR\_REFUND**](/point-of-sale/basic-tapi-integration/refund-payment/refund-webhooks#cancel-or-refund-webhook/) | | **Limitations** | Take into account:- Some payment methods do not support partial refunds and/or multiple partial refunds. You can check this in the [overview of payment methods](/payment-methods). - Refunds can only be deducted from the balance accounts to which the payment was credited. | ## Make a partial refund with split instructions The process is the same as for [providing split instructions in a Terminal API payment request](/platforms/in-person-payments/split-transactions/split-payments-at-authorization): * You gather the split instructions and format these either as a JSON object converted to a Base64-encoded string, or as a string of concatenated key-value pairs. * Then you pass the resulting string in the `SaleToAcquirerData` field. The main difference is that for a refund you need to use a reversal request, not a payment request. 1. Collect the following information: * From the [POIData.POITransactionID](https://docs.adyen.com/api-explorer/terminal-api/latest/post/payment#responses-200-POIData-POITransactionID) object in the Terminal API payment response: The `TransactionID` and `TimeStamp` of the original payment. * From the [transfer webhooks related to the original payment](/platforms/in-person-payments/split-transactions/split-payments-at-authorization#track-fund-movements): The split instructions of the original payment, specifically the `split.item[ITEM_NUMBER].reference` values. 2. [Gather the split instructions](/platforms/in-person-payments/split-transactions/split-payments-at-authorization#gather-data), taking into account the following: * For the `split.item[ITEM_NUMBER].reference` values in the reversal request, you must use the same reference values as in the payment that you are refunding. * The amounts that the refund will be split into will be *deducted* from the relevant balance accounts. * Refunds can only be deducted from the balance accounts to which the payment was credited. 3. Format the split instructions in one of the following ways: * **Option 1**: as a string of form-encoded key-value pairs (using **&** as a separator). * **Option 2**: as a JSON object converted to a Base64-encoded string. As an example, we issue a partial refund of USD 40.00 for an original split payment of USD 80.00. * A refund amount of USD 37.50 is debited from the user's balance account **BA00000000000000000000001**. * A commission of USD 2.50 is debited from your liable balance account. ### Tab: Key-value pairs 1. Turn the split instructions you gathered into key-value pairs. For a partial refund, also include the currency in the format `currency=ABC`, where `ABC` is the three-letter [currency code](/development-resources/currency-codes). This must match the currency of the original payment. For a full refund, you can omit the `currency` parameter. **Key-value pairs for split partial refund** ```raw currency=USD split.api=1 split.nrOfItems=2 split.totalAmount=4000 split.currencyCode=USD split.item1.amount=3750 split.item1.type=BalanceAccount split.item1.account=BA00000000000000000000001 split.item1.reference=Your sale reference from the payment split.item1.description=Your description for the refund amount split.item2.amount=250 split.item2.type=Commission split.item2.reference=Your commission reference from the payment split.item2.description=Your description for your commission ``` 2. Concatenate the key-value pairs into a string by separating them with ampersands (**&**). **Concatenated key-value pairs** ```bash currency=USD&split.api=1&split.nrOfItems=2&split.totalAmount=4000&split.currencyCode=USD&split.item1.amount=3750&split.item1.type=BalanceAccount&split.item1.account=BA00000000000000000000001&split.item1.reference=Your sale reference from the payment&split.item1.description=Your description for the refund amount&split.item2.amount=250&split.item2.type=Commission&split.item2.reference=Your commission reference from the payment&split.item2.description=Your description for your commission ``` ### Tab: Base64-encoded JSON 1. Create a JSON object consisting of an `additionalData` object containing the split instructions you gathered. For a partial refund, also include the currency in the format `"currency":"ABC"` where `ABC` is the three-letter [currency code](/development-resources/currency-codes). This must match the currency of the original payment. For a full refund, you can omit the `currency` parameter. **JSON object for split partial refund** ```json { "currency":"USD", "additionalData": { "split.api": "1", "split.nrOfItems": "2", "split.totalAmount": "4000", "split.currencyCode": "USD", "split.item1.amount": "3750", "split.item1.type": "BalanceAccount", "split.item1.account": "BA00000000000000000000001", "split.item1.reference": "Your sale reference from the payment", "split.item1.description": "Your description for the refund amount", "split.item2.amount": "250", "split.item2.type": "Commission", "split.item2.reference": "Your commission reference from the payment", "split.item2.description": "Your description for your commission" } } ``` 2. Encode the JSON object to Base64. **Base64 string** ```bash ewogICAgICJjdXJyZW5jeSI6IlVTRCIsCiAgICAgImFkZGl0aW9uYWxEYXRhIjogewogICAgICAgICAic3BsaXQuYXBpIjogIjEiLAogICAgICAgICAic3BsaXQubnJPZkl0ZW1zIjogIjIiLAogICAgICAgICAic3BsaXQudG90YWxBbW91bnQiOiAiNDAwMCIsCiAgICAgICAgICJzcGxpdC5jdXJyZW5jeUNvZGUiOiAiVVNEIiwKICAgICAgICAgInNwbGl0Lml0ZW0xLmFtb3VudCI6ICIzNzUwIiwKICAgICAgICAgInNwbGl0Lml0ZW0xLnR5cGUiOiAiQmFsYW5jZUFjY291bnQiLAogICAgICAgICAic3BsaXQuaXRlbTEuYWNjb3VudCI6ICJCQTAwMDAwMDAwMDAwMDAwMDAwMDAwMDAxIiwKICAgICAgICAgInNwbGl0Lml0ZW0xLnJlZmVyZW5jZSI6ICJZb3VyIHNhbGUgcmVmZXJlbmNlIGZyb20gdGhlIHBheW1lbnQiLAogICAgICAgICAic3BsaXQuaXRlbTEuZGVzY3JpcHRpb24iOiAiWW91ciBkZXNjcmlwdGlvbiBmb3IgdGhlIHJlZnVuZCBhbW91bnQiLAogICAgICAgICAic3BsaXQuaXRlbTIuYW1vdW50IjogIjI1MCIsCiAgICAgICAgICJzcGxpdC5pdGVtMi50eXBlIjogIkNvbW1pc3Npb24iLAogICAgICAgICAic3BsaXQuaXRlbTIucmVmZXJlbmNlIjogIllvdXIgY29tbWlzc2lvbiByZWZlcmVuY2UgZnJvbSB0aGUgcGF5bWVudCIsCiAgICAgICAgICJzcGxpdC5pdGVtMi5kZXNjcmlwdGlvbiI6ICJZb3VyIGRlc2NyaXB0aW9uIGZvciB5b3VyIGNvbW1pc3Npb24iCiAgICAgfQp9 ``` 4. Make a [Terminal API](/point-of-sale/design-your-integration/terminal-api) reversal request specifying: * The standard [`SaleToPOIRequest.MessageHeader` ](/point-of-sale/design-your-integration/terminal-api#request-message-header)object, with `MessageClass` set to **Service** and `MessageCategory` set to **Reversal**. | Parameter | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ProtocolVersion` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **3.0** | | `MessageClass` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Service** | | `MessageCategory` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Reversal** | | `MessageType` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Request** | | `ServiceID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (`POIID`) being used. | | `SaleID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique ID for the POS system component to send this request from. | | `POIID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique ID of the terminal to send this request to. Format: *\[device model]-\[serial number]*. | * The [ReversalRequest](https://docs.adyen.com/api-explorer/terminal-api/latest/post/reversal) object with: | Parameter | Required | Description | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OriginalPOITransaction.POITransactionID` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | An object with:- `TransactionID`: The transaction identifier of the original payment in the format `tenderReference.pspReference`. For example, **BV0q001765198054002.CWBC43ZX2VTFWR82** - `TimeStamp`: The date and time of the original payment request in [UTC format](https://en.wikipedia.org/wiki/ISO_8601#Coordinated_Universal_Time_\(UTC\)). | | `ReversalReason` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Set to **MerchantCancel**. | | `ReversedAmount` | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | Required for partial refunds. The refunded amount. If not included, defaults to the authorized amount of the referenced payment. Specify the amount as a number (not a string) with a decimal point. Do not use minor units. For example, for an amount of USD 10 specify **10.00** (not *1000*). | | `SaleData.SaleToAcquirerData` | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | The formatted string of split instructions for the refund. For a partial refund, the string must also include the currency of the partial refund. This must match the currency of the original payment and must be provided in the format `"currency":"ABC"` (or `currency=ABC` if using key-value pairs), where `ABC` is the three-letter [currency code](/development-resources/currency-codes). | | `SaleData.SaleTransactionID` | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | Required for partial refunds. An object with:- `TransactionID`: Your reference to identify the refund. We recommend using a unique value per (partial) refund. - `TimeStamp`: The date and time of the request in [UTC format](https://en.wikipedia.org/wiki/ISO_8601#Coordinated_Universal_Time_\(UTC\)). | **Partial refund with split instructions** ```json { "SaleToPOIRequest":{ "MessageHeader":{ "ProtocolVersion": "3.0", "MessageClass": "Service", "MessageCategory": "Reversal", "MessageType": "Request", "ServiceID": "207111107", "SaleID": "POSSystemID12345", "POIID": "V400m-324688179" }, "ReversalRequest":{ "OriginalPOITransaction":{ "POITransactionID":{ "TransactionID": "BV0q001765198054002.CWBC43ZX2VTFWR82", "TimeStamp": "2025-10-20T12:08:45.004Z" } }, "ReversalReason": "MerchantCancel", "ReversedAmount": 40.00, "SaleData":{ "SaleToAcquirerData": "currency=USD&split.api=1&split.nrOfItems=2&split.totalAmount=4000&split.currencyCode=USD&split.item1.amount=3750&split.item1.type=BalanceAccount&split.item1.account=BA00000000000000000000001&split.item1.reference=Your sale reference from the payment&split.item1.description=Your description for the refund amount&split.item2.amount=250&split.item2.type=Commission&split.item2.reference=Your commission reference from the payment&split.item2.description=Your description for your commission", "SaleTransactionID":{ "TimeStamp": "2025-10-20T15:04:14.004Z", "TransactionID": "27911" } } } } } ``` The payment terminal shows a waiting screen until you receive a response. 5. When you receive the [ReversalResponse](https://docs.adyen.com/api-explorer/terminal-api/latest/post/reversal/#responses-200) note the following: | Parameter | Description | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Response.Result` | **Success** means we received your request. The refund itself will be processed asynchronously. | | `Response.ReversedAmount` | The partial refund amount that we will try to get authorized. | | `POIData.POITransactionID.TransactionID` | The PSP reference for this refund request. | | `PaymentReceipt` | The generated receipt data. This includes **REFUND REQUESTED**. | | `Response.AdditionalResponse` | This includes:- `posOriginalAmountValue`: The amount (in [minor units](/development-resources/currency-codes)) of the original payment. - `posAuthAmountValue`: The refund amount (in minor units) that we will try to get authorized. - `merchantReference`: The `SaleData.SaleTransactionID.TransactionID` from the partial refund request. - `pspReference`: The PSP reference for this refund request. | **Response for the partial refund** ```json { "SaleToPOIResponse": { "MessageHeader": { "MessageCategory": "Reversal", "MessageClass": "Service", "MessageType": "Response", "POIID": "V400m-324688179", "ProtocolVersion": "3.0", "SaleID": "POSSystemID12345", "ServiceID": "207111107" }, "ReversalResponse": { "POIData": { "POITransactionID": { "TimeStamp": "2025-10-20T15:04:15.004Z", "TransactionID": "TF995R5G6L2GWR82" } }, "PaymentReceipt": [...], "Response": { "AdditionalResponse": "...posAuthAmountCurrency=USD&posAuthAmountValue=4000&posOriginalAmountValue=8000&pspReference=KHLWK3Z3FZTQ7RT5...", "Result": "Success", "ReversedAmount": 40 } } } } ``` If your request failed, the [ReversalResponse.Response](https://docs.adyen.com/api-explorer/terminal-api/latest/post/reversal/#responses-200-Response) contains: * `Result`: **Failure** * `AdditionalResponse`: This includes a `message` explaining why the request failed. For example: * *Original pspReference required for this operation*: Messages like this tell you how to fix the request so you can try again. * *Transaction is already voided*: This message tells you that we already received a full reversal request for the original transaction. 6. Wait for the [CANCEL\_OR\_REFUND](https://docs.adyen.com/api-explorer/Webhooks/latest/post/CANCEL_OR_REFUND) webhook event to learn the outcome of the refund request. Refunds are always processed asynchronously. ## Full refund with split instructions To refund the full amount of the original payment, your Terminal API reversal request requires less parameters than to refund a partial amount. Other than that, the procedure is the same. The following example shows a reversal request for a full refund of a USD 80.00 payment, where the split instructions differ from the payment: * A refund amount of USD 76.00 is debited from the user's balance account **BA00000000000000000000001**. * A commission of USD 4.00 is debited from your liable balance account. **Full refund with split instructions as key-value pairs** ```json { "SaleToPOIRequest":{ "MessageHeader":{ "ProtocolVersion":"3.0", "MessageClass":"Service", "MessageCategory":"Reversal", "MessageType":"Request", "ServiceID":"207111107", "SaleID":"POSSystemID12345", "POIID":"V400m-324688179" }, "ReversalRequest":{ "OriginalPOITransaction":{ "POITransactionID":{ "TransactionID":"BV0q001765198054002.CWBC43ZX2VTFWR82", "TimeStamp":"2025-10-20T12:08:45.004Z" } }, "ReversalReason":"MerchantCancel", "SaleData":{ "SaleToAcquirerData":"split.api=1&split.nrOfItems=2&split.totalAmount=8000&split.currencyCode=USD&split.item1.amount=7600&split.item1.type=BalanceAccount&split.item1.account=BA00000000000000000000001&split.item1.reference=Your sale reference from the payment&split.item1.description=Your description for the refund amount&split.item2.amount=400&split.item2.type=Commission&split.item2.reference=Your commission reference from the payment&split.item2.description=Your description for the commission" } } } } ``` As you can see, for a full refund with split instructions the [ReversalRequest](https://docs.adyen.com/api-explorer/terminal-api/latest/post/reversal) object only needs these parameters: | Parameter | Required | Description | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OriginalPOITransaction.POITransactionID` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | An object with:- `TransactionID`: The transaction identifier of the original payment in the format `tenderReference.pspReference`. For example, **BV0q001765198054002.CWBC43ZX2VTFWR82** - `TimeStamp`: The date and time of the original payment request in [UTC format](https://en.wikipedia.org/wiki/ISO_8601#Coordinated_Universal_Time_\(UTC\)). | | `ReversalReason` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Set to **MerchantCancel**. | | `SaleData.SaleToAcquirerData` | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | The formatted string of split instructions for the refund. There is not need to add a separate `currency` parameter. | The [ReversalResponse](https://docs.adyen.com/api-explorer/terminal-api/latest/post/reversal/#responses-200) does not contain a `ReversedAmount` because the full amount from the payment referenced in the `POITransactionID` of the reversal request will be refunded. ## Track fund movements To track the status of the funds transfers initiated by a refund: 1. Listen to the following webhooks: * [Transfer webhooks](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/overview): Adyen sends a [balancePlatform.transfer.created](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created) webhook to inform your server that funds will be credited to balance accounts, and [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhooks after every status change. * [Transaction webhooks](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/overview): Adyen sends a [balancePlatform.transaction.created](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created) webhook to inform your server that funds have been credited to a balance account. 2. Acknowledge the webhooks. We send these webhooks for every split item in the payment. 3. In the payload of the [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook, note that: * The `event` array includes all previous transfer events. * The `sequenceNumber` defines the number of webhooks sent for the transfer, including the current one. ### Examples Your server receives webhooks for each split of the refund amount. The following examples are based on a [refund request with split instructions](/platforms/online-payments/split-transactions/split-refunds?tab=1#refund-a-payment) use case. ### Tab: Refund amount You can identify refund-related transfer webhooks for the refunded sale amount by the following values: | Parameter | Description | Value | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | | [category](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-category) | Specifies the category of the transfer. | **platformPayment** | | [direction](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-direction) | The direction of the transfer based on the balance account. | **outgoing** | | [type](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-type) | Specifies the type of the transfer. | **refund** | | [platformPaymentType](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-categoryData-PlatformPayment-platformPaymentType) | Specifies the nature of each transfer on the balance platform. This parameter helps categorize transfers so you can reconcile transactions at a later time using the [Balance Platform Accounting Report](/platforms/reports-and-fees/balance-platform-accounting-report/). | **BalanceAccount** | | [pspPaymentReference](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-categoryData-PlatformPayment-pspPaymentReference) | The [PSP reference](/get-started-with-adyen/adyen-glossary#psp-reference) of the associated payment. | **CWBC43ZX2VTFWR82** | | [modificationPspReference](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-categoryData-PlatformPayment-modificationPspReference) | The PSP reference of the payment modification, in this case the refund. | **QFQTPCQ8HXSKGK82** | ** ### 1. Outgoing transfer received When a refund request is received to deduct funds from your user's balance account, Adyen sends a [balancePlatform.transfer.created](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created) webhook with `status` **received** and `direction` **outgoing**. The webhook provides information about the transfer, such as the original payment and split references and which user and balance account is debited. **Transfer received** ```json { "data": { "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001", "reference": "Your reference for the account holder" }, "amount": { "currency": "USD", "value": 7600 }, "balanceAccount": { "description": "Your description for the balance account", "id": "BA00000000000000000000001", "reference": "Your reference for the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "currency": "USD", "received": -7600 } ], "category": "platformPayment", "categoryData": { "modificationMerchantReference": "MRef#000001", "modificationPspReference": "QFQTPCQ8HXSKGK82", "paymentMerchantReference": "Payment reference", "platformPaymentType": "BalanceAccount", "pspPaymentReference": "CWBC43ZX2VTFWR82", "type": "platformPayment" }, "creationDate": "2025-10-20T13:30:05+02:00", "description": "Your description for the refund amount", "direction": "outgoing", "events": [ { "bookingDate": "2025-10-20T13:30:18+02:00", "id": "EVJN00000000000000000000000001", "mutations": [ { "currency": "USD", "received": -7600 } ], "status": "received", "type": "accounting" } ], "id": "3JERI65VWKBRFIVB", "reason": "approved", "reference": "Your reference for the refund amount", "sequenceNumber": 1, "status": "received", "type": "refund" }, "environment": "test", "type": "balancePlatform.transfer.created" } ``` ** ### 2. Outgoing transfer authorized When the transfer request is authorized, Adyen sends a [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook with `status` **authorised**. **Transfer authorised** ```json { "data": { "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001", "reference": "Your reference for the account holder" }, "amount": { "currency": "USD", "value": 7600 }, "balanceAccount": { "description": "Your description for the balance account", "id": "BA00000000000000000000001", "reference": "Your reference for the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "currency": "USD", "received": 0, "reserved": -7600 } ], "category": "platformPayment", "categoryData": { "modificationMerchantReference": "MRef#000001", "modificationPspReference": "QFQTPCQ8HXSKGK82", "paymentMerchantReference": "Payment reference", "platformPaymentType": "BalanceAccount", "pspPaymentReference": "CWBC43ZX2VTFWR82", "type": "platformPayment" }, "creationDate": "2025-10-20T13:30:05+02:00", "description": "Your description for the refund amount", "direction": "outgoing", "events": [ { "bookingDate": "2025-10-20T13:30:18+02:00", "id": "EVJN00000000000000000000000001", "mutations": [ { "currency": "USD", "received": -7600 } ], "status": "received", "type": "accounting" }, { "bookingDate": "2025-10-20T13:30:18+02:00", "id": "EVJN00000000000000000000000002", "mutations": [ { "currency": "USD", "received": 7600, "reserved": -7600 } ], "status": "authorised", "type": "accounting" } ], "id": "3JERI65VWKBRFIVB", "reason": "approved", "reference": "Your reference for the refund amount", "sequenceNumber": 2, "status": "authorised", "type": "refund" }, "environment": "test", "type": "balancePlatform.transfer.updated" } ``` ** ### 3. Outgoing transfer refunded When the funds are deducted from your user's balance account, Adyen sends a [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook with `status` **refunded** and the `transactionId`. **Transfer refunded** ```json { "data": { "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001", "reference": "Your reference for the account holder" }, "amount": { "currency": "USD", "value": 7600 }, "balanceAccount": { "description": "Your description for the balance account", "id": "BA00000000000000000000001", "reference": "Your reference for the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "balance": -7600, "currency": "USD", "received": 0, "reserved": 0 } ], "category": "platformPayment", "categoryData": { "modificationMerchantReference": "MRef#000001", "modificationPspReference": "QFQTPCQ8HXSKGK82", "paymentMerchantReference": "Payment reference", "platformPaymentType": "BalanceAccount", "pspPaymentReference": "CWBC43ZX2VTFWR82", "type": "platformPayment" }, "creationDate": "2025-10-20T13:30:05+02:00", "description": "Your description for the refund amount", "direction": "outgoing", "events": [ { "bookingDate": "2025-10-20T13:30:18+02:00", "id": "EVJN00000000000000000000000001", "mutations": [ { "currency": "USD", "received": -7600 } ], "status": "received", "type": "accounting" }, { "bookingDate": "2025-10-20T13:30:18+02:00", "id": "EVJN00000000000000000000000002", "mutations": [ { "currency": "USD", "received": 7600, "reserved": -7600 } ], "status": "authorised", "type": "accounting" }, { "bookingDate": "2025-10-20T13:30:20+02:00", "id": "EVJN00000000000000000000000003", "mutations": [ { "balance": -7600, "currency": "USD", "received": 0, "reserved": 7600 } ], "status": "refunded", "transactionId": "EVJN42272224222B5JB8BRC84N686ZUSD", "type": "accounting", "valueDate": "2025-10-22T00:00:00+02:00" } ], "id": "3JERI65VWKBRFIVB", "reason": "approved", "reference": "Your reference for the refund amount", "sequenceNumber": 3, "status": "refunded", "type": "refund" }, "environment": "test", "type": "balancePlatform.transfer.updated" } ``` ** ### 4. Transaction booked When the funds are deducted, Adyen also sends a [balancePlatform.transaction.created](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created) webhook, which includes information about the related transaction. **Transaction created** ```json { "data": { "id": "EVJN42272224222B5JB8BRC84N686ZUSD", "amount": { "value": -7600, "currency": "USD" }, "status": "booked", "transfer": { "id": "3JERI65VWKBRFIVB", "categoryData": { "modificationMerchantReference": "MRef#000001", "modificationPspReference": "QFQTPCQ8HXSKGK82", "paymentMerchantReference": "Payment reference", "platformPaymentType": "BalanceAccount", "pspPaymentReference": "CWBC43ZX2VTFWR82", "type": "platformPayment" }, "reference": "Your reference for the refund amount" }, "valueDate": "2025-10-22T00:00:00+02:00", "bookingDate": "2025-10-20T13:30:20+02:00", "creationDate": "2025-10-20T13:30:05+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", "reference": "Your reference for the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM" }, "type": "balancePlatform.transaction.created", "environment": "test" } ``` ### Tab: Transaction fees You can identify refund-related transfer webhooks for the refunded transaction fees by the following values: | Parameter | Description | Value | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | | [category](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-category) | Specifies the category of the transfer. | **platformPayment** | | [direction](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-direction) | The direction of the transfer based on the balance account. | **outgoing** | | [type](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-type) | Specifies the type of the transfer. | **refund** | | [platformPaymentType](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-categoryData-PlatformPayment-platformPaymentType) | Specifies the nature of each transfer on the balance platform. This parameter helps categorize transfers so you can reconcile transactions at a later time using the [Balance Platform Accounting Report](/platforms/reports-and-fees/balance-platform-accounting-report/). | **PaymentFee** | | [pspPaymentReference](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-categoryData-PlatformPayment-pspPaymentReference) | The [PSP reference](/get-started-with-adyen/adyen-glossary#psp-reference) of the associated payment. | **CWBC43ZX2VTFWR82** | | [modificationPspReference](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-categoryData-PlatformPayment-modificationPspReference) | The PSP reference of the payment modification, in this case the refund. | **QFQTPCQ8HXSKGK82** | ** ### 1. Outgoing transfer received Once the transaction fees are calculated for the refund, Adyen sends a [balancePlatform.transfer.created](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created) webhook with `status` **received** and `direction` **outgoing**. The webhook provides information about the transfer, such as the original payment and split references and which user and balance account is debited. **Transfer received** ```json { "data": { "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001", "reference": "Your reference for the account holder" }, "amount": { "currency": "USD", "value": 344 }, "balanceAccount": { "description": "Your description for the second balance account", "id": "BA00000000000000000000002", "reference": "Your reference for the second balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "currency": "USD", "received": -344 } ], "category": "platformPayment", "categoryData": { "modificationMerchantReference": "MRef#000001", "modificationPspReference": "QFQTPCQ8HXSKGK82", "paymentMerchantReference": "Payment reference", "platformPaymentType": "PaymentFee", "pspPaymentReference": "CWBC43ZX2VTFWR82", "type": "platformPayment" }, "creationDate": "2025-10-20T13:30:05+02:00", "description": "Your description for the payment fee", "direction": "outgoing", "events": [ { "bookingDate": "2025-10-20T13:30:18+02:00", "id": "BHTP00000000000000000000000001", "mutations": [ { "currency": "USD", "received": -344 } ], "status": "received", "type": "accounting" } ], "id": "8KREG78BWDNEKXHW", "reason": "approved", "reference": "Your reference for the payment fee", "sequenceNumber": 1, "status": "received", "type": "refund" }, "environment": "test", "type": "balancePlatform.transfer.created" } ``` ** ### 2. Outgoing transfer authorized When the transfer request is authorized, Adyen sends a [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook with `status` **authorised**. **Transfer authorised** ```json { "data": { "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001", "reference": "Your reference for the account holder" }, "amount": { "currency": "USD", "value": 344 }, "balanceAccount": { "description": "Your description for the second balance account", "id": "BA00000000000000000000002", "reference": "Your reference for the second balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "currency": "USD", "received": 0, "reserved": -344 } ], "category": "platformPayment", "categoryData": { "modificationMerchantReference": "MRef#000001", "modificationPspReference": "QFQTPCQ8HXSKGK82", "paymentMerchantReference": "Payment reference", "platformPaymentType": "PaymentFee", "pspPaymentReference": "CWBC43ZX2VTFWR82", "type": "platformPayment" }, "creationDate": "2025-10-20T13:30:05+02:00", "description": "Your description for the payment fee", "direction": "outgoing", "events": [ { "bookingDate": "2025-10-20T13:30:18+02:00", "id": "BHTP00000000000000000000000001", "mutations": [ { "currency": "USD", "received": -344 } ], "status": "received", "type": "accounting" }, { "bookingDate": "2025-10-20T13:30:18+02:00", "id": "BHTP00000000000000000000000002", "mutations": [ { "currency": "USD", "received": 344, "reserved": -344 } ], "status": "authorised", "type": "accounting" } ], "id": "8KREG78BWDNEKXHW", "reason": "approved", "reference": "Your reference for the payment fee", "sequenceNumber": 2, "status": "authorised", "type": "refund" }, "environment": "test", "type": "balancePlatform.transfer.updated" } ``` ** ### 3. Outgoing transfer refunded When the funds are deducted from your user's balance account, Adyen sends a [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook with `status` **refunded** and the `transactionId`. **Transfer refunded** ```json { "data": { "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001", "reference": "Your reference for the account holder" }, "amount": { "currency": "USD", "value": 344 }, "balanceAccount": { "description": "Your description for the second balance account", "id": "BA00000000000000000000002", "reference": "Your reference for the second balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "balance": -344, "currency": "USD", "received": 0, "reserved": 0 } ], "category": "platformPayment", "categoryData": { "modificationMerchantReference": "MRef#000001", "modificationPspReference": "QFQTPCQ8HXSKGK82", "paymentMerchantReference": "Payment reference", "platformPaymentType": "PaymentFee", "pspPaymentReference": "CWBC43ZX2VTFWR82", "type": "platformPayment" }, "creationDate": "2025-10-20T13:30:05+02:00", "description": "Your description for the payment fee", "direction": "outgoing", "events": [ { "bookingDate": "2025-10-20T13:30:18+02:00", "id": "BHTP00000000000000000000000001", "mutations": [ { "currency": "USD", "received": -344 } ], "status": "received", "type": "accounting" }, { "bookingDate": "2025-10-20T13:30:18+02:00", "id": "BHTP00000000000000000000000002", "mutations": [ { "currency": "USD", "received": 344, "reserved": -344 } ], "status": "authorised", "type": "accounting" }, { "bookingDate": "2025-10-20T13:30:20+02:00", "id": "BHTP00000000000000000000000003", "mutations": [ { "balance": -344, "currency": "USD", "received": 0, "reserved": 344 } ], "status": "refunded", "transactionId": "EVJN42272224222B5JB8BRC84N686ZUSD", "type": "accounting", "valueDate": "2025-10-22T00:00:00+02:00" } ], "id": "8KREG78BWDNEKXHW", "reason": "approved", "reference": "Your reference for the payment fee", "sequenceNumber": 3, "status": "refunded", "type": "refund" }, "environment": "test", "type": "balancePlatform.transfer.updated" } ``` ** ### 4. Transaction booked When the funds are deducted, Adyen also sends a [balancePlatform.transaction.created](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created) webhook, which includes information about the related transaction. **Transaction created** ```json { "data": { "id": "EVJN42272224222B5JB8BRC84N686ZUSD", "amount": { "value": -344, "currency": "USD" }, "status": "booked", "transfer": { "id": "3JERI65VWKBRFIVB", "categoryData": { "modificationMerchantReference": "MRef#000001", "modificationPspReference": "QFQTPCQ8HXSKGK82", "paymentMerchantReference": "Payment reference", "platformPaymentType": "PaymentFee", "pspPaymentReference": "CWBC43ZX2VTFWR82", "type": "platformPayment" }, "reference": "Your reference for the payment fee" }, "valueDate": "2025-10-22T00:00:00+02:00", "bookingDate": "2025-10-20T13:30:20+02:00", "creationDate": "2025-10-20T13:30:05+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", "reference": "Your reference for the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM" }, "type": "balancePlatform.transaction.created", "environment": "test" } ``` ### Tab: Commission You can identify refund-related transfer webhooks for the refunded commission by the following values: | Parameter | Description | Value | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | | [category](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-category) | Specifies the category of the transfer. | **platformPayment** | | [direction](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-direction) | The direction of the transfer based on the balance account. | **outgoing** | | [type](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-type) | Specifies the type of the transfer. | **refund** | | [platformPaymentType](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-categoryData-PlatformPayment-platformPaymentType) | Specifies the nature of each transfer on the balance platform. This parameter helps categorize transfers so you can reconcile transactions at a later time using the [Balance Platform Accounting Report](/platforms/reports-and-fees/balance-platform-accounting-report/). | **Commission** | | [pspPaymentReference](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-categoryData-PlatformPayment-pspPaymentReference) | The [PSP reference](/get-started-with-adyen/adyen-glossary#psp-reference) of the associated payment. | **CWBC43ZX2VTFWR82** | | [modificationPspReference](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-categoryData-PlatformPayment-modificationPspReference) | The PSP reference of the payment modification, in this case the refund. | **QFQTPCQ8HXSKGK82** | ** ### 1. Outgoing transfer received When a refund request is received to deduct funds from your liable balance account, Adyen sends a [balancePlatform.transfer.created](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created) webhook with `status` **received** and `direction` **outgoing**. The webhook provides information about the transfer, such as the original payment and split references. **Transfer received** ```json { "data": { "accountHolder": { "description": "Your description for your liable account holder", "id": "AH00000000000000000000002", "reference": "Your reference for your liable account holder" }, "amount": { "currency": "USD", "value": 400 }, "balanceAccount": { "description": "Your description for your liable balance account", "id": "BA00000000000000000000003", "reference": "Your reference for your liable balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "currency": "USD", "received": -400 } ], "category": "platformPayment", "categoryData": { "modificationMerchantReference": "MRef#000001", "modificationPspReference": "QFQTPCQ8HXSKGK82", "paymentMerchantReference": "Payment reference", "platformPaymentType": "Commission", "pspPaymentReference": "CWBC43ZX2VTFWR82", "type": "platformPayment" }, "creationDate": "2025-10-20T13:30:05+02:00", "description": "Your description for your commission", "direction": "outgoing", "events": [ { "bookingDate": "2025-10-20T13:30:18+02:00", "id": "HFJR00000000000000000000000001", "mutations": [ { "currency": "USD", "received": -400 } ], "status": "received", "type": "accounting" } ], "id": "7JHRI65VWKBRFPMG", "reason": "approved", "reference": "Your reference for your commission", "sequenceNumber": 1, "status": "received", "type": "refund" }, "environment": "test", "type": "balancePlatform.transfer.created" } ``` ** ### 2. Outgoing transfer authorized When the transfer request is authorized, Adyen sends a [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook with `status` **authorised**. **Transfer authorized** ```json { "data": { "accountHolder": { "description": "Your description for your liable account holder", "id": "AH00000000000000000000002", "reference": "Your reference for your liable account holder" }, "amount": { "currency": "USD", "value": 400 }, "balanceAccount": { "description": "Your description for your liable balance account", "id": "BA00000000000000000000003", "reference": "Your reference for your liable balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "currency": "USD", "received": 0, "reserved": -400 } ], "category": "platformPayment", "categoryData": { "modificationMerchantReference": "MRef#000001", "modificationPspReference": "QFQTPCQ8HXSKGK82", "paymentMerchantReference": "Payment reference", "platformPaymentType": "Commission", "pspPaymentReference": "CWBC43ZX2VTFWR82", "type": "platformPayment" }, "creationDate": "2025-10-20T13:30:05+02:00", "description": "Your description for your commission", "direction": "outgoing", "events": [ { "bookingDate": "2025-10-20T13:30:18+02:00", "id": "HFJR00000000000000000000000001", "mutations": [ { "currency": "USD", "received": -400 } ], "status": "received", "type": "accounting" }, { "bookingDate": "2025-10-20T13:30:18+02:00", "id": "HFJR00000000000000000000000002", "mutations": [ { "currency": "USD", "received": 400, "reserved": -400 } ], "status": "authorised", "type": "accounting" } ], "id": "7JHRI65VWKBRFPMG", "reason": "approved", "reference": "Your reference for your commission", "sequenceNumber": 2, "status": "authorised", "type": "refund" }, "environment": "test", "type": "balancePlatform.transfer.updated" } ``` ** ### 3. Outgoing transfer refunded When the funds are deducted from your liable account, Adyen sends a [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook with `status` **refunded** and the `transactionId`. **Transfer refunded** ```json { "data": { "accountHolder": { "description": "Your description for your liable account holder", "id": "AH00000000000000000000002", "reference": "Your reference for your liable account holder" }, "amount": { "currency": "USD", "value": 400 }, "balanceAccount": { "description": "Your description for your liable balance account", "id": "BA00000000000000000000003", "reference": "Your reference for your liable balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "balance": -400, "currency": "USD", "received": 0, "reserved": 0 } ], "category": "platformPayment", "categoryData": { "modificationMerchantReference": "MRef#000001", "modificationPspReference": "QFQTPCQ8HXSKGK82", "paymentMerchantReference": "Payment reference", "platformPaymentType": "Commission", "pspPaymentReference": "CWBC43ZX2VTFWR82", "type": "platformPayment" }, "creationDate": "2025-10-20T13:30:05+02:00", "description": "Your description for your commission", "direction": "outgoing", "events": [ { "bookingDate": "2025-10-20T13:30:18+02:00", "id": "HFJR00000000000000000000000001", "mutations": [ { "currency": "USD", "received": -400 } ], "status": "received", "type": "accounting" }, { "bookingDate": "2025-10-20T13:30:18+02:00", "id": "HFJR00000000000000000000000002", "mutations": [ { "currency": "USD", "received": 400, "reserved": -400 } ], "status": "authorised", "type": "accounting" }, { "bookingDate": "2025-10-20T13:30:20+02:00", "id": "HFJR00000000000000000000000003", "mutations": [ { "balance": -400, "currency": "USD", "received": 0, "reserved": 400 } ], "status": "refunded", "transactionId": "EVJN42272224222B5JB8BRC84N686ZUSD", "type": "accounting", "valueDate": "2025-10-22T00:00:00+02:00" } ], "id": "7JHRI65VWKBRFPMG", "reason": "approved", "reference": "Your reference for your commission", "sequenceNumber": 3, "status": "refunded", "type": "refund" }, "environment": "test", "type": "balancePlatform.transfer.updated" } ``` ** ### 4. Transaction booked When the funds are deducted, Adyen also sends a [balancePlatform.transaction.created](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created) webhook, which includes information about the related transaction. **Transaction created** ```json { "data": { "id": "EVJN42272224222B5JB8BRC84N686ZUSD", "amount": { "value": -400, "currency": "USD" }, "status": "booked", "transfer": { "id": "7JHRI65VWKBRFPMG", "categoryData": { "modificationMerchantReference": "MRef#000001", "modificationPspReference": "QFQTPCQ8HXSKGK82", "paymentMerchantReference": "Payment reference", "platformPaymentType": "Commission", "pspPaymentReference": "CWBC43ZX2VTFWR82", "type": "platformPayment" }, "reference": "Your reference for your commission" }, "valueDate": "2025-10-22T00:00:00+02:00", "bookingDate": "2025-10-20T13:30:20+02:00", "creationDate": "2025-10-20T13:30:05+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", "reference": "Your reference for the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM" }, "type": "balancePlatform.transaction.created", "environment": "test" } ``` ## See also * [Referenced refund](/point-of-sale/basic-tapi-integration/refund-payment/referenced) * [CANCEL\_OR\_REFUND webhook](/point-of-sale/basic-tapi-integration/refund-payment/refund-webhooks#cancel-or-refund-webhook) * [Refund with original split ratio](/platforms/in-person-payments/split-transactions/split-refunds/refund-original-split)