What do I have to do to support payments with FX?

This is a difficult question for us to answer, as it depends on how your specific integration works. The key things that are different from non-FX payments are:

  • A merchant can now collect payments in a currency for which they do not have a payout bank account. For some integrations, this may mean it’s the first time merchants can collect in multiple currencies, which will have a UI impact
  • Payments and payouts might have associated FX information (i.e. an exchange rate) which you may need to use for reconciliation

How do I know if FX is enabled?

Call the creditors endpoint for this merchant. If the field fx_payout_currency is set, then FX is enabled for this merchant.

What currencies can a merchant collect money in?

If FX is enabled, the merchant can collect money in any supported currency.

How do I know which payments will have FX applied?

There are two options, depending on when you need to know.

  1. If a payment is going to be paid out in a different currency, there will be an fx object on the payment, with information about the exchange rate.
  2. Call the creditors endpoint for this merchant. By default, all payments will be paid out in the fx_payout_currency. However, the merchant may also collect in other currencies. These will be listed in the links section. In the below example, this merchant can collect in GBP and EUR, and all other currencies will be paid out in the fx_payout_currency.
"links": {
      "default_gbp_payout_account": "BA789",
      "default_eur_payout_account": "BA456"
    }

How do I tell the merchant what money they will receive?

FX payments are not exchanged into the payout currency until the payout is transferred to the merchant. This means that until the payout has been paid out, we do not know what the exchange rate will be. Instead, we provide an estimated_exchange_rate in the fx block on both payments and payouts. You can display this as a ‘best guess’ until the actual exchange rate is fixed. Note that all items in a single payout will have the same original currency and exchange rate.

How do I reconcile FX payouts?

This very much depends on the implementation. However, if you are an accounting software or you do bank reconciliation, then you may want to think about the following. For these, we will use the example of a merchant with a GBP home currency collecting a EUR payment.

We recommend you represent the flow of money to match the flow of funds:

EUR Payer -> EUR Clearing Account -> GBP payout account

You may have challenges if your software imposes a specific exchange rate, as the transfer into the GBP payout account must be correct to enable reconciliation. In this case we recommend an alternative flow:

EUR Payer -> EUR Clearing Account -> GBP FX Suspense account -> GBP payout account

You can then calculate a ‘correction’ transaction to zero out the suspense account, which we would call ‘realised FX gains / losses’.

Note that the fx block of both payments and payouts will have either an estimated_exchange_rate and an exchange_rate, depending on whether the exchange rate has been finalised or not. We recommend not doing any FX until the exchange_rate is confirmed, to help with reconciliation.

How do I reconcile late failures, chargebacks and refunds for FX payments?

As long as you have represented the payment as described above, this should not be a cause for concern. These are accounted for in the payouts API, so as long as you are using the amount, the fx[amount] and the deducted_fees, you should be able to avoid any more complexity. If a payment late fails, chargebacks or refunds, you should simply be able to move that money back out of the clearing account. The payout will then have that amount removed, and the amount and fx[amount] will be correct.