Payment lifecycle

pending → detected → paid
   │         │
   ├─────────┴→ failed (invalid match)
   └──────────→ expired (window closed)

State	When it occurs	Fulfil?
`pending`	The checkout exists and awaits a matching transfer.	No
`detected`	A transfer matches enough rules, but confirmation is incomplete.	No
`paid`	The confirmation threshold is met and the payment is recorded.	Yes, exactly once
`failed`	The matcher rejected an invalid amount, currency, network, or other mismatch.	No
`expired`	The checkout's time-to-live, or its detected-payment grace period, elapsed.	No — investigate a late transfer separately
`deactivated`	A merchant or operator deactivated the checkout.	No

The status machine also tracks internal payment-intent states — awaiting_payment, detected, confirmed, mismatched, expired — that are not a promise every internal value appears in the public API. See schemas for exactly what each API surface returns.

Underpayment and overpayment

The matcher has explicit amount-mismatch handling, including a configurable tolerance for a slight overpayment. There is no merchant-facing automatic refund or remediation workflow — investigate a mismatch manually using the checkout reference and transaction hash.

Confirmations and finality — why detected is not paid.
Transactions — the merchant-facing view of this same lifecycle.
Handle an expired checkout — recovering from the expired terminal state.

Payment lifecycle

Related documentation

On this page