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

A subscription starts in `IN_PROGRESS`. It enters `AUTHORIZATION_REQUIRED` when the user must select a payment method or complete authorization. After the user completes authorization, processing continues toward `ACTIVE`; failures or timeouts move the subscription to `CLOSE`. Cancellation statuses and `EXPIRED` are final. The diagram shows only the key path through creation, authorization, activation, and completion; see the table below for each final status.

```mermaid theme={null}
stateDiagram-v2
    [*] --> IN_PROGRESS
    IN_PROGRESS --> AUTHORIZATION_REQUIRED: User authorization required
    IN_PROGRESS --> ACTIVE: No authorization; initial payment succeeds
    AUTHORIZATION_REQUIRED --> ACTIVE: Authorization and initial payment succeed
    IN_PROGRESS --> CLOSE: Failure or timeout
    AUTHORIZATION_REQUIRED --> CLOSE: Failure or timeout
    ACTIVE --> MERCHANT_CANCELLED: Merchant cancels
    ACTIVE --> USER_CANCELLED: User cancels
    ACTIVE --> CHANNEL_CANCELLED: Payment channel cancels
    ACTIVE --> PLATFORM_CANCELLED: Platform cancels
    CLOSE --> [*]
```

| 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 |
| `PLATFORM_CANCELLED` | Cancelled by the platform | Check `cancelReason` in the subscription inquiry response |
| `EXPIRED` | The subscription has expired | 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.

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. See [Idempotency](/docs/en/developer-docs/core-concepts/idempotency.md)
3. **Unknown status**: when you encounter error code `E0001`, query using the original `paymentRequestId` and do not automatically close the order. For the full handling flow, see [Error handling](/docs/en/developer-docs/core-concepts/error-handling.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.