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

# Order lifecycle

> Order states, time windows, and the buy and sell flows.

## States

```mermaid theme={null}
stateDiagram-v2
    [*] --> ACTIVE: signal_intent (USDC locked)
    ACTIVE --> FULFILLED: fulfill_intent(claim)
    ACTIVE --> RELEASED_MANUAL: depositor_release
    ACTIVE --> CANCELLED: cancel_intent (taker)
    ACTIVE --> EXPIRED: expire_intent (after settle_by)
    FULFILLED --> [*]
    RELEASED_MANUAL --> [*]
    CANCELLED --> [*]
    EXPIRED --> [*]
```

`FULFILLED` and `RELEASED_MANUAL` pay the taker. `CANCELLED` and `EXPIRED` return the USDC to the depositor.

## Time windows

| Time | Meaning |
| - | - |
| `pay_by` | The taker should have paid by now. The app stops showing payment details after it. |
| `settle_by` | `pay_by` plus a grace period. A claim or a depositor release is accepted until this time. |
| After `settle_by` | Anyone can call `expire_intent`. |

The grace period covers a payment made just before `pay_by` that the provider marks final a little later.

## Buy

```
LP:    deposit(USDC) → set_rail_terms(wise, PHP, min_rate, LP payee hash)
User:  signal_intent(taker = user, provider = LP, amount, rate, expected fiat, payer hash)
App:   shows the LP's Wise details and the order reference, only after the lock is confirmed
User:  pays the LP Wise-to-Wise, from their Wise balance
User:  the phone captures the transfer and the verifier signs a claim
Relay: fulfill_intent(claim) → USDC to the user
```

## Sell

```
User:  deposit(USDC) → set_rail_terms(wise, PHP, min_rate, user payee hash) → set_allowed_takers([LP])
LP:    signal_intent(taker = LP, provider = user, rate ≥ user's minimum, LP payer hash)
LP:    pays the user (Wise or bank)
LP:    captures the outgoing transfer and the verifier signs a claim
Relay: fulfill_intent(claim) → USDC to the LP
```

## Who pays the Stellar fee

Users never need XLM. Pesa's backend builds each user transaction (deposit, set terms, signal, cancel, depositor release) as an issued action. The user's wallet signs it, and Pesa's relay wraps it in a fee-bump. The relay fee-bumps only a transaction whose hash matches an action it issued for that user, once.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.