SatLane
Skip to documentation
Browse documentation
On this page

Payment lifecycle

StatusMeaningTerminal?
pendingNo payment seen yetno
seenPayment detected but not yet settled. Expiry alone does not mark it unpaid; stale unconfirmed payments can move to review.no
paidPayment confirmed (≥ conf_threshold) and amount within amount_sats ± amount_tolerance_satsno (can become reverted via reorg)
expiredpending past expires_at with no detected paymentno; address still watched through the grace window for a possible late_paid
late_paidConfirmed payment arrived after expires_at but inside the supported late-payment flowno (can become reverted)
underpaidConfirmed amount is less than amount_sats − amount_tolerance_sats. Buyer can top up; we auto-merge.no
overpaidConfirmed cumulative amount exceeds amount_sats + amount_tolerance_satsno; you may want to refund the difference
requires_reviewRouting landed on "no-match" (payment to a recycled address with no matching invoice), or cross-check disagreed. Manual admin action.no
revertedPreviously paid, then a chain reorg removed the txyes
cancelledVendor cancelled before paymentyes

Top-up payments (short-pay recovery)

If the customer sends less than the expected amount, they can send the remaining balance to the same invoice address. Do not create a second order or a fresh invoice merely to collect the shortfall.

  1. SatLane adds distinct transaction outputs assigned to that invoice. Duplicate detections do not increase the total, and reversed outputs are excluded.
  2. Split payments combine even when the first payment is still unconfirmed. amount_paid_sats is the received total; it is not proof that every payment has confirmed.
  3. A final outcome waits until every output included in the cumulative total reaches conf_threshold. A later confirmed top-up cannot confirm an earlier mempool payment.
  4. Within tolerance, the invoice becomes paid, or late_paid if completion is after expiry. A smaller total remains underpaid; a larger confirmed total becomes overpaid.

For example, an invoice expects 100,000 sats. The customer sends 60,000, then 40,000. The received total is 100,000, but fulfillment waits for the final paid event. If the 40,000 confirms first, the earlier 60,000 must still confirm.

Hosted checkout asks for only the remaining amount. Once the full balance is received, it hides payment controls and says to wait for confirmation. In a custom checkout, use payment_phase and the remaining amount to show the same behavior. Never ask for another full payment because confirmations are pending.

Webhook handling: events describe status changes, not every top-up. An additional short payment that leaves the status unchanged does not necessarily emit another invoice.underpaid event. Delivery retries reuse the event ID. Deduplicate by event_id, then make fulfillment idempotent at the order level so distinct events cannot ship the same order twice.

Late, excess and reversed payments

  • A late payment observed by the watcher may settle as late_paid, including through a supported recovery path. The grace deadline is not a guarantee that later Bitcoin is ignored or refunded. Check the current invoice and apply your policy for an order that has already expired.
  • overpaid means the customer sent excess Bitcoin. SatLane does not automatically refund it. Review the invoice and decide whether to fulfill and return the difference using your wallet.
  • requires_review is not an instruction to fulfill. Ambiguous address routing or failed chain cross-checks need review.
  • reverted means a previously accepted payment lost its on-chain basis. Reconcile the order and notify the merchant. Do not automatically fulfill again or refund without reviewing the current state.

Fulfillment checklist

Only treat invoice.paid or invoice.late_paid as automatic payment completion after verifying the signature and reconciling the expected order, amount, currency and environment. Browser redirects, SSE updates, seen, a zero remaining amount, and a received total alone are not authorization to fulfill.