> For the complete documentation index, see [llms.txt](https://docs.paymento.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.paymento.io/api-documentation/payment-states-and-confirmations.md).

# Payment States and Confirmations

### Order states

Every payment carries an `orderStatus`. These are the values your integration will see.

| Status             | Value | Means                                                                             |
| ------------------ | ----- | --------------------------------------------------------------------------------- |
| `Initialize`       | 0     | Payment request created. The customer has not chosen an asset yet.                |
| `Pending`          | 1     | Asset chosen, address issued, waiting for the customer to pay.                    |
| `PartialPaid`      | 2     | Less than the amount owed has arrived.                                            |
| `WaitingToConfirm` | 3     | Enough has arrived, but it is not confirmed yet.                                  |
| `Timeout`          | 4     | The payment window expired with nothing received.                                 |
| `UserCanceled`     | 5     | The customer cancelled at checkout.                                               |
| `Paid`             | 7     | Confirmed on-chain. The money is yours.                                           |
| `Approve`          | 8     | You have verified it. This is the terminal success state.                         |
| `Reject`           | 9     | The address is no longer monitored, or the payment was not verified by the store. |
| `Refunded`         | 10    | Fully refunded to the payer.                                                      |

Value 6 (`Revert`) is reserved and not currently produced.

### The normal path

```
Initialize → Pending → WaitingToConfirm → Paid → Approve
```

`Paid` means Paymento has seen the payment confirm on-chain. `Approve` means you have confirmed it with a server-side verify call — your first successful verify on a `Paid` order moves it there.

**Fulfil on `Paid` confirmed by your own verify call.** Do not fulfil on `WaitingToConfirm`, and do\
not fulfil on anything a browser told you.

### Reading verify responses correctly

The verify endpoint's `success` flag means one thing only: *the order is in `Approve` after this*\
*call*.

`success: false` is **not** an error. A perfectly healthy payment that is two confirmations short\
returns `success: false` with a valid token and `orderStatus: WaitingToConfirm`.

Always branch on `body.orderStatus`. Treating `success: false` as failure is a reliable way to\
cancel orders your customers have paid for.

An actually invalid token — unknown, or belonging to a different store — returns `Invalid Token` with no settlement detail.

### Transaction states

Each on-chain transaction against an order has its own status: `Pending`, `Mempool`, `InBlock`,\
`Completed`, `Revert`, `UnWatch`, `Invalid`. The verify response returns these per transaction,\
alongside the hash, an explorer link, the amount, `confirmations`, `requiredConfirmations`, and detection and confirmation timestamps.

### Confirmations

**Confirmation requirements are set per asset**, because networks differ in how quickly a block becomes hard to reverse.

Never hardcode a number. The verify response gives you `requiredConfirmations` for the asset and `confirmations` for each transaction, so a change on Paymento's side flows straight into your integration.

Solana is finalised on receipt rather than by counting blocks, in line with how that network works. Confirmation fields may be null while a transaction is still in the mempool and has no block height yet — that is expected, not missing data.

### Partial payments

If a customer sends less than the amount owed, the order becomes `PartialPaid` and the checkout page shows the exact remainder with a fresh QR code for it.

**Unconfirmed money still counts toward what the customer owes.** A transaction that is in the mempool or in a block, but not yet fully confirmed, is subtracted from the remainder. This is deliberate: a payer who has already broadcast a transaction has parted with the money, and asking for it again would produce a duplicate payment.

Settlement is a stricter matter — funds are only treated as settleable once confirmed. So there is a window in which the customer correctly owes nothing more while the order is not yet `Paid`. That window is `WaitingToConfirm`.

Your options on a `PartialPaid` order: wait for the balance, refund what arrived, or accept the shortfall and fulfil anyway. Paymento does not decide this for you.

### Underpayment tolerance

Small shortfalls happen — wallets that deduct their own fee from the amount sent, rounding, a customer typing an approximation.

You can set an **underpayment tolerance** per store, from **0% to 5%**. With a tolerance set, an\
order is accepted as paid at or above (100 − tolerance)% of the expected amount. Zero, the default, requires the exact amount.

Set it in the store's general settings in the merchant panel.

### Overpayment

If a customer sends more than the amount owed, the order is marked `Paid`. The full amount received is recorded on the order, and the excess sits at the receiving address along with the rest — it is yours, and it settles with everything else.

Paymento does not automatically refund the difference. If you want to return it, issue a refund for the excess.

### Timeouts

Once a customer chooses an asset, a payment window opens — configured per asset, and typically an hour. The separate payment **token** has its own lifetime that you control per store: 24 hours by default, adjustable from 5 minutes to 7 days.

**Only orders still in `Pending` are timed out.** An order that has already received something —\
`PartialPaid` or `WaitingToConfirm` — is not timed out from under the customer.

### Late payments

If a customer pays after an order has already timed out, contact support with the transaction hash. Do not assume the payment is lost, and do not fulfil until it has been resolved.

### Settled states are final

Once an order reaches `Paid`, `Approve`, `Reject` or `Refunded`, later chain activity does not move it backwards, and a paid notification is not sent again. Refunded orders in particular are removed from payment progression entirely.

This is why your IPN handler should be idempotent but need not handle a payment "un-paying" itself.