How it works

Before you install anything, it helps to understand the shape of the SDK: the stages a payment moves through, how the runtime plugs into your app, and why your Engine API key never reaches the browser.

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.

1. 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.

2. Connect a wallet

   The buyer connects a wallet through the WalletProvider seam. The runtime reads their accounts across the supported networks.

3. 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.

4. Select & build

   The buyer picks an option. The runtime builds the transaction(s) and the exact wallet-RPC actions to sign.

5. Sign

   The Signer drives the wallet through the required signatures (e.g. a permit + the payment).

6. Confirm & settle

   Signed results are submitted to confirm the payment. The runtime then polls status until the payment succeeds, fails, or expires.

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-appkit createAppKitSigner — one call (wraps pay-state’s signing; drop to its raw strategies only for a custom, non-AppKit wallet)
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 just the Transport (pointed at your server route); the WalletProvider and Signer come ready-made from pay-appkit (<PayAppKitProvider> + createAppKitSigner), and it 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.