How a Suward payment reaches finality.
Each payment gets its own address. We watch it block by block as the status climbs Pending → Safe → Finalized, so you release goods only once the money is real.
Five steps, one API.
- 01
Create the payment
Call the API with an amount, asset and network. The request is idempotent, so retrying with the same key returns the existing payment instead of a duplicate. One payment can hold up to 60,000.
- 02
Get a unique address
Suward forges a fresh HD deposit address bound to this one payment. Addresses are never reused, so two payments can't be confused for one.
- 03
The customer pays
Show the hosted checkout with its QR code, address and countdown, or wire your own UI to the same payment. The payer sends the exact asset on the network you chose.
- 04
Suward watches the chain
It spots the incoming transfer and counts confirmations one block at a time, raising the status only as the network agrees.
- 05
Funds settle into your balance
The status climbs Pending → Safe → Finalized. At finality the money lands in your atomic balance, split into safe and accepted. It never goes negative.
Pending, Safe, Finalized — what each means.
Transfer seen, confirmations still accumulating. Don't release goods yet.
Enough confirmations for practical safety on this network's threshold.
Confirmations reached the network's configured finality threshold. Safe to fulfill.
Each network has its own required_confirmations. The threshold is per-chain, not one-size-fits-all, because a fast L2 and a slower chain don't earn trust at the same pace.
Reorg protection: we don't trust early blocks.
A blockchain can briefly rewrite its recent history. That rewrite is a reorg. It can un-confirm a transfer that looked settled. Suward counts a payment as truly done only after it reaches the network's configured finality threshold. Until then the monitor keeps re-checking blocks automatically, all the way up to finality, and an operator can re-verify any block by hand with ReverifyBlock. If a confirmed transfer vanishes in a reorg, the balance is recomputed from on-chain reality. The safe and accepted balances move atomically, so your ledger never reflects money that the chain took back.
Idempotent by design — retries are safe.
Networks drop. Requests time out, and clients retry. Send the same create request again with its idempotency key and you get back the very same payment, not a charge and not a duplicate. That lets you build aggressive retry logic without ever double-counting a payment.
Balances that never lie.
Every credit is atomic. It is stored as Decimal128, so there's no float rounding drift to chase down later. Each balance splits into safe and accepted and can never go negative. When the chain shifts under a reorg, Suward recomputes the balance from on-chain reality, keeping your ledger and the network in agreement.
Today a withdrawal goes through operator review with a fee quote attached. On-chain auto-payout sits on the roadmap, so we won't promise "instant payout" before it ships.
Staying in sync with a payment.
Today you poll the payment status through the API, and that response is the source of truth at any moment. Webhooks (HMAC-signed callbacks) and live SSE events are still in development. They aren't here yet. Until they ship, polling keeps you fully in sync with where a payment stands.