Adyen-for-platform icon

Split refunds

Learn how to split the funds in a refund.

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. You get the outcome of the refund request asynchronously, in a REFUND webhook.

When processing a refund for your user, you can split the refund amount between the balance accounts in your platform by including the split instructions in your refund request. This allows you to choose who is liable for the refund.

Before you begin

Before you initiate a refund, make sure that you have credentials for the Checkout API.

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 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 -white_check_mark- 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 -white_check_mark- The unique identifier of the merchant account where you want to process the payment.
    reference Your reference for the refund, for example, to tag a partial refund for future reconciliation.
    splits Recommended The array of objects specifying how to split the payment. If you don't send split instructions in your request for total refunds, the fund are deducted according to split ratio of payment authorization.

We recommend that you always provide split instructions in refunds. This allows you to always be in control and support different refund scenarios, such as partial and multiple partial refunds.

You can also configure your user's store to automatically split the refund amount between predefined balance accounts. In this case, you do not need to include the split instructions in each request.

Example refund requests

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.

When you send split instructions in your refund request, you must:

  • Only use balance accounts that were part of the original split.
  • Use the same reference values from the original split.

For each item in the splits array of your POST /payments/{paymentPspReference}/refunds request, specify the following fields:

Parameter Required Description
account -white_check_mark- Your user's or your platform's balanceAccountId, from which you want to deduct the specified amount.
amount.currency The currency of the part of the refund you want deduct from the specified account.
amount.value -white_check_mark- The value of the part of the refund you want to deduct from the specified account.
type -white_check_mark- 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.
  • AdyenMarkup: deducts the transaction fee due to Adyen under blended rates from the specified balance account.
  • AdyenCommission: deducts the transaction fee due to Adyen under Interchange ++ 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.
reference -white_check_mark-
Required for type BalanceAccount
Your unique identifier for the part of the refund you want to deduct from the specified account.

Payment request

For example, you split a EUR 400.00 payment the following way:

  • EUR 4.00 booked to your liable balance account.
  • EUR 396.00 booked to your user's balance account.

Here is an example /payments request you must send in this scenario:

Refund request

When you refund the above payment, you can use a different split ratio than the original payment. For example, you can deduct:

  • EUR 8.00 from your liable balance account
  • EUR 392.00 from your user's balance account

Here is an example of the /payments/{paymentPspReference}/refunds request where you provide the split instructions in the splits array:

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.

Validating split instructions

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 payment, capture, and refund 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, the full transaction (sale amount, commission, and fees) is booked to your platform's liable balance account.

To correct the balances, you can transfer the funds between the balance accounts in your platform.

See also