Skip to main content

​
📄 Guide

In DeCard-Managed mode, DCS holds a dedicated funding ledger for every user. Both the reservation of funds (an authorization hold) and the deduction of funds (settlement) act directly on that user’s balance, with no authorization request forwarded to the partner. As a licensed issuer running its own BINs, DCS therefore keeps regulated custody and booking of user assets entirely inside its own systems. DCS holds the user’s spendable balance directly and describes the state of those funds at any point in time with three numbers: available, frozen, and total.

​
Balance model (free / freeze / total)

Each user account is booked separately per currency (asset). A call to /user-asset/v1/balance returns one balance object per asset:
The balance object also carries asset, network, and logo. The assets known today are USDT, USDC, and USD. The list may grow, so always rely on what the balance endpoint actually returns rather than hard-coding today’s list as the permanent set. Terminology: what the business side calls “available balance” and “frozen balance” are the API fields free and freeze. This documentation set uses the API field names free / freeze / total as canonical and glosses their plain meaning in parentheses where useful.
Funds move between free and freeze as a transaction progresses:
  • Authorization (hold): when a purchase is approved, the amount moves from free into freeze. The funds are held but do not leave the account, so total is unchanged.
  • Settlement (debit): once the merchant submits the final amount, the actual deduction takes place, the matching freeze is released, and the account balance drops accordingly.
  • Deposits and refunds: incoming funds land in free.
  • Fee debits: card production fees (CARD_PRINTING_FEE), postage fees (CARD_POSTAL_FEE), freeze fees (CARD_VIP_FROZEN_FEE), and similar charges are debited straight from free. free goes down and total goes down with it, without passing through freeze, unlike the two-step authorization-then-settlement path of a purchase.
For how the two stages affect balances, see Authorizing Transactions and Settlement.

​
Deposits and debits (credit / debit)

In DeCard-Managed mode, per-user balances are adjusted and queried through a set of user-asset endpoints: credit and debit take the same request body: { externalTranId, asset, amount, externalUserId, remark }. Here externalTranId is the unique idempotency ID, asset must be a currency that DCS supports, and amount must be positive with at most 18 decimal places.
For the full field tables and runnable examples, see How to Use › User Balance and Managing Transactions.

​
Movement types (transaction type)

POST /user-asset/v1/transactions and POST /user-asset/v1/transaction-detail use the type field to mark the business nature of each movement, effectively the ledger entry type:

​
Key principles

  1. Available and frozen are kept apart: an authorization moves funds from free into freeze immediately, reserving the limit ahead of actual settlement so a user cannot overspend; settlement then releases the hold from freeze and completes the debit.
  2. Booked per user and per asset: every asset of every user has its own free, freeze, and total, with no commingling.
  3. Idempotency: both credit and debit use externalTranId as the idempotency key, so a repeated request is rejected.

​
Next steps