事件列表

事件名称	事件类型	触发时机	通知数据结构
交易单支付成功	trades.succeeded	支付成功时	Trade
交易单支付失败	trades.payment_failed	支付失败时	Trade

事件对象

属性	类型	描述
trade_id	string	交易单id
access_no	string	分配的接入方编号
merchant_id	string	接入方的商户号
amount	string	支付金额，截取两位小数
currency	string	金额对应的交易币
customer_id	string	顾客ID
paid_at	string	交易单付款成功时间.
metadata	map[string]string	一组可附加到对象上的键值对，允许您以结构化格式存储附加信息。
last_payment_error	PaymentError	最后一次支付错误信息，如果该字段有值，则表示支付失败。
next_action	NextAction	下一步操作动作
order_id	string	接入方订单号
last_trans_id	string	订单流水ID。
payment_mode	string	支付业务模式： `subscription`：首次订阅支付，需要收集顾客支付信息，传入 payment_method_data 字段，支付成功时会返回 payment_token 用于后续订阅续费 `recurring_payment`：订阅续订支付，需要传入 payment_token 完成支付，无需收集用户支付信息
payment_token	string	支付token，用于订阅续订扣款。
payment_method	string	支付方式
payment_channel	string	支付渠道
return_url	string	在类似 3DS 跳转支付场景时，支付渠道受理成功后重定向的页面
trade_status	string	支付单状态： `requires_payment_method`：初始状态 `payment_failed`：支付失败 `processing`：支付处理中 `succeeded`：支付成功 `closed`: 已关闭
txn_time	string	交易发起时间，客户端发起接口的时间
created_at	string	交易单创建时间
refund_status	string	退款状态： no_refund：无退款 partially_refunded：部分退款 refunded：退款完成
total_refunded_amount	string	退款金额，截取两位小数
session_id	string	来源结账会话的 ID
invoice_id	string	发票 id
discounts	Discounts	应用于交易的折扣，包括此交易的所有折扣信息

PaymentError

属性	类型	描述
code	string	交易错误码
message	string	交易错误信息

NextAction

属性

类型

描述

type

string

客户端下一步需要操作的类型：

redirect：重定向

redirect

NextActionRedirect

重定向信息

NextActionRedirect

属性	类型	描述
url	string	重定向 URL

Discounts

属性名	类型	描述
current_period	CurrentPeriodDiscount[]	当前时期的折扣详情

CurrentPeriodDiscount

属性名	类型	描述
discount_id	string	折扣的唯一标识符
discount_amount	string	折扣金额
discount_code	string	使用的折扣代码

交易单生命周期

stateDiagram-v2
  direction TB

  state "requires_payment_method" as RPM
  state "processing" as PROC
  state "payment_failed" as FAIL
  state "succeeded" as SUCC
  state "closed" as CLOSED

  RPM --> PROC: 支付审核中
  RPM --> SUCC: 支付成功
  RPM --> FAIL: 支付失败

  PROC --> SUCC: 渠道webhook通知成功
  PROC --> FAIL: 渠道webhook通知失败

  FAIL --> PROC: 支付审核中
  FAIL --> SUCC: 重新发起支付并支付成功

  FAIL --> CLOSED: 续订失败关闭
  RPM --> CLOSED: 交易单超时关闭

交易单状态对应的处理：

requires_payment_method：交易单初始状态，顾客尚未完成付款（可能尚未发起或正在支付中），或订阅续订扣费已发起但尚未返回结果。
payment_failed：支付失败，Subotiz 向支付渠道提交支付信息之后被渠道拒绝，例如余额不足、卡验证失败或风控拦截。
processing：支付处理中，Subotiz 向支付渠道提交支付信息之后，支付渠道返回处理中，需要轮询该状态的交易单，直至处于 payment_failed（支付失败）或者 succeeded（支付成功）。
succeeded：支付成功，处于当前状态无需额外处理。
closed：已关闭，订阅续订失败（多次重试后仍失败）或超过7天无支付结果时，状态流转至已关闭。

示例数据

{
  "id": 593722493181634535,
  "type": "trades.succeeded",
  "created": "2025-12-25T08:41:13Z",
  "data": {
    "return_url": "https://checkout.dev.subotiz.com/checkout/593722303875911656/return",
    "discounts": null,
    "metadata": null,
    "last_payment_error": null,
    "payment_token": "pCD1TbQzAOjo",
    "payment_method": "credit_card",
    "currency": "USD",
    "order_id": "test_order_00111",
    "last_trans_id": "20251225593722452886957894",
    "invoice_id": "",
    "trade_status": "succeeded",
    "txn_time": "2025-12-25T08:40:36Z",
    "trade_id": "593722338718003014",
    "customer_id": "537465921338359803",
    "capture_method": "auto",
    "payment_mode": "subscription",
    "payment_channel": "shoplazzapayment",
    "refund_status": "no_refund",
    "total_refunded_amount": "0.00",
    "session_id": "593722303875911656",
    "access_no": "200010",
    "merchant_id": "100010",
    "amount": "50.00",
    "paid_at": "2025-12-25T08:41:13Z"
  }
}

{
  "id": 593722365515409383,
  "type": "trades.payment_failed",
  "created": "2025-12-25T08:40:42Z",
  "data": {
    "access_no": "200010",
    "metadata": null,
    "last_trans_id": "",
    "paid_at": null,
    "session_id": "593722303875911656",
    "refund_status": "no_refund",
    "total_refunded_amount": "0.00",
    "customer_id": "537465921338359803",
    "last_payment_error": {
      "code": "100999",
      "message": "其他错误"
    },
    "order_id": "test_order_00111",
    "payment_token": "",
    "txn_time": "2025-12-25T08:40:36Z",
    "trade_status": "requires_payment_method",
    "trade_id": "593722338718003014",
    "amount": "50.00",
    "capture_method": "auto",
    "payment_channel": "shoplazzapayment",
    "return_url": "https://checkout.dev.subotiz.com/checkout/593722303875911656/return",
    "discounts": null,
    "merchant_id": "100010",
    "currency": "USD",
    "payment_mode": "subscription",
    "payment_method": "credit_card",
    "invoice_id": ""
  }
}