Settlement & finality
Accepted means the payment has accumulated enough network confirmations to act on. Success means the payment is irreversible and the funds are available to withdraw.
Two stages
Accepted means the payment has accumulated enough network confirmations to act on — ship, credit, deliver. Success means the payment is irreversible and the funds are available to withdraw. The thresholds behind each stage are calibrated per network: proof-of-stake chains use safety checkpoints, proof-of-work chains use confirmation depth. Your integration reads stages, not raw confirmation counts — but the per-network requirements are public: GET /v1/blockchains returns requiredConfirmations for every supported chain.
Detected
A transfer is seen on-chain. Nothing is credited.
Accepted
Safe confirmations reached. Credited to the accepted bucket. Act on it.
Success
Irreversible. Moved to the safe bucket. Withdrawable.
Invalidated
Rolled back before acceptance. A reorg undid the transfer; nothing was credited.
curl https://api.suward.com/v1/blockchainsReorganizations
Blockchains can rewrite recent history. Suward handles this while a payment is still confirming: no payment is credited on a single block confirmation, and if a reorganization occurs, affected payments are re-verified automatically against the new state of the chain. Cases the chain leaves genuinely ambiguous are routed to operator review. All of it happens before the payment reaches Accepted — the stage is the end of verification, not the middle of it.
Static-wallet deposits follow the same rule with the deposit's own vocabulary: a deposit undone by a reorganization before acceptance is recorded as invalidated and nothing is credited. → Deposit lifecycle
Atomic balances
A payment's stage change and the corresponding balance change happen as one operation or not at all. Your project balance is reported in two buckets — accepted (credited, not yet final) and safe (final, withdrawable) — and every movement in either bucket is attributable to a specific payment or deposit at a specific stage. Neither bucket can go negative, and there is no window where a webhook says one thing and the balance says another.
| Bucket | Filled at | What you may do with it |
|---|---|---|
| accepted | payment.accepted · static_deposit.accepted | Fulfil the order, credit the user, deliver the goods. Not withdrawable. |
| safe | payment.success · static_deposit.success | Withdraw, sweep with an auto-withdrawal rule, treat as money. |
What this means for your code
- Fulfill orders and credit users on
payment.accepted/static_deposit.accepted. - Release withdrawals and treat money as final on
payment.success/static_deposit.success. - Never fulfill on your own mempool watching or a single confirmation — you'd be taking the reorg risk Suward exists to absorb.
Accepted is for goods, Success is for money
Accepted is safe enough to release goods and far too early to release money. If your product does both — a marketplace paying out a seller, an exchange allowing a withdrawal — gate the money side on Success.
Next: what each stage costs you → Fees & who pays what.
Something unclear? payments@suward.com — we treat every integration question as a documentation defect.