跳转到内容

查询卡交易记录 ​

GET /openapi/v2/cards/transactions
项内容
请求方法GET
请求路径/openapi/v2/cards/transactions
请求类型query

请求参数:

字段类型必填默认值说明
cardIdstring是无卡 ID。
statusstring否无平台统一交易状态筛选:SUCCESS、FAILED、VOID、PROCESSING;与 V1 相同。
currencystring否无交易币种,通常为 ISO 4217 三位代码;值域未封闭。
fromTimestring否无开始时间,ISO 8601 日期时间字符串。
toTimestring否无结束时间,ISO 8601 日期时间字符串。
pageinteger否1页码,从 1 开始。
pageSizeinteger否20每页数量,1 到 100。

响应 data:

字段类型说明
itemsarray交易记录列表。
items[].idstring交易 ID。
items[].cardIdstring卡 ID。
items[].memberIdstring平台成员 ID。
items[].amountstring原始消费本金,不含手续费;与 currency 同币种的十进制字符串。
items[].accountPrincipalAmountstring/null账户币种下的消费本金,不含渠道费;历史缺失时为空,不从原始消费金额推算。
items[].accountCurrencystring/null与 accountPrincipalAmount 配对的账户本金币种,可能不同于 currency。
items[].chargedAmountstring/null截至当前已确认的累计扣款,含渠道扣款和已扣成功的附加费;待定费用不影响已确认扣款的展示,基础扣款或已扣费用事实不足、异常时为空。
items[].totalFeestring/null平台与租户附加费用订单金额合计,不含渠道自身费用,不代表已扣成功;无费用订单时为 0,金额缺失或币种无法归一时为空。
items[].currencystring交易币种,通常为 ISO 4217 三位代码;值域可能扩展。
items[].statusstring平台统一交易状态:SUCCESS、FAILED、VOID、PROCESSING。
items[].providerStatusstring/null渠道原始交易状态,仅供排查,值域可能扩展。
items[].occurredAtstring交易发生时间,ISO 8601 日期时间字符串。
items[].providerTransactionIdstring/null服务方交易 ID;充值、提现记录为空。
items[].transactionTypestring平台统一交易类型:CONSUMPTION、REFUND、VOID、RECHARGE、WITHDRAWAL。
items[].providerTransactionTypestring/null渠道原始交易类型,仅供排查,值域可能扩展。
items[].originalTransactionIdstring/null退款、撤销等派生交易关联的原交易 ID。
items[].countryCodestring上游提供时的消费国家或地区代码。
items[].merchantNamestring卡组织或上游处理方提供时的商户展示名称。
items[].merchantCategoryCodestring上游提供时的四位商户类别代码(MCC)。
items[].feesarray平台与租户附加手续费订单,不包含渠道自身费用。
items[].fees[].feeOrderNostring手续费订单号。
items[].fees[].amountstring本订单平台费与租户费合计,是否已扣取以 chargeStatus 为准。
items[].fees[].currencystring手续费币种。
items[].fees[].statusstring手续费订单状态:CREATED、PROCESSING、UNKNOWN、FROZEN、SUCCESS 或 FAILED。
items[].fees[].chargeStatusstring/null手续费实际扣款状态,独立于订单状态;SUCCESS 表示已收取,FAILED、NOT_STARTED 表示未收取,UNKNOWN、PROCESSING 或空值表示未确认。
items[].fees[].providerTransferIdstringProvider 划转 ID。
items[].fees[].providerStatusstringProvider 划转状态。
items[].fees[].completedTimestring手续费订单完成时间。
items[].fees[].itemsarray本订单费用分配明细,金额已包含在订单 amount 中,不可重复累加。
items[].fees[].items[].feeCodestring费用编码。
items[].fees[].items[].beneficiaryTenantIdstring收益租户 ID。
items[].fees[].items[].amountstring明细金额。
items[].fees[].items[].currencystring明细币种。
pageinteger当前页码。
pageSizeinteger每页数量。
totalinteger总数。

金额与费用口径 ​

所有金额使用十进制字符串,不使用浮点数累计。消费 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 为空。