跳转到内容

查询卡交易处理过程 ​

GET /openapi/v2/cards/transactions/process

查询当前租户、指定卡的已保存交易和费用处理过程。接口只读,不触发服务方查询、状态同步或恢复操作。

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

请求参数 ​

字段类型必填说明
cardIdstring是当前租户的卡 ID。
transactionIdstring是交易列表中的 items[].id:消费、退款、撤销为服务方交易 ID,充值、提现为平台订单号。
transactionTypestring是对应列表行的统一类型,区分大小写:CONSUMPTION、REFUND、VOID、RECHARGE、WITHDRAWAL。

交易编号、类型和卡必须匹配。跨租户、跨卡或不存在的交易不能查询;不要将原始渠道类型(如 auth)作为 transactionType。

请求示例 ​

http
GET /openapi/v2/cards/transactions/process?cardId=card_001&transactionId=TXN_001&transactionType=CONSUMPTION

响应 data ​

data 是处理步骤数组,不含分页结构:

字段类型说明
[].stepTypestring步骤类型,见下表。
[].stagestring/null当前步骤的处理阶段或原始业务类型;不同步骤含义不同,值域可能扩展,不等于请求的统一交易类型。
[].statusstring/null当前步骤的状态,不代表整笔消费或订单的最终状态,取值见下表。
[].providerStatusstring/null服务方原始状态,兼容排查字段;业务展示应使用 status,不要依赖此字段进行状态判断。
[].amountstring/null十进制金额字符串;交易和订单步骤为绝对值,费用步骤为对应费用金额。
[].currencystring/null当前步骤的金额币种。
[].referenceNostring/null步骤对应的服务方交易 ID、平台流程号、订单号或费用订单号。
[].occurredAtstring/null平台处理时间,ISO 8601;按步骤使用处理或完成时间,缺失时回退更新或创建时间,不等于渠道交易发生时间。
[].notestring/null补充说明;订单步骤可能返回失败码。

步骤类型与状态 ​

stepType含义status 已知值
CONSUMPTION、REFUND、VOID本地消费、退款或撤销记录SUCCESS、FAILED、VOID、PROCESSING;历史未保存状态时可为空
ORDER_FLOW充值或提现订单的处理流程CREATED、PROCESSING、SUCCESS、FAILED
ORDER_RESULT没有流程记录时返回的订单当前结果CREATED、PROCESSING、SUCCESS、FAILED
FEE_CHARGE费用扣取步骤,优先使用实际扣款状态NOT_STARTED、PROCESSING、UNKNOWN、SUCCESS、FAILED;历史回退费用订单状态时还可能为 CREATED、FROZEN

查询口径 ​

  • 只返回已有记录,不补造授权、入账或退款步骤,也不包含 Webhook 接收和投递通知。
  • 明确关联到同租户、同卡、同服务方原消费的多次退款会进入原消费的过程;缺失或不明确的关联不会推断合并。
  • 按 occurredAt 升序排列,时间相同时按 referenceNo 升序,缺失时间排在最后。这里展示的是平台处理记录,不保证渠道事件的实际发生顺序。
  • 返回已有记录的当前状态,不是不可变事件快照;步骤金额不能简单相加作为消费本金或实际总扣款。整笔交易的状态和金额口径见交易列表。

响应示例 ​

以下为单条已落库消费步骤的示意,不表示每笔交易一定存在完整授权与入账历史:

json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "stepType": "CONSUMPTION",
      "stage": "auth",
      "status": "SUCCESS",
      "providerStatus": "succeed",
      "amount": "10.5",
      "currency": "USD",
      "referenceNo": "TXN_001",
      "occurredAt": "2026-10-10T02:00:00Z",
      "note": null
    }
  ]
}