交易管理 · 概述 - DCS Technical Documentation

一处查询，三类视图

终端用户的每一笔卡消费、每一份账单和每一条法币流水，都可以在 DCS 中查询并直接呈现给用户。作为持牌发卡机构并拥有自有 BIN，DCS 在托管模式下记录「加密货币 → 法币 → 卡消费」全流程数据。您只需按三类视图查询，无需自行拼接卡组织与账本的原始流水。 DeCard 托管模式按「账单汇总 / 法币交易记录 / 交易 ID 解析」三类视图组织数据，分别对应不同接口。先建立一张总览：

视图	回答的问题	接口	定位维度
账单（Statement）	某个账期一共消费/还款多少？	`GET /card/v2/statements`	`cardId`
账单详情	这份账单里都有哪些条目？	`GET /card/v2/statements/detail`	`cardId`
法币交易记录	这个用户的入金/出金/还款/充值全流水？（含链上充值哈希）	`GET /card/v1/fiat/transactions`	`externalUserId`
交易 ID 解析	一个 ID 到底是未入账还是已入账？关联哪条记录？	`POST /card/v1/transaction/id/resolve`	`ids[]`

范围说明：本页覆盖账单 / 法币 / 交易 ID 解析三类视图。终端用户的加密货币资金历史（user-asset/v1/transactions、transaction-detail）属于「用户余额」页的范围，本页不重复展开；需要时请参阅用户余额。

前置条件

您已开通企业（Enterprise）账户，并持有 ApiKey / SecretKey。如尚未获取，请参考前置准备与鉴权指南。
终端用户已完成注册（持有 externalUserId，见用户注册）并已开卡（持有 cardId，见卡管理 · 申请卡）。
所有请求须按鉴权指南携带签名头。本页示例省略鉴权头，只聚焦业务字段。
所有示例中的 externalUserId、cardId、卡号后 4 位、商户名、地址、txHash 均为占位 / 脱敏值，请勿在请求或日志中写入真实终端用户 PII。

一 · 查询账单（Statement）

账单把一个账期内的消费、还款、未入账金额汇总成一份记录。账单接口用 cardId 精确定位卡片，返回字段含 SGD/USD 双币种金额。

1.1 账单列表

GET /card/v2/statements?externalUserId=usr_xxxxxxxx&cardId=card_xxxxxxxx&page=1&rows=20

参数	类型	必填	说明
`externalUserId`	string	是	用户 ID
`cardId`	string	是	卡 ID
`page` / `rows`	string	否	分页：页码 / 每页行数
`startTime` / `endTime`	string	否	时间范围

成功响应（data 为账单数组）：

{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": [
    {
      "type": "POSTED",
      "statementId": "stmt_xxxxxxxx",
      "statementDateStart": "2026-06-01",
      "statementDateEnd": "2026-06-30",
      "cardNumberLast4": "0000",
      "cardOrganization": "VISA",
      "cardScheme": "Visa Platinum",
      "cardOrganizationLogo": "https://example.com/logo.png",
      "debitAmountExcludePayment": 100.00,
      "paymentAmountInSgd": 0.00,
      "paymentAmountInUsd": 100.00,
      "nonPostedAmountInSgd": 0.00,
      "nonPostedAmountInUsd": 0.00
    }
  ]
}

字段	说明
`type`	账单类型：`POSTED`（已入账）/ `NOT_POSTED`（未入账）
`statementId`	账单 ID，用于下钻账单详情
`statementDateStart` / `statementDateEnd`	账期起止日期
`cardNumberLast4`	卡号后 4 位
`cardOrganization` / `cardScheme` / `cardOrganizationLogo`	卡组织 / 卡方案 / 卡组织 Logo
`debitAmountExcludePayment`	账单实际消费金额（已扣除还款/费用）
`paymentAmountInSgd` / `paymentAmountInUsd`	SGD / USD 还款金额
`nonPostedAmountInSgd` / `nonPostedAmountInUsd`	SGD / USD 未入账金额

1.2 账单详情

拿到 statementId 后，下钻该账单内的逐条明细。

GET /card/v2/statements/detail?externalUserId=usr_xxxxxxxx&cardId=card_xxxxxxxx&statementId=stmt_xxxxxxxx&page=1&rows=20

参数	类型	必填	说明
`externalUserId`	string	是	用户 ID
`cardId`	string	是	卡 ID
`statementId`	string	是	账单 ID
`page` / `rows` / `order` / `sort`	string	否	分页与排序

账单详情响应示例（节选脱敏）：

{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": [
    {
      "merchantName": "EXAMPLE COFFEE",
      "postIndicator": 1,
      "transactionDateTime": "2026-06-15 10:00:00",
      "transactionAmount": 5.50,
      "transactionCurrency": "SGD",
      "postingAmountInSgd": 5.50,
      "postingAmountInUsd": 4.05,
      "debitCreditIndcator": "D",
      "transactionType": "SPEND",
      "mcc": "5814",
      "merchantCountryCode": "702",
      "transactionDescription": "EXAMPLE COFFEE SG",
      "postedTransactionId": "posted_xxxxxxxx",
      "assetMovements": [
        {
          "id": "asset_mvmnt_xxxxxxxx",
          "asset": "USDC",
          "amount": -4.05,
          "movementTime": "2026-06-15 10:00:00",
          "movementType": "DEBIT"
        }
      ],
      "assetMovementStatus": 1
    }
  ]
}

核心字段说明（完整字段集以 API Reference 为准）：

字段	类型	说明
`merchantName`	string	商户名称
`postIndicator`	integer	入账状态：`1` = 已入账，`0` = 未入账
`transactionDateTime` / `transactionDateTimeStr`	string	交易时间 / 原始字符串（`yyyy-MM-dd HH:mm:ss`）
`transactionAmount` / `transactionCurrency`	number / string	交易金额 / 交易币种
`postingAmountInSgd` / `postingAmountInUsd`	number	SGD / USD 入账金额（双币种）
`debitCreditIndcator`	string	借贷方向（字段名为历史拼写，语义为 debitCreditIndicator）：`C` = 贷记（入账），`D` = 借记（出账）
`transactionType`	string	`SPEND`（消费）/ `REFUND`（退款）/ `PARTIAL_REFUND`（部分退款）。注意：Webhook 中同名字段使用另一套单字母编码（R/C/Q/P），勿混用
`mcc`	string	商户类别码（Merchant Category Code）
`merchantCountryCode`	string	商户国家代码（3 位数字，如 `702` = 新加坡）
`postedTransactionId`	string	入账交易 ID，可用于 `transaction/id/resolve` 交叉核对
`assetMovements[]`	array	DeCard 托管特色：用户资产变动明细。每项含 `id`（唯一标识）/ `asset`（资产类型，如 USDC）/ `amount`（负数 = 扣款，正数 = 退款）/ `movementTime`（变动时间）/ `movementType`（如 DEBIT / CREDIT）
`assetMovementStatus`	integer	资金处理状态：`1` = 处理完成，`0` = 未完成

assetMovements（DeCard 托管特色）：DeCard 托管模式下，每笔卡消费会联动扣减用户的独立钱包余额。assetMovements 追踪这笔消费对应哪种资产、扣了多少、在什么时间——这是 DeCard 托管模型的差异化能力。

二 · 查询法币交易记录（DeCard 托管特色）

法币交易记录是 DeCard 托管模式特有的视图：它把入账/出账/还款/争议/稳定币充值等全部交易汇总在一份可按用户查询的列表中，并为链上充值返回核对所需字段（哈希、网络、资产、收发地址）。这体现了 DeCard 托管模式下「加密货币 → 法币 → 卡消费」全流程的可见性。

GET /card/v1/fiat/transactions?externalUserId=usr_xxxxxxxx&page=1&rows=20&order=time&sort=desc

参数	类型	必填	说明
`externalUserId`	string	是	用户 ID
`page` / `rows`	string	否	分页
`order`	string	否	排序字段
`sort`	string	否	排序方向：`asc` / `desc`

成功响应（节选脱敏）：

{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": [
    {
      "debitCreditIndcator": "C",
      "postingTransType": "CTU01",
      "transactionAmount": "100.00",
      "transactionCurrency": "USD",
      "merchantName": "",
      "transactionDateTime": "2026-06-15 10:00:00",
      "postedTransactionId": "posted_xxxxxxxx",
      "transferDetails": {
        "channelCode": "fomo",
        "txnAmt": 100.00,
        "txnCcy": "USDC",
        "sender": "0xSENDER_ADDRESS_REDACTED",
        "receiving": "0xRECEIVING_ADDRESS_REDACTED",
        "timeStamp": "1718438400",
        "txHash": "0xTXHASH_REDACTED",
        "network": "Polygon",
        "asset": "USDC"
      }
    }
  ]
}

借贷方向 debitCreditIndcator（字段名为历史拼写，实际语义为 debitCreditIndicator）：C = 贷记（入账）/ D = 借记（出账）。 交易类型 postingTransType（全量枚举）：

值	含义	值	含义
`1`	消费	`9`	争议释放
`2`	现金	`M`	备忘交易
`5`	消费费用	`A`	消费利息
`6`	现金费用	`B`	现金利息
`7`	还款	`N`	年费
`8`	争议登记	`P`	实体卡费
`R`	换卡费	`CTU01`	稳定币充值

充值信息 transferDetails（仅充值类交易返回）：

字段	说明
`channelCode`	充值渠道：`fomo`（FOMO 渠道）/ `icn`（ICN 渠道）
`txnAmt` / `txnCcy`	充值金额 / 充值币种
`sender` / `receiving`	发送方 / 接收方（`fomo` 为链上地址，`icn` 为姓名）
`timeStamp`	交易时间戳
`txHash`	区块链交易哈希（仅 `fomo` 渠道）
`network`	区块链网络（仅 `fomo` 渠道，如 Polygon/Base/Solana）
`asset`	资产币种（仅 `fomo` 渠道）

链上充值的地址、币种与网络配置属于「资金充提（加密货币充值）」组，本页不展开。txHash 可用于在区块浏览器中核对到账情况，是 DeCard 托管模式下的重要对账依据。

三 · 解析交易 ID

当您手上有一个交易 ID 但不确定它是未入账（outstanding）还是已入账（posted），可批量解析其入账状态与关联 ID。

POST /card/v1/transaction/id/resolve

{
  "ids": ["txn_xxxxxxxx", "txn_yyyyyyyy"]
}

字段	类型	必填	说明
`ids`	string[]	是	交易 ID 列表（可能是 `outstandingTransactionId` 或 `postedTransactionId`）

成功响应（data 为解析结果列表）的关键字段：

字段	说明
`id`	传入的原始 ID
`outstandingTransactionId`	未入账交易 ID；单报文直接入账、无 outstanding 记录时为 `null`
`postedTransactionId`	已入账交易 ID；未入账时为 `null`
`posted`	布尔，是否已入账

用途：账单/流水里同一笔消费在「授权占用（未入账）」和「清算入账（已入账）」两个阶段可能有不同 ID，本接口帮您把两端串起来。授权与入账的概念见交易生命周期 · 概述。

分页、排序与错误处理

分页：列表接口统一用 page（页码）+ rows（每页条数），使用 query string 传参，两者均为 string 类型。请以本页各接口字段表为准。
排序：支持 order（排序字段）+ sort（asc 升序 / desc 降序）的接口为 statements、statements/detail、fiat/transactions。
成功判定：以响应结构 code == SYS_SUCCESS 判断请求是否成功受理；非该值时读取 message / messageDetail 了解原因。响应结构完整说明见鉴权指南。
时间范围：未传 startTime / endTime 时按接口默认范围返回；建议显式传入以控制返回量。

能力说明

DeCard 托管模式当前不提供交易备注（memo）或收据（receipt）能力。如接入机构需要在自有界面展示备注或收据，请自行存储相关内容；如需 DCS 提供此能力，请与 DCS 团队确认。 DCS 提供账单（Statement）汇总与法币交易记录（含链上充值取证）两类视图，已在本页第一、二节覆盖。

下一步

查看用户的资产余额与加密货币资金历史，见用户余额。
理解一笔交易从授权到清算入账的全过程，见交易生命周期 · 概述。
授权在 DCS 系统内完成（转发授权决策属合作伙伴自管模式，DeCard 托管不适用），见交易生命周期 · 授权。

​一处查询，三类视图

​前置条件

​一 · 查询账单（Statement）

​1.1 账单列表

​1.2 账单详情

​二 · 查询法币交易记录（DeCard 托管特色）

​三 · 解析交易 ID

​分页、排序与错误处理

​能力说明

​下一步