Limited availability
Currency conversion in 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 refund amounts may not match the amounts in the original payment request, resulting in a remainder. For example, your user sold goods worth CZK 1000.00 to a customer who paid in PLN (PLN 201.74). Later, your user refunds the CZK 1000.00 to the customer, which results in a remainder of PLN 6.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.
- Option 2: Adjust the amount to be refunded in the settlement currency.
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. This new amount is the sum of the original payment amount and the remainder.
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:
- You calculate the amount the customer is refunded in the processing currency using the Foreign Exchange API (only for Option 2).
- You send a refund request, specifying the refund amount in both currencies.
- 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.
Requirements
Requirement | Description |
---|---|
Integration type | You must have an Adyen online payments integration and a checkout UI. |
API credentials | You must have credentials for the following APIs:
|
API credential roles | Only for option 2. To use the Foreign Exchange API, make sure you have the following role:
|
Webhooks | Ensure that your server can receive and accept standard webhooks. Subscribe to any of the following webhooks: |
Capabilities | Make sure that your account holders have the following capabilities:
|
Setup steps | Before you begin:
|
Option 1: Use the amounts from the original payment request
-
Make sure that you have the API key for the Checkout API. Your credential has the format ws@Company.[YourCompanyAccount].
-
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 thesplits.amount
. -
In the splits array, add an additional 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.
Example refund request
You receive the following response:
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.
Calculate the refund amount in the settlement currency
To calculate the exact amount your user must refund in the settlement currency:
-
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.
-
Make sure that you have the API key for the Foreign Exchange API. Your credential has the format ws@BalancePlatform.[YourBalancePlatform].
-
Make a POST
/rates/calculate
request with anexchangeCalculations
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. -
In the response, pay attention to 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.
Example request
For example, your user sold goods worth CZK 1000.00 to a customer who paid in PLN (PLN 201.74). Later, your user refunds the CZK 1000.00 to the customer. Here:
- The processing currency is PLN and the settlement currency is CZK.
- The refund amount is fixed at PLN 201.74 (the processing currency).
-
You must calculate the refund amount in CZK (the settlement currency). This is the amount your user refunds.
Here is a POST
/rates/calculate
request to calculate the amount the customer receives in the refund, when the refund amount is fixed at PLN 201.74 (the processing currency).You receive the following response:
The
targetAmount.value
field returns the adjusted amount in CZK that your user must refund in order for the customer to receive PLN 201.74 (the original payment amount). By increasing the amount your user refunds to CZK 1032.31, the customer will receive exactly PLN 201.74. Here, the remainder is the additional CZK 32.31 that you debit your user. You can include this adjusted refund amount in thesplits.amount.value
object of your refund request.
Send a refund request
To book the remainder to your user:
-
Make sure that you have the API key for the Checkout API. Your credential has the format ws@Company.[YourCompanyAccount].
-
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 -
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.
Example refund request
You receive the following response: