Reorg protection: finality you can trust
A block can be re-mined and reverted, taking a "settled" transfer with it. Suward never credits on a single block. Every payment moves Pending → Safe → Finalized, held until the configured finality threshold, with automatic and manual re-verification behind it.
What a reorg is
Picture two miners finding a block at almost the same height. For a moment the chain has two tips. The network keeps the longer branch, drops the other, and any transaction that lived only on the dropped branch simply disappears as if it had never happened. That is a reorg. A naive listener credits the merchant the instant it sees the transfer, then never walks it back when the block vanishes, and the merchant is left short the money. It's a real risk on public chains. It's the one Suward takes off your plate.
Pending → Safe → Finalized
One transfer, three states. Suward only counts a payment as truly done at the last one.
- Pending
Pending. The transfer is in a block, but the block is young and confirmations are still stacking up. A reorg here is plausible, so nothing is credited. Hold the goods.
- Safe
Safe. Enough confirmations have stacked that a reversal is unlikely against this chain's threshold. Practically safe, not yet final.
- Finalized
Finalized. The chain's configured finality threshold is met and the transfer is part of settled history. Ship the order.
Two dials sit behind this, not one. A per-chain required_confirmations counts how many blocks must stack on top. The monitor's safe and finalized offsets decide where Safe and Finalized fall. Together they draw the line you can ship against.
Automatic re-verification
The monitor watches the head of each chain. When blocks get rebuilt near the tip, it recomputes the affected statuses on its own, all the way up to Finalized, no operator needed. A payment reaches your balance only after it clears the finality level. That credit lands atomically as Decimal128 and never drops below zero. The work happens whether or not you are watching.
Manual ReverifyBlock
For the rare edge case, an operator can force a recheck. ReverifyBlock(blockchain_id, number, head_number) recomputes Pending, Safe, and Finalized for one block; pass head_number=0 to keep it as Pending. It's a backstop, not a substitute for the automatic logic. Underneath, an outbox carries the status events from the monitor to cryptopay so a service failure can't drop them.
Confirmations by network
The required_confirmations value is set per chain. Here is what each one waits for.
| Network | required_confirmations |
|---|---|
 Ethereum | 12 |
 Arbitrum | 12 |
 Optimism | 12 |
 Base | 12 |
 BSC | 15 |
 Polygon | 128 |
PlaPlasmaSoon | 12 |
Polygon waits 128 confirmations on purpose: it has a history of frequent reorgs, so it earns trust more slowly than the rest. Plasma is still marked Soon while a chainID issue is fixed. Per-chain detail lives on each network page.
Track status via API
You follow a payment by polling GET /v1/payments/{paymentId}. The response carries a PaymentStatusEnum (pending, accepted, success, failed) and a finer PaymentSubStatusEnum (confirming, acceptedCompleted, acceptedOverpaid, acceptedUnderpaid). That poll is the source of truth at any moment, because there are no merchant webhooks yet. When they ship, they'll be marked Soon first.
Two things worth knowing up front. ERC-20 detection reads the transfer() calldata only, which means it won't pick up a transferFrom or a multi-send, so the rule of thumb is to have payers send a plain transfer to the unique address and everything lines up. There are no webhooks yet either. Status comes from the poll above. These are engineering facts, not marketing ones.
Reorg FAQ
When the status reads Finalized, meaning the chain's configured finality threshold is met. Before that it sits at Pending or Safe, and the money has not reached your balance.
Safe means a reversal is unlikely, not impossible. That's exactly why it isn't Finalized. If a reorg does hit, the monitor recomputes the status automatically up to finality, and the balance is recomputed from on-chain reality. Wait for Finalized when you can.
It tracks the confirmation count, not a clock. Ethereum waits 12 confirmations, Polygon 128, so Polygon takes noticeably longer by design. Each network page lists its own number.