Balances and Transfers - DCS Technical Documentation

📄 Guide

The balance is both the precondition for spending and the real-time authorization gate. This page covers two things: reading balances (balance), and moving funds between the company pool and dedicated-balance cards (transfer + transfer-query). The funding model in one sentence: SHARED cards hold no balance and spend straight from the company pool; DEDICATED cards hold their own balance and stop when it runs out. Who holds the balance and who can be a transfer endpoint is in Holders and the funding model; how money comes in is in Deposits.

Query balances

GET /open-api-corp/fund/v1/balance returns a funding owner’s balances per currency. Request parameters

Field	Type	Required	Description
`subjectType`	String	Yes	`ORGANIZATION` / `CARD`
`subjectId`	String	Yes	≤20; company ID or card ID
`currency`	String	No	`USD` / `HKD`; omit to return every currency

Response data carries subjectType, subjectId and the per-currency list balances, one element per currency:

Field	Description
`currency`	Currency: `USD` / `HKD`
`availableAmount`	Current available balance, paired with `currency`

Request example

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

Response example

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

Error codes

Code	Description
`SUBJECT_INVALID`	The funding owner (company / card) does not exist or is invalid

The balance acts as the real-time authorization gate: a SHARED card spends straight from the company pool, a DEDICATED card from its own balance, stopping when it runs out. The authorization flow is in Authorization and 3DS.

Transfer funds

POST /open-api-corp/fund/v1/transfer moves funds between the company pool and dedicated-balance cards — same currency, no FX, closed loop within one company: COMPANY→CARD funds a card (allocates budget), CARD→COMPANY sweeps the balance back. Request parameters

Field	Type	Required	Description
`transferRef`	String	Yes	≤64; your unique transfer identifier (idempotency key), character set `^[A-Za-z0-9_-]+$`
`organizationId`	String	Yes	≤20; the owning company (the closed-loop boundary; both sides must belong to it)
`from.subjectType`	String	Yes	Source subject type: `ORGANIZATION` / `CARD`
`from.subjectId`	String	Yes	≤36; `ORGANIZATION`→`organizationId`, `CARD`→`cardId` (≤32)
`to.subjectType`	String	Yes	Destination subject type: `ORGANIZATION` / `CARD` (must differ from `from.subjectType`)
`to.subjectId`	String	Yes	≤36; same rules as `from.subjectId`
`amount`	BigDecimal	Yes	Greater than 0, at most 2 decimals
`currency`	String	Yes	`USD` / `HKD`, must match both accounts’ currency
`remark`	String	No	≤256; remark

Response data

Field	Type	Description
`transferId`	String	External id of the transfer record
`status`	String	`SUCCESS` / `PROCESSING` / `FAILED`
`completeTime`	String	Completion time, ISO-8601

PROCESSING is not a final state: you must poll GET /open-api-corp/fund/v1/transfer-query with the same transferRef until it returns SUCCESS or FAILED before acting on the result.

Request example

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

Response example

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

Error codes

Code	Description
`TRANSFER_DUPLICATE`	The `transferRef` was already submitted
`SUBJECT_INVALID`	The company / card does not exist, is not yours, or the two sides belong to different companies
`CARD_NOT_DEDICATED`	The card is not a dedicated-balance card (a SHARED card holds no balance and cannot be a transfer endpoint)
`CARD_INVALID`	The card is not ACTIVE
`CURRENCY_MISMATCH`	The currency does not match the card
`INSUFFICIENT_FUNDS`	The sender’s balance is insufficient

If a transfer request times out on the cardNetwork and you never see a response, retry with the same transferRef: if the first attempt was accepted you get TRANSFER_DUPLICATE, in which case switch to transfer-query for the result — the funds are never moved twice.

Query a transfer result

GET /open-api-corp/fund/v1/transfer-query returns the final result of one transfer, looked up by transferRef. Request parameters

Field	Type	Required	Description
`transferRef`	String	Yes	≤64; the unique transfer identifier used at submission

Response data

Field	Type	Description
`transferId`	String	External id of the transfer record
`status`	String	`SUCCESS` / `PROCESSING` (in progress) / `FAILED`
`completeTime`	String	Completion time, ISO-8601

Request example

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

Response example

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

Error codes

Code	Description
`TRANSFER_NOT_FOUND`	The transfer cannot be found, or belongs to another partner (existence is not disclosed)

Next steps

Fund the company pool or a dedicated-balance card: Deposits
How transfers and spending land on statements and in the records (internal allocations count into totalDebitAmount): Statements and Transactions

​📄 Guide

​Query balances

​Transfer funds

​Query a transfer result

​Next steps

📄 Guide

Query balances

Transfer funds

Query a transfer result

Next steps