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 marketplace 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 and the PSP reference of the original payment.
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 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 the split ratio of the payment authorization. - The
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.
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.
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.