> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedecard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 余额与划拨

> 查询资金主体各币种余额(availableAmount 与授权闸门)，以及公司资金池与独立余额卡之间的同币种闭环划拨：transfer 提交与 transfer-query 结果轮询。

## 📄 正文

余额既是消费的前提，也是授权的实时闸门。本页讲两件事：查余额（`balance`），以及公司资金池与独立余额卡之间的资金划拨（`transfer` + `transfer-query`）。

资金模型一句话回顾：SHARED 卡不持有余额，消费直接扣公司资金池；DEDICATED 卡自持余额，用尽即止。谁持有余额、谁能作为划拨端点，见[持卡主体与资金模型](../basic-concepts/identity-and-funding)；入金路径见[充值入金](./deposits)。

## 查询余额

`GET /open-api-corp/fund/v1/balance` 查询资金主体的各币种余额。

**请求参数**

| 字段            | 类型     | 必填 | 说明                      |
| ------------- | ------ | -- | ----------------------- |
| `subjectType` | String | 是  | `ORGANIZATION` / `CARD` |
| `subjectId`   | String | 是  | ≤20；公司 ID 或卡 ID         |
| `currency`    | String | 否  | `USD` / `HKD`；不传返回全部币种  |

**响应 data** 只有按币种的余额列表 `balances`，每币种一个元素（不回显请求参数）：

| 字段                | 说明                     |
| ----------------- | ---------------------- |
| `currency`        | 币种：`USD` / `HKD`       |
| `availableAmount` | 当前可用余额，与 `currency` 成对 |

**请求示例**

```http theme={null}
GET /open-api-corp/fund/v1/balance?subjectType=ORGANIZATION&subjectId=e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f
```

**响应示例**

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "subjectType": "ORGANIZATION",
    "subjectId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
    "balances": [
      { "currency": "USD", "availableAmount": "1000.00" },
      { "currency": "HKD", "availableAmount": "8000.00" }
    ]
  }
}
```

**错误码**

| 错误码               | 说明                     |
| ----------------- | ---------------------- |
| `SUBJECT_INVALID` | 资金 owner（公司 / 卡）不存在或无效 |

<Note>
  **余额实时作为授权闸门**：SHARED 卡消费时直接扣公司资金池，DEDICATED 卡扣该卡自身余额、用完即止。授权链路见[交易授权与 3DS](./authorization-and-3ds)。
</Note>

## 资金划拨

`POST /open-api-corp/fund/v1/transfer` 在公司资金池与独立余额卡之间划拨，同币种、不换汇、同公司闭环：COMPANY→CARD 为给卡充值（下拨预算），CARD→COMPANY 为回收余额。

**请求参数**

| 字段                 | 类型         | 必填 | 说明                                                        |
| ------------------ | ---------- | -- | --------------------------------------------------------- |
| `transferRef`      | String     | 是  | ≤64；合作伙伴划拨唯一标识（幂等键），字符集 `^[A-Za-z0-9_-]+$`                |
| `organizationId`   | String     | 是  | ≤20；所属公司（划拨闭环边界；双方须同属该公司）                                 |
| `from.subjectType` | String     | 是  | 转出端主体类型：`ORGANIZATION` / `CARD`                           |
| `from.subjectId`   | String     | 是  | ≤36；`ORGANIZATION`→`organizationId`、`CARD`→`cardId`（≤32）  |
| `to.subjectType`   | String     | 是  | 转入端主体类型：`ORGANIZATION` / `CARD`（须与 `from.subjectType` 相异） |
| `to.subjectId`     | String     | 是  | ≤36；取值规则同 `from.subjectId`                                |
| `amount`           | BigDecimal | 是  | 大于 0，≤2 位小数                                               |
| `currency`         | String     | 是  | `USD` / `HKD`，须与双方账户币种一致                                  |
| `remark`           | String     | 否  | ≤256；备注                                                   |

**响应 data**

| 字段             | 类型     | 说明                                  |
| -------------- | ------ | ----------------------------------- |
| `transferId`   | String | 划拨流水外部 id                           |
| `status`       | String | `SUCCESS` / `PROCESSING` / `FAILED` |
| `completeTime` | String | 完成时间 ISO-8601                       |

<Warning>
  **返回 `PROCESSING` 不是终态**：必须用同一 `transferRef` 调 `GET /open-api-corp/fund/v1/transfer-query` 轮询，直到返回 `SUCCESS` 或 `FAILED` 再做后续处理。
</Warning>

**请求示例**

```json theme={null}
{
  "transferRef": "ext-transfer-0001",
  "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "from": { "subjectType": "ORGANIZATION", "subjectId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f" },
  "to":   { "subjectType": "CARD", "subjectId": "5185740066240790530" },
  "amount": "1000.00",
  "currency": "USD",
  "remark": "monthly top-up"
}
```

**响应示例**

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "transferId": "5185740066240790531",
    "status": "SUCCESS",
    "completeTime": "2026-08-19T10:30:00Z"
  }
}
```

**错误码**

| 错误码                  | 说明                            |
| -------------------- | ----------------------------- |
| `TRANSFER_DUPLICATE` | `transferRef` 重复提交            |
| `SUBJECT_INVALID`    | 公司 / 卡不存在、非本合作伙伴、不同公司         |
| `CARD_NOT_DEDICATED` | 卡非独立余额卡（SHARED 卡不持有余额，不可单独划拨） |
| `CARD_INVALID`       | 卡非 ACTIVE                     |
| `CURRENCY_MISMATCH`  | 币种与卡不一致                       |
| `INSUFFICIENT_FUNDS` | 转出方余额不足                       |

<Tip>
  提交划拨遇到网络超时、未收到响应时，用**同一** `transferRef` 重试：若前一次已受理会返回 `TRANSFER_DUPLICATE`，此时改用 `transfer-query` 查询结果即可，不会重复扣款。
</Tip>

## 划拨结果查询

`GET /open-api-corp/fund/v1/transfer-query` 按 `transferRef` 查询单笔划拨的最终结果。

**请求参数**

| 字段            | 类型     | 必填 | 说明             |
| ------------- | ------ | -- | -------------- |
| `transferRef` | String | 是  | ≤64；提交时的划拨唯一标识 |

**响应 data**

| 字段             | 类型     | 说明                                      |
| -------------- | ------ | --------------------------------------- |
| `transferId`   | String | 划拨流水外部 id                               |
| `status`       | String | `SUCCESS` / `PROCESSING`（受理中）/ `FAILED` |
| `completeTime` | String | 完成时间 ISO-8601                           |

**请求示例**

```http theme={null}
GET /open-api-corp/fund/v1/transfer-query?transferRef=ext-transfer-0001
```

**响应示例**

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "transferId": "5185740066240790531",
    "status": "SUCCESS",
    "completeTime": "2026-08-19T10:30:00Z"
  }
}
```

**错误码**

| 错误码                  | 说明                      |
| -------------------- | ----------------------- |
| `TRANSFER_NOT_FOUND` | 查不到该划拨 / 非本合作伙伴（不泄漏存在性） |

## 下一步

* 给资金池或独立余额卡入金：[充值入金](./deposits)
* 划拨与消费如何进入账单与流水（内部调拨计入 `totalDebitAmount`）：[账单与交易查询](./statements-and-transactions)