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

# 账户间转账

> 使用 Transfer API 在 Global Account 主账户与子账户之间划转资金。

你可以使用内部转账，在 Global Account 主账户与某个子账户之间划转可用余额。常见场景包括：在子账户发起出款前为其划拨资金、将子账户收取的资金归集回主账户，或在账户结构内重新分配余额。

内部转账不同于出款和充值：

| 使用场景           | 应使用的流程                                                                                                                                                                                                                      |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 在主账户与子账户之间划转资金 | [Create Transfer](/zh/global-account/v1.6/api-reference/create-transfer)                                                                                                                                                    |
| 向外部银行账户或受益人打款  | [Create Payout](/zh/global-account/v1.6/api-reference/create-payout)                                                                                                                                                        |
| 通过虚拟账户收取资金     | 由付款方向你的虚拟账户发起银行转账。使用[充值指南](/zh/global-account/v1.6/guide/deposit)、[List Deposits](/zh/global-account/v1.6/api-reference/list-deposits) 和 [Retrieve Deposit](/zh/global-account/v1.6/api-reference/retrieve-deposit) 跟踪入账资金。 |

<h2 id="supported-transfer-directions">
  支持的转账方向
</h2>

转账必须包含当前 API Token 所代表的账户。系统不支持子账户到子账户的直接转账。如果需要将资金从一个子账户转到另一个子账户，请先从源子账户转回主账户，再从主账户转到目标子账户。

| 方向      | `source_account_id` | `target_account_id` | 常见场景             |
| ------- | ------------------- | ------------------- | ---------------- |
| 主账户到子账户 | 主账户 ID              | 子账户 ID              | 在子账户发起出款前为其划拨资金。 |
| 子账户到主账户 | 子账户 ID              | 主账户 ID              | 将子账户收取的资金归集回主账户。 |

源账户和目标账户必须不同。两个账户都必须处于已激活状态，并且双方都必须启用 transfer 产品。

<h2 id="prerequisites">
  前置条件
</h2>

创建转账前，请确认：

* 当前认证账户是源账户或目标账户之一。
* 源账户和目标账户属于同一个主账户 / 子账户关系。
* 两个账户均已激活。如果涉及个人账户，该账户还必须完成验证。
* 两个账户均已启用 transfer 产品，并支持对应转账方向。
* 源账户有足够可用余额覆盖转账金额及可能产生的手续费。
* 你已获得双方的 account ID。对子账户，请使用 Account Center connected account API 返回的 `account_id`，而不是短展示 ID。
* 每次创建请求都使用唯一的 `x-idempotency-key`。

<h2 id="step-1-check-the-source-balance">
  步骤1：检查源账户余额
</h2>

使用 [Retrieve Balance](/zh/global-account/v1.6/api-reference/retrieve-balance) 或 [List Balances](/zh/global-account/v1.6/api-reference/list-balances) 确认源账户有足够可用余额。

```bash theme={null}
curl --location 'https://api-sandbox.uqpaytech.com/api/v1/balances/USD' \
  --header 'Accept: application/json' \
  --header 'x-auth-token: {{token}}'
```

如果可用余额低于转账金额加手续费，创建转账会失败。对于 `IDR`、`JPY` 等零小数币种，转账金额必须为整数。

<h2 id="step-2-create-the-transfer">
  步骤2：创建转账
</h2>

调用 [Create Transfer](/zh/global-account/v1.6/api-reference/create-transfer)，传入源账户、目标账户、币种、金额和转账原因。

```bash theme={null}
curl --location 'https://api-sandbox.uqpaytech.com/api/v1/transfer' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'x-auth-token: {{token}}' \
  --header 'x-idempotency-key: 6a931dcb-ec6f-4f0c-90d7-ff7ebdfdf9b4' \
  --data '{
    "source_account_id": "2cc4f12a-9d1f-4e86-a98a-2f3a67d7e5a1",
    "target_account_id": "6d0af26e-475e-4fd4-a2e7-39f0ea38cbbb",
    "currency": "USD",
    "amount": "1000.00",
    "reason": "Fund sub-account before supplier payout"
  }'
```

成功响应会返回转账标识：

