A blockchain transaction can look successful for a moment and then disappear — a "reorganization," where the network settles on a different version of recent history. If a platform marks a payment as paid the instant it sees a transaction, a reorg can leave it having promised money that never actually arrived.
What we wait for
Once a payment transaction is detected, it sits in a confirming state. Our watcher waits for a configurable number of block confirmations (5 on our test network) before doing anything final. Even then, we don't just trust the count — we re-check that the transaction's block hash and event details still match what we originally saw, immediately before marking the payment paid.
Only after that re-check passes do we, in a single database transaction, mark the payment succeeded, write the ledger entries, and queue the webhook that tells the merchant's server the payment is done. All three happen together, so a crash between steps can't leave a payment marked paid without a matching ledger entry, or vice versa.
What happens if a reorg does happen
If the transaction disappears from the canonical chain after we already flagged it as "receipt missing," we wait a grace period for it to reappear (the network catching up, or an RPC provider being temporarily behind). If it doesn't come back within that window, the payment is marked failed, and — critically — nothing is booked to the ledger for it. No money was promised that didn't arrive.
Why this matters for a merchant
It means "payment succeeded" is a claim we can actually stand behind, not an optimistic guess based on the first thing we saw. It also means a merchant fulfilling an order on our succeeded webhook is fulfilling against money that has already, genuinely, reached their wallet — not money that's still probabilistically at risk of vanishing.