Fix the cost of goods in the settlement 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 settlement currency, your user always receives the same, fixed amount in their currency of choice (the settlement currency). The amount the customer pays in the processing 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 settlement currency (the currency your user receives) is fixed:

1. You calculate the amount the customer must pay in the processing currency, using either the Foreign Exchange API or the Exchange Rate Report.
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 processing currency

To calculate the exact amount the customer must pay in their currency of choice (the processing currency), you have two options:

• Make a POST /rates/calculate request using the Foreign Exchange API to get the exact payment amount in the processing currency.
• Use our Exchange Rate Report to manually calculate the exact payment amount in the processing currency.

curl https://balanceplatform-api-live.adyen.com/fx/api/v1/rates/calculate \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-X POST \
-d '{
    "exchangeCalculations": [
        {
            "type": "splitPayment",
            "sourceAmount": {
               "currency": "CZK"
               "value": 100000
            },
            "targetCurrency": "PLN",
            "exchangeSide": "buy"
        }
    ]
}'

{
   "exchangeCalculations": [
      {
         "type": "splitPayment",
         "exchangeSide": "sell",
         "sourceAmount": {
            "currency": "CZK",
            "value": 100000
         },
         "targetAmount": {
            "currency": "PLN",
            "value": "20174"
         },
         "appliedExchangeRate": "0.20174"
      }
   ]
}

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: 20174
   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: 100000
   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

   Payment request with currency conversion

   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": "4111111111111111",
           "cvc": "737",
           "expiryMonth": "03",
           "expiryYear": "2030",
           "holderName": "John Doe"
       },
       "billingAddress": {
           "city":"London",
           "country":"GB",
           "houseNumberOrName":"10",
           "postalCode":"SW1A 2AA",
           "street":"Downing Street"
       },
       "amount": {
           "value": 20174,
           "currency": "PLN"
       },
       "reference": "YOUR_PAYMENT_REFERENCE",
       "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
       "splits": [
           {
               "type": "BalanceAccount",
               "account": "BA00000000000000000000001",
               "amount": {
                   "currency": "CZK",
                   "value": 100000
               },
               "reference": "YOUR_SPLIT_REFERENCE_1",
               "description": "YOUR_SPLIT_DESCRIPTION_1"
           },
           {
               "type": "Remainder",
               "account": "BA00000000000000000000001",
               "reference": "YOUR_REMAINDER_REFERENCE",
               "description": "YOUR_REMAINDER_DESCRIPTION"
           },
           {
               "type": "PaymentFee",
               "account": "BA00000000000000000000001",
               "reference": "YOUR_PAYMENT-FEE_REFERENCE",
               "description": "YOUR_PAYMENT-FEE_DESCRIPTION"
           }
       ]
   }'

   
   

3. You receive the following response:

   Response

   Expand view

   Copy link to code block

   Copy code

   Copy code

   {
      ...
      "pspReference":"LVP53Z9PQGNG5S82",
      "resultCode":"Authorised",
      "amount":{
         "currency":"PLN",
         "value":20174
      },
      "merchantReference":"YOUR_PAYMENT_REFERENCE",
      "paymentMethod":{
         "brand":"mc",
         "type":"scheme"
      }
   }

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.