--- title: "Split refunds" description: "Learn how to split the funds in a refund." url: "https://docs.adyen.com/marketplaces/split-transactions/split-refunds" source_url: "https://docs.adyen.com/marketplaces/split-transactions/split-refunds.md" canonical: "https://docs.adyen.com/marketplaces/split-transactions/split-refunds" last_modified: "2026-05-24T12:54:31+02:00" language: "en" --- # Split refunds Learn how to split the funds in a refund. [View source](/marketplaces/split-transactions/split-refunds.md) If you want to return the funds to a customer, for example, if they returned an item to your user, you need to refund the payment. When processing a refund for your user, you can split the refund amount between the balance accounts in your marketplace by including the split instructions in your refund request. This allows you to choose who is liable for the refund. ## Requirements Take into account the following requirements, limitations, and preparations for processing refunds. | Requirement | Description | | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **[API credentials](/development-resources/api-credentials/)** | You must have credentials for the [Checkout API](https://docs.adyen.com/api-explorer/Checkout/latest/overview). | | **[Webhooks](/development-resources/webhooks)** | Ensure that your server can receive and accept [standard webhooks](/development-resources/webhooks). Subscribe to any of the following webhooks:- [Transfer webhooks](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/overview) - [Transaction webhooks](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/overview) | | **Limitations** | When you refund a payment, you must take into account the following:- Some payment methods do not support partial refunds. You can check which ones support partial and multiple partial refunds in the [overview of payment methods](/payment-methods). - Refunds can only be deducted from the balance accounts to which the payment was credited. - Use the same `pspReference` values as in the original split. - You get the outcome of the refund request asynchronously, in a [REFUND webhook](/online-payments/refund#refund-webhook?target="_blank"). | ## Refund a payment 1. Get the PSP reference of the original payment from either the API response, or the authorization or transfer webhooks triggered by the original payment request. 2. Make a POST [/payments/{paymentPspReference}/refunds](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/refunds) request, specifying the PSP reference of the original payment in the path. In the body of the request, include the following fields: | Parameter | Required | Description | | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [amount](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/refunds#request-amount) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The amount that you want to refund. - The `value` must be the same, or, in case of a partial refund, less than the captured amount. - The `currency` must match the currency used in the payment authorization. | | [merchantAccount](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/refunds#request-merchantAccount) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The unique identifier of the merchant account where you want to process the payment. | | [reference](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/refunds#request-reference) | | Your reference for the refund, for example, to tag a partial refund for future reconciliation. | | [splits](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/refunds#request-splits) | ![Recommended](/user/pages/reuse/image-library/01.icons/recommended/recommended.svg?decoding=auto\&fetchpriority=auto) | The array of objects specifying how to split the payment. For partial refunds, we strongly recommend that you **always** provide split instructions in your request. If you do not send split instructions in your request for total refunds, the funds are deducted according to the split ratio of the payment authorization. | The following tabs show you examples for refund requests: one where you specify the split instructions, and another where you send the request without them. ### Tab: Refund with split instructions (recommended) For each item in the [splits](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/refunds#request-splits) array of your POST [/payments/{paymentPspReference}/refunds](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/refunds) request, specify the following fields: | Parameter | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `account` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your user's or your platform's `balanceAccountId`, from which you want to deduct the specified `amount`. | | `amount.currency` | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | Required if you want to refund the payment in a different currency from the original payment's currency The currency of the part of the refund you want to deduct from the specified `account`. | | `amount.value` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The value of the part of the refund you want to deduct from the specified `account`. | | `type` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The part of the refund you want to book to the specified `account`. Possible values:- **BalanceAccount**: deducts the specified `amount` from the specified balance account. - **Commission**: deducts the amount of your platform's commission for the original payment from your [liable balance account](/marketplaces/account-structure-resources). - **AdyenMarkup**: deducts the transaction fee due to Adyen under [blended rates](https://www.adyen.com/knowledge-hub/get-the-best-from-your-card-processing) from the specified balance account. - **AdyenCommission**: deducts the transaction fee due to Adyen under [Interchange ++ pricing](https://www.adyen.com/pricing) from the specified balance account. - **PaymentFee** or **AdyenFees**: deducts the aggregated amount of Adyen's commission and markup fees from the specified balance account. By default, all fees deducted from your platform's liable balance account. - **Remainder**: The amount left over after a currency conversion, booked to the specified account.. | | `reference` | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | Required if `type` is **BalanceAccount** Your unique identifier for the part of the refund you want to deduct from the specified `account`. | Here is an example of the [/payments/{paymentPspReference}/refunds](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/refunds) request where you provide the split instructions in the [splits](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/refunds#request-splits) array: **Split a refund with different data** #### curl ```bash curl https://checkout-test.adyen.com/v72/payments/CWBC43ZX2VTFWR82/refunds \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "reference": "YOUR_REFERENCE_NUMBER", "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "amount": { "value": 8000, "currency": "USD" }, "splits": [ { "amount": { "value": 400 }, "type": "Commission", "reference": "Your reference for your commission" }, { "amount": { "value": 7600 }, "type": "BalanceAccount", "account": "BA00000000000000000000001", "reference": "Your reference for the refund amount" } ] }' ``` #### Java ```java // Adyen Java API Library v40.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.checkout.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.model.RequestOptions; import com.adyen.service.checkout.*; // For the LIVE environment, also include your liveEndpointUrlPrefix. Client client = new Client("ADYEN_API_KEY", Environment.TEST); // Create the request object(s) SplitAmount splitAmount1 = new SplitAmount() .value(400L); SplitAmount splitAmount2 = new SplitAmount() .value(7600L); Amount amount = new Amount() .currency("USD") .value(8000L); Split split1 = new Split() .reference("Your reference for your commission") .amount(splitAmount1) .type(Split.TypeEnum.COMMISSION); Split split2 = new Split() .reference("Your reference for the refund amount") .amount(splitAmount2) .type(Split.TypeEnum.BALANCEACCOUNT) .account("BA00000000000000000000001"); PaymentRefundRequest paymentRefundRequest = new PaymentRefundRequest() .reference("YOUR_REFERENCE_NUMBER") .amount(amount) .splits(Arrays.asList(split1, split2)) .merchantAccount("YOUR_MERCHANT_ACCOUNT"); // Send the request ModificationsApi service = new ModificationsApi(client); PaymentRefundResponse response = service.refundCapturedPayment("paymentPspReference", paymentRefundRequest, new RequestOptions().idempotencyKey("UUID")); ``` #### PHP ```php setXApiKey("ADYEN_API_KEY"); // For the LIVE environment, also include your liveEndpointUrlPrefix. $client->setEnvironment(Environment::TEST); // Create the request object(s) $splitAmount1 = new SplitAmount(); $splitAmount1 ->setValue(400); $splitAmount2 = new SplitAmount(); $splitAmount2 ->setValue(7600); $amount = new Amount(); $amount ->setCurrency("USD") ->setValue(8000); $split1 = new Split(); $split1 ->setReference("Your reference for your commission") ->setAmount($splitAmount1) ->setType("Commission"); $split2 = new Split(); $split2 ->setReference("Your reference for the refund amount") ->setAmount($splitAmount2) ->setType("BalanceAccount") ->setAccount("BA00000000000000000000001"); $paymentRefundRequest = new PaymentRefundRequest(); $paymentRefundRequest ->setReference("YOUR_REFERENCE_NUMBER") ->setAmount($amount) ->setSplits(array($split1, $split2)) ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT"); $requestOptions['idempotencyKey'] = 'UUID'; // Send the request $service = new ModificationsApi($client); $response = $service->refundCapturedPayment('paymentPspReference', $paymentRefundRequest, $requestOptions); ``` #### C\# ```cs // Adyen .NET API Library v32.2.1 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Checkout; using Adyen.Service.Checkout; // For the LIVE environment, also include your liveEndpointUrlPrefix. var config = new Config() { XApiKey = "ADYEN_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) SplitAmount splitAmount1 = new SplitAmount { Value = 400 }; SplitAmount splitAmount2 = new SplitAmount { Value = 7600 }; Amount amount = new Amount { Currency = "USD", Value = 8000 }; Split split1 = new Split { Reference = "Your reference for your commission", Amount = splitAmount1, Type = Split.TypeEnum.Commission }; Split split2 = new Split { Reference = "Your reference for the refund amount", Amount = splitAmount2, Type = Split.TypeEnum.BalanceAccount, Account = "BA00000000000000000000001" }; PaymentRefundRequest paymentRefundRequest = new PaymentRefundRequest { Reference = "YOUR_REFERENCE_NUMBER", Amount = amount, Splits = new List{ split1, split2 }, MerchantAccount = "YOUR_MERCHANT_ACCOUNT" }; // Send the request var service = new ModificationsService(client); var response = service.RefundCapturedPayment("paymentPspReference", paymentRefundRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"}); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v30.0.0 const { Client, CheckoutAPI } = require('@adyen/api-library'); // For the LIVE environment, also include your liveEndpointUrlPrefix. const config = new Config({ apiKey: "ADYEN_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const paymentRefundRequest = { reference: "YOUR_REFERENCE_NUMBER", merchantAccount: "YOUR_MERCHANT_ACCOUNT", amount: { value: 8000, currency: "USD" }, splits: [ { amount: { value: 400 }, type: "Commission", reference: "Your reference for the commission" }, { amount: { value: 7600 }, type: "BalanceAccount", account: "BA00000000000000000000001", reference: "Your reference for the refund amount" } ] } // Send the request const checkoutAPI = new CheckoutAPI(client); const response = checkoutAPI.ModificationsApi.refundCapturedPayment("paymentPspReference", paymentRefundRequest, { idempotencyKey: "UUID" }); ``` #### Go ```go // Adyen Go API Library v21.1.0 import ( "context" "github.com/adyen/adyen-go-api-library/v21/src/common" "github.com/adyen/adyen-go-api-library/v21/src/adyen" "github.com/adyen/adyen-go-api-library/v21/src/checkout" ) // For the LIVE environment, also include your liveEndpointUrlPrefix. client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) splitAmount1 := checkout.SplitAmount{ Value: 400, } splitAmount2 := checkout.SplitAmount{ Value: 7600, } amount := checkout.Amount{ Currency: "USD", Value: 8000, } split1 := checkout.Split{ Reference: common.PtrString("Your reference for your commission"), Amount: &splitAmount1, Type: "Commission", } split2 := checkout.Split{ Reference: common.PtrString("Your reference for the refund amount"), Amount: &splitAmount2, Type: "BalanceAccount", Account: common.PtrString("BA00000000000000000000001"), } paymentRefundRequest := checkout.PaymentRefundRequest{ Reference: common.PtrString("YOUR_REFERENCE_NUMBER"), Amount: amount, Splits: []checkout.Split{ split1, split2, }, MerchantAccount: "YOUR_MERCHANT_ACCOUNT", } // Send the request service := client.Checkout() req := service.ModificationsApi.RefundCapturedPaymentInput("paymentPspReference").IdempotencyKey("UUID").PaymentRefundRequest(paymentRefundRequest) res, httpRes, err := service.ModificationsApi.RefundCapturedPayment(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v14.0.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_API_KEY" # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "reference": "YOUR_REFERENCE_NUMBER", "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "amount": { "value": 8000, "currency": "USD" }, "splits": [ { "amount": { "value": 400 }, "type": "Commission", "reference": "Your reference for your commission" }, { "amount": { "value": 7600 }, "type": "BalanceAccount", "account": "BA00000000000000000000001", "reference": "Your reference for the refund amount" } ] } # Send the request result = adyen.checkout.modifications_api.refund_captured_payment(request=json_request, paymentPspReference="paymentPspReference", idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v11.0.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_API_KEY' # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :reference => 'YOUR_REFERENCE_NUMBER', :merchantAccount => 'YOUR_MERCHANT_ACCOUNT', :amount => { :value => 8000, :currency => 'USD' }, :splits => [ { :amount => { :value => 400 }, :type => 'Commission', :reference => 'Your reference for your commission' }, { :amount => { :value => 7600 }, :type => 'BalanceAccount', :account => 'BA00000000000000000000001', :reference => 'Your reference for the refund amount' } ] } # Send the request result = adyen.checkout.modifications_api.refund_captured_payment(request_body, 'paymentPspReference', headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v30.0.0 import { Client, CheckoutAPI, Types } from "@adyen/api-library"; // For the LIVE environment, also include your liveEndpointUrlPrefix. const config = new Config({ apiKey: "ADYEN_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const splitAmount1: Types.checkout.SplitAmount = { value: 400 }; const splitAmount2: Types.checkout.SplitAmount = { value: 7600 }; const amount: Types.checkout.Amount = { currency: "USD", value: 8000 }; const split1: Types.checkout.Split = { reference: "Your reference for your commission", amount: splitAmount1, type: Types.checkout.Split.TypeEnum.Commission }; const split2: Types.checkout.Split = { reference: "Your reference for the refund amount", amount: splitAmount2, type: Types.checkout.Split.TypeEnum.BalanceAccount, account: "BA00000000000000000000001" }; const paymentRefundRequest: Types.checkout.PaymentRefundRequest = { reference: "YOUR_REFERENCE_NUMBER", amount: amount, splits: [split1, split2], merchantAccount: "YOUR_MERCHANT_ACCOUNT" }; // Send the request const checkoutAPI = new CheckoutAPI(client); const response = checkoutAPI.ModificationsApi.refundCapturedPayment("paymentPspReference", paymentRefundRequest, { idempotencyKey: "UUID" }); ``` ### Tab: Use split instructions from payment authorization If you want to use the same split ratio for the refund as you did for the payment, you can send the refund request without specifying the split instructions. The funds are deducted according the split instructions in the payment authorization, *not* the capture. In this scenario: * The refund amount is the same as the original payment amount. * The payment authorization contained split instructions. * You want to debit the amount based on the original split. If the payment authorization didn't contain split instructions, the full refund amount is debited from your liable balance account. To split a refund using the original split ratio, send a [/payments/{paymentPspReference}/refunds](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/refunds) request without the `splits` array. **Split a refund according to the original split ratio** #### curl ```bash curl https://checkout-test.adyen.com/v72/payments/CWBC43ZX2VTFWR82/refunds \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "reference": "YOUR_REFERENCE_NUMBER", "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "amount": { "value": 8000, "currency": "USD" } }' ``` #### Java ```java // Adyen Java API Library v40.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.checkout.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.model.RequestOptions; import com.adyen.service.checkout.*; // For the LIVE environment, also include your liveEndpointUrlPrefix. Client client = new Client("ADYEN_API_KEY", Environment.TEST); // Create the request object(s) Amount amount = new Amount() .currency("USD") .value(8000L); PaymentRefundRequest paymentRefundRequest = new PaymentRefundRequest() .reference("YOUR_REFERENCE_NUMBER") .amount(amount) .merchantAccount("YOUR_MERCHANT_ACCOUNT"); // Send the request ModificationsApi service = new ModificationsApi(client); PaymentRefundResponse response = service.refundCapturedPayment("paymentPspReference", paymentRefundRequest, new RequestOptions().idempotencyKey("UUID")); ``` #### PHP ```php setXApiKey("ADYEN_API_KEY"); // For the LIVE environment, also include your liveEndpointUrlPrefix. $client->setEnvironment(Environment::TEST); // Create the request object(s) $amount = new Amount(); $amount ->setCurrency("USD") ->setValue(8000); $paymentRefundRequest = new PaymentRefundRequest(); $paymentRefundRequest ->setReference("YOUR_REFERENCE_NUMBER") ->setAmount($amount) ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT"); $requestOptions['idempotencyKey'] = 'UUID'; // Send the request $service = new ModificationsApi($client); $response = $service->refundCapturedPayment('paymentPspReference', $paymentRefundRequest, $requestOptions); ``` #### C\# ```cs // Adyen .NET API Library v32.2.1 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Checkout; using Adyen.Service.Checkout; // For the LIVE environment, also include your liveEndpointUrlPrefix. var config = new Config() { XApiKey = "ADYEN_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) Amount amount = new Amount { Currency = "USD", Value = 8000 }; PaymentRefundRequest paymentRefundRequest = new PaymentRefundRequest { Reference = "YOUR_REFERENCE_NUMBER", Amount = amount, MerchantAccount = "YOUR_MERCHANT_ACCOUNT" }; // Send the request var service = new ModificationsService(client); var response = service.RefundCapturedPayment("paymentPspReference", paymentRefundRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"}); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v30.0.0 const { Client, CheckoutAPI } = require('@adyen/api-library'); // For the LIVE environment, also include your liveEndpointUrlPrefix. const config = new Config({ apiKey: "ADYEN_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const paymentRefundRequest = { reference: "YOUR_REFERENCE_NUMBER", merchantAccount: "YOUR_MERCHANT_ACCOUNT", amount: { value: 8000, currency: "USD" } } // Send the request const checkoutAPI = new CheckoutAPI(client); const response = checkoutAPI.ModificationsApi.refundCapturedPayment("paymentPspReference", paymentRefundRequest, { idempotencyKey: "UUID" }); ``` #### Go ```go // Adyen Go API Library v21.1.0 import ( "context" "github.com/adyen/adyen-go-api-library/v21/src/common" "github.com/adyen/adyen-go-api-library/v21/src/adyen" "github.com/adyen/adyen-go-api-library/v21/src/checkout" ) // For the LIVE environment, also include your liveEndpointUrlPrefix. client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) amount := checkout.Amount{ Currency: "USD", Value: 8000, } paymentRefundRequest := checkout.PaymentRefundRequest{ Reference: common.PtrString("YOUR_REFERENCE_NUMBER"), Amount: amount, MerchantAccount: "YOUR_MERCHANT_ACCOUNT", } // Send the request service := client.Checkout() req := service.ModificationsApi.RefundCapturedPaymentInput("paymentPspReference").IdempotencyKey("UUID").PaymentRefundRequest(paymentRefundRequest) res, httpRes, err := service.ModificationsApi.RefundCapturedPayment(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v14.0.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_API_KEY" # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "reference": "YOUR_REFERENCE_NUMBER", "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "amount": { "value": 8000, "currency": "USD" } } # Send the request result = adyen.checkout.modifications_api.refund_captured_payment(request=json_request, paymentPspReference="paymentPspReference", idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v11.0.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_API_KEY' # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :reference => 'YOUR_REFERENCE_NUMBER', :merchantAccount => 'YOUR_MERCHANT_ACCOUNT', :amount => { :value => 8000, :currency => 'USD' } } # Send the request result = adyen.checkout.modifications_api.refund_captured_payment(request_body, 'paymentPspReference', headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v30.0.0 import { Client, CheckoutAPI, Types } from "@adyen/api-library"; // For the LIVE environment, also include your liveEndpointUrlPrefix. const config = new Config({ apiKey: "ADYEN_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const amount: Types.checkout.Amount = { currency: "USD", value: 8000 }; const paymentRefundRequest: Types.checkout.PaymentRefundRequest = { reference: "YOUR_REFERENCE_NUMBER", amount: amount, merchantAccount: "YOUR_MERCHANT_ACCOUNT" }; // Send the request const checkoutAPI = new CheckoutAPI(client); const response = checkoutAPI.ModificationsApi.refundCapturedPayment("paymentPspReference", paymentRefundRequest, { idempotencyKey: "UUID" }); ``` 3. Listen to the [REFUND webhook](/online-payments/refund/#refund-webhook?target="_blank") for the outcome of the refund request. ### Troubleshooting The API request validates only the format of the split instructions, **not** the balance accounts specified in the request. This means that even if the transaction is successful, it is possible that the funds are not credited to/deducted from the specified balance account. If the balance account does not exist, or it is linked to an account holder with a **closed** [status](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/accountHolders#responses-200-status), the full transaction and its fees are booked to your marketplace's liable balance account. To correct the balances, you can [transfer the funds](/marketplaces/internal-fund-transfers) between the balance accounts in your marketplace. ## 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](/marketplaces/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](/marketplaces/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](/marketplaces/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](/marketplaces/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" } ``` ## Additional split instructions The above examples show you how to: * Deduct the sale amount from your user's balance account (using `type` **BalanceAccount**). * Deduct the commission from your liable balance account (using `type` **Commission**). This is the standard use case for most refunds. However, you can additionally extend your split instructions to cover more specific use cases. ### Remainder after currency conversion When you process refunds on behalf of your users, you can convert the currency of those refunds. Due to the constantly fluctuating exchange rates, you may have a leftover amount after currency conversion, called a **Remainder**. You can book this remainder to the balance account of your choice. For more information about currency conversion and booking the remainder, see [Currency conversion](/marketplaces/currency-conversion#convert-the-currency-of-a-refund). ## See also * [Handle transaction fees](/marketplaces/transaction-fees) * [Convert the currency of a transaction](/marketplaces/currency-conversion)