Book the remainder to your user

Limited availability
Currency conversion is currently in pilot phase. Some of the processes and documentation may change as the feature evolves. If you are interested in piloting currency conversion or have any feedback, reach out to your Adyen contact.

When you refund a payment with currency conversion, the exchange rate at the time of the refund may be different from the exchange rate used to convert the currency of the original payment. This means that when you convert the payment amount back to the original currency to make the refund, this amount will not match what the customer originally paid. This mismatch between the payment and refund amount because of a change in the exchange rate is called a remainder.

The remainder can be positive or negative depending on how much the exchange rate changed between the payment and the refund. If the exchange rate to convert the processing currency to the settlement currency increased, then the remainder is positive. If this exchange rate decreased, then the remainder is negative. To ensure that the customer always gets refunded the same amount that they originally paid, you can choose to book the remainder to your user.

For example, your user sells goods worth CZK 1000.00 to a customer who pays in PLN (PLN 201.74). Later, your user refunds the payment to the customer. At the time of the refund, the exchange rate to convert PLN (the processing currency) to CZK (the settlement currency) increased, which results in a positive remainder of CZK 32.31. You can choose to book this remainder to your user.

Booking options

To book the remainder to your user, you have two options:

• Option 1: Use the amounts from the original payment request. When you use this option:
  • Adyen does all the calculations for you
  • Original settlement amounts are reused in the refund request. This can make reconciliation easier.
  • The remainder is booked separately to your user.
• Option 2: Adjust the amount to be refunded in the settlement currency. When you use this option:
  • You must calculate the amounts yourself.
  • The refunded amount can vary from the settlement amount.
  • If calculated correctly, you avoid a separate remainder booking.

When you book the remainder amount to your user:

• The refund amount is fixed in the processing currency
• The customer is credited the exact amount they originally paid in the processing currency
• Your user is debited a different amount than what they originally received, based on the change in the exchange rate between the payment and the refund. This new amount is the sum of the original payment amount and the remainder.

Requirements

How it works

You process a payment with currency conversion on behalf of your user. The customer is debited in the processing currency and your user is credited in the settlement currency.

When refunding this payment, you want to book the remainder to your user. This means that the refund amount is fixed in the processing currency, and any mismatch is booked to your user in the settlement currency. To refund this payment:

1. You calculate the amount that the user must refund in the settlement currency using the /rates/calculate (only for Option 2).
2. You send a refund request, specifying the refund amount in both currencies.
3. When Adyen receives the request, we credit the customer and debit your user in their respective currencies. Your user is debited a different amount in the refund than what they originally received.

Option 1: Use the amounts from the original payment request

To book the remainder to your user's balance account, send a POST /payments/{paymentPspReference}/refunds request.

• Use the values from the original payment for the amount and splits.amount objects of the request. For our example refund, this is PLN 201.74 for the amount, and CZK 1000.00 for the splits.amount.
• In the splits array, add a split item for the remainder, with type Remainder. In the account field of this split item, specify your user's balance account. You do not need to specify the amount of the remainder.

When Adyen receives your request, we credit the customer with their original payment amount and book the remainder to the balance account you specified in the Remainder split item.

Option 2: Adjust the amount to be refunded in the settlement currency

To ensure that the customer receives the exact amount they originally paid in the processing currency, you can adjust the amount your user refunds in the settlement currency. The magnitude of the adjustment depends on how much the exchange rate changed between the time of payment and time of refund.

• If the exchange rate from the processing currency to the settlement currency increased, the remainder is positive. This means that the user must be debited a higher amount than what they originally received.
• If the exchange rate from the processing currency to the settlement currency decreased, the remainder is negative. This means that the user must be debited a lower amount than what they originally received.

Calculate the refund amount in the settlement currency

To calculate the exact amount your user must refund in the settlement currency:

1. Contact our Support Team to:

   • Enable the use of the Foreign Exchange API for your merchant account.
   • Configure the required currencies for your merchant account.
     

2. Make sure that you have the API key for the Foreign Exchange API. Your credential has the format ws@BalancePlatform.[YourBalancePlatform].

3. Make a POST /rates/calculate request with an exchangeCalculations array. Each item in the array defines a currency and value for which you want to perform a calculation. In each item of the array, specify:

   Parameter	Required	Description
   type		Set to splitRefund
   sourceAmount.currency		The processing currency.
   sourceAmount.value		The refund amount in the processing currency, in minor units.
   targetCurrency		The settlement currency.
   exchangeSide		The operation performed on the currency provided in the sourceAmount.currency field. Set this to sell because you are selling the amount in the processing currency to obtain the amount in the settlement currency.

4. In the response, note the following fields:

   Parameter	Description
   type	Returns splitRefund
   exchangeSide	The operation performed on the currency provided in the sourceAmount.currency field. Returns sell.
   sourceAmount.currency	The processing currency.
   sourceAmount.value	The refund amount in the processing currency, in minor units.
   targetAmount.currency	The settlement currency.
   targetAmount.value	The refund amount in the settlement currency, in minor units. This is the amount your user refunds.
   appliedExchangeRate	The exchange rate to convert the processing currency to the settlement currency that includes Adyen's Markup.

Send a refund request

To book the remainder to your user:

1. Make sure that you have the API key for the Checkout API. Your credential has the format ws@Company.[YourCompanyAccount].

2. Send a POST /payments/{paymentPspReference}/refunds request specifying the following fields for the currency conversion:

   Parameter	Required	Description	Example
   amount.value		The original amount the customer paid in the processing currency.	amount.value: 20174
   amount.currency		The original processing currency.	amount.currency: "PLN"
   splits.amount.value		The adjusted refund amount in the settlement currency. In case of multiple splits, the sum of the split amounts in the splits array must equal the adjusted refund amount in the settlement currency. Any mismatch will be booked to the balance account you specify in the split item with type Remainder.	splits.amount.value: 103231
   splits.amount.currency		The original settlement currency.	splits.amount.currency: "CZK"
   splits.type		The type of the split item. We recommend to always add a split item for the type Remainder.	split.type: BalanceAccount split.type: Remainder

3. The splits are guaranteed, and the refund is booked according to the data you provide in the splits array. Any mismatch or miscalculation is booked to the balance account you specify in the split item with type Remainder. You can reconcile these mismatches per transaction using the Balance Platform Accounting Report.