Guides

Payment statuses

Every payment moves through a small finite-state machine. Use this reference when reading payment.status on responses, webhooks, or polling loops.

pending — Waiting for the customer to pay. The invoice/address has been created and is live until the expiration window elapses.

partial — On-chain only: 50–79% of the requested amount has been received. The payment has not cleared yet; do not fulfil the order.

confirming — On-chain only: the network has seen the payment but it has not reached the required confirmation depth. Lightning skips this state because settlement is instant.

completed — Terminal. Payment confirmed in full — fulfil the order. This is the only status you should treat as paid.

expired — Terminal. The expiration window elapsed before the customer paid (or paid enough). The invoice cannot be revived; create a new payment if the customer still wants to check out.

failed — Terminal. Something went wrong on the rails (e.g. routing failure on Lightning, malformed invoice). Rare; surface a retry to the customer.

Terminal statuses are completed, expired, and failed. Polling loops should stop on any of these. Webhooks are sent for every transition, including transitional ones.