WalletConnect Pay SDK

TypeScript SDK for WalletConnect Pay - a payment solution for React Native and web applications.

Installation

npm install @walletconnect/pay

React Native Setup

This SDK requires the WalletConnect React Native native module. Make sure you have @walletconnect/react-native-compat installed and linked in your React Native project.

Web Setup (Coming Soon)

WASM provider support for web browsers is coming in a future release.

Architecture

The SDK uses a provider abstraction that allows different implementations:

• NativeProvider: Uses React Native uniffi module (current)
• WasmProvider: Uses WebAssembly module (coming soon)

The SDK auto-detects the best available provider for your environment.

Usage

Initialize the Client

import { WalletConnectPay } from "@walletconnect/pay";

const client = new WalletConnectPay({
  appId: "your-app-id",
  // OR use apiKey instead:
  // apiKey: "your-api-key",
});

Get Payment Options

Retrieve available payment options for a payment link:

const options = await client.getPaymentOptions({
  paymentLink: "https://pay.walletconnect.com/pay_123",
  accounts: ["eip155:8453:0xYourAddress"], // CAIP-10 accounts
  includePaymentInfo: true,
});

console.log("Payment ID:", options.paymentId);
console.log("Options:", options.options);

Get Required Actions

Get the wallet RPC actions required to complete a payment option:

const actions = await client.getRequiredPaymentActions({
  paymentId: options.paymentId,
  optionId: options.options[0].id,
});

// Each action contains wallet RPC data to sign
for (const action of actions) {
  console.log("Chain:", action.walletRpc.chainId);
  console.log("Method:", action.walletRpc.method);
  console.log("Params:", action.walletRpc.params);
}

Sign and Confirm Payment

Sign the actions with your wallet and confirm the payment:

// Sign each action with your wallet (implementation depends on your wallet SDK)
const signatures = await Promise.all(
  actions.map((action) =>
    wallet.signTypedData(action.walletRpc.chainId, JSON.parse(action.walletRpc.params)),
  ),
);

// Confirm the payment
const result = await client.confirmPayment({
  paymentId: options.paymentId,
  optionId: options.options[0].id,
  signatures,
});

if (result.status === "succeeded") {
  console.log("Payment successful!");
} else if (result.status === "processing") {
  console.log("Payment is processing...");
}

Collected Data

Some payments may require additional user data:

const options = await client.getPaymentOptions({
  paymentLink,
  accounts,
});

if (options.collectData) {
  // Show UI to collect required fields
  const collectedData = options.collectData.fields.map((field) => ({
    id: field.id,
    value: getUserInput(field.name, field.fieldType),
  }));

  // Include collected data when confirming
  const result = await client.confirmPayment({
    paymentId: options.paymentId,
    optionId: selectedOptionId,
    signatures,
    collectedData,
  });
}

API Reference

WalletConnectPay

Constructor

new WalletConnectPay(options: WalletConnectPayOptions)

| Option | Type | Required | Description | | -------- | ------ | -------- | -------------------------------------------- | | appId | string | No* | App ID for authentication | | apiKey | string | No* | API key for authentication | | clientId | string | No | Client ID for tracking | | baseUrl | string | No | Custom API base URL | | logger | Logger | No | Custom logger instance or level |

* Either appId or apiKey must be provided for authentication.

Methods

getPaymentOptions(params)

Get available payment options for a payment link.

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

getRequiredPaymentActions(params)

Get the wallet RPC actions required to complete a payment.

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

confirmPayment(params)

Submit signatures and confirm the payment.

interface ConfirmPaymentParams {
  paymentId: string; // Payment ID
  optionId: string; // Selected option ID
  signatures: string[]; // Wallet RPC signatures
  collectedData?: CollectDataFieldResult[]; // Collected data fields
}

static isAvailable()

Check if a provider is available on the current platform.

Provider Utilities

import {
  isProviderAvailable,
  detectProviderType,
  isNativeProviderAvailable,
  setNativeModule,
} from "@walletconnect/pay";

// Check if any provider is available
if (isProviderAvailable()) {
  // SDK can be used
}

// Detect which provider type is available
const providerType = detectProviderType(); // 'native' | 'wasm' | null

// Check specifically for native provider
if (isNativeProviderAvailable()) {
  // React Native native module is available
}

// Manually inject native module (if auto-discovery fails)
import { NativeModules } from "react-native";
setNativeModule(NativeModules.RNWalletConnectPay);

Types

PaymentStatus

type PaymentStatus = "requires_action" | "processing" | "succeeded" | "failed" | "expired";

PaymentOption

interface PaymentOption {
  id: string;
  account: string; // CAIP-10 account for this option
  amount: PayAmount;
  etaS: number;
  actions: Action[];
}

Action

interface Action {
  walletRpc: WalletRpcAction;
}

interface WalletRpcAction {
  chainId: string;
  method: string;
  params: string; // JSON string
}

PayProviderType

type PayProviderType = "native" | "wasm";

Error Handling

The SDK throws typed errors for different failure scenarios:

import { PayError, PaymentOptionsError, ConfirmPaymentError } from "@walletconnect/pay";

try {
  const options = await client.getPaymentOptions({
    paymentLink: link,
    accounts,
  });
} catch (error) {
  if (error instanceof PaymentOptionsError) {
    console.error("Failed to get options:", error.originalMessage);
  } else if (error instanceof PayError) {
    console.error("Pay error:", error.code, error.message);
  }
}

License

WalletConnect Community License