Status Model

Every Manatee payment has a lifecycle status. Your backend should use this status together with received amounts and webhook events to update checkout and order state.

Payment statuses

Status	Meaning	Typical action
pending	No matching Bitcoin transaction has been detected yet.	Show payment instructions and wait.
detected	A matching transaction was seen, but confirmations are below the required threshold.	Show "payment seen" and keep waiting.
confirmed	The transaction reached required_confirmations.	Mark the order as paid.
expired	The payment expired before a matching transaction was detected.	Close or recreate the checkout session.
cancelled	Your backend cancelled a still-pending payment.	Stop showing this payment to the customer.

Missing confirmations

If a payment is detected but not confirmed, the transaction has not reached the configured required_confirmations.

Typical causes:

• The transaction is still waiting for blocks.
• The configured confirmation threshold is higher than expected.
• Your UI is treating payment.detected as final settlement.

Use payment.detected as an early signal and payment.confirmed for fulfillment in most production flows.

Payment expired

Only pending payments expire automatically. If a matching transaction was detected before expires_at, Manatee keeps tracking confirmations instead of changing the payment to expired.

If a checkout expires:

• Stop showing that payment to the customer.
• Create a new payment if the customer still wants to pay.
• Do not reuse stale amounts if your price was based on a fiat-to-BTC quote.

Underpayment and overpayment

underpaid and overpaid are not separate Manatee lifecycle statuses. They are reconciliation cases your integration can derive from amount fields.

Case	Signal	Typical action
Underpayment	received_sats is below amount_sats or below your configured tolerance.	Wait, expire, or flag for manual review depending on your policy.
Overpayment	received_sats is above amount_sats.	Mark paid if policy allows, then handle the difference through your own refund or support process.

Manatee does not move funds or send refunds. Refunds, store credit, and manual review remain your business process.

For the compact status reference, see Payment Status Lifecycle.