余额与划拨 - DCS Technical Documentation

📄 正文

余额既是消费的前提，也是授权的实时闸门。本页讲两件事：查余额（balance），以及公司资金池与独立余额卡之间的资金划拨（transfer + transfer-query）。资金模型一句话回顾：SHARED 卡不持有余额，消费直接扣公司资金池；DEDICATED 卡自持余额，用尽即止。谁持有余额、谁能作为划拨端点，见持卡主体与资金模型；入金路径见充值入金。

查询余额

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` 成对

请求示例

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

响应示例

{
  "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（公司 / 卡）不存在或无效

余额实时作为授权闸门：SHARED 卡消费时直接扣公司资金池，DEDICATED 卡扣该卡自身余额、用完即止。授权链路见交易授权与 3DS。

资金划拨

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

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

请求示例

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

响应示例

{
  "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`	转出方余额不足

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

划拨结果查询

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

请求示例

GET /open-api-corp/fund/v1/transfer-query?transferRef=ext-transfer-0001

响应示例

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

错误码

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

下一步

给资金池或独立余额卡入金：充值入金
划拨与消费如何进入账单与流水（内部调拨计入 totalDebitAmount）：账单与交易查询

​📄 正文

​查询余额

​资金划拨

​划拨结果查询

​下一步

📄 正文

查询余额

资金划拨

划拨结果查询

下一步