WalletConnect Pay SDK

The WalletConnect Pay SDK allows wallet users to pay merchants using their crypto assets. The SDK handles payment option discovery, permit signing coordination, and payment confirmation while leveraging your wallet’s existing signing infrastructure.

Sample Wallet

For a complete working example, check out our sample wallet implementation:

[**Sample Wallet - Flutter**

A reference Flutter wallet app demonstrating WalletConnect Pay integration.](https://github.com/reown-com/reown_flutter/tree/develop/packages/reown_walletkit/example)

Requirements

• Flutter 3.0+
• iOS 13.0+
• Android API 23+

Installation

Add walletconnect_pay package to your pubspec.yaml or simply run:

flutter pub add walletconnect_pay

Initialization

Initialize the WalletConnectPay client with your WCP ID and client ID or API key:

import 'package:walletconnect_pay/walletconnect_pay.dart';

// Initialize WalletConnect Pay. Either apiKey or appId must be passed
final payClient = WalletConnectPay(
  apiKey: 'YOUR_API_KEY', // Optional
  appId: 'YOUR_WCP_ID', // Optional
  clientId: 'OPTIONAL_CLIENT_ID', // Optional
  baseUrl: 'https://api.pay.walletconnect.com', // Optional
);

// Initialize the SDK
try {
  await payClient.init();
} on PayInitializeError catch (e) {
  // Handle initialization error
}

Configuration Parameters

Either apiKey or appId must be provided for authentication.

Supported Networks & Tokens

WalletConnect Pay currently supports the following tokens and networks:

Include accounts for all supported networks to maximize payment options for your users.

Payment Flow

The payment flow consists of five main steps: Get Options -> Collect Data (if required) -> Get Actions -> Sign Actions -> Confirm Payment

Get Payment Options

Retrieve available payment options for a payment link:

final request = GetPaymentOptionsRequest(
  paymentLink: 'https://pay.walletconnect.com/pay_123',
  accounts: ['eip155:1:0x...', 'eip155:137:0x...'], // User's wallet CAIP-10 accounts
  includePaymentInfo: true, // Include payment details in response
);

final response = await payClient.getPaymentOptions(request: request);

// Access payment information
print('Payment ID: ${response.paymentId}');
print('Options available: ${response.options.length}');

if (response.info != null) {
  print('Amount: ${response.info!.amount.formatAmount()}');
  print('Status: ${response.info!.status}');
  print('Merchant: ${response.info!.merchant.name}');
}

// Check which options require data collection (per-option)
for (final option in response.options) {
  if (option.collectData != null) {
    print('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. The form is loaded from selectedOption.collectData.url and embedded in your wallet (a WebView on mobile, an iframe on web).

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

Get Required Actions

Get the required wallet actions (e.g., transactions to sign) for a selected payment option:

final actionsRequest = GetRequiredPaymentActionsRequest(
  optionId: response.options.first.id, // Or whatever other option chosen by the user
  paymentId: response.paymentId,
);
final actions = await payClient.getRequiredPaymentActions(
  request: actionsRequest,
);

// Process each action (e.g., sign transactions)
for (final action in actions) {
  final walletRpc = action.walletRpc;
  print('Chain ID: ${walletRpc.chainId}');
  print('Method: ${walletRpc.method}');
  print('Params: ${walletRpc.params}');
}

Sign Actions

Sign each action using your wallet’s signing implementation, dispatching on the RPC method:

// Sign each action based on its RPC method
final signatures = <String>[];
for (final action in actions) {
  final rpc = action.walletRpc;
  switch (rpc.method) {
    case 'eth_signTypedData_v4':
      signatures.add(await signTypedData(rpc.chainId, rpc.params));
      break;
    case 'eth_sendTransaction':
      signatures.add(await sendTransaction(rpc.chainId, rpc.params));
      break;
    case 'personal_sign':
      signatures.add(await personalSign(rpc.chainId, rpc.params));
      break;
    default:
      throw UnimplementedError('Unsupported RPC method: ${rpc.method}');
  }
}

Confirm Payment

Confirm a payment with the collected signatures:

final confirmRequest = ConfirmPaymentRequest(
  paymentId: response.paymentId,
  optionId: response.options.first.id,
  signatures: ['0x...', '0x...'], // Signatures from wallet actions
  maxPollMs: 60000, // Optional: max polling time in milliseconds
);

final confirmResponse = await payClient.confirmPayment(request: confirmRequest);

print('Payment Status: ${confirmResponse.status}');
print('Is Final status: ${confirmResponse.isFinal}');

if (!confirmResponse.isFinal && confirmResponse.pollInMs != null) {
  // Poll again after the specified interval
  await Future.delayed(Duration(milliseconds: confirmResponse.pollInMs!));
}

Complete Example

Here’s a complete implementation example:

import 'package:walletconnect_pay/walletconnect_pay.dart';

class PaymentService {
  late final WalletConnectPay _payClient;

Future<void> initialize() async {
    _payClient = WalletConnectPay(
      appId: 'YOUR_WCP_ID',
    );
    await _payClient.init();
  }

Future<ConfirmPaymentResponse> processPayment(
    String paymentLink,
    List<String> accounts,
  ) async {
    // Step 1: Get payment options
    final optionsResponse = await _payClient.getPaymentOptions(
      request: GetPaymentOptionsRequest(
        paymentLink: paymentLink,
        accounts: accounts,
        includePaymentInfo: true,
      ),
    );

if (optionsResponse.options.isEmpty) {
      throw Exception('No payment options available');
    }

// Step 2: Select payment option (simplified - use first option)
    final selectedOption = optionsResponse.options.first;

// Step 3: Collect data via WebView if required.
    // This must happen BEFORE fetching the required payment actions.
    if (selectedOption.collectData?.url != null) {
      // Show WebView and wait for IC_COMPLETE
      await showDataCollectionWebView(selectedOption.collectData!.url);
    }

// Step 4: Get required payment actions
    final actions = await _payClient.getRequiredPaymentActions(
      request: GetRequiredPaymentActionsRequest(
        optionId: selectedOption.id,
        paymentId: optionsResponse.paymentId,
      ),
    );

// Step 5: Sign all actions
    final signatures = <String>[];
    for (final action in actions) {
      final signature = await signAction(action.walletRpc);
      signatures.add(signature);
    }

// Step 6: Confirm payment
    final confirmResponse = await _payClient.confirmPayment(
      request: ConfirmPaymentRequest(
        paymentId: optionsResponse.paymentId,
        optionId: selectedOption.id,
        signatures: signatures,
        maxPollMs: 60000,
      ),
    );

return confirmResponse;
  }

Future<String> signAction(WalletRpcAction walletRpc) async {
    switch (walletRpc.method) {
      case 'eth_signTypedData_v4':
        return await signTypedData(walletRpc.chainId, walletRpc.params);
      case 'eth_sendTransaction':
        return await sendTransaction(walletRpc.chainId, walletRpc.params);
      case 'personal_sign':
        return await personalSign(walletRpc.chainId, walletRpc.params);
      default:
        throw UnimplementedError('Unsupported RPC method: ${walletRpc.method}');
    }
  }
}

API Reference

WalletConnectPay The main class for interacting with the WalletConnect Pay SDK.

Constructor

WalletConnectPay({
  String? apiKey,
  String? appId,
  String? clientId,
  String? baseUrl,
})

Methods

Error Handling

The SDK throws specific exception types for different error scenarios. All errors extend the abstract PayError class, which itself extends PlatformException:

abstract class PayError extends PlatformException {
  PayError({
    required super.code,
    required super.message,
    required super.details,
    required super.stacktrace,
  });
}