## Documentation Index

Fetch the complete documentation index at: [/llms.txt](https://docs.walletconnect.com/llms.txt)

Use this file to discover all available pages before exploring further.

This documentation covers integrating WalletConnect Pay through WalletKit for React Native 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:

[**Sample Wallet - React Native (WalletKit)**  
\
A reference React Native wallet app demonstrating WalletConnect Pay via WalletKit.](https://github.com/reown-com/react-native-examples/tree/main/wallets/rn_cli_wallet)

**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](https://docs.walletconnect.com/payments/wallets/walletkit/ai-prompts/react-native) for better context and guidance.

## 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:

- npm

- yarn

```
npm install @reown/walletkit @walletconnect/core
```

```
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:

```
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: "<your WCP ID >",
     // or
     apiKey: "<your linked WCP Api Key>",
  }
});
```

## Payment Link Detection

Use `isPaymentLink` to determine if a scanned URI is a payment link or a standard WalletConnect pairing URI:

```
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**

### Get Payment Options

Retrieve available payment options for a payment link:

```
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`);
  }
}
```

### Collect User Data (If Required)

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.

### 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](https://docs.walletconnect.com/payments/wallets/walletkit/react-native#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.

### Get Required Actions

Get the wallet RPC actions needed to complete the payment:

```
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 Actions

Sign each required action using your wallet’s signing implementation:

```javascript
// 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}`);
    }
  })
);
```

### Confirm Payment

Submit the signatures and collected data to complete the payment:

```
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 a WebView using `react-native-webview`. Install the dependency:

```
npm install react-native-webview@13.16.0
```

**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/).

```javascript
import React, { useCallback } from "react";
import { WebView } from "react-native-webview";
import { Linking, View, ActivityIndicator } from "react-native";

function PayDataCollectionWebView({ url, onComplete, onError }) {
  const handleMessage = useCallback(
    (event) => {
      try {
        const data = JSON.parse(event.nativeEvent.data);
        switch (data.type) {
          case "IC_COMPLETE":
            onComplete();
            break;
          case "IC_ERROR":
            onError(data.error || "Unknown error");
            break;
        }
      } catch {
        // Ignore non-JSON messages
      }
    },
    [onComplete, onError]
  );

const handleNavigationRequest = useCallback((request) => {
    if (!request.url.includes("pay.walletconnect.com")) {
      Linking.openURL(request.url);
      return false;
    }
    return true;
  }, []);

return (
    <WebView
      source={{ uri: url }}
      onMessage={handleMessage}
      onShouldStartLoadWithRequest={handleNavigationRequest}
      javaScriptEnabled
      domStorageEnabled
      startInLoadingState
      renderLoading={() => (
        <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
          <ActivityIndicator size="large" />
        </View>
      )}
    />
  );
}

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:

```
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 WebView if required — must happen BEFORE
      // fetching the required actions, otherwise the backend rejects the request
      if (selectedOption.collectData?.url) {
        await this.showDataCollectionWebView(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**

```
interface GetPaymentOptionsParams {
  paymentLink: string;      // Payment link URL
  accounts: string[];       // CAIP-10 accounts
  includePaymentInfo?: boolean;  // Include payment info in response
}
```

**GetRequiredPaymentActionsParams**

```
interface GetRequiredPaymentActionsParams {
  paymentId: string;        // Payment ID from getPaymentOptions
  optionId: string;         // Selected option ID
}
```

**ConfirmPaymentParams**

```
interface ConfirmPaymentParams {
  paymentId: string;        // Payment ID
  optionId: string;         // Selected option ID
  signatures: string[];     // Signatures from wallet RPC calls
}
```

**Response Types**

**PaymentOptionsResponse**

```
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**

```
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**

```
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**

```
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**

```
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**

```
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**

```
interface CollectDataAction {
  /** WebView URL for data collection */
  url: string;
  /** JSON schema describing required fields */
  schema?: string;
}
```

## Error Handling

Handle errors gracefully in your payment flow:

```
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

01. **Use WalletKit Integration**: If your wallet already uses WalletKit, prefer this approach for automatic configuration
02. **Use `isPaymentLink()` for Detection**: Use the utility function instead of manual URL parsing for reliable payment link detection
03. **Account Format**: Always use CAIP-10 format for accounts: `eip155:{chainId}:{address}`
04. **Multiple Chains**: Provide accounts for all supported chains to maximize payment options
05. **Signature Order**: Maintain the same order of signatures as the actions array
06. **Error Handling**: Always handle errors gracefully and show appropriate user feedback
07. **Loading States**: Show loading indicators during API calls and signing operations
08. **Expiration**: Check `paymentInfo.expiresAt` and warn users if time is running low
09. **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. **WebView Data Collection**: When `selectedOption.collectData.url` is present, display the URL in a WebView using `react-native-webview` rather than building native forms. The WebView handles form rendering, validation, and T&C acceptance.