交易列表

返回当前 AppID 账号下 所有虚拟卡 的 交易明细（消费、退款、撤销、手续费等），支持分页和丰富的筛选条件。

• 范围始终限于你自己的账号 —— 服务端会根据你的 HMAC 凭证绑定账号，无法查询其他账号的数据。
• 严格 脱敏：不含完整 PAN、不含持卡人 PII、不含提供商侧 / 内部订单引用。每条记录都携带 card_id + last_four，便于你归因到具体卡片。
• 如需查询 单张 卡，请使用 卡片交易列表（或在此处以可选筛选项传入 card_id）。

端点

项	值
Method	POST
Path	/api/v1/openapi/transactions/list
鉴权	HMAC
幂等键	不需要

请求字段

所有字段均为可选。

字段	类型	默认值	说明
card_id	string	—	可选筛选项 —— card_<id>。传入后结果仅限该卡（会校验归属 + 虚拟卡类型）。
transaction_time_from	string	—	交易时间范围起点，格式 YYYY-MM-DD HH:MM:SS
transaction_time_to	string	—	交易时间范围终点，格式 YYYY-MM-DD HH:MM:SS
type	string	—	类型筛选 —— 见 类型取值
status	string	—	状态筛选 —— 取 PENDING / APPROVED / FAILED / REVERSED 之一
amount_from	string	—	交易金额下限，如 "10.00"
amount_to	string	—	交易金额上限，如 "1000.00"
merchant_name	string	—	商户名称（模糊匹配）
keyword	string	—	自由文本关键词（在商户 / 描述 / 城市 等上模糊匹配）
page	int	1	页码（≥ 1）
page_size	int	20	每页数量（≤ 100）

请求示例

{
  "status": "APPROVED",
  "transaction_time_from": "2026-04-01 00:00:00",
  "transaction_time_to": "2026-04-30 23:59:59",
  "page": 1,
  "page_size": 20
}

响应

一个分页信封（list / total / page / page_size / total_pages / has_next / has_prev）。list 中的每一项都是一笔交易：

交易字段

字段	类型	说明
transaction_id	string	txn_<id> —— 不透明令牌，请勿解析
card_id	string	该交易所属的 card_<id>
card_type	string	小写业务代码（virtual_v …）
card_brand	string	卡组织展示名（如 VISA）
last_four	string	卡号末 4 位（绝不含完整 PAN）
type	string	归一化后的大写类型（PURCHASE / REFUND / AUTHORIZATION / REVERSAL / FEE …）
type_category	string	用于标签配色的归一化分类 —— 见 分类
type_i18n	object	{ "en-US": …, "zh-CN": …, "zh-HK": … } 展示文案
status	string	PENDING / APPROVED / FAILED / REVERSED
transaction_time	string nullable	交易发生时间（提供商时钟）。未知时为 null
transaction_currency	string	交易币种（ISO 4217）
transaction_amount	string	交易金额（小数字符串，2 位小数）
billing_currency	string	账单 / 卡内币种
billing_amount	string	账单金额（小数字符串，2 位小数）
merchant_name	string	商户名称
merchant_id	string	商户 ID（由卡组织上报）
merchant_category	string	商户分类 / MCC 标签
merchant_country	string	商户国家（如 US）
merchant_city	string	商户城市
merchant_logo_url	string	品牌 Logo URL（解析完成前可能为空）
approval_code	string	批准码（对账用）
auth_code	string	授权码（对账用）
cross_border_type	string	0 = 境内，1 = 跨境
decline_reason	string	失败 / 拒付原因（如适用）
description	string	交易描述
remark	string	备注
created_at	string	记录入库时间

省略字段是刻意的

为空的可选字符串字段会从 JSON 中整体省略（而非 null）。文档所述结构即完整契约 —— 内部 DB ID、提供商交易 ID、关联订单号、用户身份以及完整 PAN 绝不返回。参见 ID 与前缀。

响应示例

{
  "code": 200,
  "message": "OK",
  "data": {
    "list": [
      {
        "transaction_id": "txn_9087654",
        "card_id": "card_12345",
        "card_type": "virtual_v",
        "card_brand": "VISA",
        "last_four": "1234",
        "type": "PURCHASE",
        "type_category": "consumption",
        "type_i18n": { "en-US": "Purchase", "zh-CN": "消费", "zh-HK": "消費" },
        "status": "APPROVED",
        "transaction_time": "2026-04-12T08:31:20Z",
        "transaction_currency": "USD",
        "transaction_amount": "12.90",
        "billing_currency": "USD",
        "billing_amount": "12.90",
        "merchant_name": "OPENAI",
        "merchant_country": "US",
        "merchant_logo_url": "https://img.logo.dev/openai.com",
        "approval_code": "091234",
        "cross_border_type": "0",
        "created_at": "2026-04-12T08:31:25Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

类型取值

type 请求筛选项接受以下标准枚举（服务端会映射到各提供商的原始值）：

值	含义
PURCHASE	消费 / 已结算购买
AUTHORIZATION	预授权（占用，未结算）
REFUND	退款
REVERSAL	撤销
TOPUP	充值 / 充值入账
WITHDRAW	提现
FEE	手续费

未知值会做精确匹配（通常返回空结果）。响应中的 type 字段是归一化后的大写原始类型；请在你的一侧映射用于展示，或使用 type_i18n。

类型分类

type_category 取以下之一：consumption · refund · reversal · topup · fee · close · transfer · withdraw · interest · 3ds · unknown。

隐藏的交易类型

内部记账类型（如系统追加的跨境手续费行、销卡记账条目）会从本接口隐藏，与面向客户的 App 一致。卡片销卡时间之后的交易同样被排除。

常见错误

HTTP	message_key	说明
400	openapi_invalid_card_id	card_id 筛选项错误
400	openapi_card_type_not_supported	card_id 筛选项指向非虚拟卡
400	invalid_date_format	transaction_time_from/to 不符合 YYYY-MM-DD HH:MM:SS
400	invalid_params	金额格式错误（amount_from / amount_to）
401	openapi_invalid_credentials	鉴权失败
404	card_not_found	card_id 筛选项不存在 / 不属于当前账号
500	openapi_list_transactions_failed	服务端异常

说明

• 数据来自 Coinepay 的本地账本（由提供商 webhook 填充）；本接口不会同步调用上游提供商。
• 实时流水优先使用 webhook（card.*）；本接口用于定期对账与历史查询。