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

# Statuses

> Every transaction is pending, processing, successful or failed.

Payouts, pay-ins and conversions all report one of four statuses in the `status` field.

| Status | Meaning | Final? |
| - | - | - |
| `pending` | Payve accepted the request. Nothing has been sent or received yet. | No |
| `processing` | The transaction is with the bank or operator. Wait for the outcome. | No |
| `successful` | Done. The money arrived. | Yes |
| `failed` | Done. The money did not reach its destination. | Yes |

```mermaid
flowchart LR
  pending --> processing
  pending --> failed
  processing --> successful
  processing --> failed
```

> [!WARNING]
>
> Only `successful` means the money arrived. Do not release goods, mark an invoice paid or tell a
> customer "sent" on `pending` or `processing`.

## Sub-status

`subStatus` adds detail when there is some. It is `null` when the status says everything.

| `status` | `subStatus` | What happened |
| - | - | - |
| `pending` | `received` | Accepted, not yet started. |
| `successful` | `credited` | A pay-in was credited to your wallet. |
| `successful` | `completed` | Finished. An older name for the same outcome. |
| `successful` | `overpaid` | A payment link received more than it asked for. You keep the expected amount and the excess goes back to the payer. |
| `successful` | `underpaid` | A payment link received less than it asked for. **Nothing was credited** and the whole payment goes back to the payer. |
| `failed` | `reversed` | The money was returned to your wallet. |
| `failed` | `cancelled` | Cancelled before it was sent. |
| `failed` | `expired` | A pay-in was not paid in time. |

> [!WARNING]
>
> A pay-in with `status: successful` and `subStatus: underpaid` did **not** credit your wallet.
> Check `subStatus` before you fulfil an order from a payment link.

## Payout lifecycle

1. You create the payout. It is `pending`.
2. Payve debits your wallet and sends the payout. It is `processing`.
3. The bank or operator confirms. It becomes `successful`, or `failed` with the money back in your wallet.

If one route fails, Payve can try another. The payout stays `processing` while that happens and becomes `failed` only when no route is left.

## How to learn the outcome

* **Webhooks**, for speed. Payve posts an event when a transaction finishes. See [Webhooks](/webhooks/overview.md).
* **A `GET` on the object**, for certainty. `GET /v1/payouts/{id}` returns the current status and a timeline in `events`.

> [!TIP]
>
> Use both. Act on the webhook, and poll with a `GET` for anything still not final after the time
> you expect.

## Filter by status

`GET /v1/payouts?status=failed` returns every payout whose status is `failed`, whatever its sub-status. The same filter works on pay-ins and conversions.

## Other objects

These have their own vocabularies:

| Object | Statuses |
| - | - |
| Refund | `awaiting_recipient`, `awaiting_approval`, `processing`, `succeeded`, `failed`, `rejected` |
| Payment link | `active`, `paid`, `inactive`, `expired` |
| Quote | `active`, `used`, `expired` (in the quote list) |
| Webhook delivery | `pending`, `delivered`, `failed`, `dead` |
| Statement | `pending`, `processing`, `completed`, `failed` |

> [!NOTE]
>
> Webhook payloads report the transaction's detailed internal state in `data.status`, which can be a
> value such as `credited` or `reversed`. Branch on the event `type`, not on `data.status`. See
> [Webhook event object](/webhooks/event-samples.md).
