Create Conversion - via API - UQPAY Developer Docs

Step 1: Generate a Quote ID

Before creating a conversion order, you must obtain a valid quote_id, which defines the exchange rate and other parameters for the transaction. Use the Create Quote API to generate this ID. Call List Conversion Dates first to confirm that today’s date is available for the currency pair. Create Quote and Create Conversion currently require conversion_date to be today’s date and do not support scheduling a future conversion date. Before creating the quote, use List Balances or Retrieve Balance to confirm that the sell currency account has enough available balance.

Important:

Ensure that the sell_amount value exactly matches the amount you intend to use for the conversion order.
Using a different amount may result in the request being rejected, as it must align with the quote_id generated for that specific amount.

A Quote ID is valid for 75 seconds. You must create the conversion within this time frame; otherwise, the quote will expire.

Create Quote - Request example

curl --location 'https://api-sandbox.uqpaytech.com/api/v1/conversion/quote' \
--header 'x-on-behalf-of;' \
--header 'x-idempotency-key: {{$uuid}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-auth-token: {{$token}}' \
--data '{
  "sell_currency": "USD",
  "buy_currency": "SGD",
  "conversion_date": "2025-11-13",
  "sell_amount": "10.00"
}'

Notes:

You can use buy_amount instead of sell_amount.
The system will automatically calculate the corresponding amount in the other currency.
However, make sure to include only one of these parameters — either sell_amount or buy_amount, but not both.

Use the same parameter in both APIs — if buy_amount is used in Create Quote, use buy_amount in Create Conversion, and the same applies to sell_amount.
This ensures consistency and successful processing.

Create Quote - Response example

{
    "buy_amount": "12.68",
    "buy_currency": "SGD",
    "quote_price": {
        "currency_pair": "USDSGD",
        "direct_rate": "1.268334",
        "inverse_rate": "0.788436",
        "quote_id": "03858526-27af-4086-a147-279e7054f111",
        "validity": {
            "valid_from": 1762999020113,
            "valid_to": 1762999095113
        }
    },
    "sell_amount": "10",
    "sell_currency": "USD"
}

Step 2: Create the Conversion

Once you have a valid Quote ID, use the Create Conversion API to initiate the conversion order.

Create Conversion - Request example

curl --location 'https://api-sandbox.uqpaytech.com/api/v1/conversion' \
--header 'x-on-behalf-of;' \
--header 'x-idempotency-key: {{$uuid}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-auth-token: {{$token}}' \
--data '{
  "quote_id": "03858526-27af-4086-a147-279e7054f111",
  "buy_currency": "SGD",
  "sell_currency": "USD",
  "conversion_date": "2025-11-13",
  "sell_amount": "10.00"
}'

Create Conversion - Response example

{
    "buy_amount": "12.68",
    "buy_currency": "SGD",
    "conversion_id": "70404eb3-21ca-44b8-9ced-f673646c9a22",
    "created_date": "2025-11-13T09:57:24.585528229+08:00",
    "currency_pair": "USDSGD",
    "reference": "XC251113-CFOXI1XV",
    "sell_amount": "10",
    "sell_currency": "USD",
    "short_reference_id": "XC251113-CFOXI1XV",
    "status": "AWAITING_FUNDS"
}

After you make the conversion order, the system will trigger the following webhooks: conversion.funds.awaiting and conversion.funds.arrived.

conversion.funds.awaiting: The conversion order has been placed successfully.
conversion.funds.arrived: The funds in the sell currency account have been deducted.

Webhook example: `conversion.funds.awaiting`

{
  "version": "V1.6.0",
  "event_name": "CONVERSION",
  "event_type": "conversion.funds.awaiting",
  "event_id": "a26fafca-a110-4fcc-bb5a-b120c26f9b1d",
  "source_id": "06cf9f74-b826-4095-82c5-18a5172a4a44",
  "data": {
    "account_id": "3b9ba144-b0fd-4729-af0a-b4f09e196a9a",
    "account_name": "UQPAY TEST",
    "buy_amount": "1.26",
    "buy_currency": "SGD",
    "client_rate": "1.268334",
    "conversion_id": "06cf9f74-b826-4095-82c5-18a5172a4a44",
    "conversion_status": "AWAITING_FUNDS",
    "conversion_way": "",
    "create_time": "2025-11-12T10:02:16+08:00",
    "creator": "TESTER1",
    "direct_id": "0",
    "sell_amount": "1",
    "sell_currency": "USD",
    "settle_time": "0001-01-01T00:00:00Z",
    "short_reference_id": "C251112-O7R1STKQ"
  }
}

Webhook example: `conversion.funds.arrived`

{
  "version": "V1.6.0",
  "event_name": "CONVERSION",
  "event_type": "conversion.funds.arrived",
  "event_id": "11b330d7-af93-4027-a02a-c57532f3fb5f",
  "source_id": "06cf9f74-b826-4095-82c5-18a5172a4a44",
  "data": {
    "account_id": "3b9ba144-b0fd-4729-af0a-b4f09e196a9a",
    "account_name": "UQPAY TEST",
    "buy_amount": "1.26",
    "buy_currency": "SGD",
    "client_rate": "1.268334",
    "conversion_id": "06cf9f74-b826-4095-82c5-18a5172a4a44",
    "conversion_status": "FUNDS_ARRIVED",
    "conversion_way": "",
    "create_time": "2025-11-12T10:02:16+08:00",
    "creator": "TESTER1",
    "direct_id": "0",
    "sell_amount": "1",
    "sell_currency": "USD",
    "settle_time": "0001-01-01T00:00:00Z",
    "short_reference_id": "C251112-O7R1STKQ"
  }
}

