selects payment option,
and signs the transaction alt Payment succeeds BX->>MF: Redirect to successUrl?payment_id={paymentId} else Payment fails BX->>MF: Redirect to errorUrl?payment_id={paymentId} end MF->>MB: Verify payment status MB->>API: GET /v1/merchant/payment/{paymentId}/status API-->>MB: { status: "succeeded" } MB-->>MF: Order confirmed MF->>B: Show order confirmation ``` ## Integration Steps
Logos and brands shown are for illustrative purposes only and do not imply affiliation or endorsement.
### Buyer checkout On the WalletConnect Pay buyer checkout page (opened when a buyer scans the payment QR with a generic camera or QR scanner), the merchant logo anchors the "Pay X to \Logos and brands shown are for illustrative purposes only and do not imply affiliation or endorsement.
Because the logo renders inside different container shapes across surfaces (square cards on web, rounded squares in wallets), the asset needs to work across all of them. The specification below is designed for that. ## Specification | Field | Value | | ---------------------- | --------------------------- | | Aspect ratio | 1:1 (square), ±5% tolerance | | Minimum dimensions | 500 × 500 px | | Recommended dimensions | 1024 × 1024 px | | Maximum dimensions | 4096 × 4096 px | | Accepted formats | JPEG, PNG, WebP, AVIF | | Max file size | 2 MB | | Transparency | Allowed in PNG and WebP | ### Format guidance * **PNG** or **WebP** for logos with transparent backgrounds. * **JPEG** for flat photographic logos with no transparency. * **AVIF** if your asset pipeline already produces it; otherwise prefer PNG. * **1024 × 1024 px** is the recommended size: it gives retina headroom across surfaces while staying well under the 2 MB cap. ### Why square Logos render inside square and rounded-square containers across surfaces. Non-square images get center-cropped, and the result is unpredictable: a tall rectangle that looks fine in one wallet may have its bottom half clipped in another. Square assets with the ±5% tolerance render consistently everywhere. Create a merchant with a logo hosted on your own CDN: ```http theme={null} POST /v1/merchants HTTP/1.1 Host: api.pay.walletconnect.com Authorization: Beareryour UI, branding, routing"] React["@walletconnect/pay-react
usePaymentSession"] State["@walletconnect/pay-state
payment runtime"] Host -->|consumes| React React -->|drives| State State -->|reaches the outside world
only through seams| Seams subgraph Seams["Injectable seams"] direction LR Transport["Transport"] Wallet["WalletProvider"] Signer["Signer"] Clock["Clock"] Telemetry["Telemetry"] end Transport --> T2["your server → Engine API"] Wallet --> W2["AppKit / your wallet"] Signer --> S2["signing strategy"] Clock --> C2["timers / polling"] Telemetry --> A2["analytics"] ``` 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) |
Transport seam
(no secret)"] Server["Your server route
createEngineClient
(holds the API key)"] Engine["WalletConnect Pay
Engine API"] Browser -->|"fetch /api/wcp/payment/:id/*"| Server Server -->|"Api-Key header"| 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
{/* render per snapshot.state — see Step 5 */}
}
```
```typescript JavaScript — main.ts theme={null}
import { createHttpTransport } from '@walletconnect/pay-core'
import { createAppKitSigner, createAppKitWalletList } from '@walletconnect/pay-appkit'
import { browserClock, createPaymentController } from '@walletconnect/pay-state'
import { appKit } from './appkit'
// The framework-neutral wallet-list controller: list / search / paginate / QR URI /
// connect — and `walletList.wallet`, the seam the runtime drives.
const walletList = createAppKitWalletList(appKit, {
wcPayUrl: window.location.href
})
const wallet = walletList.wallet
const controller = createPaymentController({
paymentId,
wallet,
seams: {
transport: createHttpTransport({ baseUrl: '/api/wcp' }),
clock: browserClock,
signer: createAppKitSigner(wallet)
}
})
controller.subscribe(() => render(controller.getSnapshot()))
controller.start()
```
| Package | Role | Depends on |
|---|---|---|
@walletconnect/pay-core
|
Engine API client — contract types, CAIP utilities, the browser Transport seam (createHttpTransport), and the server-side createEngineClient that holds your API key. The foundation. |
— |
@walletconnect/pay-state
|
The headless runtime — the payment state machine, orchestration, the injectable seam contracts, the session factory, and the public PaymentSnapshot view-model. No React, no HTTP client, no wallet SDK. |
pay-core |
@walletconnect/pay-react
|
Thin React binding — usePaymentSession returns the snapshot plus domain actions. Zero state-machine leak. |
pay-state |
@walletconnect/pay-appkit
|
Reown AppKit adapter — implements the WalletProvider seam over a Reown AppKit instance (plus the Solana web3 loader). A /react subpath ships the wallet-connection hook. |
pay-state |
(matches URI: https://pay.walletconnect.com) alt 1 wallet with verified App Link OS->>W: App Link opens NfcPaymentActivity W->>W: Extract payment URL from intent data W->>W: Start payment flow else Multiple wallets installed OS->>OS: Show Activity Chooser
("Open with...") OS->>W: User selects wallet W->>W: Extract payment URL from intent data W->>W: Start payment flow else No wallet installed OS->>B: Open https://pay.walletconnect.com/?pid=pay_xxx B->>B: Wallet chooser web page
(App Store / Play Store links) end ``` #### Flow: Tap from Wallet App (Foreground) ```mermaid theme={null} sequenceDiagram participant POS as POS Terminal participant NFC as Android NFC participant W as Wallet App (Foreground) Note over W: App is open, NFC foreground dispatch active POS->>NFC: NDEF tag emulated (URI record) NFC->>W: NDEF_DISCOVERED dispatched
to foreground Activity W->>W: Parse URI record W->>W: Extract payment URL W->>W: Start payment flow immediately ``` ### Integration Steps
Find URI record with Universal Link alt 1 wallet registered in AASA OS->>OS: Show notification banner:
"Open in [Wallet]" OS->>W: User taps notification W->>W: SceneDelegate receives Universal Link W->>W: Start payment flow (autoPayMode) else Multiple wallets in AASA OS->>OS: AASA evaluated top-to-bottom OS->>W: First installed match wins
(no disambiguation UI) W->>W: SceneDelegate receives Universal Link W->>W: Start payment flow (autoPayMode) else Multiple wallets in AASA (iOS 26) OS->>OS: Show system wallet chooser modal OS->>W: User picks a wallet W->>W: SceneDelegate receives Universal Link W->>W: Start payment flow (autoPayMode) else No wallet installed OS->>S: Open payment URL in Safari S->>S: Wallet chooser web page
(App Store links) end ``` #### Flow: Tap from Wallet App (Foreground) ```mermaid theme={null} sequenceDiagram participant POS as POS Terminal participant W as Wallet App (Foreground) participant NFC as NFCNDEFReaderSession participant Pay as Payment Flow W->>W: Press NFC scanner button W->>NFC: onAppear() -> NFCPaymentReader.scan() NFC->>NFC: Show "Ready to Pay" NFC sheet Note over NFC: Active reader session takes
priority over Background Tag Reading POS->>NFC: NDEF tag detected NFC->>NFC: invalidateAfterFirstRead: true NFC->>W: didDetectNDEFs callback W->>W: Extract URI from NDEF record NFC->>NFC: Auto-close NFC sheet W->>Pay: Present PayModule (full screen) Pay->>Pay: Payment confirmation + signing Note over Pay: Payment completes Pay->>W: Dismiss PayModule W->>W: Return to Balances screen W->>NFC: onAppear() restarts NFC session NFC->>NFC: Show "Ready to Pay" again ``` ### Integration Steps
Do NOT broadcast Wallet->>Gateway: Confirm payment (results: [signed tx blob]) Gateway->>Chain: Broadcast signed transaction Chain-->>Gateway: Confirmation Gateway-->>Wallet: status + isFinal Wallet->>User: Show result / status ```