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

# Payment lifecycle

Every payment has a `status`. It starts at `scheduled` when you create it and ends in one of three terminal states: `completed`, `failed`, or `canceled`.

## Statuses

| Status        | What it means                                                                                            |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| `scheduled`   | Created and queued. You can still edit or cancel it. A payment under risk review also stays `scheduled`. |
| `in-progress` | Processing has begun (funds are being collected and delivered). The payment is locked.                   |
| `completed`   | Funds were delivered to the payee. Terminal.                                                             |
| `failed`      | Collection or delivery did not succeed, for example insufficient funds or a returned transfer. Terminal. |
| `canceled`    | You canceled the payment before it began processing. Terminal.                                           |

## How the status changes

```mermaid theme={null}
flowchart LR
  A([created]) --> S[scheduled]
  S --> P[in-progress]
  S --> F[failed]
  P --> C[completed]
  P --> F
  S --> X[canceled]
```

| Change                      | When it happens                                                                                | Webhook               |
| --------------------------- | ---------------------------------------------------------------------------------------------- | --------------------- |
| → `scheduled`               | You create the payment (`POST /payments`).                                                     | `api.payment.created` |
| `scheduled` → `in-progress` | Processing begins on the deduction date.                                                       | `api.payment.updated` |
| `scheduled` → `failed`      | The payment is not sent, for example a risk review is not approved or collection cannot begin. | `api.payment.updated` |
| `in-progress` → `completed` | Funds are delivered to the payee.                                                              | `api.payment.updated` |
| `in-progress` → `failed`    | Collection or delivery fails or is returned.                                                   | `api.payment.updated` |
| `scheduled` → `canceled`    | You cancel it (`POST /payments/{id}/cancel`).                                                  | `api.payment.updated` |

## Editing and canceling

You can edit or cancel a payment only while it is `scheduled`. Once it is `in-progress`, both are rejected with `409` (`PAYMENT_NOT_EDITABLE` / `PAYMENT_NOT_CANCELABLE`).

## Risk review

A payment being reviewed stays `scheduled` the whole time; there is no separate review status. If the review is approved it proceeds as normal. If it is not, the payment is not sent and moves to `failed`.

<Note>
  Payment events are notifications, not snapshots. `api.payment.updated` fires on every change but carries no payment body, so fetch `GET /payments/{id}` to read the current `status`.
</Note>