Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.clear-box.io/llms.txt

Use this file to discover all available pages before exploring further.

This is the moment everything else leads to: a verified user with a funded, card-backed wallet taps to pay, and ClearBox settles the transaction faster than the underlying blockchain could confirm. It corresponds to the tap-to-pay settlement sequence your team works from.

​
Flow at a glance

1

User taps to pay

The user taps their phone at a checkout terminal — for example, a $15.00 coffee.
2

Network routes the authorization

The merchant POS and card network route an authorization request to ClearBox.
3

Mirror ledger validates the balance

ClearBox validates the wallet’s available balance against the amount and places a hold.
4

Approve in real time

ClearBox returns an approval (≈0.2s) and the terminal completes the sale.
5

Settle on-chain in the background

ClearBox burns the equivalent stablecoin from the wallet and reconciles on-chain after the customer has left.

​
Real-time authorization

When the authorization request reaches ClearBox, it does not wait for the blockchain. It checks the mirror ledger — a continuously reconciled view of the wallet’s available balance — and answers the network’s question: “does this card have $15.00 available?” If the balance covers the amount, ClearBox places a hold for $15.00 and returns an approval. The terminal shows success and the customer walks away. This typically completes in around 0.2 seconds, which avoids the multi-minute wait that on-chain confirmation would require at the counter.

​
Asynchronous settlement

After approval, ClearBox settles the underlying value:
  • An async webhook records that the card was charged $15.00.
  • ClearBox burns the equivalent stablecoin from the smart-contract wallet.
  • The on-chain settlement is reconciled against the mirror ledger.
  • The app balance updates (for example, from 100.00to100.00 to 85.00).
Because the wallet is non-custodial, the on-chain settlement is the authoritative record. The mirror ledger is the accelerated view that makes the counter experience instant.

​
Handling declines

If the mirror balance does not cover the amount, ClearBox declines the authorization and the terminal shows a decline — exactly as a fiat card would. No hold is placed and no stablecoin is burned.

​
Observability

Subscribe to settlement webhooks to keep your systems in sync:
EventWhen it fires
transaction.authorizedAn authorization was approved and a hold placed.
transaction.declinedAn authorization was declined.
transaction.settledThe on-chain settlement completed.
See Webhook event types for payloads.

​
Reference