WalletConnect Pay — Headless SDK Integration

What this is

WalletConnect Pay lets an app accept stablecoin payments from any WalletConnect-compatible wallet. The Headless SDK is the set of framework-agnostic npm packages (@walletconnect/pay-*) that run the payment flow — loading the payment, connecting a wallet, quoting, signing, and settling — without imposing any UI. You render the screens; the SDK runs the machine.

It is the same runtime that powers WalletConnect's own hosted checkout ("Buyer Experience"), extracted so you can build a fully branded checkout on the same engine.

This skill teaches the SDK contract, not a prescribed app structure. The code here shows how to call the SDK correctly. How you route requests, lay out files, and structure your UI is yours — treat the example scaffolding as one illustration, not a required shape. For a complete, opinionated build, see the reference example and the official docs.

When to use

• Building a self-hosted, branded stablecoin checkout inside your own product and domain
• Embedding pay-with-crypto into an existing checkout flow instead of redirecting to a WalletConnect-hosted page
• Wiring the server proxy that keeps the Engine API key off the browser
• Rendering the payment lifecycle (load → connect → quote → sign → confirm → settle) from a snapshot
• Troubleshooting the four SDK packages (see [The four packages](#the-four-packages) below)

Not this skill: if you only want to create a payment request (a link/QR) or poll its status as a merchant, or you're adding WC Pay acceptance to a wallet app, this is the wrong integration — those are separate products. If you just want the fastest path with no UI to build, use WalletConnect's hosted gateway instead.

The mental model: headless runtime + host

The payment flow lives entirely in the SDK. Your app is the host that consumes it. The runtime only touches the outside world through five injectable seams — swappable adapters — so you can supply your own transport, wallet, timing, and analytics and reuse the exact same payment machine.

In practice you wire only the first three; browserClock and noopTelemetry are the shipped defaults.

AppKit = Reown AppKit, the wallet-connection library. @walletconnect/pay-appkit wraps it so you get EVM + Solana wallet connection, a wallet picker, and a signer without touching @reown/*, wagmi, or viem yourself. If you already have your own wallet connector, you can skip AppKit and implement the WalletProvider seam directly ([custom-wallet.md](references/custom-wallet.md)).

The four packages

Layered; lower packages never import higher ones, so you take only what you need. Full API surface and current signatures live in the packages reference — treat that public page as the source of truth (this is a beta API, v0.1.x, and signatures can change between minor releases).

Canonical docs — the source of truth

This skill intentionally carries only the stable contract (below) and defers everything version-sensitive — exhaustive API signatures, full walkthrough code, the current package surface — to the docs, which are kept current with each release. When in doubt, or when something here disagrees with your installed types, trust the docs and the reference example, not this skill:

• Overview — https://docs.walletconnect.com/payments/psps/headless-sdk/overview
• How it works (seams, lifecycle) — https://docs.walletconnect.com/payments/psps/headless-sdk/how-it-works
• Implementation (full walkthrough) — https://docs.walletconnect.com/payments/psps/headless-sdk/implementation
• Packages reference (full API) — https://docs.walletconnect.com/payments/psps/headless-sdk/packages-reference
• Reference example — https://github.com/WalletConnect/walletconnect-pay-examples/tree/main/gateway/headless-checkout

Choose your path

Every path needs the server proxy → [server-proxy.md](references/server-proxy.md). Each reference gives the durable shape; for the complete, current code, follow it to the docs page above.

Prerequisites

1. Node 18+.
2. A Reown Project ID — from dashboard.reown.com, with the headless feature enabled. Used for wallet connection / QR pairing. Public (client-side).
3. A WalletConnect Pay Gateway API key — server-side only. Talk to WalletConnect to get onboarded.

Install

npm install @walletconnect/pay-core @walletconnect/pay-state \
            @walletconnect/pay-appkit @walletconnect/pay-react

Wallet connectivity (@reown/appkit, wagmi, viem, @solana/web3.js) comes transitively through @walletconnect/pay-appkit — you don't add it directly. Omit @walletconnect/pay-react if you're not using React.

The payment lifecycle

Whatever UI you build, the runtime moves a payment through the same stages. You render each stage and call the matching action:

Load payment → Connect wallet → Fetch options → Select & build → Sign → Confirm & settle

The SDK drives all transitions. You never advance it manually — you read snapshot.state and call one of the named actions in response to user input.

The snapshot is the whole UI contract

snapshot.state is one of 17 values (the exact PaymentState union from @walletconnect/pay-state). Render per state, call the matching action:

Group the five terminal failures — Failed, PaymentExpired, PaymentCancelled, InvalidPayment, SanctionedUser — with the exported helper isFailureState(state). Succeeded is terminal but not a failure.

Snapshot fields you'll read

interface PaymentSnapshot {
  state: PaymentState                    // one of the 17 above (always present)
  payment?: GetPaymentResponse           // intent: amount, merchant, tokens (once loaded)
  options: PaymentOptionExtended[]       // payable options (always present; empty when none)
  selectedOption?: PaymentOptionExtended // the picked option (has .actions)
  collectData?: CollectData | null       // Engine's KYC/contact REQUIREMENTS (.fields)
  infoCaptureData?: InfoCaptureData      // what the user SUBMITTED
  wallet: { isConnected: boolean; accounts: string[] } // flat across all namespaces
  requiresApproval: boolean              // true iff state === 'RequiresApproval'
  signingError?: { code; message; details? } // set only on a non-rejection signing failure
  isQuoteExpired?: boolean
  lastEngineErrorCode?: string           // DIAGNOSTIC ONLY — never present as "why it failed"
  profileId?: string
  profileNotFound?: boolean
}

Named actions

Both usePaymentSession (React) and createPaymentController (JS) expose the same domain actions. There is no raw send/actor on the surface — you drive the machine only through these:

(There's also a rarely-needed host-orchestration channel — refreshOptions, notifyQuoteExpired, markUserSanctioned, … — for signals the runtime can't observe itself. Most integrations don't need it to start.)

The one hard rule: the API key stays server-side

The WalletConnect Pay Engine is authenticated with a secret API key that must never reach the browser. pay-core enforces this with two entry points: a browser-safe main entry (createHttpTransport, no key) and a server-only @walletconnect/pay-core/server entry (createEngineClient, holds the key). The browser talks to your server; your server talks to the Engine. That server proxy is the one piece of backend you must build — see [server-proxy.md](references/server-proxy.md).

Validation checklist

• The Engine API key is read from server env only — never in client code or a NEXTPUBLIC / VITE_ var
• The browser transport baseUrl matches wherever your proxy is mounted
• Your proxy exposes all five Engine calls (getPayment, getPaymentOptions, fetchOptionActions, confirmPayment, getPaymentStatus)
• The proxy has origin allowlist / rate limiting / auth before production
• All 17 snapshot.state values are handled (group the 5 failures via isFailureState)
• snapshot.requiresApproval toggles the confirm CTA ("Approve & pay" vs "Confirm")
• The KYC form is built from snapshot.collectData.fields, not hardcoded
• The Reown project has the headless feature enabled

Common errors