Fix the cost of goods in the processing currency

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 fix the cost of the goods in the processing currency, the customer always pays the same, fixed amount in their currency of choice (the processing currency). The amount your user receives in the settlement currency is not fixed and depends on the prevailing exchange rate and Adyen's conversion markup.

How it works

If the cost of the goods in the processing currency (the currency in which the customer pays) is fixed:

1. You calculate the amount your user receives in the settlement currency using the Foreign Exchange API.
2. You make a POST /payments request, specifying the cost of the goods in both currencies.
3. When Adyen receives the request, we debit the customer and credit your user in their respective currencies.

Requirements

Calculate the amount in the settlement currency

To calculate the exact amount your user receives in their currency of choice (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 splitPayment
   sourceAmount.currency		The processing currency.
   sourceAmount.value		The cost of the goods in the processing currency, in minor units.
   targetCurrency		The settlement currency.
   exchangeSide		The operation performed on the fixed currency (the currency provided in the sourceAmount.currency field. Set this to sell.

4. In the response, pay attention to the following fields:

   Parameter	Description
   type	Returns splitPayment
   exchangeSide	The operation performed on the fixed currency (the currency provided in the sourceAmount.currency field). Returns sell.
   sourceAmount.currency	The processing currency.
   sourceAmount.value	The cost of the goods in the processing currency, in minor units.
   targetAmount.currency	The settlement currency.
   targetAmount.value	The cost of the goods in the settlement currency, in minor units. This is the amount your user receives.
   appliedExchangeRate	The exchange rate to convert the processing currency to the settlement currency that includes Adyen's markup.

   Example request

   For example, your user sells goods worth PLN 200.00 to a customer:

   • Your user accepts CZK (the settlement currency).
   • The customer pays in PLN (the processing currency).
   • The cost of the goods is fixed in PLN (the processing currency).
   • You must calculate the cost of the goods in CZK (the settlement currency). This is the amount your user receives.

   Here is a POST /rates/calculate request to calculate the amount your user receives, when the cost of the goods is fixed at PLN 200.00 (the processing currency).

   You receive the following response:

   The targetAmount.value field returns the amount your user receives in CZK when the customer pays PLN 200.00. Here, your user receives CZK 1015.31 when the customer pays PLN 200.00.

Send a payment request with the calculated amount

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, /sessions, or /payments/{paymentPspReference}/captures request, specifying the following fields for the currency conversion:

   Parameter		Description	Example
   amount.value		The cost of the goods in the processing currency, calculated in step 1.	amount.value: 20000
   amount.currency		The currency in which the customer pays.	amount.currency: "PLN"
   splits.amount.value		The cost of the goods in the settlement currency. In case of multiple splits, the sum of the split amounts in the splits array must equal the cost of the goods in the settlement currency. Any mismatch is booked to the balance account you specify in the split item with type Remainder.	splits.amount.value: 101531
   splits.amount.currency		The settlement currency. This is the currency in which your user receives the funds.	splits.amount.currency: "CZK"
   splits.type		The type of the split item. We recommend to always add a split item for the Remainder and the transaction fees.	split.type: BalanceAccount split.type: PaymentFee split.type: Remainder

   
   

3. You receive the following response:

The splits are guaranteed, and the payment 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.