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

# 充值入金

> 获取收款虚拟账号、客户银行转账、到账通知与充值流水对账的完整入金链路：deposit-info 收款信息、BANK_TRANSFER_INFO 到账事件与 deposit-records 充值流水查询。

## 📄 正文

资金侧只有一个原则：先充值、后消费。公司资金池与独立余额卡均由客户银行转账至各自的收款虚拟账号（VA）入金：公司级 VA 开户时建立，卡级 VA 按需为单卡开通。资金主体（owner）概念见[持卡主体与资金模型](../basic-concepts/identity-and-funding)，资金全链路总览见[资金与对账](./funding-and-reconciliation)。

入金三步流程：

| 步骤       | 动作                   | 接口 / 事件                                   |
| -------- | -------------------- | ----------------------------------------- |
| ① 取收款账户  | 查询该资金主体、该币种的收款 VA 信息 | `GET /open-api-corp/fund/v1/deposit-info` |
| ② 客户银行转账 | 客户按收款信息电汇 / 转账至 VA   | 银行侧动作，无 API                               |
| ③ 到账通知   | 入金到账后 DCS 推送 Webhook | `BANK_TRANSFER_INFO`                      |

到账后资金进入对应主体的余额（查询与后续划拨见[余额与划拨](./balances-and-transfers)）；日常对账用 `deposit-records` 拉取充值流水，与银行水单核对。

## 获取收款账户

`GET /open-api-corp/fund/v1/deposit-info` 返回充值入金的收款账户（VA）信息，供客户汇款。

**请求参数**

| 字段            | 类型     | 必填 | 说明                      |
| ------------- | ------ | -- | ----------------------- |
| `subjectType` | String | 是  | `ORGANIZATION` / `CARD` |
| `subjectId`   | String | 是  | ≤20；公司 ID 或卡 ID         |
| `currency`    | String | 是  | `USD` / `HKD`           |

**响应 data**

| 字段                   | 类型     | 说明                            |
| -------------------- | ------ | ----------------------------- |
| `currency`           | String | `USD` / `HKD`                 |
| `payeeAccountNumber` | String | 收款虚拟账号                        |
| `payeeBankCode`      | String | 收款银行编码                        |
| `payeeBankName`      | String | 银行名称                          |
| `payeeAccountName`   | String | 收款户名（受益人账户名）                  |
| `payeeSwiftCode`     | String | SWIFT/BIC（跨境电汇必填）             |
| `payeeBankAddress`   | String | 银行地址                          |
| `payeeAddress`       | String | 收款人地址                         |
| `remark`             | String | 转账附言要求（如需备注 `organizationId`） |

**请求示例**

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

