> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 支付生命周期与订单状态

> 了解 Waffo 支付订单、订阅与退款如何在不同状态之间流转。

## 订单状态流转

```mermaid theme={null}
stateDiagram-v2
    [*] --> PAY_IN_PROGRESS
    PAY_IN_PROGRESS --> AUTHORIZATION_REQUIRED
    PAY_IN_PROGRESS --> PAY_SUCCESS
    PAY_IN_PROGRESS --> ORDER_CLOSE
    AUTHORIZATION_REQUIRED --> AUTHED_WAITING_CAPTURE
    AUTHORIZATION_REQUIRED --> PAY_SUCCESS
    AUTHED_WAITING_CAPTURE --> PAY_SUCCESS
    PAY_SUCCESS --> ORDER_PARTIALLY_REFUNDED
    PAY_SUCCESS --> ORDER_FULLY_REFUNDED
    ORDER_CLOSE --> [*]
    PAY_SUCCESS --> [*]
```

## 订单状态参考

| 状态                       | 描述                         | 终态 |
| ------------------------ | -------------------------- | -- |
| `PAY_IN_PROGRESS`        | 订单已被受理，用户正在支付中             | 否  |
| `AUTHORIZATION_REQUIRED` | 支付方式需要用户授权（例如电子钱包）         | 否  |
| `AUTHED_WAITING_CAPTURE` | 已授权，等待确认扣款（银行卡支付；需要商户确认扣款） | 否  |
| `PAY_SUCCESS`            | 支付成功                       | 是  |
| `ORDER_CLOSE`            | 订单已关闭（取消、失败或超时）            | 是  |

## 订阅状态

| 状态                       | 描述             | 动作                            |
| ------------------------ | -------------- | ----------------------------- |
| `AUTHORIZATION_REQUIRED` | 需要用户授权（电子钱包场景） | 重定向到 `subscriptionAction` URL |
| `IN_PROGRESS`            | 用户正在确认订阅       | 等待 Webhook                    |
| `ACTIVE`                 | 订阅已生效并正常扣款     | 存储 `subscriptionId`           |
| `CLOSE`                  | 已关闭（超时或失败）     | 如有需要重新发起                      |
| `MERCHANT_CANCELLED`     | 由商户取消          | —                             |
| `USER_CANCELLED`         | 由用户取消          | 更新本地记录                        |
| `CHANNEL_CANCELLED`      | 由渠道取消          | 通知用户                          |
| `EXPIRED`                | 未激活即已过期        | 如有需要重新发起                      |

## 退款状态

| 状态                         | 描述     |
| -------------------------- | ------ |
| `REFUND_IN_PROGRESS`       | 退款处理中  |
| `ORDER_PARTIALLY_REFUNDED` | 部分退款完成 |
| `ORDER_FULLY_REFUNDED`     | 全额退款完成 |
| `ORDER_REFUND_FAILED`      | 退款失败   |

## 最佳实践

<Tip>
  **仅以 Webhook 作为唯一事实来源**：重定向 URL 仅用于用户体验，不应被用来判断支付结果。
</Tip>

1. **处理中间状态**：不要在 `PAY_IN_PROGRESS` 时自动关闭订单；请等待 Webhook 或主动查询
2. **幂等处理**：Webhook 可能会被重复投递；请确保你的处理逻辑具备幂等性。详见 [幂等性](/docs/zh/developer-docs/core-concepts/idempotency)
3. **未知状态**：当遇到错误码 `E0001` 时，请使用原始的 `paymentRequestId` 进行查询，不要自动关闭订单。完整处理流程见 [错误处理](/docs/zh/developer-docs/core-concepts/error-handling)