📄 正文
DeCard 托管模式为每个用户托管一份独立的资金账本。资金的占用（授权冻结）与扣减（清算入账）都直接作用于该用户的余额，无需把授权请求转发给接入机构。作为持牌、自有 BIN 的发卡机构，DCS 由此把用户资产的合规托管与记账都在自有系统内完成。 DCS 直接托管用户的可支配余额，用 可用 / 冻结 / 总额 三个数描述任意时刻的资金状态。余额模型（free / freeze / total）
每个用户账户按币种（资产）分别记账。查询/user-asset/v1/balance 返回一组按资产维度的余额对象：
余额对象还含资金随交易生命周期在asset、network、logo。当前已知资产为USDT、USDC、USD；后续可能扩展，请仍以 balance 接口实际返回为准，不要把当前清单硬编码为永久全集。 术语对应：业务上常说的”可用余额 / 冻结余额”即 API 字段free/freeze；本套文档统一以 API 字段名free/freeze/total为准，行文中括注其中文语义。
free 与 freeze 之间流动：
- 授权（冻结）：批准一笔消费时，对应金额从
free移入freeze——资金被冻结但不离开账户，total不变。 - 清算（入账）：商户提交最终金额后完成实际扣减，对应的
freeze被释放、账户余额相应下降。 - 充值 / 退款：资金增加时进入
free。 - 费用扣款：制卡费（
CARD_PRINTING_FEE）、邮寄费（CARD_POSTAL_FEE）、冻结费（CARD_VIP_FROZEN_FEE）等直接从free扣除。free减少、total同步下降（不经过freeze，与消费授权-清算两段路径不同）。
授权/清算两阶段对余额的影响详见 授权 与 清算。
充值与扣款（Credit / Debit）
DeCard 托管模型下，用户独立余额通过一组 user-asset 接口调整与查询：credit / debit 请求体一致：{ externalTranId, asset, amount, externalUserId, remark }——其中 externalTranId 为幂等唯一 ID，asset 须是 DeCard 支持的币种，amount 必须为正数且小数位 ≤ 18 位。
字段全表与可跑示例见 使用指南 → 用户余额 与 交易查询。
资金变动类型（Transaction Type）
POST /user-asset/v1/transactions 与 POST /user-asset/v1/transaction-detail 通过 type 字段标识每笔变动的业务类型，相当于”账本分录类型”：
关键原则
- 可用与冻结分离：授权立即把资金从
free移入freeze，先于实际清算占用额度，防止超额消费；清算时再从freeze释放并完成扣减。 - 按用户、按资产独立记账：每个用户的每种资产各有一份
free/freeze/total，互不混淆。 - 幂等保护：充值、扣款均以
externalTranId作幂等键，重复请求被拒绝。