Using Embedded FX

⚠️

Note: This feature is currently available only upon request. Attempting to place an Embedded FX order in production without having it enabled will result in a 400 response.

If you’re interested in enabling Embedded FX in your production environment, you can sign up here or contact your account manager for assistance.

What is Embedded FX?

Embedded FX is a new feature within the existing Runa Order API. It 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 Synchronous or Asynchronous mode guides for detailed instructions. The key difference is that we've relaxed the validation requirement for the payment_method currency to match the currency of your order items.

Rules:

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.

Here's an example of a basic request body with embedded FX:

{
  "payment_method": {
    "type": "ACCOUNT_BALANCE",
    "currency": "GBP"
  },
  "items": [
    {
      "face_value": 10,
      "distribution_method": {
        "type": "EMAIL",
        "email_address": "[email protected]"
      },
      "products": {
        "type": "MULTIPLE",
        "values": ["AMZ-US", "AMC-US"]
      }
    }
  ]
}

If the order was successfully processed, the client will receive the following response, including a 200 OK status:

{
  "id": "O-01234567890ABCDEFGHIJK",
  "status": "COMPLETED",
  "created_at": "2023-11-14T14:37:54.093824+00:00",
  "completed_at": "2023-11-14T15:25:07.728788+00:00",
  "description": "My first order.",
  "payment_method": {
    "type": "ACCOUNT_BALANCE",
    "currency": "GBP"
  },
  "currency": "GBP",
  "total_discount": "0.00",
  "total_price": "8.49",
  "items": [
    {
      "id": "E-0123456789ABCDEFG",
      "distribution_method": {
        "type": "EMAIL",
        "email_address": "[email protected]"
      },
      "products": {
        "type": "MULTIPLE",
        "values": ["AMZ-US", "AMC-US"]
      },
      "currency": "USD",
      "face_value": "10.00",
      "price": "10.00",
      "redemption_url": "https://payout.runa.io/ej99mjdmf958324d2f38",
      "payout": {
        "status": "ACTIVE",
        "status_updated_at": "2023-11-23T08:29:15.940064+00:00",
        "url": "https://example-test.spend.runa.io/055306f2-466b-4fc4-8b59-9538eaf1be92",
        "expiry_date": null
      }
    }
  ],
  "transaction_detail": {
    "USD": {
      "value": "10.00",
      "fx": {
        "rate": "1.2",
        "rate_symbol": "GBPUSD",
        "fee": {
          "value": "0.16",
          "currency": "GBP"
        }
      }
    }
  }
}

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.

💹

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 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

Although we have listed the currencies currently supported by the Runa API, Embedded FX will initially support a limited set of these currencies. We will continue to add more as we enhance the feature. Please find the list of supported currencies here.