Payment Reconciliation and Edge Cases

Start with the Payment Status Lifecycle for the canonical status reference. This guide covers the reconciliation cases that need additional business rules in your integration.

Use the lifecycle status together with amount_sats, received_sats, expires_at, and your own order state. Underpayment and overpayment are reconciliation outcomes, not additional Manatee statuses.

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.