> ## 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.

# 账单与交易查询

> 按公司或按卡拉取月度账单（statements / statement-detail）与不受账期限制的交易流水（transactions）：账单头、按币种汇总、交易明细字段，以及应还与溢缴的计算口径。

## 📄 正文

DCS 按自然月为每个出账主体自动出具账单，无需合作伙伴触发，数据经 API 拉取。出账主体由余额模式决定：公司资金池（SHARED）按公司出具一份账单，卡独立余额（DEDICATED）按卡各出一份。账期与关键日期的机制见[限额与账单](../basic-concepts/limits-and-billing)。

三个查询接口分工：

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

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

## 账单列表

`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（划拨见[余额与划拨](./balances-and-transfers)） |
| `totalDueAmount`             | 到期应还（+）                                                            |
| `overpaymentAmount`          | 溢缴款（−）                                                             |

**请求示例**

```http theme={null}
# 按公司查，不带 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
```

**响应示例**

```json theme={null}
{
  "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 推导——消费、费用、取现为正，还款 / 充值与退款为负，净额为正即欠款、为负即溢缴：

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

<Note>
  两种查法：查**已出账单**传 `statementId`、不传 `status`；查**当前未出账单**不传 `statementId`、传 `status=OPEN`。
</Note>

**响应 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 |

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

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

`transactionCategory` 七枚举：

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

`postStatus` 三态：

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

**请求示例**

```http theme={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
```

**响应示例**

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

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

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

**请求示例**

```http theme={null}
# 按卡查询
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
```

**响应示例**

```json theme={null}
// 响应：一条授权占用中的消费
{
  "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](./authorization-and-3ds)
* 还款即充值，入金路径与到账通知：[充值入金](./deposits)