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

# Order Status

> Track order status through its lifecycle using webhooks or polling.

# Order Status

After creating an order, you can track its progress through the payment lifecycle.

## Order lifecycle

All orders follow the same status progression regardless of the payment gateway:

```mermaid theme={null}
stateDiagram-v2
    [*] --> pending: Order created
    pending --> processing: Payment initiated
    processing --> confirmed: Payment successful
    processing --> cancelled: Rejected / Timeout
    confirmed --> refunded: Refund processed
```

| Status       | Description                                                                                                                                      |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `pending`    | Order created but payment has not been initiated with the gateway yet.                                                                           |
| `processing` | Payment is in progress — waiting for buyer action (push approval, OTP, transfer).                                                                |
| `confirmed`  | Payment completed successfully. Funds will be settled to your wallet. Settlement timelines average 36 hours but vary by gateway and are dynamic. |
| `cancelled`  | Order was cancelled — buyer rejected the payment, it timed out, or it was cancelled via API.                                                     |
| `refunded`   | A refund has been processed for this order.                                                                                                      |

## Checking order status

You have two options to track when a payment completes:

### Option 1: Webhooks (recommended)

Configure a webhook URL in your dashboard to receive real-time notifications when an order status changes. This is the most efficient approach — no polling required.

```json theme={null}
{
  "event": "order_payment",
  "timestamp": "2026-06-24T02:05:12.952Z",
  "id_order": 12345,
  "id_external": "order-12345",
  "status": "confirmed",
  "total_price": 50000,
  "currency": "COP"
}
```

Payloads are a **flat JSON object** — every field is at the top level, with no nested `data` wrapper. The order total is `total_price` (not `amount`). The example above is abridged; see [Webhook Events](/webhooks/events) for the full `order_payment` payload and [Webhooks](/webhooks/overview) for setup instructions.

### Option 2: Polling

If you cannot receive webhooks, poll the order status endpoint:

```bash theme={null}
curl -X GET "https://api.wava.co/v1/orders/12345" \
  -H "merchant-key: YOUR_MERCHANT_KEY"
```

<Warning>
  Polling should be used as a fallback only. We recommend a polling interval of 3–5 seconds. Excessive polling may be rate-limited.
</Warning>

## Cancelling an order

You can cancel an order that is still in `pending` or `processing` status:

```bash theme={null}
curl -X PUT "https://api.wava.co/v1/orders/12345/cancel" \
  -H "merchant-key: YOUR_MERCHANT_KEY"
```

<Note>
  Orders in `confirmed` status cannot be cancelled. To reverse a confirmed payment, use the refund flow.
</Note>

## Timeout behavior

Each gateway has a different timeout window. If the buyer does not complete the payment within the timeout period, the order is automatically moved to `cancelled` status.

| Gateway   | Approximate timeout |
| --------- | ------------------- |
| Nequi     | \~5 minutes         |
| Daviplata | \~5 minutes         |
| Breb      | \~15 minutes        |
| Stripe    | Session-based       |

## Settlement timelines

Once an order reaches `confirmed` status, funds are settled to your Wava wallet. Settlement timelines average **36 hours** but vary by gateway and are subject to change. Exact per-gateway timelines will be visible in the Wava dashboard in an upcoming release.

## Next steps

* Set up [Webhooks](/webhooks/overview) for real-time notifications
* Review [Error Handling](/errors/overview) for failed payment scenarios
* See [Testing](/testing/sandbox) to simulate different order outcomes