查询卡交易处理过程
GET/openapi/v2/cards/transactions/process查询当前租户、指定卡的已保存交易和费用处理过程。接口只读,不触发服务方查询、状态同步或恢复操作。
| 项 | 内容 |
|---|---|
| 请求方法 | GET |
| 请求路径 | /openapi/v2/cards/transactions/process |
| 请求类型 | query |
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
cardId | string | 是 | 当前租户的卡 ID。 |
transactionId | string | 是 | 交易列表中的 items[].id:消费、退款、撤销为服务方交易 ID,充值、提现为平台订单号。 |
transactionType | string | 是 | 对应列表行的统一类型,区分大小写:CONSUMPTION、REFUND、VOID、RECHARGE、WITHDRAWAL。 |
交易编号、类型和卡必须匹配。跨租户、跨卡或不存在的交易不能查询;不要将原始渠道类型(如 auth)作为 transactionType。
请求示例
http
GET /openapi/v2/cards/transactions/process?cardId=card_001&transactionId=TXN_001&transactionType=CONSUMPTION响应 data
data 是处理步骤数组,不含分页结构:
| 字段 | 类型 | 说明 |
|---|---|---|
[].stepType | string | 步骤类型,见下表。 |
[].stage | string/null | 当前步骤的处理阶段或原始业务类型;不同步骤含义不同,值域可能扩展,不等于请求的统一交易类型。 |
[].status | string/null | 当前步骤的状态,不代表整笔消费或订单的最终状态,取值见下表。 |
[].providerStatus | string/null | 服务方原始状态,兼容排查字段;业务展示应使用 status,不要依赖此字段进行状态判断。 |
[].amount | string/null | 十进制金额字符串;交易和订单步骤为绝对值,费用步骤为对应费用金额。 |
[].currency | string/null | 当前步骤的金额币种。 |
[].referenceNo | string/null | 步骤对应的服务方交易 ID、平台流程号、订单号或费用订单号。 |
[].occurredAt | string/null | 平台处理时间,ISO 8601;按步骤使用处理或完成时间,缺失时回退更新或创建时间,不等于渠道交易发生时间。 |
[].note | string/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
}
]
}