WalletConnect Pay via WalletKit - Flutter

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.

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

Pre-Requisites

In order to use your WalletConnect Pay, you need to obtain an App ID for your project from the WalletConnect Dashboard.

How to obtain an App ID

Navigate to the WalletConnect Dashboard.
Select the project that is associated with your wallet (as in, the projectId that is being used for your wallet’s WalletConnect integration).

Select the project on WalletConnect Dashboard

Click on the “Get Started” button to get an App ID associated with your project.
The Dashboard will now show the App ID associated with your project.
Click on the three dots on the right of the App ID and select “Copy App ID”. You will be using this for your wallet’s WalletConnect Pay integration.

Copy App ID from WalletConnect Dashboard

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'],
  ),
);

Accessing the Pay Client

You can access the WalletConnectPay instance directly:

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 five main steps: Detect Payment Link -> Get Options -> 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 if data collection is required
if (response.collectData != null) {
  print('Data collection required: ${response.collectData!.fields.length} fields');
}

Get Required Payment Actions

Get the required wallet actions for a selected payment option:

final actions = await walletKit.getRequiredPaymentActions(
  request: GetRequiredPaymentActionsRequest(
    optionId: 'option-id',
    paymentId: 'payment-id',
  ),
);

// 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}');
  // Sign the transaction using your wallet SDK
}

Collect User Data (If Required)

Some payments may require additional user data:

WebView-Based Data Collection

When a payment requires user information (e.g., for Travel Rule compliance), the SDK returns a collectDataAction with a url field pointing to a WalletConnect-hosted form page.Instead of building native forms, wallets display this URL in a WebView. The hosted form handles rendering, validation, and Terms & Conditions acceptance. When the user completes the form, the WebView communicates back to the wallet via JavaScript bridge messages.

How It Works

Check if collectDataAction.url is present in the payment options response
Open the URL in a WebView within your wallet
Optionally append a prefill=<base64-json> query parameter with known user data (e.g., name, date of birth, address). Use proper URL building to handle existing query parameters.
Listen for JS bridge messages: IC_COMPLETE (success) or IC_ERROR (failure)
On IC_COMPLETE, proceed to confirmPayment() without passing collectedData — the WebView submits data directly to the backend

The collectDataAction also includes a schema field — a JSON schema string describing the required fields. The required list in this schema tells you which fields the form expects. Wallets can use these field names as keys when building the prefill JSON object. For example, if the schema’s required array contains ["fullName", "dateOfBirth", "pobAddress"], you can prefill with {"fullName": "...", "dateOfBirth": "...", "pobAddress": "..."}.

When using the WebView approach, do not pass collectedData to confirmPayment(). The WebView handles data submission directly.

if (response.collectData?.url != null) {
  // Use the "required" list from response.collectData.schema to determine which fields to prefill
  final prefillData = {
    'fullName': 'John Doe',
    'dateOfBirth': '1990-01-15',
    'pobAddress': '123 Main St, New York, NY 10001',
  };
  final prefillJson = jsonEncode(prefillData);
  final prefillBase64 = base64Url.encode(utf8.encode(prefillJson));
  final uri = Uri.parse(response.collectData!.url);
  final webViewUrl = uri.replace(
    queryParameters: {...uri.queryParameters, 'prefill': prefillBase64},
  ).toString();

  // Show WebView and wait for IC_COMPLETE message
  showDataCollectionWebView(webViewUrl);
}

WebView Message Types

The WebView communicates with your wallet through JavaScript bridge messages. 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.

Platform-Specific Bridge Names

Platform	Bridge Name	Handler
Kotlin (Android)	`AndroidWallet`	`@JavascriptInterface onDataCollectionComplete(json: String)`
Swift (iOS)	`payDataCollectionComplete`	`WKScriptMessageHandler.didReceive(message:)`
Flutter	`ReactNativeWebView` (injected via JS bridge)	`JavaScriptChannel.onMessageReceived`
React Native	`ReactNativeWebView` (native)	`WebView.onMessage` prop

Confirm Payment

Confirm the payment with signatures and optional collected data:

