查询卡交易记录
GET/openapi/v2/cards/transactions| 项 | 内容 |
|---|---|
| 请求方法 | GET |
| 请求路径 | /openapi/v2/cards/transactions |
| 请求类型 | query |
请求参数:
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
cardId | string | 是 | 无 | 卡 ID。 |
status | string | 否 | 无 | 平台统一交易状态筛选:SUCCESS、FAILED、VOID、PROCESSING;与 V1 相同。 |
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 | 原始消费本金,不含手续费;与 currency 同币种的十进制字符串。 |
items[].accountPrincipalAmount | string/null | 账户币种下的消费本金,不含渠道费;历史缺失时为空,不从原始消费金额推算。 |
items[].accountCurrency | string/null | 与 accountPrincipalAmount 配对的账户本金币种,可能不同于 currency。 |
items[].chargedAmount | string/null | 截至当前已确认的累计扣款,含渠道扣款和已扣成功的附加费;待定费用不影响已确认扣款的展示,基础扣款或已扣费用事实不足、异常时为空。 |
items[].totalFee | string/null | 平台与租户附加费用订单金额合计,不含渠道自身费用,不代表已扣成功;无费用订单时为 0,金额缺失或币种无法归一时为空。 |
items[].currency | string | 交易币种,通常为 ISO 4217 三位代码;值域可能扩展。 |
items[].status | string | 平台统一交易状态:SUCCESS、FAILED、VOID、PROCESSING。 |
items[].providerStatus | string/null | 渠道原始交易状态,仅供排查,值域可能扩展。 |
items[].occurredAt | string | 交易发生时间,ISO 8601 日期时间字符串。 |
items[].providerTransactionId | string/null | 服务方交易 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是已确认的渠道扣款与已扣成功附加费之和;未开始、处理中、结果未知或失败的费用不计入,后续确认成功再增加。不能用amount + totalFee代替实际扣款。totalFee是附加费用订单金额合计,不是实际已扣金额;是否收取应查看各订单的chargeStatus,不能只看订单status。fees[].items是费用订单内部的分配明细,已包含在fees[].amount中;费用订单金额也已计入totalFee,不能重复累加。
例如,原始消费 10 USD、渠道扣款 10.15 USD、平台费 0.05 USD、租户费 1.05 USD,且附加费已扣成功,则 totalFee 为 1.10 USD,chargedAmount 为 11.25 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"
}
]
}本地数据与关联退款
本接口查询当前租户的本地交易。明确关联同卡、同服务方原消费的退款归入该消费的处理过程,不再单独列出;没有明确关联的退款仍单列,不会仅凭金额或时间推断关联。消费 amount 仍为原始本金,不因退款减少。
查询处理过程时传入 items[].id 和 items[].transactionType。消费、退款、撤销的 id 是服务方交易 ID;充值、提现的 id 是平台订单号,providerTransactionId 为空。
