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

# Order Lifecycle and Status Transitions in Nova.Pay

> Track orders from creation through payment to fulfillment. Learn Nova.Pay order statuses, transitions, and how to query order state via the API.

Every checkout in Nova.Pay — whether initiated through a hosted checkout page, a programmatic cart, or a charge link — produces an order that progresses through a defined set of statuses. Understanding this lifecycle lets you build reliable fulfillment logic, handle edge cases like partial payments and refunds, and keep your customers informed at every step. You can query an order's current status at any time using the REST API, and you can react to transitions in real time via webhooks.

## Status Reference

The table below describes every possible order status and what it means for fulfillment:

| Status               | Description                                                                                                                                                                    |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `pending`            | The order has been created but no payment attempt has been made yet.                                                                                                           |
| `waiting_payment`    | A payment has been initiated — for example, a boleto has been generated or a Pix QR code issued — but confirmation has not yet been received from the bank or payment network. |
| `partially_paid`     | At least one installment or partial amount has been paid, but the order total has not been reached.                                                                            |
| `paid`               | The order is fully paid. This is the status that should trigger fulfillment.                                                                                                   |
| `cancelled`          | The order has been cancelled, either by the merchant, the customer, or automatically (e.g. a Pix QR code expiry). No further payment attempts are allowed.                     |
| `partially_refunded` | A partial refund has been issued against a paid order. The order is still considered fulfilled, but some amount has been returned to the customer.                             |
| `refunded`           | The order has been fully refunded. Fulfillment should be reversed if applicable.                                                                                               |
| `billed`             | An invoice has been issued for this order. This status is typically used in B2B or subscription billing flows.                                                                 |

## Lifecycle Diagram

The steps below show the happy path from order creation to payment and optional refund:

<Steps>
  <Step title="Order created → pending">
    The order is created when the customer initiates checkout. At this point no payment has been attempted and the status is `pending`.
  </Step>

  <Step title="Payment initiated → waiting_payment">
    The customer submits a bank slip or Pix payment request. Nova.Pay generates the payment voucher or QR code and the order moves to `waiting_payment`. For instant methods like credit card, this status may be skipped entirely.
  </Step>

  <Step title="Payment confirmed → paid">
    The bank or payment network confirms receipt of funds. The order transitions to `paid` and you can safely fulfill the purchase.
  </Step>

  <Step title="(Optional) Refund issued → partially_refunded or refunded">
    If you initiate a refund via the API, the order moves to `partially_refunded` (if partial) or `refunded` (if full). Reverse any fulfillment actions as appropriate.
  </Step>
</Steps>

<Note>
  Not every order follows this exact path. An order may jump directly from `pending` to `paid` for synchronous payment methods, or from `waiting_payment` to `cancelled` if a boleto expires unpaid.
</Note>

## Querying Order Status

You can check the current status of any order at any time using the Orders API. An API key is required.

```http theme={null}
GET https://pay.nova.money/api/v1/orders/{id}
Authorization: Bearer <your_api_key>
```

Example response:

```json theme={null}
{
  "id": "ord_abc123",
  "status": "paid",
  "total": 10000,
  "currency": "BRL",
  "created_at": "2024-08-01T12:00:00Z",
  "updated_at": "2024-08-01T12:05:43Z",
  "payments": [
    {
      "id": "pay_xyz789",
      "status": "paid",
      "amount": 10000,
      "payment_method": "pix"
    }
  ]
}
```

Use the top-level `status` field to drive your fulfillment logic. The nested `payments` array gives you the status of each individual payment transaction associated with the order.

## Payment Statuses vs. Order Statuses

Individual payment records have their own status that is separate from the parent order status. A single order can have multiple payment records — for example, a split credit card purchase creates two payment records, or a retry after a failed attempt creates a new record alongside the failed one.

| Payment Status         | Meaning                                                                            |
| ---------------------- | ---------------------------------------------------------------------------------- |
| `pending`              | Payment created, not yet submitted to the gateway.                                 |
| `waiting_payment`      | Submitted to the gateway; awaiting external confirmation (boleto, Pix).            |
| `paid`                 | Gateway confirmed receipt of funds.                                                |
| `cancelled`            | Payment was cancelled before completion.                                           |
| `failed`               | The gateway rejected or failed to process the payment.                             |
| `waiting_cancellation` | A cancellation request has been submitted but is not yet confirmed by the gateway. |

<Warning>
  Do not rely solely on individual payment statuses to trigger fulfillment. Always check the parent **order status** — an order only reaches `paid` when the full amount has been confirmed across all payment records.
</Warning>

## Subscriptions

<Note>
  When a payment belongs to a subscription, the payment response includes `"is_subscription": true`. Use this flag to distinguish recurring charges from one-time purchases in your fulfillment and notification logic. Subscription orders cycle through the same statuses as standard orders, but they are created automatically on each billing interval rather than by customer action.
</Note>


## Related topics

- [Nova.Pay Payment Methods: Credit Card, Pix, and Boleto](/concepts/payment-methods.md)
- [Nova.Pay API: Payments, Checkout & Order Management](/introduction.md)
- [Webhooks API — Handle Payment Gateway Event Callbacks](/api-reference/webhooks.md)
- [Nova.Pay API Errors: Status Codes and Response Handling](/errors.md)
- [Charges API — Pay Invoice and Charge Link Endpoints](/api-reference/charges.md)