final confirmResponse = await walletKit.confirmPayment(
  request: ConfirmPaymentRequest(
    paymentId: 'payment-id',
    optionId: 'option-id',
    signatures: ['0x...', '0x...'], // Signatures from wallet actions
    collectedData: [
      CollectDataFieldResult(id: 'fullName', value: 'John Doe'),
      CollectDataFieldResult(id: 'dob', value: '1990-01-01'),
    ], // Optional: if data collection was required
    maxPollMs: 60000, // Maximum polling time in milliseconds
  ),
);

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

WebView Implementation

When collectData.url is present, display the URL in a WebView using webview_flutter (v4.10.0+). Add dependencies:

dependencies:
  webview_flutter: ^4.10.0
  url_launcher: ^6.1.0

import 'dart:convert';
import 'package:flutter/material.dart';
import 'package:webview_flutter/webview_flutter.dart';
import 'package:url_launcher/url_launcher.dart';

class PayDataCollectionWebView extends StatefulWidget {
  final String url;
  final VoidCallback onComplete;
  final ValueChanged<String> onError;

  const PayDataCollectionWebView({
    super.key,
    required this.url,
    required this.onComplete,
    required this.onError,
  });

  @override
  State<PayDataCollectionWebView> createState() =>
      _PayDataCollectionWebViewState();
}

class _PayDataCollectionWebViewState extends State<PayDataCollectionWebView> {
  late final WebViewController _controller;
  bool _isLoading = true;

  @override
  void initState() {
    super.initState();
    _controller = WebViewController()
      ..setJavaScriptMode(JavaScriptMode.unrestricted)
      ..setNavigationDelegate(NavigationDelegate(
        onPageFinished: (_) => setState(() => _isLoading = false),
        onNavigationRequest: (request) {
          if (!request.url.contains('pay.walletconnect.com')) {
            launchUrl(Uri.parse(request.url),
                mode: LaunchMode.externalApplication);
            return NavigationDecision.prevent;
          }
          return NavigationDecision.navigate;
        },
      ))
      ..addJavaScriptChannel(
        'ReactNativeWebView',
        onMessageReceived: (message) {
          try {
            final data = jsonDecode(message.message) as Map<String, dynamic>;
            switch (data['type']) {
              case 'IC_COMPLETE':
                widget.onComplete();
                break;
              case 'IC_ERROR':
                widget.onError(data['error'] ?? 'Unknown error');
                break;
            }
          } catch (_) {}
        },
      )
      ..loadRequest(Uri.parse(widget.url));
  }

  @override
  Widget build(BuildContext context) {
    return Stack(
      children: [
        WebViewWidget(controller: _controller),
        if (_isLoading)
          const Center(child: CircularProgressIndicator()),
      ],
    );
  }
}

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

  /// Process a payment from a payment link (e.g., after scanning QR code)
  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: Collect data via WebView if required
      if (optionsResponse.collectData?.url != null) {
        await showDataCollectionWebView(optionsResponse.collectData!.url);
      }

      // Step 3: Select payment option (or let user choose)
      PaymentOption selectedOption = optionsResponse.options.first;
      final paymentId = optionsResponse.paymentId;
      final optionId = selectedOption.id;

      // Step 4: Get required payment actions (if not already in the option)
      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) {
        // Sign the transaction using your wallet SDK
        // Example: signatures.add(await signTransaction(action.walletRpc));
      }

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

      // Step 7: Poll until final status (if needed)
      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.requires_action:
          throw Exception('Payment requires additional action');
        case PaymentStatus.processing:
          // Should not happen if isFinal is true
          break;
      }
    } catch (e) {
      print('Payment error: $e');
      rethrow;
    }
  }

  Future<List<String>> getWalletAccounts() async {
    // Return your wallet's CAIP-10 formatted accounts
    // Example: ['eip155:1:0x1234...', 'eip155:137:0x5678...']
    return [];
  }
}

Direct Access

You can also access the underlying WalletConnectPay instance directly if needed:

final payClient = walletKit.pay;
// Use payClient methods directly
final response = await payClient.getPaymentOptions(request: request);

API Reference

ReownWalletKit Pay Methods

