> ## 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.

# Payment lifecycle and order statuses

> Learn how Waffo payment orders, subscriptions, and refunds transition between statuses.

## Order status transitions

```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 --> [*]
```

## Order status reference

| Status                   | Description                                                                                         | Final |
| ------------------------ | --------------------------------------------------------------------------------------------------- | ----- |
| `PAY_IN_PROGRESS`        | The order has been accepted and the user is in the process of paying                                | No    |
| `AUTHORIZATION_REQUIRED` | The payment method requires user authorization (e.g., an e-wallet)                                  | No    |
| `AUTHED_WAITING_CAPTURE` | Authorized, awaiting capture confirmation (card payments; requires the merchant to confirm capture) | No    |
| `PAY_SUCCESS`            | Payment succeeded                                                                                   | Yes   |
| `ORDER_CLOSE`            | The order is closed (cancelled, failed, or timed out)                                               | Yes   |

## Subscription statuses

| Status                   | Description                                        | Action                                   |
| ------------------------ | -------------------------------------------------- | ---------------------------------------- |
| `AUTHORIZATION_REQUIRED` | User authorization is required (e-wallet scenario) | Redirect to the `subscriptionAction` URL |
| `IN_PROGRESS`            | The user is confirming the subscription            | Wait for the Webhook                     |
| `ACTIVE`                 | The subscription is active and charging normally   | Store the `subscriptionId`               |
| `CLOSE`                  | Closed (timed out or failed)                       | Re-initiate if needed                    |
| `MERCHANT_CANCELLED`     | Cancelled by the merchant                          | —                                        |
| `USER_CANCELLED`         | Cancelled by the user                              | Update local records                     |
| `CHANNEL_CANCELLED`      | Cancelled by the channel                           | Notify the user                          |
| `EXPIRED`                | Expired without being activated                    | Re-initiate if needed                    |

## Refund statuses

| Status                     | Description               |
| -------------------------- | ------------------------- |
| `REFUND_IN_PROGRESS`       | Refund is being processed |
| `ORDER_PARTIALLY_REFUNDED` | Partial refund completed  |
| `ORDER_FULLY_REFUNDED`     | Full refund completed     |
| `ORDER_REFUND_FAILED`      | Refund failed             |

## Best practices

<Tip>
  **Use the Webhook as the only source of truth**: redirect URLs are only for user experience and should not be used to determine the payment result.
</Tip>

1. **Handle intermediate states**: do not automatically close orders in `PAY_IN_PROGRESS`; wait for the Webhook or query proactively
2. **Idempotent handling**: Webhooks may be delivered more than once; ensure your handling logic is idempotent
3. **Unknown status**: when you encounter error code `E0001`, query using the original `paymentRequestId` and do not automatically close the order