> ## Documentation Index > Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](/global-account/v1.6/api-reference/create-quote) API to generate this ID. Call [List Conversion Dates](/global-account/v1.6/api-reference/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](/global-account/v1.6/api-reference/list-balances) or [Retrieve Balance](/global-account/v1.6/api-reference/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 theme={null} 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 ```json theme={null} { "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](/global-account/v1.6/api-reference/create-conversion) API to initiate the conversion order. ### Create Conversion - Request example ```curl theme={null} 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 ```json theme={null} { "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` ```json theme={null} { "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` ```json theme={null} { "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` ```json theme={null} { "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` ```json theme={null} { "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](/global-account/v1.6/api-reference/list-balances-transactions). To check one conversion order directly, use the [Retrieve Conversion](/global-account/v1.6/api-reference/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](/global-account/v1.6/api-reference/list-conversion) API. This endpoint retrieves a list of all conversion orders associated with your account. ### List Conversion - Request example ```curl theme={null} 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 ```curl theme={null} { "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: * [List Conversion Dates](/global-account/v1.6/api-reference/list-conversion-dates) * [Create Quote](/global-account/v1.6/api-reference/create-quote) * [Create Conversion](/global-account/v1.6/api-reference/create-conversion) * [Retrieve Conversion](/global-account/v1.6/api-reference/retrieve-conversion) * [List Conversion](/global-account/v1.6/api-reference/list-conversion) * [Conversion status](/global-account/v1.6/webhooks/conversion-status)