By default, this feature applies standard FX fees in production. If you haven’t negotiated custom rates, those standard fees will apply. To learn more or discuss custom pricing, talk to an expert or contact your account manager

​
What is Runa FX?

Runa FX allows you to top up your balance in your preferred currency and seamlessly pay for orders across different countries. Runa Embedded FX handles currency exchanges in real-time at the point of payment, offering a smooth, cost-effective, and efficient solution for hassle-free international spending.

​
Placing an Embedded FX order

Placing an Embedded FX order follows the same request schema as the existing method for placing orders via the /v2/order endpoint. You can refer to the ordering guides or create order reference for detailed instructions. To use embedded FX you should specify the desired billing currency in the payment_method object.

​
Requirements

  1. You must have sufficient funds in your payment_method balance to cover the entire order amount. For example, if purchasing a $10 payout link using your GBP account balance, you must have at least $10 worth of GBP available.
  2. All order items must still be from the same country, ensuring they are in the same currency.
  3. This feature currently supports only single item orders.
  4. This feature currently supports only synchronous orders.

​
Example

Here’s an example of a basic request and response for an order with embedded FX.
  • The payment_method.currency has been set to GBP.
  • The products specified in the items.products array are US products priced in USD.
{
  "payment_method": {
    "type": "ACCOUNT_BALANCE",
    "currency": "GBP"
  },
  "items": [
    {
      "face_value": 10,
      "distribution_method": {
        "type": "EMAIL",
        "email_address": "fred@bloggs.com"
      },
      "products": {
        "type": "MULTIPLE",
        "values": ["AMZ-US", "AMC-US"]
      }
    }
  ]
}
In the above example, a $10 USD payout link has been purchased using a GBP balance. To help you understand the costs involved in making this embedded FX order, we provide a transaction_detail object that breaks down each component:
  1. You purchased $10.00 USD, as shown in the transaction_detail value.
  2. An exchange rate (fx.rate) of 1.2 was applied for converting GBP to USD. (See below for more details on how our rates work.)
  3. A fee of £0.16 GBP was charged for the currency conversion. This fee is included in the total_price of the order and is always charged in the currency specified for the payment_method.

​
Rates and Fees

​
FX Rates

The fx_rate provided by our API reflects the exchange rate applied for the Embedded FX conversion at the time of placing the order. You can use the fx.rate_symbol to determine the equivalent amount in the other currency within the currency pair.

For example, if the fx.rate is 1.2 and the fx.rate_symbol is GBPUSD:
  • When converting GBP to USD: If your payment_method currency is GBP and you’re purchasing an item priced at $10 USD, the calculation is: $10 ÷ 1.2 = £8.33
  • When converting USD to GBP: If your payment_method currency is USD and you’re purchasing an item priced at £10 GBP, the calculation is: £10 × 1.2 = $12

​
FX Fees

The fee is always calculated and included in the billing currency, so that you can operate in one currency. The fee amount depends on the transaction value, the currency of the order, and the fee rate agreed with us. If you’re already using our FX platform with custom fees, those same rates will apply. If you haven’t set up custom fees, a standard fee rate of 1.9% will be applied to the conversion. For more information on custom FX fee rates, please contact your Account Manager.

​
Currencies

Embedded FX support varies by currency. Check the currencies page for detail on what is supported today. We are actively working to expand support for more combinations.

Currencies

View the list of currencies supported by the Runa API.