Payments: FX Payments
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
Call the creditors endpoint for this merchant. If the field
fx_payout_currency is set, then FX is enabled for this merchant.
If FX is enabled, the merchant can collect money in any supported currency.
There are two options, depending on when you need to know.
If a payment is going to be paid out in a different currency, there will be an
fxobject on the payment, with information about the exchange rate.
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
linkssection. In the below example, this merchant can collect in GBP and EUR, and all other currencies will be paid out in the
2 "default_gbp_payout_account": "BA789",
3 "default_eur_payout_account": "BA456"
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.
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.
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
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
fx[amount] will be correct.