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. 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	You must have credentials for the Checkout API.
Webhooks	Ensure that your server can receive and accept standard webhooks. Subscribe to any of the following webhooks: Transfer webhooks Transaction webhooks
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. 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.

Refund a payment

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.

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		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		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		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.

Listen to the REFUND webhook 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, the full transaction and its fees are booked to your marketplace's liable balance account.

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

Track fund movements

To track the status of the fund transfers initiated by a refund:

Listen to the following webhooks:
- Transfer webhooks: Adyen sends a balancePlatform.transfer.created webhook to inform your server that funds will be credited to balance accounts, and balancePlatform.transfer.updated webhooks after every status change.
- Transaction webhooks: Adyen sends a balancePlatform.transaction.created webhook to inform your server that funds have been credited to a balance account.
Acknowledge the webhooks. We send these webhooks for every split item in the payment.
In the balancePlatform.transfer.updated webhook payload, note that the event array includes all previous transfer events, and 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 use case.

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.