跳转到内容

查询卡交易记录 ​

GET /openapi/v1/cards/transactions

仅适用于 V1 支持的卡产品。其他卡产品请使用 V2 接口。

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

请求参数:

字段类型必填默认值说明
cardIdstring是无卡 ID。
statusstring否无平台统一交易状态筛选:SUCCESS、FAILED、VOID、PROCESSING;与 V2 相同。
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 / null原始消费本金,不含任何手续费,与 currency 同币种。
items[].accountPrincipalAmountstring/null账户币种下的消费本金,不含渠道费;历史缺失时为空,不从原始消费金额推算。
items[].accountCurrencystring/null与 accountPrincipalAmount 配对的账户本金币种,可能不同于 currency。
items[].chargedAmountstring / null截至当前已确认的累计扣款,含渠道扣款及已扣附加费;不等待其他费用确认,基础扣款或已扣费用事实不足时为空。
items[].totalFeestring / null平台与租户附加费用订单金额合计,不含渠道费,不代表已扣取;无附加费用订单时为零,订单金额缺失或币种无法归一时为空。
items[].currencystring交易币种,通常为 ISO 4217 三位代码;值域可能扩展。
items[].statusstring平台统一交易状态:SUCCESS、FAILED、VOID、PROCESSING。
items[].providerStatusstring/null渠道原始交易状态,仅供排查,值域可能扩展。
items[].occurredAtstring交易发生时间,ISO 8601 日期时间字符串。
items[].providerTransactionIdstringProvider 交易 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 为截至当前已确认累计扣款,包含渠道扣款以及确认扣取的平台、租户附加费用。不能再次累加 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"
    }
  ]
}