Marketplace icon

Book the remainder to the customer

Learn how to convert the currency of a refund and book the remainder to the customer.

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. You can choose to book this remainder to the customer.

When you book the remainder amount to the customer:

  • The refund amount is fixed in the settlement currency.
  • Your user is debited the exact amount they received in the payment.
  • The customer is credited a different amount than what they originally paid. 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 the customer. This means that the refund amount is fixed in the settlement currency, and any mismatch is booked to the customer in the processing currency. To refund this payment:

  1. You calculate the amount the customer is refunded in the processing currency using the Foreign Exchange API.
  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. The customer receives a different amount in the refund than what they originally paid.

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:
  • Checkout API (format: ws@Company.[YourCompanyAccount])
  • Foreign Exchange API (format: ws@BalancePlatform.[YourBalancePlatform]).
API credential roles To use the Foreign Exchange API, make sure you have the following role:
  • Balance Platform fx rates and conversions 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:
  • receivePayments
  • receiveFromPlatformPayments
  • sendToTransferInstrument
Setup steps Before you begin:
  • Ask our Support Team to:
    • Enable the use of the Foreign Exchange API for your merchant account.
    • Configure the required currencies for your merchant account.
  • Your payment must be captured before you can initiate the refund.

Calculate the refund amount in the processing currency

To calculate the exact amount the customer is refunded in their currency of choice (the processing 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 -white_check_mark- Set to splitRefund
    sourceAmount.currency -white_check_mark- The settlement currency.
    sourceAmount.value -white_check_mark- The refund amount in the settlement currency, in minor units.
    targetCurrency -white_check_mark- The processing currency.
    exchangeSide -white_check_mark- The operation performed on the currency provided in the sourceAmount.currency field. Set this to buy.

  4. 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 buy.
    sourceAmount.currency The settlement currency.
    sourceAmount.value The refund amount in the settlement currency, in minor units.
    targetAmount.currency The processing currency.
    targetAmount.value The refund amount in the processing currency, in minor units. This is the amount the customer receives in the refund.
    appliedExchangeRate The exchange rate to convert the settlement currency to the processing currency that includes Adyen's markup.

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 CZK 1000.00 (the settlement currency).

  • You must calculate the refund amount in PLN (the processing currency). This is the amount the customer receives in the refund.

    Here is a POST /rates/calculate request to calculate the amount the customer receives in the refund, when the refund amount is fixed at CZK 1000.00 (the settlement currency).

    You receive the following response:

    The targetAmount.value field returns the amount the customer receives in PLN when your user refunds CZK 1000.00. Here, the customer receives PLN 195.43 when your user refunds CZK 1000.00. This is PLN 6.31 less than the amount they originally paid (PLN 201.74). This mismatched amount of PLN 6.31 is the remainder.

Send a refund request

To book the remainder to the customer

  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 -white_check_mark- The amount to be refunded to the customer in the processing currency, calculated in step 1. amount.value: 19543
    amount.currency -white_check_mark- The processing currency. amount.currency: "PLN"
    splits.amount.value -white_check_mark- The refund amount in the settlement currency. In case of multiple splits, the sum of the split amounts in the splits array must equal the original 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 -white_check_mark- The original settlement currency. splits.amount.currency: "CZK"
    splits.type -white_check_mark- 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. You receive the following response:

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.