Transaction Lifecycle
Every card payment travels the same path, from the terminal to on-chain settlement. Understanding this lifecycle helps you build accurate balance displays and transaction feeds.
This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: API v2 replaces it, and the platform today works as described in the rest of this manual.
Stages
Authorization → Clearing → Settlement (on-chain)
1. Authorization
The cardholder taps or enters the card. Visa routes the authorization request to Web3Card, which checks in real time:
- Card status is
active - Amount is within the card's daily limit
- The vault balance covers the amount
If all checks pass, the amount is put on hold and the merchant receives approval, typically in under a second. The transaction appears with status pending.
2. Clearing
The merchant submits the final capture (usually within hours, up to a few days for hotels and similar). The captured amount replaces the hold; small differences (tips, currency adjustments) are normal.
3. Settlement
The captured amount is settled from the user's vault: the settlement operator co-signs a transfer out of the vault, and funds flow to the issuing bank as standard Visa settlement. The transaction status becomes settled, and the on-chain transfer hash is attached to the transaction record.
Transaction statuses
| Status | Meaning |
|---|---|
pending | Authorized, amount on hold |
settled | Cleared and settled on-chain |
declined | Authorization refused (limit, balance, card status) |
reversed | Authorization released without capture |
refunded | Merchant refund credited back to the vault |
disputed | Chargeback in progress |
Refunds and disputes
Refunds arrive as separate credit transactions to the vault. Disputes can be opened through the API within 60 days of settlement; see Transactions API.
Real-time events
Every status change emits a webhook (transaction.created, transaction.updated), so your app can show payment activity live. See Webhooks.