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

# Payment lifecycle

> State machine from invoice creation through settlement and webhook delivery.

This page describes the **runtime payment lifecycle** as implemented in the Meum platform API.

## Lifecycle diagram

```mermaid theme={null}
stateDiagram-v2
    [*] --> awaiting_payment: Invoice created
    awaiting_payment --> quoted: Customer selects token
    quoted --> awaiting_payment: Quote refresh
    awaiting_payment --> paid: Full payment detected
    quoted --> paid: Full payment detected
    awaiting_payment --> underpaid: Partial payment
    quoted --> underpaid: Partial payment
    awaiting_payment --> expired: Timeout reached
    quoted --> expired: Timeout reached
    awaiting_payment --> failed: Payment failed
    quoted --> failed: Payment failed
    awaiting_payment --> cancelled: Cancelled
    paid --> [*]: Webhook delivered
    underpaid --> [*]: Webhook delivered
    expired --> [*]: Webhook delivered
    failed --> [*]: Webhook delivered
    cancelled --> [*]: Webhook delivered
```

## Stage-by-stage

| Stage                                     | What happens                                                                      |
| ----------------------------------------- | --------------------------------------------------------------------------------- |
| **Invoice created**                       | `POST /v1/invoices` → status `awaiting_payment`, webhook `invoice.created` queued |
| **Awaiting payment**                      | Customer opens checkout at `pay.meum.io/{invoiceId}`                              |
| **Quote created**                         | Customer selects origin token → status may become `quoted`                        |
| **Blockchain payment detected**           | Meum payment monitor detects deposit                                              |
| **Confirmation/validation**               | Amount compared to expected; status set to `paid` or `underpaid`                  |
| **Invoice paid**                          | Terminal status; settlement log written                                           |
| **Webhook queued**                        | BullMQ job enqueued for delivery                                                  |
| **Merchant integration receives webhook** | HTTP POST with signed payload                                                     |
| **Order updated**                         | WooCommerce calls `payment_complete()` on `invoice.paid`                          |

## Open vs terminal statuses

**Open** (can receive payment): `awaiting_payment`, `quoted`, `pending`

**Terminal** (no further payment updates): `paid`, `underpaid`, `failed`, `expired`, `refunded`, `cancelled`

## Related pages

* [Invoice lifecycle](/payments/invoice-lifecycle)
* [Payment statuses](/payments/payment-statuses)
* [Webhooks overview](/webhooks/overview)