事件列表

事件名称	事件类型	触发时机	通知数据结构
交易单支付成功	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": ""
  }
}