> ## Documentation Index
> Fetch the complete documentation index at: https://walletconnect-pay-docs-review-wpay-data-collection-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# WalletConnect Pay via WalletKit - Web/Node.js
> Integrate WalletConnect Pay through WalletKit for a unified payment experience in your Web/Node.js wallet.
This documentation covers integrating WalletConnect Pay through WalletKit for Web/Node.js wallets. This approach provides a unified API where Pay is built into WalletKit, simplifying the integration for wallet developers.
## Sample Wallet
For a complete working example, check out our sample wallet implementation:
A reference web wallet app demonstrating WalletConnect Pay via WalletKit.
**Using AI for Integration?** If you're using an AI IDE or assistant to help with integration, you can provide it with our comprehensive [AI integration prompt](/payments/wallets/walletkit/ai-prompts/react-native) for better context and guidance. The React Native prompt applies to Web/Node.js as well since they share the same JavaScript SDK.
## Requirements
* Node.js 16+
* WalletKit (`@reown/walletkit`)
You also need a WCP ID for your project, obtained from the [WalletConnect Dashboard](https://dashboard.walletconnect.com).
**How to obtain a WCP ID**
1. Navigate to the [WalletConnect Dashboard](https://dashboard.walletconnect.com).
2. Select the project that is associated with your wallet (as in, the projectId that is being used for your wallet's WalletConnect integration).
3. Click on the "Get Started" button to get a WCP ID associated with your project.
4. The Dashboard will now show the WCP ID associated with your project.
5. Click on the three dots on the right of the WCP ID and select "Copy WCP ID". You will be using this for your wallet's WalletConnect Pay integration.
## Installation
Install WalletKit using npm or yarn:
```bash theme={null}
npm install @reown/walletkit @walletconnect/core
```
```bash theme={null}
yarn add @reown/walletkit @walletconnect/core
```
WalletConnect Pay is automatically included as part of WalletKit.
Check the [npm page](https://www.npmjs.com/package/@reown/walletkit) for the latest version.
## Initialization
Initialize WalletKit as usual. Pay functionality is automatically available:
```javascript theme={null}
import { Core } from "@walletconnect/core";
import { WalletKit } from "@reown/walletkit";
const core = new Core({
projectId: process.env.PROJECT_ID,
});
const walletkit = await WalletKit.init({
core, // <- pass the shared `core` instance
metadata: {
name: "Demo app",
description: "Demo Client as Wallet/Peer",
url: "www.walletconnect.com",
icons: [],
},
payConfig: {
appId: "",
// or
apiKey: "",
}
});
```
## Payment Link Detection
Use `isPaymentLink` to determine if a scanned URI is a payment link or a standard WalletConnect pairing URI:
```javascript theme={null}
import { isPaymentLink } from "@reown/walletkit";
// Use when handling a scanned QR code or deep link
if (isPaymentLink(uri)) {
// Handle as payment (see below)
await processPayment(uri);
} else {
// Handle as WalletConnect pairing
await walletkit.pair({ uri });
}
```
## Payment Flow
The payment flow consists of six main steps:
**Detect Payment Link -> Get Options -> Collect Data (if required) -> Get Actions -> Sign Actions -> Confirm Payment**
```mermaid theme={null}
sequenceDiagram
participant User
participant Wallet
participant WalletKit as WalletKit.Pay
participant Backend as WalletConnect Pay
participant Iframe
User->>Wallet: Scan QR / Open payment link
Wallet->>WalletKit: isPaymentLink(uri)
WalletKit-->>Wallet: true
Wallet->>WalletKit: pay.getPaymentOptions(params)
WalletKit->>Backend: Fetch payment options
Backend-->>WalletKit: Payment options + merchant info
WalletKit-->>Wallet: PaymentOptionsResponse
Wallet->>User: Display payment options
User->>Wallet: Select payment option
alt Data collection required
Wallet->>Iframe: Load collectDataAction.url in iframe
Iframe->>User: Display data collection form
User->>Iframe: Fill form & accept T&C
Iframe-->>Wallet: IC_COMPLETE message via postMessage
end
Wallet->>WalletKit: pay.getRequiredPaymentActions(params)
WalletKit->>Backend: Get signing actions
Backend-->>WalletKit: Required wallet RPC actions
WalletKit-->>Wallet: List of actions to sign
Wallet->>User: Request signature(s)
User->>Wallet: Approve & sign
Wallet->>WalletKit: pay.confirmPayment(params)
WalletKit->>Backend: Submit payment
Backend-->>WalletKit: Payment status
WalletKit-->>Wallet: ConfirmPaymentResponse
Wallet->>User: Show result
```
Retrieve available payment options for a payment link:
```javascript theme={null}
const options = await walletkit.pay.getPaymentOptions({
paymentLink: "https://pay.walletconnect.com/...",
accounts: ["eip155:1:0x...", "eip155:8453:0x..."],
includePaymentInfo: true,
});
// options.paymentId - unique payment identifier
// options.options - array of payment options (different tokens/chains)
// options.info - payment details (amount, merchant, expiry)
// Display merchant info
if (options.info) {
console.log("Merchant:", options.info.merchant.name);
console.log("Amount:", options.info.amount.display.assetSymbol, options.info.amount.value);
}
// Check which options require data collection (per-option)
for (const option of options.options) {
if (option.collectData) {
console.log(`Option ${option.id} requires info capture`);
}
}
```
After the user selects an option, check for `collectData` on it. If present, collect the data **before** fetching the required actions.
## Embedded Data Collection Form
When a payment requires user information (e.g., for Travel Rule compliance), the SDK returns a `collectData` field on individual payment options. Each option may independently require data collection — some options may require it while others don't.
The form is loaded from `selectedOption.collectData.url` and embedded in your wallet (a WebView on mobile, an iframe on web). It handles field rendering, validation, Terms & Conditions and Privacy Policy acceptance, and submits data directly to the backend.
Collect this data **before** fetching the required actions. For an option that requires Information Capture, `getRequiredPaymentActions` fails with `400 IC data required` until the data has been submitted.
### Recommended Flow
The recommended approach is to display all payment options upfront, then handle data collection only when the user selects an option that requires it:
1. Call `getPaymentOptions` and display all available options to the user
2. Show a visual indicator (e.g., "Info required" badge) on options where `option.collectData` is present
3. When the user selects an option, check `selectedOption.collectData`
4. If present, load `selectedOption.collectData.url` in the embedded form
5. Optionally append query parameters to the form URL — `prefill` (known user data), `theme`, and `themeVariables` (appearance). See [Form URL parameters](#form-url-parameters) below. Use proper URL building so existing query parameters are preserved.
6. Listen for completion messages: `IC_COMPLETE` (success) or `IC_ERROR` (failure)
7. On `IC_COMPLETE`, continue the flow — fetch the required actions, sign, and confirm the payment. Don't pass `collectedData` to `confirmPayment()`; the form submits data directly to the backend
### Decision Matrix
| Response `collectData` | `option.collectData` | Behavior |
| ---------------------- | -------------------- | ------------------------------------------------------------------- |
| present | present | Option requires IC — use `option.collectData.url` |
| present | `null` | Option does NOT require IC (others might) — skip IC for this option |
| `null` | `null` | No IC needed for any option |
### Form URL parameters
The form URL accepts the following optional query parameters. Append them to `selectedOption.collectData.url` before loading it, preserving any existing query parameters.
| Parameter | Format | Description |
| ---------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prefill` | base64url-encoded JSON | Pre-populates known user fields so the user doesn't re-enter them. Keys must match the `required` fields from `collectData.schema` (e.g. `fullName`, `dob`, `pobAddress`). |
| `theme` | `light` or `dark` | Sets the form's base color mode. |
| `themeVariables` | base64url-encoded JSON | Overrides design tokens to match your brand — font, font size, select colors, button border radius, and input border radius. Generate and export this value from the [WalletConnect Pay Dashboard](https://dashboard.walletconnect.com). |
`collectData.schema` is a JSON schema **string** — parse it and read its `required` array to discover the field keys for `prefill`. For example, a `required` array of `["fullName", "dob", "pobAddress"]` maps to a prefill object of `{"fullName": "...", "dob": "...", "pobAddress": "..."}`.
#### Customizing the form appearance
`theme` and `themeVariables` are optional and independent — pass either, both, or neither:
* **`theme`** switches the form between `light` and `dark` base color modes. Match it to your wallet's active mode for a seamless transition.
* **`themeVariables`** applies brand-level overrides (font, font size, select colors, button border radius, and input border radius). Generate the theme in the [WalletConnect Pay Dashboard](https://dashboard.walletconnect.com), export it as a base64url string, and append it to the form URL verbatim — you don't need to encode it at runtime.
The top-level `collectData` on the payment options response is still available for backward compatibility. However, the per-option `collectData` is the recommended approach as it provides more granular control over the flow.
Do **not** pass `collectedData` to `confirmPayment()` when using the embedded form. The form handles data submission directly.
```javascript theme={null}
if (selectedOption.collectData?.url) {
// Use the "required" list from selectedOption.collectData.schema to determine which fields to prefill
const prefillData = {
fullName: "John Doe",
dob: "1990-01-15",
pobAddress: "123 Main St, New York, NY 10001",
};
// Encode prefill as base64url (URL-safe, no padding)
const prefill = btoa(JSON.stringify(prefillData))
.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
// Optional appearance params (see "Form URL parameters"):
// theme=light|dark — base color mode
// themeVariables= — exported from the WalletConnect Pay Dashboard
const themeVariables = "";
const query = `prefill=${prefill}&theme=dark&themeVariables=${themeVariables}`;
const separator = selectedOption.collectData.url.includes("?") ? "&" : "?";
const iframeUrl = `${selectedOption.collectData.url}${separator}${query}`;
// Show data collection in an iframe or popup and wait for IC_COMPLETE message
showDataCollectionView(iframeUrl);
}
```
### Iframe Message Types
The iframe communicates with your wallet through `postMessage` events. The message payload is a JSON string with the following structure:
| Message Type | Payload | Description |
| ------------- | -------------------------------------------- | ------------------------------------------------------------------------- |
| `IC_COMPLETE` | `{ "type": "IC_COMPLETE", "success": true }` | User completed the form successfully. Proceed to payment confirmation. |
| `IC_ERROR` | `{ "type": "IC_ERROR", "error": "..." }` | An error occurred. Display the error message and allow the user to retry. |
Get the wallet RPC actions needed to complete the payment:
```javascript theme={null}
const actions = await walletkit.pay.getRequiredPaymentActions({
paymentId: options.paymentId,
optionId: options.options[0].id,
});
// actions - array of wallet RPC calls to sign
// Each action contains: { walletRpc: { chainId, method, params } }
for (const action of actions) {
console.log("Chain:", action.walletRpc.chainId);
console.log("Method:", action.walletRpc.method);
console.log("Params:", action.walletRpc.params);
}
```
Sign each required action using your wallet's signing implementation:
```javascript theme={null}
// Sign each action based on its RPC method
const signatures = await Promise.all(
actions.map(async (action) => {
const { chainId, method, params } = action.walletRpc;
const parsedParams = JSON.parse(params);
switch (method) {
case "eth_signTypedData_v4":
return await wallet.signTypedData(chainId, parsedParams);
case "eth_sendTransaction":
return await wallet.sendTransaction(chainId, parsedParams[0]);
case "personal_sign":
return await wallet.personalSign(chainId, parsedParams);
default:
throw new Error(`Unsupported RPC method: ${method}`);
}
})
);
```
Payment options may include multiple actions with different RPC methods. For example, a Permit2 payment where the user lacks sufficient allowance returns two actions: an `eth_sendTransaction` to approve the token allowance, followed by an `eth_signTypedData_v4` to sign the Permit2 transfer. Your wallet must check `action.walletRpc.method` and dispatch to the appropriate handler. For full implementation guidance, see [USDT support](/payments/wallets/token-chain-support/usdt-support).
Signatures must be in the same order as the actions array.
Submit the signatures and collected data to complete the payment:
```javascript theme={null}
const result = await walletkit.pay.confirmPayment({
paymentId: options.paymentId,
optionId: options.options[0].id,
signatures,
collectedData, // Optional, if collectData was present
});
// result.status - "succeeded" | "processing" | "failed" | "expired"
// result.isFinal - whether the payment is complete
// result.pollInMs - if not final, poll again after this delay
if (result.status === "succeeded") {
console.log("Payment successful!");
} else if (result.status === "processing") {
console.log("Payment is processing...");
} else if (result.status === "failed") {
console.log("Payment failed");
}
```
## Data Collection Implementation
When `selectedOption.collectData.url` is present, display the URL in an iframe or modal. Listen for `postMessage` events to handle completion:
**Data Collection Best Practices**
* **Display prominently**: Show the form full-screen or as a prominent modal so users can interact with it easily
* **Loading indicator**: Show a loading indicator while the form loads
* **Handle errors**: Listen for `IC_ERROR` messages and display a user-facing error message with an option to retry
* **External links**: Open Terms & Conditions and Privacy Policy links in the system browser rather than navigating within the form
* **Domain restriction**: Only allow navigation to WalletConnect pay domains and HTTPS URLs
* **Back navigation**: Handle back/dismiss gracefully — confirm cancellation with the user before closing the form mid-flow
* **Keyboard behavior**: Test that the soft keyboard appears and behaves correctly when users tap on form inputs
* **Theme to match your brand**: Pass `theme=light` or `theme=dark` to match your wallet's active color mode, and apply brand tokens with `themeVariables` exported from the [WalletConnect Pay Dashboard](https://dashboard.walletconnect.com). See [Form URL parameters](#form-url-parameters).
```javascript theme={null}
function showDataCollectionView(url) {
// Create a modal/overlay container
const overlay = document.createElement("div");
overlay.style.cssText =
"position:fixed;top:0;left:0;width:100%;height:100%;background:rgba(0,0,0,0.5);display:flex;align-items:center;justify-content:center;z-index:9999;";
const iframe = document.createElement("iframe");
iframe.src = url;
iframe.style.cssText = "width:450px;height:650px;border:none;border-radius:12px;";
overlay.appendChild(iframe);
document.body.appendChild(overlay);
return new Promise((resolve, reject) => {
function handleMessage(event) {
try {
const data = typeof event.data === "string" ? JSON.parse(event.data) : event.data;
if (data.type === "IC_COMPLETE") {
cleanup();
resolve();
} else if (data.type === "IC_ERROR") {
cleanup();
reject(new Error(data.error || "Unknown error"));
}
} catch {
// Ignore non-JSON messages
}
}
function cleanup() {
window.removeEventListener("message", handleMessage);
document.body.removeChild(overlay);
}
window.addEventListener("message", handleMessage);
});
}
function buildFormUrl(baseUrl, options = {}) {
const params = [];
if (options.prefill && Object.keys(options.prefill).length > 0) {
// base64url: URL-safe, no padding
const prefill = btoa(JSON.stringify(options.prefill))
.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
params.push(`prefill=${prefill}`);
}
if (options.theme) params.push(`theme=${options.theme}`);
if (options.themeVariables) params.push(`themeVariables=${options.themeVariables}`);
if (params.length === 0) return baseUrl;
const separator = baseUrl.includes("?") ? "&" : "?";
return `${baseUrl}${separator}${params.join("&")}`;
}
```
## Complete Example
Here's a complete implementation example:
```javascript theme={null}
import { Core } from "@walletconnect/core";
import { WalletKit, isPaymentLink } from "@reown/walletkit";
class PaymentManager {
constructor() {
this.walletkit = null;
}
async initialize(projectId) {
const core = new Core({ projectId });
this.walletkit = await WalletKit.init({
core,
metadata: {
name: "My Wallet",
description: "A crypto wallet",
url: "https://mywallet.com",
icons: ["https://mywallet.com/icon.png"],
},
});
}
async handleScannedUri(uri) {
if (isPaymentLink(uri)) {
await this.processPayment(uri);
} else {
await this.walletkit.pair({ uri });
}
}
async processPayment(paymentLink) {
const walletAddress = "0xYourAddress";
try {
// Step 1: Get payment options
const options = await this.walletkit.pay.getPaymentOptions({
paymentLink,
accounts: [
`eip155:1:${walletAddress}`,
`eip155:8453:${walletAddress}`,
`eip155:137:${walletAddress}`,
],
includePaymentInfo: true,
});
if (options.options.length === 0) {
throw new Error("No payment options available");
}
// Step 2: Let user select an option (simplified - use first option)
const selectedOption = options.options[0];
// Step 3: Collect data via iframe if required for selected option.
// This must happen BEFORE fetching required actions, otherwise the
// backend rejects the fetch for options that require info capture.
if (selectedOption.collectData?.url) {
await this.showDataCollectionView(selectedOption.collectData.url);
}
// Step 4: Get required actions
const actions = await this.walletkit.pay.getRequiredPaymentActions({
paymentId: options.paymentId,
optionId: selectedOption.id,
});
// Step 5: Sign all actions
const signatures = await Promise.all(
actions.map((action) => this.signAction(action, walletAddress))
);
// Step 6: Confirm payment
const result = await this.walletkit.pay.confirmPayment({
paymentId: options.paymentId,
optionId: selectedOption.id,
signatures,
});
return result;
} catch (error) {
console.error("Payment failed:", error);
throw error;
}
}
async signAction(action, walletAddress) {
const { chainId, method, params } = action.walletRpc;
const parsedParams = JSON.parse(params);
switch (method) {
case "eth_signTypedData_v4":
return await wallet.signTypedData(chainId, parsedParams);
case "eth_sendTransaction":
return await wallet.sendTransaction(chainId, parsedParams[0]);
case "personal_sign":
return await wallet.personalSign(chainId, parsedParams);
default:
throw new Error(`Unsupported RPC method: ${method}`);
}
}
}
```
## API Reference
**WalletKit Pay Methods**
Pay methods are accessed via `walletkit.pay.*`.
**Utility Functions**
| Function | Description |
| ------------------------------------- | ----------------------------------------------------------------- |
| `isPaymentLink(uri: string): boolean` | Check if URI is a payment link (imported from `@reown/walletkit`) |
**Instance Methods (walletkit.pay)**
| Method | Description |
| ----------------------------------- | ---------------------------------------- |
| `getPaymentOptions(params)` | Fetch available payment options |
| `getRequiredPaymentActions(params)` | Get signing actions for a payment option |
| `confirmPayment(params)` | Confirm and execute the payment |
**Parameters**
**GetPaymentOptionsParams**
```typescript theme={null}
interface GetPaymentOptionsParams {
paymentLink: string; // Payment link URL
accounts: string[]; // CAIP-10 accounts
includePaymentInfo?: boolean; // Include payment info in response
}
```
**GetRequiredPaymentActionsParams**
```typescript theme={null}
interface GetRequiredPaymentActionsParams {
paymentId: string; // Payment ID from getPaymentOptions
optionId: string; // Selected option ID
}
```
**ConfirmPaymentParams**
```typescript theme={null}
interface ConfirmPaymentParams {
paymentId: string; // Payment ID
optionId: string; // Selected option ID
signatures: string[]; // Signatures from wallet RPC calls
}
```
**Response Types**
**PaymentOptionsResponse**
```typescript theme={null}
interface PaymentOptionsResponse {
paymentId: string; // Unique payment identifier
info?: PaymentInfo; // Payment information
options: PaymentOption[]; // Available payment options
collectData?: CollectDataAction; // Data collection requirements
resultInfo?: PaymentResultInfo; // Transaction result details (present when payment already completed)
}
interface PaymentResultInfo {
txId: string; // Transaction ID
optionAmount: PayAmount; // Token amount details
}
```
**PaymentOption**
```typescript theme={null}
interface PaymentOption {
id: string; // Option identifier
amount: PayAmount; // Amount in this asset
etaS: number; // Estimated time to complete (seconds)
actions: Action[]; // Required signing actions
collectData?: CollectDataAction; // Per-option data collection (undefined if not required)
}
```
**Action**
```typescript theme={null}
interface Action {
walletRpc: WalletRpcAction;
}
interface WalletRpcAction {
chainId: string; // CAIP-2 chain ID (e.g., "eip155:8453")
method: string; // RPC method (e.g., "eth_signTypedData_v4", "eth_sendTransaction")
params: string; // JSON-encoded parameters
}
```
**ConfirmPaymentResponse**
```typescript theme={null}
interface ConfirmPaymentResponse {
status: PaymentStatus; // Payment status
isFinal: boolean; // Whether status is final
pollInMs?: number; // Suggested poll interval
info?: PaymentResultInfo; // Transaction result details (present on success)
}
type PaymentStatus =
| "requires_action"
| "processing"
| "succeeded"
| "failed"
| "expired"
| "cancelled";
```
**PaymentInfo**
```typescript theme={null}
interface PaymentInfo {
status: PaymentStatus; // Current payment status
amount: PayAmount; // Requested payment amount
expiresAt: number; // Expiration timestamp (seconds since epoch)
merchant: MerchantInfo; // Merchant details
buyer?: BuyerInfo; // Buyer info if available
}
interface MerchantInfo {
name: string; // Merchant display name
iconUrl?: string; // Merchant logo URL
}
```
**PayAmount**
```typescript theme={null}
interface PayAmount {
unit: string; // Asset unit
value: string; // Raw value in smallest unit
display: AmountDisplay; // Human-readable display info
}
interface AmountDisplay {
assetSymbol: string; // Token symbol (e.g., "USDC")
assetName: string; // Token name (e.g., "USD Coin")
decimals: number; // Token decimals
iconUrl?: string; // Token icon URL
networkName?: string; // Network name (e.g., "Base")
}
```
**CollectDataAction**
```typescript theme={null}
interface CollectDataAction {
/** URL for data collection (displayed in iframe) */
url: string;
/** JSON schema describing required fields */
schema?: string;
}
```
## Error Handling
Handle errors gracefully in your payment flow:
```javascript theme={null}
try {
const options = await walletkit.pay.getPaymentOptions({
paymentLink,
accounts,
});
} catch (error) {
if (error.message.includes("payment not found")) {
console.error("Payment not found");
} else if (error.message.includes("expired")) {
console.error("Payment has expired");
} else {
console.error("Payment error:", error);
}
}
```
## Best Practices
1. **Use WalletKit Integration**: If your wallet already uses WalletKit, prefer this approach for automatic configuration
2. **Use `isPaymentLink()` for Detection**: Use the utility function instead of manual URL parsing for reliable payment link detection
3. **Account Format**: Always use CAIP-10 format for accounts: `eip155:{chainId}:{address}`
4. **Multiple Chains**: Provide accounts for all supported chains to maximize payment options
5. **Signature Order**: Maintain the same order of signatures as the actions array
6. **Error Handling**: Always handle errors gracefully and show appropriate user feedback
7. **Loading States**: Show loading indicators during API calls and signing operations
8. **Expiration**: Check `paymentInfo.expiresAt` and warn users if time is running low
9. **User Data**: Only collect data when `collectData` is present in the response and you don't already have the required user data. If you already have the required data, you can submit this without collecting from the user. You must make sure the user accepts WalletConnect Terms and Conditions and Privacy Policy before submitting user information to WalletConnect.
10. **Data Collection**: When `selectedOption.collectData.url` is present, display the URL in an iframe or modal rather than building custom forms. The hosted form handles rendering, validation, and T\&C acceptance.