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

# 跨币种出款指南

> 使用 UQPAY 账户中的一种币种出款，向受益人以另一种币种收款。

<h2 id="overview">概览</h2>

跨币种出款允许你使用 UQPAY 账户中的一种币种发起出款，由受益人以另一种币种收款。这样就无需单独进行换汇，简化了国际支付流程。

完整的支持币种对清单，请参阅[跨币种出款支持的币种对](/zh/global-account/v1.6/guide/cross-currency-payout-supported-currency-pairs)。

<h2 id="key-benefits">核心优势</h2>

* **流程简化**：无需在出款前单独发起换汇
* **实时汇率**：通过即时报价锁定有竞争力的汇率

<h2 id="step-by-step-implementation">分步实施</h2>

本指南演示以 100 USD 出款、受益人收取等值 THB 的示例。

<h3 id="step-1-create-beneficiary-optional">步骤 1：创建受益人（可选）</h3>

如果你尚未为目标币种（THB）创建受益人，请先创建。

**API 参考：** [Create Beneficiary](/zh/global-account/v1.6/api-reference/create-beneficiary)
**请求：**

```json theme={null}
{
  "email": "crosscurrencyTHB@uqpay.com",
  "nickname": "THB beneficiary",
  "entity_type": "COMPANY",
  "company_name": "UQPAY TECHNOLOGY SG PTE LTD",
  "payment_method": "LOCAL",
  "bank_details": {
    "bank_name": "The Currency Cloud Limited",
    "bank_address": "12 Steward Street, The Steward Building, London, E1 6FQ, GB",
    "bank_country_code": "TH",
    "account_holder": "UQPAY PTE. LTD.",
    "account_currency_code": "THB",
    "clearing_system": "LOCAL",
    "swift_code": "BKKBTHBKXXX",
    "account_number": "123456789012",
    "iban": "123456789012"  
  },
  "address": {
    "country": "TH",
    "city": "th",
    "street_address": "123 Main St",
    "postal_code": "123456",
    "state": "thqwe",
    "nationality": "TH"
  },
  "additional_info": {}
}
```

**响应：**

```json theme={null}
{
  "beneficiary_id": "e15436e2-35e8-4680-920d-4852940c18ba",
  "short_reference_id": "BF250917-WQEQ2D7Q"
}
```

<h3 id="step-2-create-quote">步骤 2：创建报价</h3>

创建报价以锁定当前汇率。报价必须在有效期内使用。

如果传入 `conversion_date`，请先调用 [List Conversion Dates](/zh/global-account/v1.6/api-reference/list-conversion-dates)，确认当天是否为该币种对的可用换汇日期。当前 API 不支持预约未来日期换汇。可用日期已经排除了周末以及该币种对相关的公共假期。

**API 参考：** [Create Quote](/zh/global-account/v1.6/api-reference/create-quote)

**请求：**

```json theme={null}
{
  "sell_currency": "USD",
  "sell_amount": "100",
  "buy_currency": "THB",
  "conversion_date": "2025-09-17",
  "transaction_type": "payout"
}
```

**响应：**

```json theme={null}
{
  "buy_amount": "3160.3",
  "buy_currency": "THB",
  "quote_price": {
    "currency_pair": "USDTHB",
    "direct_rate": "31.60308",
    "inverse_rate": "0.031642",
    "quote_id": "a202824c-2f93-4561-b298-b5bba76d8a10",
    "validity": {
      "valid_from": 1758102115087,
      "valid_to": 1758102415093
    }
  },
  "sell_amount": "100",
  "sell_currency": "USD"
}
```

**关键参数：**

* `sell_currency`：你账户中的币种（USD）
* `sell_amount`：你希望出款的金额（100）
* `buy_currency`：受益人收款的币种（THB）
* `transaction_type`：跨币种出款必须设置为 "payout"

**说明：** 你也可以指定固定的 `buy_amount` 而不是 `sell_amount`，即若希望受益人收到特定金额（例如 1000 THB），系统会按当前汇率自动计算所需的 `sell_amount`。

**从响应中提取以下字段值：**

* `buy_amount`："3160.3"
* `buy_currency`："THB"
* `sell_amount`："100"
* `sell_currency`："USD"
* `quote_id`："a202824c-2f93-4561-b298-b5bba76d8a10"

<h3 id="step-3-create-payout">步骤 3：创建出款</h3>

在报价有效期内，使用报价信息创建出款。

**API 参考：** [Create Payout](/zh/global-account/v1.6/api-reference/create-payout)

**请求：**

```json theme={null}
{
  "currency": "USD",
  "amount": "100",
  "quote_id": "a202824c-2f93-4561-b298-b5bba76d8a10",
  "payout_currency": "THB",
  "payout_amount": "3160.3",
  "purpose_code": "AUDIO_VISUAL_SERVICES",
  "payout_reference": "cross currency INR test",
  "fee_paid_by": "OURS",
  "payout_date": "2025-09-17",
  "beneficiary_id": "e15436e2-35e8-4680-920d-4852940c18ba"
}
```

**响应：**

```json theme={null}
{
  "payout_id": "3357f314-14bd-477a-bdf8-12245e863f98",
  "short_reference_id": "P250917-VKVAKHWQ",
  "payout_status": "READY_TO_SEND"
}
```

**参数映射：**

