> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subotiz.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 交易单
## 事件列表
| **事件名称** | **事件类型** | **触发时机** | **通知数据结构** |
| :------- | :--------------------- | :------- | :--------------------------- |
| 交易单支付成功 | trades.succeeded | 支付成功时 | [Trade](/zh/webhook/trade-1) |
| 交易单支付失败 | trades.payment\_failed | 支付失败时 | [Trade](/zh/webhook/trade-1) |
## 事件对象
| **属性** | **类型** | **描述** |
| ----------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 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 | 使用的折扣代码 |
## 交易单生命周期
```mermaid theme={null}
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天无支付结果时，状态流转至已关闭。
## 示例数据
```json trades.succeeded theme={null}
{
"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"
}
}
```
```json trades.payment_failed theme={null}
{
"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": ""
}
}
```