查询卡交易记录
GET/openapi/v1/cards/transactions仅适用于 V1 支持的卡产品。其他卡产品请使用 V2 接口。
| 项 | 内容 |
|---|---|
| 请求方法 | GET |
| 请求路径 | /openapi/v1/cards/transactions |
| 请求类型 | query |
请求参数:
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
cardId | string | 是 | 无 | 卡 ID。 |
status | string | 否 | 无 | 平台统一交易状态筛选:SUCCESS、FAILED、VOID、PROCESSING;与 V2 相同。 |
currency | string | 否 | 无 | 交易币种,通常为 ISO 4217 三位代码;值域未封闭。 |
fromTime | string | 否 | 无 | 开始时间,ISO 8601 日期时间字符串。 |
toTime | string | 否 | 无 | 结束时间,ISO 8601 日期时间字符串。 |
page | integer | 否 | 1 | 页码,从 1 开始。 |
pageSize | integer | 否 | 20 | 每页数量,1 到 100。 |
响应 data:
| 字段 | 类型 | 说明 |
|---|---|---|
items | array | 交易记录列表。 |
items[].id | string | 交易 ID。 |
items[].cardId | string | 卡 ID。 |
items[].memberId | string | 平台成员 ID。 |
items[].amount | string / null | 原始消费本金,不含任何手续费,与 currency 同币种。 |
items[].accountPrincipalAmount | string/null | 账户币种下的消费本金,不含渠道费;历史缺失时为空,不从原始消费金额推算。 |
items[].accountCurrency | string/null | 与 accountPrincipalAmount 配对的账户本金币种,可能不同于 currency。 |
items[].chargedAmount | string / null | 截至当前已确认的累计扣款,含渠道扣款及已扣附加费;不等待其他费用确认,基础扣款或已扣费用事实不足时为空。 |
items[].totalFee | string / null | 平台与租户附加费用订单金额合计,不含渠道费,不代表已扣取;无附加费用订单时为零,订单金额缺失或币种无法归一时为空。 |
items[].currency | string | 交易币种,通常为 ISO 4217 三位代码;值域可能扩展。 |
items[].status | string | 平台统一交易状态:SUCCESS、FAILED、VOID、PROCESSING。 |
items[].providerStatus | string/null | 渠道原始交易状态,仅供排查,值域可能扩展。 |
items[].occurredAt | string | 交易发生时间,ISO 8601 日期时间字符串。 |
items[].providerTransactionId | string | Provider 交易 ID。 |
items[].transactionType | string | 平台统一交易类型:CONSUMPTION、REFUND、VOID、RECHARGE、WITHDRAWAL。 |
items[].providerTransactionType | string/null | 渠道原始交易类型,仅供排查,值域可能扩展。 |
items[].originalTransactionId | string/null | 退款、撤销等派生交易关联的原交易 ID。 |
items[].countryCode | string | 上游提供时的消费国家或地区代码。 |
items[].merchantName | string | 卡组织或上游处理方提供时的商户展示名称。 |
items[].merchantCategoryCode | string | 上游提供时的四位商户类别代码(MCC)。 |
items[].fees | array | 平台与租户附加手续费订单;不包含渠道自身费用。 |
items[].fees[].feeOrderNo | string | 手续费订单号。 |
items[].fees[].amount | string | 本订单平台费与租户费合计;是否已扣取以 chargeStatus 为准。 |
items[].fees[].currency | string | 手续费币种。 |
items[].fees[].status | string | 手续费订单状态:CREATED、PROCESSING、UNKNOWN、FROZEN、SUCCESS 或 FAILED。 |
items[].fees[].chargeStatus | string / null | 附加费扣款状态:SUCCESS 已扣取,FAILED / NOT_STARTED 未扣取,UNKNOWN / PROCESSING 或空值为结果未确认;与订单及分账状态独立。 |
items[].fees[].providerTransferId | string | Provider 划转 ID。 |
items[].fees[].providerStatus | string | Provider 划转状态。 |
items[].fees[].completedTime | string | 手续费订单完成时间。 |
items[].fees[].items | array | 本订单费用分配明细,金额已包含在订单 amount 中,不可重复累加。 |
items[].fees[].items[].feeCode | string | 费用编码。 |
items[].fees[].items[].beneficiaryTenantId | string | 收益租户 ID。 |
items[].fees[].items[].amount | string | 明细金额。 |
items[].fees[].items[].currency | string | 明细币种。 |
page | integer | 当前页码。 |
pageSize | integer | 每页数量。 |
total | integer | 总数。 |
金额与费用口径
所有金额使用十进制字符串,不使用浮点数累计。消费 Webhook 与本接口遵循同一金额定义:
amount为不含手续费的消费本金。chargedAmount为截至当前已确认累计扣款,包含渠道扣款以及确认扣取的平台、租户附加费用。不能再次累加fees或totalFee。totalFee为平台与租户附加费用订单金额合计,不包含渠道费,也不代表已扣成功。不能使用amount + totalFee代替chargedAmount。fees展示附加费用订单,fees[].items展示其分配明细;二者是总额与拆分关系,不是两笔收费。- 费用订单
status与扣款chargeStatus分别表示订单处理结果与扣款结果;扣款成功但本地分账仍在处理时,已扣费用仍计入chargedAmount。 - 交易处理中、尚无附加费订单或存在待定费用时,已知渠道扣款及成功扣取的费用仍计入
chargedAmount;未开始、处理中、结果未知或失败费用不计入,后续确认成功再增加。渠道扣款缺失、费用列表未知或成功费用事实异常(包括币种无法归一、金额缺失、订单号缺失或重复)时,chargedAmount为空,不用本金或预计费用补齐。已知本金仍通过amount返回,已知附加费用订单金额仍计入totalFee。 fees: []时totalFee为零,但不代表渠道手续费为零。香港消费按免附加费规则处理,chargedAmount仍包含渠道费用;其他地区尚无附加费用订单时也返回已知渠道扣款,不等于最终免收附加费。- 卡消费领域 USD 与 USDT 按 1:1 合并,其他币种不直接相加。
- Webhook 是事件生成时的快照,本接口返回查询时的最新状态,后续扣费确认可能使
chargedAmount更新。
例如,原始消费 10 USD、渠道扣款 10.15 USD、平台费 0.05 USD、租户费 1.05 USD,且附加费已扣取:
json
{
"amount": "10.00",
"chargedAmount": "11.25",
"totalFee": "1.10",
"currency": "USD",
"fees": [
{
"feeOrderNo": "FEE001",
"amount": "1.10",
"currency": "USD",
"status": "SUCCESS",
"chargeStatus": "SUCCESS"
}
]
}