Method	Description
`isPaymentLink(String uri)`	Check if URI is a payment link
`getPaymentOptions({required GetPaymentOptionsRequest request})`	Get available payment options
`getRequiredPaymentActions({required GetRequiredPaymentActionsRequest request})`	Get actions requiring signatures
`confirmPayment({required ConfirmPaymentRequest request})`	Confirm and finalize payment
`pay`	Access the underlying WalletConnectPay instance

Models

GetPaymentOptionsRequest

GetPaymentOptionsRequest({
  required String paymentLink,
  required List<String> accounts,
  @Default(false) bool includePaymentInfo,
})

PaymentOptionsResponse

PaymentOptionsResponse({
  required String paymentId,
  PaymentInfo? info,
  required List<PaymentOption> options,
  CollectDataAction? collectData,
  PaymentResultInfo? resultInfo,     // Transaction result details (present when payment already completed)
})

PaymentResultInfo

class PaymentResultInfo {
  final String txId;               // Transaction ID
  final PayAmount optionAmount;    // Token amount details
}

PaymentInfo

PaymentInfo({
  required PaymentStatus status,
  required PayAmount amount,
  required int expiresAt,
  required MerchantInfo merchant,
  BuyerInfo? buyer,
})

PaymentOption

PaymentOption({
  required String id,
  required String account,
  required PayAmount amount,
  @JsonKey(name: 'etaS') required int etaSeconds,
  required List<Action> actions,
})

ConfirmPaymentRequest

ConfirmPaymentRequest({
  required String paymentId,
  required String optionId,
  required List<String> signatures,
  int? maxPollMs,
})

ConfirmPaymentResponse

ConfirmPaymentResponse({
  required PaymentStatus status,
  required bool isFinal,
  int? pollInMs,
})

PaymentStatus

enum PaymentStatus {
  requires_action,
  processing,
  succeeded,
  failed,
  expired,
}

CollectDataAction

class CollectDataAction {
  final String url;                // WebView URL for data collection
  final String? schema;            // JSON schema describing required fields
}

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

Exception	Description
`PayInitializeError`	Initialization failures
`GetPaymentOptionsError`	Errors when fetching payment options
`GetRequiredActionsError`	Errors when getting required actions
`ConfirmPaymentError`	Errors when confirming payment

All errors include:

code: Error code
message: Error message
details: Additional error details
stacktrace: Stack trace

Example Error Handling

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

Best Practices

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

Examples

For a complete example implementation with UI components showing the full payment flow, see the reown_walletkit example. The example demonstrates:

Payment link detection and processing
Payment options retrieval with UI
Data collection for compliance (KYB/KYC)
Payment details display
Transaction signing and confirmation
Payment status polling and result display

WalletConnect Pay

Point of Sale (POS) Integration

Merchant Dashboard

WalletConnect Pay for Wallets

Ecommerce and Online Checkout

​Requirements

​Pre-Requisites

​How to obtain an App ID

​Installation

​Initialization

​Accessing the Pay Client

​Payment Link Detection

​Payment Flow

Get Payment Options

Get Required Payment Actions

Collect User Data (If Required)

​WebView-Based Data Collection

​How It Works

​WebView Message Types

​Platform-Specific Bridge Names

Confirm Payment

​WebView Implementation

​Complete Example

​Direct Access

​API Reference

​ReownWalletKit Pay Methods

​Models

​GetPaymentOptionsRequest

​PaymentOptionsResponse

​PaymentResultInfo

​PaymentInfo

​PaymentOption

​ConfirmPaymentRequest

​ConfirmPaymentResponse

​PaymentStatus

​CollectDataAction

​Error Handling

​Example Error Handling

​Best Practices

​Examples

Requirements

Pre-Requisites

How to obtain an App ID

Installation

Initialization

Accessing the Pay Client

Payment Link Detection

Payment Flow

WebView-Based Data Collection

How It Works

WebView Message Types

Platform-Specific Bridge Names

WebView Implementation

Complete Example

Direct Access

API Reference

ReownWalletKit Pay Methods

Models

GetPaymentOptionsRequest

PaymentOptionsResponse

PaymentResultInfo

PaymentInfo

PaymentOption

ConfirmPaymentRequest

ConfirmPaymentResponse

PaymentStatus

CollectDataAction

Error Handling

Example Error Handling

Best Practices

Examples