清算（系统内完成与账单查询） - DCS Technical Documentation

📄 正文

清算（Settlement）是卡资金生命周期的第二阶段：在授权冻结资金之后，商户向卡组织提交最终金额，卡组织与发卡方完成实际入账，并释放对应的冻结额。清算是机制，账单（statements）是这套机制产出的可查询视图。在 DeCard 托管模型下，清算全程由 DCS 系统内部完成：DCS 收到卡组织的清算报文后，自动把对应账单从未出账（NOT_POSTED）转为已出账（POSTED），扣减用户的冻结余额、完成实际扣款，并同步联动用户独立账户的资产变动。接入机构无需自行维护冻结额或在收到清算 Webhook 后手动入账——这正是 DeCard 托管模式的便利所在。清算的核心语义是 outstanding（未入账）→ posted（已入账） 的转换，由两组字段表达：

账单层面：账单 type 在 NOT_POSTED（未出账单）与 POSTED（已出账单）之间转换。
交易明细层面：postIndicator（1-已入账 / 0-未入账）标识每笔明细是否已落入已出账单。

余额模型（free / freeze / total、托管策略）的完整定义见账户与资产模型。

五类清算与退款形态

清算可能出现多种形态。以下逐一说明每种如何发生，以及 DCS 系统内部如何完成冻结释放与入账——接入机构无需为每种形态编写自管逻辑。

标准清算

最常见的清算形态：商户按授权金额全额清算。DCS 收到清算报文后，释放全额授权冻结、按授权金额入账。

部分清算

商户清算金额小于授权金额（如餐饮去掉小费后实际结算）。DCS 释放全额授权冻结，仅按实际金额入账，多余冻结额自动回到可用余额。

超额清算

特定商户类别（如餐饮、酒店等含小费/附加费的行业）允许清算金额略高于授权金额。DCS 校验通过后，释放原授权冻结并按其实际金额入账。

超额清算仅在卡网络规则与特定商户类别码（MCC）允许的范围内生效；超出允许上限的请求将被拒绝。

多笔清算

一次授权对应多次分批清算（如电商分批发货）。DCS 在首批清算时维持授权冻结，直到全部清算完成后统一释放冻结并入账。

强制清算

无前置授权直接清算（离线/不联网场景，如机上购物）。DCS 无冻结可释放，直接入账扣减可用余额。

强制清算仅在特定商户类别下生效（离线场景通常允许不超过 15% 的差额缓冲以覆盖运费/税费等调整）。

退款

退款是反向交易，把金额贷记回持卡人账户；它不一定关联某笔原始交易。DCS 校验退款请求后直接入账，增加可用余额。

退款可在原始交易完成后的任意时间发起。账单明细中 debitCreditIndcator=C 标识退款入账。

清算完成后的 Webhook 对账通知

DCS 在清算完成后会推送 CARD_TRANSACTION_SETTLEMENT Webhook 事件，主要字段包括：清算金额与币种（settledAmount / settledCurrencyCode）、原始交易金额与币种（transactionAmount / transactionCurrencyCode）、交易方向（direction）、外部交易 ID（externalTranId）、卡号后 4 位（cardNumber）、交易类型（transactionType，单字母编码 R/C/Q/P）、本地交易日期/时间（localTransactionDate / localTransactionTime）与商户信息（cardAcceptorNameLocation、mcc、merchantCountryCode）。Webhook 全部字段、签名校验及示例 JSON 见 Webhook 与 WebSocket 实时通知。

授权 Webhook 与清算 Webhook 对照

维度	授权 Webhook `CARD_TRANSACTION`	清算 Webhook `CARD_TRANSACTION_SETTLEMENT`	接入机构动作
阶段	授权发生时（冻结）	清算完成时（入账）	—
核心字段	`response`（A-批准 / D-拒绝）、`authType`	`settledAmount`、`settledCurrencyCode`、`transactionType`（单字母）	—
金额语义	预授权金额（可能 ≠ 最终入账）	最终入账金额	以此为准对账
余额影响	不扣可用余额（仅冻结）	实际扣款或入账	DCS 已自动完成，无需手动操作余额

