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

# Proposal: Transaction statuses

> A proposed deposit state machine and tracking channels.

<Info>
  **Proposal, not live spec.** Status names below are a proposal shaped after on-chain
  deposit flows (Li.Fi execution events) and payment lifecycles (Stripe, Transak). The team
  should confirm the final set with the routing layer.
</Info>

## Proposed lifecycle

```
created → routing → source_confirmed → completed
                                      ↘ failed
                  ↘ (after completion, if reversed) refunded
```

| Status             | Meaning                               | Terminal? | Credit the user?    |
| ------------------ | ------------------------------------- | --------- | ------------------- |
| `created`          | Deposit created, funds not yet moving | No        | No                  |
| `routing`          | Funds being settled cross-chain       | No        | No                  |
| `source_confirmed` | Source payment confirmed on-chain     | No        | No                  |
| `completed`        | USDC landed on the target chain       | Yes       | **Yes**             |
| `failed`           | Deposit could not be completed        | Yes       | No                  |
| `refunded`         | A completed deposit was reversed      | Yes       | No (reverse credit) |

## Rules worth adopting (from Stripe)

* **Credit on `completed` only.** Never credit from a client-side event.
* **Statuses can arrive out of order.** Don't assume order; reconcile against current status.
* **Final states are terminal** - `completed`, `failed`, `refunded` don't change.

## Two model shapes we saw

* **On-chain execution events (Li.Fi):** `RouteExecutionStarted / Updated / Completed /
  Failed`. Closest to Rheon, because the deposit settles on-chain.
* **Fiat-order statuses (Transak):** a longer chain like `AWAITING_PAYMENT → PROCESSING →
  COMPLETED` (+ `FAILED / REFUNDED / EXPIRED`). Relevant once the Bank On/Off-Ramp lands.

## Three tracking channels (Transak)

The same status can be delivered three ways, with one consistent payload - the partner
picks per need:

* **Polling** - reconciliation
* **Webhook** - push (recommended for crediting)
* **WebSocket** - near-real-time stream