创建换汇 - 通过 API - UQPAY Developer Docs

步骤 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"
}

提交换汇订单后，系统将触发以下 Webhook：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 接口。该接口会返回与你的账户关联的全部换汇订单列表。

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
}

Conversion status

​步骤 1：生成 Quote ID

​Create Quote - 请求示例

​Create Quote - 响应示例

​步骤 2：创建换汇订单

​Create Conversion - 请求示例

​Create Conversion - 响应示例

​Webhook 示例：conversion.funds.awaiting

​Webhook 示例：conversion.funds.arrived

​步骤 3：订单完成

​Webhook 示例：conversion.trade.failed

​Webhook 示例：conversion.trade.settled

​List Conversion - 请求示例

​List Conversion - 响应示例

​相关：