您需要做的

查询账单：用 statements / statements/detail（见下节）确认清算金额与明细。
收 Webhook 对账：用 CARD_TRANSACTION_SETTLEMENT 事件把 DCS 侧的清算记录与自有系统账务做异步比对——无需据此手动入账。
按 ID 解析状态（可选）：当您持有一组交易 ID 不确定是否已入账时，用 POST /card/v1/transaction/id/resolve 查询（见下文）。

DeCard 托管模型下，清算入账与余额扣减已由 DCS 系统内部自动完成——接入机构无需据此 Webhook 操作 DCS 账户的余额变动。

如何查询清算结果

清算完成后，您可通过以下接口查询账单与明细，均以 cardId 定位卡片。

接口	方法	路径	用途
账单列表	GET	`/card/v2/statements`	查账单列表（按 `externalUserId` + `cardId` 筛选）
账单详情	GET	`/card/v2/statements/detail`	按 `statementId` + `cardId` 查明细（含 `assetMovements` 资产变动明细）
解析交易 ID	POST	`/card/v1/transaction/id/resolve`	按交易 ID 解析其入账状态

另见 /card/v1/fiat/transactions（GET 法币交易流水），其返回字段 postingTransType 表示清算后的交易分类，与账单明细中 transactionType 语义相关但字段名不同，不可混淆。详情见交易管理。

账单列表

获取用户的卡账单列表，包含已出账单（POSTED）与未出账单（NOT_POSTED），支持分页与筛选。 前置条件：用户已注册并完成开卡，且产生过交易。请求（v2，GET /card/v2/statements）：

参数	必填	说明
`externalUserId`	必填	渠道用户 ID
`cardId`	必填	卡 ID
`page`	可选	页码
`rows`	可选	每页条数
`order`	可选	排序方向
`sort`	可选	排序字段
`startTime`	可选	起始时间
`endTime`	可选	结束时间

GET /card/v2/statements?externalUserId=usr_demo_001&cardId=card_demo_001&page=1&rows=20

响应（金额双币种 SGD / USD；示例为脱敏占位数据）：

{
  "code": "SYS_SUCCESS",
  "message": "success",
  "messageDetail": null,
  "data": [
    {
      "type": "POSTED",
      "statementDateStart": "2025-01-01",
      "statementDateEnd": "2025-01-31",
      "paymentAmountInSgd": 0.0,
      "paymentAmountInUsd": 0.0,
      "nonPostedAmountInSgd": 0.0,
      "nonPostedAmountInUsd": 0.0,
      "statementId": "stmt_demo_001",
      "cardNumberLast4": "1234",
      "cardOrganizationLogo": "https://example.com/logo.png",
      "cardOrganization": "VISA",
      "cardScheme": "VISA",
      "debitAmountExcludePayment": 0.0
    }
  ]
}

字段说明：

字段	说明
`type`	账单类型：`POSTED`（已出账单）/ `NOT_POSTED`（未出账单）
`statementDateStart` / `statementDateEnd`	账单时间范围
`paymentAmountInSgd` / `paymentAmountInUsd`	还款金额（SGD / USD 双币种）
`nonPostedAmountInSgd` / `nonPostedAmountInUsd`	未入账金额（SGD / USD 双币种）
`statementId`	账单 ID
`cardNumberLast4`	卡号后 4 位
`cardOrganizationLogo`	卡组织 Logo 图片链接
`cardOrganization` / `cardScheme`	卡组织 / 卡方案类型（如 `VISA`、`MASTERCARD`）
`debitAmountExcludePayment`	账单实际消费金额（扣除所有还款 / 费用等）

账单详情

按 statementId 查询某账单下每笔交易的明细，包含商户、金额、币种、入账状态及资产变动记录。请求（v2，GET /card/v2/statements/detail）：

