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

# Transaction Lifecycle

> Status model, transition intent, and operator interpretation for partner transactions.

## Lifecycle Diagram

```mermaid theme={null}
stateDiagram-v2
    [*] --> pending
    pending --> awaiting_deposit
    awaiting_deposit --> deposit_confirming
    awaiting_deposit --> expired
    awaiting_deposit --> cancelled
    deposit_confirming --> selling_crypto
    deposit_confirming --> failed
    selling_crypto --> order_filled
    selling_crypto --> failed
    order_filled --> completed
    order_filled --> refunded
```

## Statuses

| Status               | Meaning                                                                           | Partner interpretation                                                         |
| -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `pending`            | Transaction has been accepted but is not yet ready for normal deposit processing. | Treat as newly created and re-check shortly.                                   |
| `awaiting_deposit`   | Deposit address is active and CashWeb is waiting for the seller to send funds.    | Show payment instructions and wait for deposit activity.                       |
| `deposit_confirming` | A deposit was detected and is waiting for required confirmations.                 | Do not treat as final yet; wait for confirmation or the next lifecycle update. |
| `selling_crypto`     | Confirmed funds are being processed for conversion and settlement.                | Treat as in progress; do not retry or cancel.                                  |
| `order_filled`       | Crypto execution completed and the transaction is close to final settlement.      | Treat as nearly complete and continue monitoring for terminal completion.      |
| `completed`          | Transaction finished successfully.                                                | Final success state. Reconcile and close the transaction.                      |
| `failed`             | Transaction could not be completed successfully.                                  | Final failure state. Trigger your failure handling and reconciliation flow.    |
| `expired`            | The deposit window elapsed before successful completion.                          | Final state. Do not instruct the seller to send funds without manual recovery. |
| `cancelled`          | Transaction was cancelled before completion.                                      | Final state. Stop further action for this intent.                              |
| `refunded`           | Transaction was reversed after funds had entered the process.                     | Final state. Reconcile as a returned transaction.                              |

## Typical Success Path

`awaiting_deposit` -> `deposit_confirming` -> `selling_crypto` -> `order_filled` -> `completed`

## Early-State Notes

* `pending` should usually be short-lived.
* `awaiting_deposit` is the state in which the seller can still send funds normally.
* `expired` and `cancelled` should be treated as stop conditions for any seller instructions.

## Terminal States

* `completed`
* `failed`
* `expired`
* `cancelled`
* `refunded`

Terminal states should be treated as final in partner operations.

## How to Monitor Progress

1. Prefer webhooks for near-real-time state updates.
2. Use `GET /transactions/{id}` for synchronous checks.
3. Use `GET /transactions/{id}/status-history` to understand transition chronology.

## Integration Advice

* Build user messaging around lifecycle phases, not only terminal states.
* Assume some transitions can occur quickly in sequence.
* Always reconcile eventual terminal status via API reads.