WalletConnect Pay via WalletKit - Flutter

Integrate WalletConnect Pay through WalletKit for a unified payment experience in your Flutter wallet.

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

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 an App ID associated with your project.
4. The Dashboard will now show the App ID associated with your project.
5. 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.

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

1. 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');
   }
   
2. 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
   }
   
3. 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 collectData field on individual payment options. Each option may independently require data collection — some options may require it while others don’t.

   Recommended Flow (Per-Option)

   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, open selectedOption.collectData.url in a WebView within your wallet
   5. 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.
   6. Listen for JS bridge messages: IC_COMPLETE (success) or IC_ERROR (failure)
   7. On IC_COMPLETE, proceed to confirmPayment() without passing collectedData — the WebView submits data directly to the backend

   Decision Matrix

   Response collectData	option.collectData	Behavior
   present	present	Option requires IC — use option.collectData.url
   present	null	Option does NOT require IC (others might) — skip IC for this option
   null	null	No IC needed for any option

   The collectData 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", "dob", "pobAddress"], you can prefill with {"fullName": "...", "dob": "...", "pobAddress": "..."}.

   The top-level collectData on the payment options response is still available for backward compatibility. However, the per-option collectData is the recommended approach as it provides more granular control over the flow.

   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',
       'dob': '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

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

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

7. Loading States: Show loading indicators during API calls and signing operations

8. Expiration: Check paymentInfo.expiresAt and warn users if time is running low

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