GuidesAPI ReferenceChangelog
Log In
Guides

Create Conversion - via API

Use the Conversion API to perform foreign exchange conversions between supported currencies.

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.

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.

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
}


Related:

Updated 7 months ago