Protocol model
Understand PaymentRef, x402 negotiation, settlement, receipts, and trust boundaries.
The core object is PaymentRef, not the QR code. Rendering and scanning are optional transport concerns; payment behavior is defined by the reference and the x402 exchange.
The four trust domains
| Domain | Trusted for | Never trusted for |
|---|---|---|
| Wallet | User authorization and key custody | Merchant fulfillment or gateway policy |
| Gateway | Ref resolution, validation, relay, signed offers and receipts | Holding user funds or declaring chain finality alone |
| Facilitator | Verification and transaction broadcast | Custodying payer funds |
| Chain | Token transfer, nonce enforcement, and final settlement truth | Merchant order fulfillment |
PaymentRef forms
The recommended gateway reference is short, revocable, and suitable for a QR code:
Textx402pay://x402.example/receive/0xReceiver?ref=ref_abc123
Snapshot references can embed immutable payment data for offline distribution. They cannot be centrally revoked unless the gateway remains part of resolution. Encrypted snapshots are future work.
Stateless by default
The default gateway does not maintain payment lifecycle rows. Chain state and signed receipts are the source of truth. The gateway may store refs, merchant profiles, credential verifiers, idempotency entries, and recovery hints, but merchants keep their own order and fulfillment state.
Order mode is an explicit opt-in. It adds tenant-isolated order state, compare-and-swap transitions, and refund-intent binding without changing the default protocol path.
Current chain scope
EVM USDC with EIP-3009 is the primary settlement path. The payer signs an off-chain authorization, the facilitator pays gas, and USDC moves directly to payTo. Solana/SVM settlement remains future work until its required settlement cache is implemented.