Split refunds

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.

Requirements

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

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		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 do not send split instructions in your request for total refunds, the fund are deducted according to the split ratio of the 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.

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.

Provide split instructions (recommended)Use split instructions from payment authorizationProvide split instructions (recommended)Use split instructions from payment authorization

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		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		The value of the part of the refund you want to deduct from the specified account.
type		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	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 USD 400.00 payment the following way:

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

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

Make a payment with split instructions

curlJavaPHPC#NodeJS (JavaScript)GoPythonRubyNodeJS (TypeScript)curlJavaPHPC#NodeJS (JavaScript)GoPythonRubyNodeJS (TypeScript)

Expand view

Copy link to code block

Copy code

Copy code

curl https://checkout-test.adyen.com/checkout/v71/payments \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-X POST \
-d '{
   "paymentMethod": {
      "type": "scheme",
      "number": "4400 0000 0000 0008",
      "expiryMonth": "10",
      "expiryYear": "2020",
      "holderName": "John Smith",
      "cvc": "737"
   },
   "amount": {
      "value": 40000,
      "currency": "USD"
   },
   "reference":"YOUR_REFERENCE_NUMBER",
   "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
   "returnUrl":"https://your-company.com/...",
   "splits": [
      {
         "amount": {
             "value": 400
         },
         "type": "Commission",
         "reference": "Your reference for the commission"
      },
      {
         "amount": {
             "value": 39600
         },
         "type": "BalanceAccount",
         "account": "BA00000000000000000000001",
         "reference": "Your reference for the split"
      }
   ]
}'

Refund request

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

• USD 8.00 from your liable balance account
• USD 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:

Split a refund with different data

curlJavaPHPC#NodeJS (JavaScript)GoPythonRubyNodeJS (TypeScript)curlJavaPHPC#NodeJS (JavaScript)GoPythonRubyNodeJS (TypeScript)

Expand view

Copy link to code block

Copy code

Copy code

curl https://checkout-test.adyen.com/checkout/v71/payments/HGGKZCD6J3RZNN82/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": 40000,
      "currency": "USD"
   },
   "splits": [
      {
         "amount": {
             "value": 800
         },
         "type": "Commission",
         "reference": "Your reference for the commission"
      },
      {
         "amount": {
             "value": 39200
         },
         "type": "BalanceAccount",
         "account": "BA00000000000000000000001",
         "reference": "Your reference for the split"
      }
   ]
}'

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