参数	必填	说明
`externalUserId`	必填	渠道用户 ID
`cardId`	必填	卡 ID
`statementId`	必填	账单 ID
`page` / `rows` / `order` / `sort`	可选	分页与排序

GET /card/v2/statements/detail?externalUserId=usr_demo_001&cardId=card_demo_001&statementId=stmt_demo_001&page=1&rows=20

响应（示例为脱敏占位数据，卡号已脱敏、商户名为占位）：

{
  "code": "SYS_SUCCESS",
  "message": "success",
  "messageDetail": null,
  "data": [
    {
      "merchantName": "DEMO MERCHANT",
      "mcc": "5411",
      "merchantCountryCode": "702",
      "transactionType": "SPEND",
      "cardOrganizationLogo": "https://example.com/logo.png",
      "postIndicator": 1,
      "transactionDateTime": "2025-01-15T10:00:00+08:00",
      "postingAmountInSgd": 0.0,
      "postingAmountInUsd": 0.0,
      "debitCreditIndcator": "D",
      "transactionDescription": "DEMO MERCHANT PURCHASE",
      "cardNumber": "************1234",
      "postingDate": "2025-01-16",
      "transactionAmount": 0.0,
      "transactionCurrency": "USD",
      "externalTranId": 0,
      "cardOrganization": "VISA",
      "postedTransactionId": "ptx_demo_001",
      "cardScheme": "VISA",
      "systemTraceAuditNumber": "000000",
      "transactionDateTimeStr": "2025-01-15 10:00:00",
      "assetMovements": [
        {
          "id": "am_demo_001",
          "asset": "USDT",
          "amount": 0.0,
          "movementTime": "2025-01-15T10:00:01+08:00",
          "movementType": "DEBIT"
        }
      ],
      "assetMovementStatus": 1
    }
  ]
}

字段说明：

字段	说明
`merchantName`	商户名称
`mcc`	商户类别码（MCC, Merchant Category Code）
`merchantCountryCode`	商户国家码
`transactionType`	交易类型（取值含 `SPEND` / `REFUND` / `PARTIAL_REFUND`）
`cardOrganizationLogo`	卡组织 Logo 图片链接
`postIndicator`	入账状态：`1`-已入账，`0`-未入账
`transactionDateTime` / `transactionDateTimeStr`	交易时间 / 原始时间字符串（`yyyy-MM-dd HH:mm:ss`）
`postingAmountInSgd` / `postingAmountInUsd`	入账金额（SGD / USD 双币种）
`debitCreditIndcator`	借贷方向：`C`-贷记（入账，如退款）/ `D`-借记（出账，如消费）
`transactionDescription`	交易描述
`cardNumber`	卡号（脱敏处理）
`postingDate`	入账日期
`transactionAmount` / `transactionCurrency`	交易金额 / 交易币种
`externalTranId`	外部交易 ID
`cardOrganization` / `cardScheme`	卡组织 / 卡方案类型
`postedTransactionId`	入账交易 ID
`systemTraceAuditNumber`	系统跟踪号
`assetMovements`	用户资产变动明细列表（详情见下节）
`assetMovementStatus`	资产处理状态：`1`-资金处理完成，`0`-资金未完成

字段定义详见交易管理 › 报告字段说明。

注意区分三套 transaction type 编码体系：本节讨论的是 API 查询接口中的单词编码（SPEND/REFUND/PARTIAL_REFUND）。Webhook 中同名字段使用另一套单字母编码：R-卡消费 / C-ATM 提现 / Q-查询类交易 / P-转账或退款（见 Webhook 与 WebSocket 实时通知的 CARD_TRANSACTION_SETTLEMENT 字段表）。此外，法币交易流水接口 /card/v1/fiat/transactions 使用的字段名为 postingTransType（非 transactionType），与前述两套编码体系均不同，不可混淆。 assetMovements 资产变动明细作为「卡清算关联链上资产变动」的核心特色，见下节专述。

资产变动明细 assetMovements

