充值入金 - DCS Technical Documentation

📄 正文

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

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

到账后资金进入对应主体的余额（查询与后续划拨见余额与划拨）；日常对账用 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`）

请求示例

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

响应示例

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

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

到账通知：BANK_TRANSFER_INFO

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

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

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

充值流水查询

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` 按此过滤）

请求示例

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

响应示例

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

充值入金在账单中计入还款 / 充值合计（totalRepaymentAmount，REPAYMENT 类交易），账单口径见账单与交易查询；资金池低余额预警（LOW_BALANCE）的配置见管理公司。

下一步

到账后查余额、在公司资金池与独立余额卡之间划拨：余额与划拨
充值如何进入账单与交易流水、如何冲抵应还：账单与交易查询

​📄 正文

​获取收款账户

​到账通知：BANK_TRANSFER_INFO

​充值流水查询

​下一步

📄 正文

获取收款账户

到账通知：BANK_TRANSFER_INFO

充值流水查询

下一步