Live FX rates

A live FX rate is an indicative exchange rate for a currency pair that Mambu Payments retrieves on demand from your liquidity or payment provider. It can be used to show a live FX rate to your users before you create a payment order that includes a currency conversion.

ℹ️
Live FX rates are currently only available for Mastercard Cross-Border Services. More liquidity and payment providers will be supported in the future.

How it works

Send a request to GET /v1/live_fx_rates with a currency pair. Mambu Payments requests the current rate from your provider, normalizes it, and returns it in the same response.

A live FX rate is indicative, so the rate the provider applies to a payment order can differ. To convert currencies, create a payment order with an fx block.

%%{init: {'themeVariables': {'actorBkg': '#E1F3F2', 'actorBorder': '#2FA5A1', 'actorLineColor': '#2FA5A1'}}}%%
sequenceDiagram
    participant Y as Your system
    participant M as Mambu Payments
    participant P as Your provider

    Y->>M: GET /v1/live_fx_rates
    M->>P: Request current FX rates
    P-->>M: FX rates
    M-->>Y: Records (normalized)

Retrieve live FX rates

Get the ID of your connected account for Mastercard Cross-Border Services. Go to Settings > Connectivity > Connectors or use the List connected accounts API endpoint
Choose a currency pair, for example EUR/USD
Send the request

Query parameter	Type	Required	Description
`connected_account_id`	string	`required`	ID of the connected account.
`symbol`	string	`required`	Currency pair, written `<base currency>/<quote currency>` with two different ISO 4217 codes. Mambu Payments validates the pair.
`recipient_instrument_type`	enum	`optional`	Filters rates by recipient account type: `bank_account` or `wallet`. Only for Matercard Cross-Border Services.

Request

curl --request GET \
     --url 'https://sandbox.numeral.io/v1/live_fx_rates?connected_account_id=9a2d6c41-7f3e-4b85-a0c9-1e5f8d2b7a64&symbol=EUR/USD' \
     --header 'Accept: application/json' \
     --header 'X-API-Key: Your_API_Key'

Response

{
  "records": [
    {
      "connected_account_id": "9a2d6c41-7f3e-4b85-a0c9-1e5f8d2b7a64",
      "symbol": "EUR/USD",
      "bid_price": "1.08500",
      "valid_from": "2026-10-06T08:00:00Z",
      "valid_until": "2026-10-06T09:00:00Z",
      "recipient_instrument_type": "bank_account"
    }
  ]
}

Field	Type	Description
`records`	array	One record per live FX rate.
`connected_account_id`	string	ID of the connected account that returned the rate.
`symbol`	string	Same currency pair as in your request.
`bid_price`	string	Rate for the pair. See Key concepts.
`valid_from`	datetime	Start of the validity window, in UTC.
`valid_until`	datetime	End of the validity window, in UTC.
`recipient_instrument_type`	enum	Recipient account type the rate applies to: `bank_account` or `wallet`.

Live FX rates can be used to calculate the amount sent or received when creating a processing a payment order using Mambu Payments and your preferred partner bank.

Goal	Calculation	Result
Send 1,000.00 EUR	1,000.00 × 1.08500	1,085.00 USD
Deliver exactly 1,000.00 USD	1,000.00 ÷ 1.08500	921.66 EUR

Related resources

Type	Page
Reference	List live FX rates
Reference	Create a payment order
Guide	Send payments
Guide	FX quotes