Exchange Rates

Use exchange rates to check whether UQPAY has a current rate for a currency pair before you create a conversion or cross-currency payout. The List Current Rates API returns the latest available rates for one or more currency pairs, plus any requested pairs that are currently unavailable. Exchange rates are useful for discovery, pricing previews, and operational checks. They do not create a quote_id and do not reserve a rate for execution. To execute a conversion or cross-currency payout, create a quote immediately before submitting the transaction.

When to use exchange rates

Call List Current Rates when you need to:

Show available FX pairs in your UI.
Check whether a currency pair is currently supported before calling Create Quote.
Refresh indicative buy and sell prices for treasury or operations teams.
Detect unsupported or temporarily unavailable pairs through unavailable_currency_pairs.
Run pricing checks for a master account or a sub-account before creating a conversion or payout.

For an executable rate, use Create Quote. The quote response returns a quote_id, the calculated buy_amount or sell_amount, and a validity window.

Exchange rates versus quotes

Capability	List Current Rates	Create Quote
Primary purpose	Check current available rates and pair availability.	Lock the transaction parameters for execution.
Returns a `quote_id`	No	Yes
Calculates exact transaction amount	No	Yes
Has a validity window	Response includes `last_updated`, but no execution window.	Quote must be used within its `validity` window.
Used by Create Conversion or Create Payout	No, use it for pre-checks only.	Yes, pass the returned `quote_id` to the create request.

buy_price and sell_price are for rate previews and currency-pair availability checks only. They are not executable rates and do not lock the final transaction amount. When a customer confirms a conversion or cross-currency payout, call Create Quote and use the returned quote_id and calculated amounts.

Step 1: Query current rates

You can query specific currency pairs or omit currency_pairs to return all available pairs.

Query selected currency pairs

Pass currency_pairs as a comma-separated list. Each pair must be a six-letter uppercase code such as USDEUR or USDJPY. You can request up to 100 pairs.

curl --location 'https://api-sandbox.uqpaytech.com/api/v1/exchange/rates?currency_pairs=USDEUR,USDJPY,JPYKRW' \
  --header 'Accept: application/json' \
  --header 'x-auth-token: {{token}}'

Query all available rates

Omit currency_pairs when you need the full list of currently available currency pairs.

curl --location 'https://api-sandbox.uqpaytech.com/api/v1/exchange/rates' \
  --header 'Accept: application/json' \
  --header 'x-auth-token: {{token}}'

If you are checking rates for a sub-account, include the sub-account ID in x-on-behalf-of.

curl --location 'https://api-sandbox.uqpaytech.com/api/v1/exchange/rates?currency_pairs=USDSGD' \
  --header 'Accept: application/json' \
  --header 'x-auth-token: {{token}}' \
  --header 'x-on-behalf-of: {{sub_account_id}}'

Step 2: Read the response

A successful response wraps the result in a data object: available rates in data.rates, unavailable requested pairs in data.unavailable_currency_pairs, and the rate timestamp in data.last_updated.

{
  "data": {
    "rates": [
      {
        "currency_pair": "USDEUR",
        "buy_price": "0.8688",
        "sell_price": "0.8757"
      },
      {
        "currency_pair": "USDJPY",
        "buy_price": "161.4914",
        "sell_price": "162.7986"
      }
    ],
    "unavailable_currency_pairs": [
      "JPYKRW"
    ],
    "last_updated": "2026-07-16T16:15:58+08:00"
  }
}

Field	Meaning
`rates`	The rate records currently available for the requested pairs, or all available pairs if no filter was provided.
`currency_pair`	The pair that the rate applies to. The order may follow market convention, so always read the returned value.
`buy_price`	The current buy price, rounded to 4 decimal places.
`sell_price`	The current sell price, rounded to 4 decimal places.
`unavailable_currency_pairs`	Requested pairs that are unsupported or have no available rate at the moment.
`last_updated`	The timestamp of the last rate update in ISO 8601 format.

If a requested pair appears in unavailable_currency_pairs, do not continue to quote creation for that pair. Show a clear message to the user or route the transaction through another supported currency pair.

Step 3: Use rates before creating a quote

Use List Current Rates as a pre-check, then use Create Quote when the user or system is ready to execute. Recommended flow:

Query current rates for the pair you plan to use.
If the pair is unavailable, stop the flow and ask the user to choose another pair.
If the pair is available, show the rate preview or continue to your approval flow.
Immediately before execution, call Create Quote.
Submit Create Conversion or Create Payout with the returned quote_id within the quote validity window.

Sub-account pricing

The endpoint accepts x-on-behalf-of. Use it when you need the rate context for a specific sub-account:

For a master account operation, omit x-on-behalf-of.
For a sub-account operation, set x-on-behalf-of to the sub-account account_id.
Use the same account context when you later call Create Quote and the corresponding create endpoint.

Keeping the same account context avoids mismatches in FX product configuration, currency enablement, and pricing.

Common validation issues

Issue	How to resolve
`currency_pairs` contains lowercase values	Send six-letter uppercase pairs such as `USDEUR`.
More than 100 pairs are requested	Split the request into multiple calls.
A pair is returned in `unavailable_currency_pairs`	Do not create a quote for that pair. Select another supported pair or try again later.
Create Quote fails after rates looked available	Confirm the account context, FX product configuration, quote `transaction_type`, and conversion date.
The displayed rate differs from the quote rate	The quote is the executable rate. Refresh the preview and create a new quote before execution.

Overview

Virtual Account

Payout & Deposit

Foreign Exchange

Reference

When to use exchange rates

Exchange rates versus quotes

Step 1: Query current rates

Query selected currency pairs

Query all available rates

Step 2: Read the response

Step 3: Use rates before creating a quote

Sub-account pricing

Common validation issues

​When to use exchange rates

​Exchange rates versus quotes

​Step 1: Query current rates

​Query selected currency pairs

​Query all available rates

​Step 2: Read the response

​Step 3: Use rates before creating a quote

​Sub-account pricing

​Common validation issues

​Related API reference

​Related guides

When to use exchange rates

Exchange rates versus quotes

Step 1: Query current rates

Query selected currency pairs

Query all available rates

Step 2: Read the response

Step 3: Use rates before creating a quote

Sub-account pricing

Common validation issues

Related API reference

Related guides