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 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.

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.

Webhook events

Manatee sends webhook events when a transaction is detected and when it reaches the confirmation threshold:

• payment.detected
• payment.confirmed

Use payment.confirmed for fulfillment. Treat payment.detected as an early signal that a transaction exists but is not final enough for most production flows.