```json theme={null}
{
  "transfer_id": "e08146de-4267-4e76-b35b-f7b34b656a53",
  "short_reference_id": "TQ8K9M2X4"
}
```

请保存这两个标识。`transfer_id` 用于 API 查询，`short_reference_id` 常用于运营、财务或客服沟通。

<h2 id="idempotency">
  幂等性
</h2>

Create Transfer 要求传入 `x-idempotency-key`。请由你的系统生成 UUID，并且只在网络超时或连接中断后重试同一笔请求时复用该值。

如果使用同一个幂等键重试完全相同的请求体，UQPAY 会返回原始转账标识。如果同一个幂等键被用于不同请求体，请求会被拒绝。

推荐的重试方式：

* 仅在网络超时、连接重置或客户端无法确认结果时重试。
* 对同一笔转账的重试复用相同的 `x-idempotency-key`。
* 除非你确实要创建一笔新的转账，否则不要生成新的幂等键。
* 收到响应后，使用 [Retrieve Transfer](/zh/global-account/v1.6/api-reference/retrieve-transfer) 确认最终状态。

<h2 id="step-3-retrieve-the-transfer">
  步骤3：查询转账详情
</h2>

使用 [Retrieve Transfer](/zh/global-account/v1.6/api-reference/retrieve-transfer) 获取最新状态和转账详情。

```bash theme={null}
curl --location 'https://api-sandbox.uqpaytech.com/api/v1/transfer/e08146de-4267-4e76-b35b-f7b34b656a53' \
  --header 'Accept: application/json' \
  --header 'x-auth-token: {{token}}'
```

响应会包含源账户名称、目标账户名称、转账金额、转账原因、状态和相关时间。

常见转账状态：

| 状态          | 含义                                     |
| ----------- | -------------------------------------- |
| `completed` | 转账已成功完成。                               |
| `failed`    | 转账失败。请先检查请求参数、账户状态、产品配置和源账户余额，再决定是否重试。 |

<h2 id="step-4-list-transfers-for-reconciliation">
  步骤4：列出转账用于对账
</h2>

使用 [List Transfers](/zh/global-account/v1.6/api-reference/list-transfers) 对一段时间内的内部资金划转进行对账。

```bash theme={null}
curl --location 'https://api-sandbox.uqpaytech.com/api/v1/transfer?page_size=10&page_number=1&currency=USD&transfer_status=completed' \
  --header 'Accept: application/json' \
  --header 'x-auth-token: {{token}}'
```

你可以按以下字段筛选：

* `page_size` 和 `page_number`
* `start_time` 和 `end_time`
* `transfer_status`
* `currency`

对账时可使用响应中的 `transfer_id`、`short_reference_id`、`source_account_name`、`destination_account_name`、`transfer_amount` 和 `complete_time` 匹配内部账务记录。

<h2 id="common-validation-failures">
  常见校验失败
</h2>

| 失败原因             | 处理方式                                                |
| ---------------- | --------------------------------------------------- |
| 源账户和目标账户相同       | 为 `source_account_id` 和 `target_account_id` 使用不同账户。 |
| 转账不是主账户与子账户之间的划转 | 通过主账户中转资金。系统不支持子账户到子账户的直接转账。                        |
| 账户未激活或未完成验证      | 创建转账前完成账户验证或激活。                                     |
| Transfer 产品未启用   | 联系 UQPAY 支持，为两个账户及所需转账方向启用 transfer 产品。             |
| 余额不足             | 检查源账户余额，并预留可能产生的转账手续费。                              |
| 金额无效             | 使用正数金额，最多保留两位小数。`IDR` 和 `JPY` 必须使用整数金额。             |
| 幂等键被用于不同请求体      | 对新转账生成新的幂等键；如果是重试，请使用原始请求体。                         |

<h2 id="related-api-reference">
  相关 API Reference
</h2>

* [Create Transfer](/zh/global-account/v1.6/api-reference/create-transfer)
* [Retrieve Transfer](/zh/global-account/v1.6/api-reference/retrieve-transfer)
* [List Transfers](/zh/global-account/v1.6/api-reference/list-transfers)
* [List Balances](/zh/global-account/v1.6/api-reference/list-balances)
* [Retrieve Balance](/zh/global-account/v1.6/api-reference/retrieve-balance)