**响应示例**

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "currency": "USD",
    "payeeAccountNumber": "74012345678901",
    "payeeBankCode": "SCB",
    "payeeBankName": "Standard Chartered Bank (Hong Kong) Limited",
    "payeeAccountName": "EXAMPLE COMPANY LIMITED",
    "payeeSwiftCode": "SCBLHKHH",
    "payeeBankAddress": "4-4A Des Voeux Road Central, Hong Kong",
    "payeeAddress": "Unit 1001, 10/F, Tower 1, Harbour City, Tsim Sha Tsui, Hong Kong",
    "remark": "转账附言请备注 organizationId：e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f"
  }
}
```

**错误码**

| 错误码               | 说明                              |
| ----------------- | ------------------------------- |
| `SUBJECT_INVALID` | 公司 / 卡不存在或无效，或该 owner 未绑定该币种 VA |

<Tip>
  请务必让付款客户按 `remark` 的要求填写转账附言；跨境电汇时向客户提供 `payeeSwiftCode` 与银行、收款人地址。
</Tip>

## 到账通知：BANK\_TRANSFER\_INFO

入金到账后 DCS 推送 Webhook 事件 `BANK_TRANSFER_INFO`，成功与失败由 `status` 区分（`SUCCESS` 为成功）。载荷示例：

```json theme={null}
{
  "webhookId": "7800000000000000951", "webhookType": "BANK_TRANSFER_INFO",
  "businessId": "DEP20260731000000455", "notificationTime": "2026-07-31T09:20:00Z",
  "data": { "depositId": "DEP20260731000000455", "amount": "20000.00", "currency": "USD",
    "payeeAccountNumber": "8613300012345678", "payerName": "EXAMPLE HOLDINGS PTE LTD",
    "payerAccountNumber": "1234567890", "payerBankCode": "003",
    "referenceCode": "REF20260731000455", "status": "SUCCESS",
    "errorCode": null, "errorMessage": null }
}
```

`data` 字段：

| 字段                    | 说明                 |
| --------------------- | ------------------ |
| `depositId`           | 充值流水 ID            |
| `amount` / `currency` | 入金金额与币种            |
| `payeeAccountNumber`  | 入金账号               |
| `payerName`           | 付款方户名              |
| `status`              | 到账状态，`SUCCESS` 为成功 |
| `detail`              | 关联流水明细             |

外层为全站统一的 Webhook 事件外壳：`webhookId`、`webhookType`、`businessId`（本事件为 `depositId`）与 `notificationTime`。

<Warning>
  请以 `status` 判断到账成败，不要把「收到事件」本身当作入金成功。
</Warning>

## 充值流水查询

`GET /open-api-corp/fund/v1/deposit-records` 分页查询充值（VA 入金）流水，供对账。

**请求参数**

| 字段            | 类型      | 必填 | 说明                                        |
| ------------- | ------- | -- | ----------------------------------------- |
| `subjectType` | String  | 否  | `ORGANIZATION` / `CARD`（与 `subjectId` 配对） |
| `subjectId`   | String  | 否  | ≤20；公司 ID 或卡 ID                           |
| `currency`    | String  | 否  | `USD` / `HKD`                             |
| `startTime`   | String  | 否  | ≤32；起始时间 ISO-8601（按到账时间过滤）                |
| `endTime`     | String  | 否  | ≤32；结束时间 ISO-8601                         |
| `page`        | Integer | 否  | 从 1 起，默认 1                                |
| `pageSize`    | Integer | 否  | 1\~100，默认 20                              |

**响应 data** 为标准分页壳：`page`（当前页）、`pageSize`（每页条数）、`total`（总条数）与 `result`（充值流水列表）。流水元素字段：

| 字段                          | 说明                                                |
| --------------------------- | ------------------------------------------------- |
| `depositId`                 | 充值流水 ID                                           |
| `organizationId` / `cardId` | 入金归属：公司资金池入金给 `organizationId`，独立余额卡入金给 `cardId`  |
| `payeeAccountNumber`        | 入账的收款虚拟账号                                         |
| `amount` / `currency`       | 入金金额与币种                                           |
| `status`                    | 到账状态：`SUCCESS`（已到账）/ `PENDING`（处理中）/ `FAILED`（失败） |
| `payerName`                 | 付款方户名                                             |
| `payerAccountNumber`        | 付款方账号                                             |
| `payerBankCode`             | 付款方银行                                             |
| `completeTime`              | 到账时间 ISO-8601（`startTime` / `endTime` 按此过滤）       |

**请求示例**

```http theme={null}
GET /open-api-corp/fund/v1/deposit-records?subjectType=COMPANY&subjectId=e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f&currency=USD&startTime=2026-08-01T00:00:00&endTime=2026-08-19T23:59:59&page=1&pageSize=20
```

**响应示例**

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "page": 1,
    "pageSize": 20,
    "total": 2,
    "result": [
      {
        "depositId": "5185740066240790533",
        "subjectType": "ORGANIZATION",
        "subjectId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
        "payeeAccountNumber": "74012345678901",
        "amount": "1000.00",
        "currency": "USD",
        "status": "SUCCESS",
        "payerName": "EXAMPLE COMPANY LIMITED",
        "payerAccountNumber": "12345678901234",
        "payerBankCode": "HSBC",
        "completeTime": "2026-08-18T15:20:00Z"
      },
      {
        "depositId": "5185740066240790534",
        "subjectType": "ORGANIZATION",
        "subjectId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
        "payeeAccountNumber": "74012345678901",
        "amount": "500.00",
        "currency": "USD",
        "status": "PENDING",
        "payerName": "EXAMPLE COMPANY LIMITED",
        "payerAccountNumber": "12345678901234",
        "payerBankCode": "HSBC",
        "completeTime": "2026-08-19T10:30:00Z"
      }
    ]
  }
}
```

<Note>
  充值入金在账单中计入还款 / 充值合计（`totalRepaymentAmount`，`REPAYMENT` 类交易），账单口径见[账单与交易查询](./statements-and-transactions)；资金池低余额预警（`LOW_BALANCE`）的配置见[管理公司](./managing-companies)。
</Note>

## 下一步

* 到账后查余额、在公司资金池与独立余额卡之间划拨：[余额与划拨](./balances-and-transfers)
* 充值如何进入账单与交易流水、如何冲抵应还：[账单与交易查询](./statements-and-transactions)