> ## 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.

# 创建换汇 - 通过 API

> 使用换汇 API 在支持的币种之间进行外汇换汇。

<h2 id="step-1-generate-a-quote-id">步骤 1：生成 Quote ID</h2>

在创建换汇订单之前，你必须先获取一个有效的 `quote_id`，它定义了本次交易的汇率和其他参数。

使用 [Create Quote](/zh/global-account/v1.6/api-reference/create-quote) 接口生成该 ID。

请先调用 [List Conversion Dates](/zh/global-account/v1.6/api-reference/list-conversion-dates)，确认当天是否为该币种对的可用换汇日期。Create Quote 和 Create Conversion 当前要求 `conversion_date` 为当天日期，不支持预约未来日期换汇。

创建报价前，请使用 [List Balances](/zh/global-account/v1.6/api-reference/list-balances) 或 [Retrieve Balance](/zh/global-account/v1.6/api-reference/retrieve-balance) 确认卖出币种账户有足够可用余额。

> 重要提示：
>
> * 请确保 `sell_amount` 的值与换汇订单中实际使用的金额完全一致。
>   使用不同的金额可能导致请求被拒绝，因为该值必须与针对此金额生成的 `quote_id` 保持一致。
> * Quote ID 的有效期为 75 秒。请在此时间内创建换汇订单，否则报价将过期。

<h3 id="create-quote-request-example">Create Quote - 请求示例</h3>

```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"
}'
```

> 说明：
>
> * 你可以使用 `buy_amount` 代替 `sell_amount`。
>   系统将自动按另一种币种计算相应金额。
>   注意：`sell_amount` 和 `buy_amount` 只能二选一，不能同时传入。
> * 两个接口要使用同一参数 —— 如果 Create Quote 用的是 `buy_amount`，Create Conversion 也必须用 `buy_amount`；`sell_amount` 同理。
>   保持一致才能确保请求被正常处理。

<h3 id="create-quote-response-example">Create Quote - 响应示例</h3>

```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"
}
```

<h2 id="step-2-create-the-conversion">步骤 2：创建换汇订单</h2>

获取到有效的 Quote ID 后，使用 [Create Conversion](/zh/global-account/v1.6/api-reference/create-conversion) 接口发起换汇订单。

<h3 id="create-conversion-request-example">Create Conversion - 请求示例</h3>

```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"
}'
```

<h3 id="create-conversion-response-example">Create Conversion - 响应示例</h3>

```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"
}
```

提交换汇订单后，系统将触发以下 Webhook：`conversion.funds.awaiting` 和 `conversion.funds.arrived`。

* `conversion.funds.awaiting`：换汇订单已成功提交。
* `conversion.funds.arrived`：源币种账户的资金已扣款。

<h2 id="webhook-example-conversion-funds-awaiting">Webhook 示例：`conversion.funds.awaiting`</h2>

```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"
  }
}
```

<h2 id="webhook-example-conversion-funds-arrived">Webhook 示例：`conversion.funds.arrived`</h2>

```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"
  }
}
```

<h2 id="step-3-order-completion">步骤 3：订单完成</h2>

订单提交后，请等待 UQPAY 审核并批准该笔换汇。

根据换汇订单的处理结果，用户可能收到以下 Webhook 之一：

* `conversion.trade.failed`：换汇订单失败或已取消。
* `conversion.trade.settled`：换汇已成功完成。

<h2 id="webhook-example-conversion-trade-failed">Webhook 示例：`conversion.trade.failed`</h2>

```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"
  }
}
```

<h2 id="webhook-example-conversion-trade-settled">Webhook 示例：`conversion.trade.settled`</h2>

```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"
  }
}
```

审批通过后，换汇流程完成，兑换后的资金将到账至你的账户。

如需核对卖出币种的扣款和买入币种的入账，可使用 [List Balances Transactions](/zh/global-account/v1.6/api-reference/list-balances-transactions)。

如需直接查询某一笔换汇订单，请使用 [Retrieve Conversion](/zh/global-account/v1.6/api-reference/retrieve-conversion)，并传入 Create Conversion 或换汇 Webhook 返回的 `conversion_id`。

若需查询你创建的换汇订单，使用 [List Conversion](/zh/global-account/v1.6/api-reference/list-conversion) 接口。该接口会返回与你的账户关联的全部换汇订单列表。

<h3 id="list-conversion-request-example">List Conversion - 请求示例</h3>

```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}}'
```

<h3 id="list-conversion-response-example">List Conversion - 响应示例</h3>

```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
}
```

***

<h2 id="related">相关：</h2>

* [List Conversion Dates](/zh/global-account/v1.6/api-reference/list-conversion-dates)
* [Create Quote](/zh/global-account/v1.6/api-reference/create-quote)
* [Create Conversion](/zh/global-account/v1.6/api-reference/create-conversion)
* [Retrieve Conversion](/zh/global-account/v1.6/api-reference/retrieve-conversion)
* [List Conversion](/zh/global-account/v1.6/api-reference/list-conversion)
* [Conversion status](/zh/global-account/v1.6/webhooks/conversion-status)