assetMovements 是 DeCard 托管模型用来关联卡清算与用户独立账户/自有账本的链上资产变动的核心特色字段。它让接入机构在查询某笔卡消费的同时，直接看到背后对应用户加密资产（如 USDT / USDC）被扣减或退回的明细，资金流向全程透明。

字段	说明
`id`	资产变动唯一标识（userId 后两位 + 分库内自增 ID）
`asset`	资产类型（如 `USDT`、`USDC` 等）
`amount`	变动金额（负数表示扣款，正数表示退款）
`movementTime`	变动时间
`movementType`	变动类型（如 `DEBIT` 扣减 / `CREDIT` 入账等）

外层 assetMovementStatus 标识这笔清算对应的资金是否已处理完成（1-完成 / 0-未完成）。

该字段于 2025 年 8 月随响应格式更新新增，由账单详情接口返回；体现 DCS 自有账本（Crypto-Ledger）模式下卡消费直接联动稳定币扣减的资金透明度。

按 ID 解析入账状态：transaction/id/resolve

当您手上只有一组交易 ID、需要快速判断它们各自处于未入账（outstanding）还是已入账（posted）时，使用解析接口 POST /card/v1/transaction/id/resolve。它正是上文 outstanding → posted 语义的「按 ID 查询入口」。请求（POST /card/v1/transaction/id/resolve）：

{
  "ids": ["tx_demo_001", "tx_demo_002"]
}

响应（脱敏占位数据）：

{
  "code": "SYS_SUCCESS",
  "message": "success",
  "messageDetail": null,
  "data": [
    {
      "id": "tx_demo_001",
      "outstandingTransactionId": "ost_demo_001",
      "postedTransactionId": null,
      "posted": false
    },
    {
      "id": "tx_demo_002",
      "outstandingTransactionId": null,
      "postedTransactionId": "ptx_demo_002",
      "posted": true
    }
  ]
}

字段	说明
`id`	传入的原始 ID
`outstandingTransactionId`	未入账交易 ID；单报文直接入账的交易没有 outstanding 记录时为 `null`
`postedTransactionId`	已入账交易 ID；未入账时为 `null`
`posted`	是否已入账（`true` / `false`）

用法对照：posted=false + 有 outstandingTransactionId → 该笔仍在未出账阶段；posted=true + 有 postedTransactionId → 已完成清算入账。

响应结构与错误处理

本页所有接口统一使用全站响应结构 {code, message, messageDetail, data}（无 success 布尔字段）。成功码字面量为 SYS_SUCCESS。messageDetail 通常为 null；当非 null 时，其结构化对象包含以下子字段：

字段	类型	说明
`message`	string	消息内容
`title`	string	标题
`type`	string	类型
`icon`	string	图标标识
`action`	string	动作
`linkTitle`	string	链接标题
`linkUrl`	string	链接 URL

失败时通过 code / message 提示异常原因（如卡片不存在、用户不存在等）。以下为错误响应示例（脱敏，错误码为占位值）；简单错误场景下 messageDetail 通常为 null：

{
  "code": "CARD_NOT_FOUND",
  "message": "卡片不存在",
  "messageDetail": null,
  "data": null
}

本产品暂无集中的错误码字典；请以接口实际返回的 code / message 判断，必要时按问题上报与支持路径上报。

下一步

想了解清算前的冻结决策（授权阶段），请看授权。
如需了解授权、清算、Outstanding 与余额变化的整体关系，请看交易生命周期 · 概述。
想了解 free / freeze / total 余额模型与托管策略，请看账户与资产模型。
想了解 Webhook 通知如何接入与验证签名，请看 Webhook 与 WebSocket 实时通知。

​📄 正文

​五类清算与退款形态

​标准清算

​部分清算

​超额清算

​多笔清算

​强制清算

​退款

​清算完成后的 Webhook 对账通知

​授权 Webhook 与清算 Webhook 对照

​您需要做的

​如何查询清算结果

​账单列表

​账单详情

​资产变动明细 assetMovements

​按 ID 解析入账状态：transaction/id/resolve

​响应结构与错误处理

​下一步