| 出款参数              | 报价响应            | 说明          |
| ----------------- | --------------- | ----------- |
| `currency`        | `sell_currency` | 账户中的源币种     |
| `amount`          | `sell_amount`   | 待出款金额       |
| `payout_currency` | `buy_currency`  | 受益人收款币种     |
| `payout_amount`   | `buy_amount`    | 受益人收款金额     |
| `quote_id`        | `quote_id`      | 用于锁定汇率的报价标识 |

<h2 id="webhook-notifications">Webhook 通知</h2>

**API 参考：** [Payout Status Webhook](/zh/global-account/v1.6/webhooks/payout-status)
<h3 id="payout-ready-to-send">出款待发送</h3>

当出款被 UQPAY 受理时，你会收到以下 webhook：

```json theme={null}
{
  "version": "V1.6.0",
  "event_name": "PAYOUT",
  "event_type": "payout.ready.send",
  "event_id": "ecefbe35-e1a6-42da-a780-8687e0842dd4",
  "source_id": "3357f314-14bd-477a-bdf8-12245e863f98",
  "data": {
    "account_id": "44fb810d-6bca-411c-964a-3013de34b798",
    "amount": "100",
    "authorisation_steps_required": "0",
    "beneficiary_id": "e15436e2-35e8-4680-920d-4852940c18ba",
    "conversion": {
      "client_rate": "31.60308",
      "currency_pair": "USDTHB"
    },
    "currency": "USD",
    "direct_id": "0",
    "failure_reason": "",
    "failure_returned_amount": "",
    "fee_amount": "0.4",
    "fee_currency": "USD",
    "fee_paid_by": "OURS",
    "payment_date": "2025-09-17",
    "payment_type": "LOCAL",
    "payout_amount": "3160.3",
    "payout_currency": "THB",
    "payout_id": "3357f314-14bd-477a-bdf8-12245e863f98",
    "payout_way": "API",
    "quote_id": "a202824c-2f93-4561-b298-b5bba76d8a10",
    "reason": "audiovisual services",
    "reference": "cross currency INR test",
    "short_reference": "P250917-VKVAKHWQ",
    "short_reference_id": "P250917-VKVAKHWQ",
    "status": "READY_TO_SEND",
    "unique_request_id": ""
  }
}
```

<h3 id="payout-completed">出款完成</h3>

当出款成功处理完成时：

```json theme={null}
{
  "version": "V1.6.0",
  "event_name": "PAYOUT",
  "event_type": "payout.completed",
  "event_id": "58b82ca4-7196-47b8-9ddb-5d7c26a1920f",
  "source_id": "3357f314-14bd-477a-bdf8-12245e863f98",
  "data": {
    "account_id": "44fb810d-6bca-411c-964a-3013de34b798",
    "amount": "100",
    "authorisation_steps_required": "0",
    "beneficiary_id": "e15436e2-35e8-4680-920d-4852940c18ba",
    "conversion": {
      "client_rate": "31.60308",
      "currency_pair": "USDTHB"
    },
    "currency": "USD",
    "direct_id": "0",
    "failure_reason": "",
    "failure_returned_amount": "",
    "fee_amount": "0.4",
    "fee_currency": "USD",
    "fee_paid_by": "OURS",
    "payment_date": "2025-09-17",
    "payment_type": "LOCAL",
    "payout_amount": "3160.3",
    "payout_currency": "THB",
    "payout_id": "3357f314-14bd-477a-bdf8-12245e863f98",
    "payout_way": "API",
    "quote_id": "a202824c-2f93-4561-b298-b5bba76d8a10",
    "reason": "audiovisual services",
    "reference": "cross currency INR test",
    "short_reference": "P250917-VKVAKHWQ",
    "short_reference_id": "P250917-VKVAKHWQ",
    "status": "COMPLETED",
    "unique_request_id": ""
  }
}
```

<h2 id="additional-considerations">其他注意事项</h2>

不同的出款币种可能有特定的参数要求：

<h3 id="inr-payouts">INR 出款</h3>

* 在出款请求的 `documentation` 字段中上传发票文件

<h3 id="cop-payouts">COP 出款</h3>

需要在受益人的 `additional_info` 中补充以下信息：

| 字段          | 类型     | 适用对象  | 说明                          | 示例                                         |
| ----------- | ------ | ----- | --------------------------- | ------------------------------------------ |
| `id_type`   | string | 个人受益人 | 证件类型                        | `PASSPORT`、`NATIONAL_ID`、`DRIVERS_LICENSE` |
| `id_number` | string | 个人受益人 | 证件号码                        | `A1234567`                                 |
| `tax_id`    | string | 企业受益人 | 税号                          | `123456`                                   |
| `msisdn`    | string | 所有受益人 | 手机号码，格式为 `+[国家/地区代码][电话号码]` | `+65111111`                                |

<h2 id="related-documentation">相关文档</h2>

* [Create Beneficiary API](/zh/global-account/v1.6/api-reference/create-beneficiary)
* [Create Quote API](/zh/global-account/v1.6/api-reference/create-quote)
* [Create Payout API](/zh/global-account/v1.6/api-reference/create-payout)
* [Payout Status Webhook](/zh/global-account/v1.6/webhooks/payout-status)
* [跨币种出款支持的币种对](/zh/global-account/v1.6/guide/cross-currency-payout-supported-currency-pairs)