> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedecard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 清算（系统内完成与账单查询）

> 说明 5 类清算场景如何在 DCS 系统内完成、清算后如何通过 Webhook 对账，以及如何查询账单、明细、资产变动和入账状态。授权与清算的整体关系见交易生命周期。

## 📄 正文

清算（Settlement）是卡资金生命周期的**第二阶段**：在[授权](./authorizing-transactions)冻结资金之后，商户向卡组织提交最终金额，卡组织与发卡方完成实际入账，并释放对应的冻结额。**清算是机制，账单（statements）是这套机制产出的可查询视图**。

在 DeCard 托管模型下，清算全程由 **DCS 系统内部**完成：DCS 收到卡组织的清算报文后，自动把对应账单从**未出账（`NOT_POSTED`）**转为**已出账（`POSTED`）**，扣减用户的冻结余额、完成实际扣款，并同步联动用户独立账户的资产变动。接入机构无需自行维护冻结额或在收到清算 Webhook 后手动入账——这正是 DeCard 托管模式的便利所在。

清算的核心语义是 **outstanding（未入账）→ posted（已入账）** 的转换，由两组字段表达：

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

> 余额模型（`free` / `freeze` / `total`、托管策略）的完整定义见 [账户与资产模型](../../basic-concepts/ledgering-system)。

## 五类清算与退款形态

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

### 标准清算

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

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-settle-standard-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=4266b0f78d9e3269a5ef6bb052d98e9d" alt="标准清算流程" width="712" height="678" data-path="imgs/diagrams/va-settle-standard-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-settle-standard-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=9304e4ff14a0bb7beed4afa90921bef3" alt="标准清算流程" width="712" height="678" data-path="imgs/diagrams/va-settle-standard-dark.svg" />
</Frame>

### 部分清算

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

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-settle-partial-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=9bb58bfbff065ad0306680da0ccad40c" alt="部分清算流程" width="712" height="678" data-path="imgs/diagrams/va-settle-partial-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-settle-partial-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=d95ac63e012b693b2a0faa40f9711507" alt="部分清算流程" width="712" height="678" data-path="imgs/diagrams/va-settle-partial-dark.svg" />
</Frame>

### 超额清算

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

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-settle-excess-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=7208755a076232dc1a93cd8df2f1c5f5" alt="超额清算流程" width="712" height="678" data-path="imgs/diagrams/va-settle-excess-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-settle-excess-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=5c3ceea71628c717bfcefbf82545ea1b" alt="超额清算流程" width="712" height="678" data-path="imgs/diagrams/va-settle-excess-dark.svg" />
</Frame>

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

### 多笔清算

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

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-settle-multi-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=ef2a128793d747f935cd43892f87f84d" alt="多笔清算流程" width="712" height="926" data-path="imgs/diagrams/va-settle-multi-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-settle-multi-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=fbe08a3e5c22ab0d074aa1e1195fcfcf" alt="多笔清算流程" width="712" height="926" data-path="imgs/diagrams/va-settle-multi-dark.svg" />
</Frame>

### 强制清算

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

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-settle-force-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=6fb22befaac1104727c00fc21be7384d" alt="强制清算流程" width="712" height="538" data-path="imgs/diagrams/va-settle-force-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-settle-force-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=2d6fd3364c46eb89f17737cf1e3ec104" alt="强制清算流程" width="712" height="538" data-path="imgs/diagrams/va-settle-force-dark.svg" />
</Frame>

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

### 退款

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

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-settle-refund-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=522687e6373ab97c7ba3bc9575a53356" alt="退款入账流程" width="712" height="466" data-path="imgs/diagrams/va-settle-refund-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-settle-refund-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=2db22173a94d243fab853cb6dd8d3431" alt="退款入账流程" width="712" height="466" data-path="imgs/diagrams/va-settle-refund-dark.svg" />
</Frame>

> 退款可在原始交易完成后的任意时间发起。账单明细中 `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 实时通知](../../integration-resources/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` 语义相关但字段名不同，不可混淆。详情见 [交易管理](./overview)。

### 账单列表

获取用户的卡账单列表，包含已出账单（`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；示例为脱敏占位数据）：

```json theme={null}
{
  "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
```

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

```json theme={null}
{
  "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`-资金未完成                     |

> 字段定义详见 [交易管理 › 报告字段说明](./reporting-field-descriptions)。

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

## 资产变动明细 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、需要快速判断它们各自处于<b>未入账（outstanding）</b>还是<b>已入账（posted）</b>时，使用解析接口 POST `/card/v1/transaction/id/resolve`。它正是上文 outstanding → posted 语义的「按 ID 查询入口」。

**请求**（POST `/card/v1/transaction/id/resolve`）：

```json theme={null}
{
  "ids": ["tx_demo_001", "tx_demo_002"]
}
```

**响应**（脱敏占位数据）：

```json theme={null}
{
  "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`：

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

本产品暂无集中的错误码字典；请以接口实际返回的 `code` / `message` 判断，必要时按 [问题上报与支持路径](../../customer-success/escalations-and-support-paths#五、参考码-/-排查索引（在哪查？）) 上报。

## 下一步

* 想了解清算前的冻结决策（授权阶段），请看 [授权](./authorizing-transactions)。
* 如需了解授权、清算、Outstanding 与余额变化的整体关系，请看[交易生命周期 · 概述](../../basic-concepts/transaction-lifecycle)。
* 想了解 `free` / `freeze` / `total` 余额模型与托管策略，请看 [账户与资产模型](../../basic-concepts/ledgering-system)。
* 想了解 Webhook 通知如何接入与验证签名，请看 [Webhook 与 WebSocket 实时通知](../../integration-resources/webhook-websocket)。