Guides

Payment statuses

A v2 payment moves through a four-state machine. Use this reference when reading payment.status from a create call, a read, or a polling loop.

pending — The invoice has been issued by the merchant's wallet and is waiting to be paid. Trevi-issued invoices are payable for 15 minutes.

paid — Terminal. The customer's payment settled on the merchant's wallet. This is the only status you should treat as paid; fulfil the order. It also triggers the order.confirmed webhook and the cashback decision.

expired — The invoice lapsed before it was paid. Create a new payment (with a NEW external_order_id) if the customer still wants to check out.

failed — Terminal. A rails-level failure. Rare; surface a retry to the customer.

Settlement is decided by the wallet's own settled_at, never by a status field Trevi guessed at. Trevi's expiry is bookkeeping, not the wallet's ruling: it keeps asking about an invoice for 5 minutes past expiry, and a payment that lands in that grace window still becomes paid. That is why expired is not quite terminal — a late settlement is still a real sale on the merchant's wallet and is honoured as one.

There is no partial or confirming state. Trevi v2 settles over Lightning, where a payment either arrives in full or does not arrive.