The payment lifecycle
Whatever UI you build, the runtime moves a payment through the same stages. Your job is to render each stage and call the matching action.Load the payment
The buyer arrives with a payment ID (from a QR code, link, or your checkout). The runtime fetches the payment intent — amount, merchant, accepted tokens.
Connect a wallet
The buyer connects a wallet through the
WalletProvider seam. The runtime reads their accounts across the supported networks.Fetch payment options
Given the connected accounts, the Engine returns the concrete ways to pay — token, network, amount, fees, and whether compliance data is required.
Select & build
The buyer picks an option. The runtime builds the transaction(s) and the exact wallet-RPC actions to sign.
How it fits together
The Headless SDK follows a headless runtime + host model. The payment flow lives entirely in the SDK; your application is the host that consumes it. The runtime reaches the outside world only through five injectable seams — so you can swap in your own transport, wallet, timing, and analytics, and reuse the exact same payment machine. The five seams the runtime depends on:| Seam | What it abstracts | Provided by |
|---|---|---|
Transport | Engine HTTP calls | pay-core createHttpTransport → your server route |
WalletProvider | connect / accounts / provider / switch | pay-appkit, or your own wallet integration |
Signer | sign a payment option’s wallet-RPC actions | pay-state signing strategies over the wallet seam |
Clock | intervals + page visibility (for polling) | browser timers (the SDK ships a default) |
Telemetry | analytics breadcrumbs | your analytics pipeline (optional) |
@walletconnect/pay-state ships browser-ready Clock and Telemetry defaults (browserClock, noopTelemetry). In practice a React/Next.js gateway wires three seams itself — a Transport (pointed at your server route), a WalletProvider (the AppKit adapter), and a Signer (built from the wallet) — and reuses browserClock for the rest. Telemetry is optional.The Engine API key never reaches the browser
WalletConnect Pay’s Engine API is authenticated with a secret API key that must stay server-side. The SDK enforces this split: the browser talks to your server, and your server talks to the Engine.pay-core exposes two entry points for exactly this: createHttpTransport for the browser (talks to your server) and createEngineClient (imported from @walletconnect/pay-core/server) which holds the API key and talks to the Engine. In a Next.js app, your Route Handler sits in the middle.
Next steps
Implementation
Build a complete checkout in React / Next.js, step by step.
Packages Reference
The public API of pay-core, pay-state, pay-react, and pay-appkit.