WalletConnect Pay via WalletKit - Flutter - WalletConnect Pay Docs

Documentation Index

This documentation covers integrating WalletConnect Pay through ReownWalletKit. This approach provides a unified API where Pay is automatically initialized alongside WalletKit, simplifying the integration for wallet developers.

Sample Wallet

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

Sample Wallet - Flutter (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 for better context and guidance.

Requirements

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

You also need a WCP ID for your project, obtained from the WalletConnect Dashboard.

How to obtain a WCP ID

1. Navigate to the WalletConnect Dashboard.

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

Add reown_walletkit to your pubspec.yaml:

dependencies:
  reown_walletkit: ^1.4.0

Then run:

flutter pub get

WalletConnectPay is automatically included as a dependency of ReownWalletKit.

Check the pub.dev page for the latest version.

Initialization

The WalletConnectPay client is automatically initialized during ReownWalletKit.init(). No additional setup is required.

import 'package:reown_walletkit/reown_walletkit.dart';

final walletKit = await ReownWalletKit.createInstance(
  projectId: 'YOUR_PROJECT_ID',
  metadata: PairingMetadata(
    name: 'My Wallet',
    description: 'My Wallet App',
    url: 'https://mywallet.com',
    icons: ['https://mywallet.com/icon.png'],
  ),
);

Access the WalletConnectPay client directly via walletKit.pay:

final payClient = walletKit.pay;

Payment Link Detection

Detect if a URI is a payment link before processing:

if (walletKit.isPaymentLink(uri)) {
  // Handle as payment. See [Get Payment Options] section
} else {
  // Handle as regular WalletConnect pairing
  await walletKit.pair(uri: Uri.parse(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:

final response = await walletKit.getPaymentOptions(
  request: GetPaymentOptionsRequest(
    paymentLink: 'https://pay.walletconnect.com/pay_123',
    accounts: ['eip155:1:0x...', 'eip155:137:0x...'], // Wallet's CAIP-10 accounts
    includePaymentInfo: true,
  ),
);

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

if (response.info != null) {
  print('Amount: ${response.info!.amount.formatAmount()}');
  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 — 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.

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

Decision Matrix

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.

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.
• themeVariables applies brand-level overrides.

Complete Example

Here’s a complete example of processing a payment:

import 'package:reown_walletkit/reown_walletkit.dart';

class PaymentService {
  final ReownWalletKit walletKit;

PaymentService(this.walletKit);

Future<void> processPayment(String paymentLink) async {
    try {
      // Step 1: Get payment options
      final accounts = await getWalletAccounts(); // Your wallet accounts
      final optionsResponse = await walletKit.getPaymentOptions(
        request: GetPaymentOptionsRequest(
          paymentLink: paymentLink,
          accounts: accounts,
          includePaymentInfo: true,
        ),
      );

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

// Step 2: Select payment option
      PaymentOption selectedOption = optionsResponse.options.first;
      final paymentId = optionsResponse.paymentId;
      final optionId = selectedOption.id;

// Step 3: Collect data via WebView if required for selected option.
      if (selectedOption.collectData?.url != null) {
        await showDataCollectionWebView(selectedOption.collectData!.url);
      }

// Step 4: Get required payment actions
      List<Action> actions = selectedOption.actions;
      if (actions.isEmpty) {
        actions = await walletKit.getRequiredPaymentActions(
          request: GetRequiredPaymentActionsRequest(
            optionId: optionId,
            paymentId: paymentId,
          ),
        );
      }

// Step 5: Execute wallet actions and collect signatures
      final signatures = <String>[];
      for (final action in actions) {
        signatures.add(await signAction(action.walletRpc));
      }

// Step 6: Confirm payment
      ConfirmPaymentResponse confirmResponse = await walletKit.confirmPayment(
        request: ConfirmPaymentRequest(
          paymentId: paymentId,
          optionId: optionId,
          signatures: signatures,
          maxPollMs: 60000,
        ),
      );

// Step 7: Poll until final status
      while (!confirmResponse.isFinal && confirmResponse.pollInMs != null) {
        await Future.delayed(Duration(milliseconds: confirmResponse.pollInMs!));
        confirmResponse = await walletKit.confirmPayment(
          request: ConfirmPaymentRequest(
            paymentId: paymentId,
            optionId: optionId,
            signatures: signatures,
            maxPollMs: 60000,
          ),
        );
      }

// Handle final payment status
      switch (confirmResponse.status) {
        case PaymentStatus.succeeded:
          print('Payment succeeded!');
          break;
        case PaymentStatus.failed:
          throw Exception('Payment failed');
        case PaymentStatus.expired:
          throw Exception('Payment expired');
        case PaymentStatus.cancelled:
          throw Exception('Payment cancelled');
        case PaymentStatus.requires_action:
          throw Exception('Payment requires additional action');
      }
    } catch (e) {
      print('Payment error: $e');
      rethrow;
    }
  }

Future<List<String>> getWalletAccounts() async {
    return [];
  }
}

API Reference

ReownWalletKit Pay Methods

Error Handling

The SDK throws specific exception types for different error scenarios.

Example Error Handling

try {
  final response = await walletKit.getPaymentOptions(request: request);
} on GetPaymentOptionsError catch (e) {
  print('Error code: ${e.code}');
} on PayError catch (e) {
  print('Pay error: ${e.message}');
} catch (e) {
  print('Unexpected error: $e');
}

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