Step 3: Order Completion

Once the order is submitted, please wait for UQPAY to review and approve the currency exchange. Users may receive one of the following webhooks, depending on the outcome of the conversion order:

conversion.trade.failed: The conversion order has failed or been cancelled.
conversion.trade.settled: The conversion has been successfully completed.

Webhook example: `conversion.trade.failed`

{
  "version": "V1.6.0",
  "event_name": "CONVERSION",
  "event_type": "conversion.trade.failed",
  "event_id": "6ba52ad0-ee1b-4bfd-9bb6-aad7eb89e36f",
  "source_id": "75255093-f67b-494c-8839-ddb5847025bb",
  "data": {
    "account_id": "3b9ba144-b0fd-4729-af0a-b4f09e196a9a",
    "account_name": "UQPAY TEST",
    "buy_amount": "1.27",
    "buy_currency": "SGD",
    "client_rate": "1.268334",
    "conversion_id": "75255093-f67b-494c-8839-ddb5847025bb",
    "conversion_status": "TRADE_FAILED",
    "conversion_way": "",
    "create_time": "2025-11-12T10:14:06+08:00",
    "creator": "TESTER1",
    "direct_id": "0",
    "sell_amount": "1",
    "sell_currency": "USD",
    "settle_time": "2025-11-12T11:42:11+08:00",
    "short_reference_id": "C251112-9CNSX8OR"
  }
}

Webhook example: `conversion.trade.settled`

{
  "version": "V1.6.0",
  "event_name": "CONVERSION",
  "event_type": "conversion.trade.settled",
  "event_id": "6ba52ad0-ee1b-4bfd-9bb6-aad7eb89e36f",
  "source_id": "75255093-f67b-494c-8839-ddb5847025bb",
  "data": {
    "account_id": "3b9ba144-b0fd-4729-af0a-b4f09e196a9a",
    "account_name": "UQPAY TEST",
    "buy_amount": "1.27",
    "buy_currency": "SGD",
    "client_rate": "1.268334",
    "conversion_id": "75255093-f67b-494c-8839-ddb5847025bb",
    "conversion_status": "TRADE_SETTLED",
    "conversion_way": "",
    "create_time": "2025-11-12T10:14:06+08:00",
    "creator": "TESTER1",
    "direct_id": "0",
    "sell_amount": "1",
    "sell_currency": "USD",
    "settle_time": "2025-11-12T11:42:11+08:00",
    "short_reference_id": "C251112-9CNSX8OR"
  }
}

After approval, the conversion process will be completed, and the exchanged funds will be available in your account. If you need to reconcile the debit from the sell currency and the credit to the buy currency, use List Balances Transactions. To check one conversion order directly, use the Retrieve Conversion API with the conversion_id returned by Create Conversion or conversion webhooks. To view the conversion orders you’ve created, use the List Conversion API. This endpoint retrieves a list of all conversion orders associated with your account.

List Conversion - Request example

curl --location 'https://api-sandbox.uqpaytech.com/api/v1/conversion?page_size=10&page_number=1' \
--header 'Accept: application/json' \
--header 'x-auth-token: {{$token}}'

List Conversion - Response example

{
    "data": [
        {
            "account_name": "UQPAY TEST",
            "conversion_id": "70404eb3-21ca-44b8-9ced-f673646c9a22",
            "short_reference_id": "XC251113-CFOXI1XV",
            "creator": "UQPAY TEST",
            "client_rate": "1.268334",
            "buy_amount": "12.68",
            "buy_currency": "SGD",
            "sell_amount": "10",
            "sell_currency": "USD",
            "create_time": "2025-11-13T09:57:25+08:00",
            "settle_time": "2025-11-13T00:00:00+08:00",
            "conversion_status": "AWAITING_FUNDS"
        }
    ],
    "total_items": 1,
    "total_pages": 1
}

Overview

Virtual Account

Payout & Deposit

Foreign Exchange

Reference

Create Conversion - via API

Step 1: Generate a Quote ID

Create Quote - Request example

Create Quote - Response example

Step 2: Create the Conversion

Create Conversion - Request example

Create Conversion - Response example

Webhook example: `conversion.funds.awaiting`

Webhook example: `conversion.funds.arrived`

Step 3: Order Completion

Webhook example: `conversion.trade.failed`

Webhook example: `conversion.trade.settled`

List Conversion - Request example

List Conversion - Response example

​Step 1: Generate a Quote ID

​Create Quote - Request example

​Create Quote - Response example

​Step 2: Create the Conversion

​Create Conversion - Request example

​Create Conversion - Response example

​Webhook example: conversion.funds.awaiting

​Webhook example: conversion.funds.arrived

​Step 3: Order Completion

​Webhook example: conversion.trade.failed

​Webhook example: conversion.trade.settled

​List Conversion - Request example

​List Conversion - Response example

​Related:

Step 1: Generate a Quote ID

Create Quote - Request example

Create Quote - Response example

Step 2: Create the Conversion

Create Conversion - Request example

Create Conversion - Response example

Webhook example: `conversion.funds.awaiting`

Webhook example: `conversion.funds.arrived`

Step 3: Order Completion

Webhook example: `conversion.trade.failed`

Webhook example: `conversion.trade.settled`

List Conversion - Request example

List Conversion - Response example

Related: