账单与交易查询 - DCS Technical Documentation

📄 正文

DCS 按自然月为每个出账主体自动出具账单，无需合作伙伴触发，数据经 API 拉取。出账主体由余额模式决定：公司资金池（SHARED）按公司出具一份账单，卡独立余额（DEDICATED）按卡各出一份。账期与关键日期的机制见限额与账单。三个查询接口分工：

接口	用途
`GET /open-api-corp/statement/v1/statements`	账单列表：按公司或按卡查指定区间账单
`GET /open-api-corp/statement/v1/statement-detail`	账单详情：账单头 + 按币种汇总 + 交易明细
`GET /open-api-corp/statement/v1/transactions`	交易列表：按时间区间查流水，不受账单期限制

以已出账单为最终口径：已出账单（SETTLED）内容固定、只含已入账交易；未出账单（OPEN，statementId 为 null）是当前账期的实时汇总，包含尚未清算的授权占用，其消费合计会随交易清算而回落，属预期行为。

账单列表

GET /open-api-corp/statement/v1/statements 按公司或按卡查指定区间账单，账期倒序排列返回。 请求参数

字段	类型	必填	说明
`organizationId`	String	是	≤36；账单所属组织
`cardId`	String	否	≤32；传则按该卡出账、不传则按公司出账。只有独立余额卡有独立账单
`startTime`	String	是	区间起，ISO-8601
`endTime`	String	是	区间止，ISO-8601
`page`	Integer	否	默认 1
`pageSize`	Integer	否	默认 20，上限 100

响应 data 是标准分页壳 page / pageSize / total + result[]（总条数已包含未出账单），不再回显请求参数。result[] 每项是账单头 + 按币种汇总：

字段	说明
`statementId`	账单 ID。未出账单为 null
`statementPeriod`	账期 yyyy-MM
`status`	`OPEN`（未出）/ `SETTLED`（已出）
`statementDate`	账单日 yyyy-MM-dd。未出账单为预计账单日
`paymentDueDate`	到期还款日 yyyy-MM-dd。未出账单为预计还款日
`paymentStatus`	还款状态，实时计算，见下
`summary`	按币种的汇总数组，每币种一个元素，见下

paymentStatus 四态：

值	含义
`CURRENT`	当期正常
`AWAITING_PAYMENT`	待还款
`PAID`	已还清
`OVERDUE`	已逾期

summary 按币种字段：

字段	说明
`currency`	分组币种，如 `USD` / `HKD`
`creditLimitAmount`	名义额度，按币种由平台配置
`availableCreditLimitAmount`	可用充值余额（溢缴金额取正，无溢缴为 0.00）
`totalPurchaseAmount`	消费合计（+）
`totalRefundAmount`	退款与拒付合计（−）
`totalFeeAmount`	费用合计（+）
`totalRepaymentAmount`	还款 / 充值合计（−）
`totalCashAdvanceAmount`	取现合计（净额，+）
`totalDebitAmount`	内部调拨合计。不在明细展示，SHARED 恒为 0.00（划拨见余额与划拨）
`totalDueAmount`	到期应还（+）
`overpaymentAmount`	溢缴款（−）

请求示例

# 按公司查，不带 cardId
GET /open-api-corp/statement/v1/statements?organizationId=e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f&page=1&pageSize=20

# 按独立余额卡查
GET /open-api-corp/statement/v1/statements?organizationId=e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f&cardId=5185740066240790530&page=1&pageSize=20

响应示例

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "page": 1,
    "pageSize": 20,
    "total": 3,
    "result": [{
        "statementId": "6410000000000000001",
        "statementPeriod": "2026-03",
        "status": "SETTLED",
        "statementDate": "2026-04-01",
        "paymentDueDate": "2026-04-27",
        "paymentStatus": "AWAITING_PAYMENT",
        "summary": [{
          "currency": "USD",
          "creditLimitAmount": "500.00",
          "availableCreditLimitAmount": "0.00",
          "totalPurchaseAmount": "120.00",
          "totalRefundAmount": "-20.00",
          "totalFeeAmount": "1.50",
          "totalRepaymentAmount": "-80.00",
          "totalCashAdvanceAmount": "0.00",
          "totalDebitAmount": "0.00",
          "totalDueAmount": "21.50",
          "overpaymentAmount": "0.00"
        }]
    }]
  }
}

应还与溢缴的计算口径

summary 中的结果字段由同一净额 S 推导——消费、费用、取现为正，还款 / 充值与退款为负，净额为正即欠款、为负即溢缴：

S = totalRepaymentAmount + totalPurchaseAmount + totalRefundAmount
  + totalFeeAmount + totalCashAdvanceAmount + totalDebitAmount

totalDueAmount       = max(0, S)        到期应还，正数展示欠款
overpaymentAmount          = min(0, S)        溢缴款，负数展示
availableCreditLimitAmount = S < 0 ? -S : 0   可用充值余额，溢缴取正

以上文响应示例验证：S = −80.00 + 120.00 + (−20.00) + 1.50 + 0 + 0 = 21.50，故 totalDueAmount 为 21.50、overpaymentAmount 为 0.00。

账单详情

GET /open-api-corp/statement/v1/statement-detail 返回账单头 + 按币种汇总 + 交易明细（分页只作用于明细）。 请求参数

字段	类型	必填	说明
`organizationId`	String	是	≤36；账单所属组织
`cardId`	String	否	≤32；传则按该卡出账、不传则按公司出账。只有独立余额卡有独立账单（`COMPANY_DEDICATED_PURPOSE_CARD` / `EMPLOYEE_CARD_SELF_FUNDED`）；公司资金池模式的卡不独立出账、其交易归入公司账单，传这类卡的 `cardId` 返回 `CARD_INVALID`，按卡查其交易请用交易列表
`statementId`	String	条件	≤32；查已出账单必填。与 `status` 至少满足一个，否则无法定位账单，返回 `DAPI_PARAM_INVALID`
`status`	String	条件	查未出账单时必填 `OPEN`（此时不传 `statementId`）
`page`	Integer	否	页码，从 1 起，缺省 1
`pageSize`	Integer	否	每页条数，缺省 20、上限 100

两种查法：查已出账单传 statementId、不传 status；查当前未出账单不传 statementId、传 status=OPEN。

响应 data 是标准分页壳 page / pageSize / total + result[],不再返回账单头与 summary——那两块请调账单列表。result[] 每项是一条交易明细：

字段	说明
`transactionId`	交易平台侧标识
`transactionCategory`	交易分类，七个枚举见下
`transactionTime`	交易时刻，收单地当地时刻 `yyyy-MM-dd HH:mm:ss`——卡组报文只提供当地日期与时间、不含时区，平台按参照时刻补出年份
`remark`	明细行备注 / 交易描述，自由文本
`cardId`	该笔交易所属卡 ID。充值 / 划转等无卡场景为 null
`panLast4`	卡号后四位。无卡场景为 null
`postStatus`	入账状态，三态见下
`currency`	账单币种——该笔交易归入哪个币种的汇总
`originalCurrency` / `originalAmount`	持卡人实际刷的币种与金额
`postCurrency` / `postAmount`	平台入账的币种与金额（换算后）
`postTime`	入账时刻 ISO-8601 UTC。授权占用中的行为 null
`merchant`	商户信息，含 `merchantName` / `mcc` / `merchantCountryCode`。还款等无商户的行整体为 null

三个币种字段互不相同是正常的：originalCurrency 是持卡人刷的币种，postCurrency 是平台入账的币种，currency 决定这笔计入账单列表 summary[] 的哪一组。

merchant.merchantCountryCode 的取值形态有变：由数字码（如 "458"）改为 ISO-3166-1 alpha-2 两位大写（如 "MY"），解析逻辑需同步调整。

transactionCategory 七枚举：

值	含义
`PURCHASE`	消费
`REFUND`	退款
`FEE`	费用
`REPAYMENT`	还款
`CASH_ADVANCE`	取现
`DEPOSIT`	入金
`TRANSFER`	划转

postStatus 三态：

值	含义
`POSTED`	已入账
`UNPOSTED`	授权占用中（`postTime` 为 null）
null	还款类无此语义

请求示例

# 查已出账单的明细：传 statementId
GET /open-api-corp/statement/v1/statement-detail?organizationId=e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f&statementId=6410000000000000001&page=1&pageSize=20

# 查当前未出账单的明细：不传 statementId，传 status=OPEN
GET /open-api-corp/statement/v1/statement-detail?organizationId=e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f&status=OPEN&page=1&pageSize=20

响应示例

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "page": 1,
    "pageSize": 20,
    "total": 2,
    "result": [
      {
        "transactionId": "6510000000000000001",
        "transactionCategory": "REPAYMENT",
        "transactionTime": "2026-03-10 16:00:12",
        "remark": "REPAYMENT",
        "cardId": null,
        "panLast4": null,
        "postStatus": null,
        "currency": "USD",
        "originalCurrency": "USD",
        "originalAmount": "-80",
        "postCurrency": "USD",
        "postAmount": "-80",
        "postTime": "2026-03-10T08:00:12Z",
        "merchant": null
      },
      {
        "transactionId": "6510000000000000002",
        "transactionCategory": "PURCHASE",
        "transactionTime": "2026-03-05 20:03:41",
        "remark": "ACME ONLINE STORE",
        "cardId": "5185740066240790530",
        "panLast4": "5492",
        "postStatus": "POSTED",
        "currency": "USD",
        "originalCurrency": "JPY",
        "originalAmount": "18000",
        "postCurrency": "USD",
        "postAmount": "121.35",
        "postTime": "2026-03-06T02:10:05Z",
        "merchant": {
          "merchantName": "ACME ONLINE STORE",
          "mcc": "5732",
          "merchantCountryCode": "JP"
        }
      }
    ]
  }
}

交易列表

GET /open-api-corp/statement/v1/transactions 按时间区间查交易流水，不受账单期限制，时间倒序。 请求参数

字段	类型	必填	说明
`organizationId`	String	是	公司 ID
`cardId`	String	否	不传 = 公司维度；传 = 收窄到该卡（含该卡绑定虚拟账号的充值）
`startTime`	String	是	区间起，ISO-8601
`endTime`	String	是	区间止，ISO-8601
`page`	Integer	否	默认 1
`pageSize`	Integer	否	默认 20，上限 100

startTime 与 endTime 的窗口不得超过半年；更早的流水请分段查询。

响应 data 为标准分页壳（page / pageSize / total / result），result 元素按 transactionTime 倒序，字段与上文账单明细的交易行完全一致。 请求示例

# 按卡查询
GET /open-api-corp/statement/v1/transactions?organizationId=e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f&cardId=5185740066240790530&startTime=2026-01-01T00:00:00Z&endTime=2026-06-30T23:59:59Z&page=1&pageSize=20

响应示例

// 响应：一条授权占用中的消费
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "page": 1, "pageSize": 20, "total": 152,
    "result": [{
      "currency": "USD",
      "transactionId": "178289884146286860002494",
      "transactionCategory": "PURCHASE",
      "transactionTime": "2026-03-05 20:03:41",
      "remark": "ACME ONLINE STORE",
      "cardId": "5185740066240790530",
      "panLast4": "5492",
      "postStatus": "UNPOSTED",
      "originalCurrency": "USD",
      "originalAmount": "50.00",
      "postCurrency": "USD",
      "postAmount": "50.00",
      "postTime": null,
      "merchant": {
        "merchantName": "ACME ONLINE STORE",
        "mcc": "5732",
        "merchantCountryCode": "JP"
      }
    }]
  }
}

下一步

欠款如何产生、授权如何占用与清算：交易授权与 3DS
还款即充值，入金路径与到账通知：充值入金

​📄 正文

​账单列表

​应还与溢缴的计算口径

​账单详情

​交易列表

​下一步

📄 正文

账单列表

应还与溢缴的计算口径

账单详情

交易列表

下一步