Payment Status Lifecycle

Every Manatee payment has a lifecycle status. Your backend should treat the status as the source of truth for checkout, fulfillment, and reconciliation decisions.

Statuses

Status	Meaning	Typical action
pending	No matching on-chain transaction has been detected yet.	Show payment instructions and wait.
detected	A matching transaction was seen, but confirmations are below the required threshold. It is not final settlement.	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.

Confirmation policy

required_confirmations controls when Manatee moves a payment to confirmed. Lower values are faster and higher values reduce settlement risk.

For testnet and low-risk test flows, 1 confirmation is often enough. For production, choose the threshold based on order value, fulfillment speed, and your risk policy.

Expiry behavior

Only pending payments expire automatically. If a matching transaction is already detected before expires_at, Manatee keeps tracking confirmations instead of changing the payment to expired. A payment received only after expiry remains expired for fulfillment safety and is retained for reconciliation.

Webhook events

Manatee sends webhook events when a transaction is detected, confirmed, or a still-pending payment expires:

• payment.detected
• payment.confirmed
• payment.expired

Use payment.confirmed for fulfillment. Treat payment.detected only as an early signal: an unconfirmed transaction can still be dropped, replaced, conflicted, or affected by a chain reorganisation. Use payment.expired to close stale checkout instructions without marking the order paid.