Documentation Index
Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/llms.txt
Use this file to discover all available pages before exploring further.
步骤 1：生成 Quote ID
在创建换汇订单之前，你必须先获取一个有效的 quote_id，它定义了本次交易的汇率和其他参数。
使用 Create Quote 接口生成该 ID。
重要提示：
- 请确保
sell_amount 的值与换汇订单中实际使用的金额完全一致。
使用不同的金额可能导致请求被拒绝，因为该值必须与针对此金额生成的 quote_id 保持一致。
- Quote ID 的有效期为 75 秒。请在此时间内创建换汇订单，否则报价将过期。
Create Quote - 请求示例
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"
}'
说明：
- 你可以使用
buy_amount 代替 sell_amount。
系统将自动按另一种币种计算相应金额。
注意：sell_amount 和 buy_amount 只能二选一，不能同时传入。
- 两个接口要使用同一参数 —— 如果 Create Quote 用的是
buy_amount，Create Conversion 也必须用 buy_amount；sell_amount 同理。
保持一致才能确保请求被正常处理。
Create Quote - 响应示例
{
"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"
}
步骤 2：创建换汇订单
获取到有效的 Quote ID 后，使用 Create Conversion 接口发起换汇订单。
Create Conversion - 请求示例
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 - 响应示例
{
"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"
}
conversion.funds.awaiting 和 conversion.funds.arrived。
conversion.funds.awaiting：换汇订单已成功提交。conversion.funds.arrived：源币种账户的资金已扣款。
Webhook 示例：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 示例：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"
}
}
步骤 3：订单完成
订单提交后，请等待 UQPAY 审核并批准该笔换汇。
根据换汇订单的处理结果，用户可能收到以下 Webhook 之一：
conversion.trade.failed：换汇订单失败或已取消。conversion.trade.settled：换汇已成功完成。
Webhook 示例：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 示例：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"
}
}
List Conversion - 请求示例
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 - 响应示例
{
"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
}
