# Status Lifecycles

PayChain exposes statuses so your system can decide what to do next. Build your integration around lifecycle states, not raw transaction observations alone.

{% hint style="info" %}
**Fulfillment rule:** Fulfill customer orders from confirmed invoice state, not from raw balance changes or unverified transaction history.
{% endhint %}

### Invoice statuses

| Status       | Meaning                                                                        | Typical action                                                    |
| ------------ | ------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
| `pending`    | Invoice has been created and is waiting for payment.                           | Show payment instructions.                                        |
| `confirming` | Payment has been observed and is waiting for required settlement confirmation. | Wait. Do not fulfill yet.                                         |
| `paid`       | Invoice is fully settled.                                                      | Fulfill the order after webhook verification and canonical fetch. |
| `overpaid`   | More than the requested amount was settled.                                    | Fulfill according to your policy; reconcile the excess.           |
| `underpaid`  | Less than the requested amount was settled.                                    | Wait for completion or follow your underpayment policy.           |
| `failed`     | Invoice is no longer valid or was rejected.                                    | Do not fulfill.                                                   |
| `expired`    | Invoice expired before settlement.                                             | Ask customer to create or request a new invoice.                  |
| `cancelled`  | Invoice was cancelled.                                                         | Do not accept it for fulfillment.                                 |

### Withdrawal statuses

| Status        | Meaning                                                   | Typical action                                      |
| ------------- | --------------------------------------------------------- | --------------------------------------------------- |
| `quoted`      | A quote was generated but no withdrawal has been created. | Confirm terms before creating.                      |
| `queued`      | Withdrawal is accepted and waiting for processing.        | Show pending state.                                 |
| `processing`  | PayChain is preparing or submitting the transfer.         | Wait for final state.                               |
| `broadcasted` | Transaction has been submitted to the network.            | Track hash if available.                            |
| `completed`   | Withdrawal completed.                                     | Mark payout as complete.                            |
| `failed`      | Withdrawal failed.                                        | Review failure reason and retry only when safe.     |
| `cancelled`   | Withdrawal was cancelled before completion.               | Do not retry automatically without operator intent. |
| `gas_blocked` | Sponsored outbound operation is waiting for gas credits.  | Top up gas credits or wait for operator action.     |

### Payout routing statuses

| Status       | Meaning                                                                        |
| ------------ | ------------------------------------------------------------------------------ |
| `pending`    | Invoice has routing instructions but settlement has not triggered routing yet. |
| `processing` | PayChain is creating withdrawal legs.                                          |
| `completed`  | All routing legs completed.                                                    |
| `failed`     | Routing setup failed or all created legs failed.                               |
| `cancelled`  | Routing was cancelled before execution.                                        |

### Gas-blocked state

Gas-blocked means PayChain can see the payment or operation, but an eligible sponsored outbound action is paused because gas credits are insufficient.

Inbound payment detection does not stop when gas credits run out. Sponsored outbound actions may pause, including:

* Automatic settlement.
* Sponsored withdrawals.
* Payout route withdrawal legs.
* Dynamic payout recipient withdrawal legs.
* Contract execution where PayChain sponsors network cost.

### Status handling rules

* Treat unknown statuses as non-final.
* Make fulfillment idempotent.
* Store PayChain IDs and your own order references together.
* Fetch the resource after webhook verification.
* Do not assume a transaction hash alone means the invoice is payable or fulfilled.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.paychainhq.io/paychainhq-documentation-page/status-lifecycles.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.