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

# 交易列表

> 查询 Visa 卡交易记录。

## 接口信息

| 项目            | 说明                                                    |
| ------------- | ----------------------------------------------------- |
| 方法            | `POST`                                                |
| 路径            | `/mc-platformapi/v1/open/et/vs/card/transaction/list` |
| Content-Type  | `application/json`                                    |
| Authorization | 完整 JSON 请求体经 `SHA256withRSA` 签名后再 `BASE64` 编码得到的签名值   |

## 请求参数

| 字段           | 类型        | 必填 | 说明                                           |
| ------------ | --------- | -- | -------------------------------------------- |
| `app_id`     | `string`  | 是  | 应用 ID，在商户平台生成                                |
| `timestamp`  | `integer` | 是  | Unix 秒级时间戳，参与请求验签                            |
| `card_no`    | `string`  | 是  | Visa 卡号                                      |
| `start_time` | `string`  | 是  | 开始时间，格式 `YYYY-MM-DD` 或 `YYYY-MM-DD HH:mm:ss` |
| `end_time`   | `string`  | 是  | 结束时间，格式 `YYYY-MM-DD` 或 `YYYY-MM-DD HH:mm:ss` |
| `page`       | `integer` | 是  | 页码；小于等于 `0` 时按 `1` 处理                        |
| `page_size`  | `integer` | 是  | 每页条数；小于等于 `0` 时按 `10` 处理                     |

## 请求示例

```json theme={null}
{
  "app_id": "app_123456",
  "timestamp": 1784880000,
  "card_no": "493875******0990",
  "start_time": "2026-07-01 00:00:00",
  "end_time": "2026-07-25 23:59:59",
  "page": 1,
  "page_size": 10
}
```

## 返回字段

| 字段                           | 类型              | 说明             |
| ---------------------------- | --------------- | -------------- |
| `total`                      | `integer`       | 总条数            |
| `list`                       | `array<object>` | 交易记录列表         |
| `list[].trade_no`            | `string`        | 平台交易流水号        |
| `list[].pan`                 | `string`        | 主账号，通常为卡号或脱敏卡号 |
| `list[].pan_type`            | `string`        | 主账户号类型         |
| `list[].app_time`            | `string`        | 交易时间           |
| `list[].channel_code`        | `string`        | 交易渠道           |
| `list[].mer_order_no`        | `string`        | 商户订单号          |
| `list[].order_type`          | `string`        | 订单类型           |
| `list[].trans_type`          | `string`        | 交易类型           |
| `list[].trans_status`        | `string`        | 交易状态           |
| `list[].return_code`         | `string`        | 返回码            |
| `list[].return_desc`         | `string`        | 返回信息或失败原因      |
| `list[].trans_amount`        | `string`        | 交易金额           |
| `list[].trans_currency_type` | `string`        | 交易币种           |
| `list[].freeze_amount`       | `string`        | 交易后冻结金额        |
| `list[].balance_avail`       | `string`        | 交易后可用余额        |
| `list[].fee_list`            | `array<object>` | 费用列表           |
| `list[].merchant_name`       | `string`        | 商户名称           |

### `fee_list[]` 对象字段

| 字段                | 类型       | 说明          |
| ----------------- | -------- | ----------- |
| `fee_code`        | `string` | 费用编码        |
| `amt_fee`         | `string` | 手续费金额，字符串类型 |
| `currcy_code_fee` | `string` | 手续费币种       |
| `fee_memo`        | `string` | 费用备注或说明     |

```json theme={null}
{
  "fee_code": "F003",
  "amt_fee": "10.00",
  "currcy_code_fee": "HKD",
  "fee_memo": "异常交易手续费"
}
```

## 枚举值说明

### 主账户号类型 `pan_type`

| 值    | 说明                        |
| ---- | ------------------------- |
| `01` | 卡号                        |
| `02` | 账号                        |
| `03` | FPS 识别代号，包含手机号、邮箱或 FPS ID |
| `05` | 用户号                       |
| `06` | 卡 ID                      |
| `08` | 账户 ID                     |
| `09` | 卡激活条码                     |

### 订单类型 `order_type`

| 值   | 说明   |
| --- | ---- |
| `0` | 正常交易 |
| `1` | 冲正交易 |

### 交易类型 `trans_type`

| 值      | 说明 |
| ------ | -- |
| `0001` | 消费 |

`trans_type` 可能随业务场景扩展。商户应按返回值保存原始编码，并结合 `goods_id`、`goods_name`、`return_code`、`return_desc` 判断具体交易场景。

### 交易状态 `trans_status`

| 值    | 说明 |
| ---- | -- |
| `00` | 成功 |

非 `00` 状态请结合 `return_code` 和 `return_desc` 判断失败或处理中原因。

### 返回码 `return_code`

| 值      | 说明 |
| ------ | -- |
| `0000` | 成功 |

非 `0000` 表示业务未成功，具体原因以 `return_desc` 为准。

### 支付方式 `pay_type`

| 值      | 说明       |
| ------ | -------- |
| `0000` | 余额       |
| `0001` | 网银支付     |
| `0002` | 快捷协议支付   |
| `0003` | 快捷四要素支付  |
| `0004` | FPS 扫码支付 |
| `0005` | 微信扫码     |
| `0006` | 支付宝扫码    |

## 返回示例

```json theme={null}
{
  "code": 0,
  "msg": "success",
  "data": {
    "total": 1,
    "list": [
      {
        "trade_no": "T202607250001",
        "pan": "493875******0990",
        "pan_type": "01",
        "app_time": "2026-07-25 12:00:00",
        "channel_code": "VISA",
        "mer_order_no": "ORDER202607250001",
        "order_type": "0",
        "trans_type": "0001",
        "trans_status": "00",
        "return_code": "0000",
        "return_desc": "success",
        "trans_amount": "10.00",
        "trans_currency_type": "USD",
        "freeze_amount": "0.00",
        "balance_avail": "100.00",
        "merchant_name": "EXAMPLE MERCHANT",
        "fee_list": [
          {
            "fee_code": "F003",
            "amt_fee": "0.50",
            "currcy_code_fee": "HKD",
            "fee_memo": "异常交易手续费"
          }
        ]
      }
    ]
  }
}
```