WalletConnect Pay SDK - Flutter

Integrate WalletConnect Pay into your Flutter wallet to enable seamless crypto payments for your users.

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.

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

Configuration

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

Parameter	Type	Required	Description
apiKey	String?	No*	WalletConnect Pay API key
appId	String?	No*	WCP ID
clientId	String?	No	Client identifier
baseUrl	String?	No	Base URL for the API (defaults to production)

Either apiKey or appId must be provided for authentication.

Don’t have a project ID? Create one at the WalletConnect Dashboard by signing up and creating a new project.

Supported Networks & Tokens

WalletConnect Pay currently supports the following tokens and networks:

Token	Network	Chain ID	CAIP-10 Format
USDC	Arbitrum	42161	eip155:42161:{address}
USDC	Base	8453	eip155:8453:{address}
USDC	Polygon	137	eip155:137:{address}
USDC	Ethereum	1	eip155:1:{address}
USDC	Optimism	10	eip155:10:{address}
USDC	Monad	143	eip155:143:{address}
USDC	Celo	42220	eip155:42220:{address}
USDC	BSC	56	eip155:56:{address}
EURC	Ethereum	1	eip155:1:{address}
EURC	Base	8453	eip155:8453:{address}
USDT0	Arbitrum	42161	eip155:42161:{address}
PYUSD	Ethereum	1	eip155:1:{address}
PYUSD	Arbitrum	42161	eip155:42161:{address}
USDG	Ethereum	1	eip155:1:{address}
USDT	Ethereum	1	eip155:1:{address}
USDT	Polygon	137	eip155:137:{address}
USDT	BSC	56	eip155:56:{address}

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

Payment Flow

The payment flow consists of four main steps:

Get Options -> Get Actions -> Sign Actions -> Confirm Payment

1. 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 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 (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}');
     
     // Dispatch based on walletRpc.method — see Sign Actions below
   }
   

   Payment options may include multiple actions with different RPC methods. For example, a Permit2 payment where the user lacks sufficient allowance returns two actions: an eth_sendTransaction to approve the token allowance, followed by an eth_signTypedData_v4 to sign the Permit2 transfer. Your wallet must check action.walletRpc.method and dispatch to the appropriate handler. For full implementation guidance, see USDT support.

3. Collect User Data (If Required)

   Some payments may require additional user data. Check for collectData in the payment options response:

   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 — see WebView Implementation section below
     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 a payment with signatures and optional collected data:

   final confirmRequest = ConfirmPaymentRequest(
     paymentId: response.paymentId,
     optionId: response.options.first.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, // 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!));
     // Re-confirm or check status
   }
   

WebView Implementation

When collectData.url is present, display the URL in a WebView using the webview_flutter package (v4.10.0+). Add it to your pubspec.yaml:

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 (_) {
            // Ignore non-JSON messages
          }
        },
      )
      ..loadRequest(Uri.parse(widget.url));

    // Inject JS bridge for compatibility
    _controller.runJavaScript('''
      window.ReactNativeWebView = {
        postMessage: function(data) {
          ReactNativeWebView.postMessage(data);
        }
      };
    ''');
  }

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

String buildPrefillUrl(String baseUrl, Map<String, String> prefillData) {
  if (prefillData.isEmpty) return baseUrl;
  final json = jsonEncode(prefillData);
  final base64 = base64Url.encode(utf8.encode(json));
  final uri = Uri.parse(baseUrl);
  return uri.replace(
    queryParameters: {...uri.queryParameters, 'prefill': base64},
  ).toString();
}

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: Get required payment actions
    final actions = await _payClient.getRequiredPaymentActions(
      request: GetRequiredPaymentActionsRequest(
        optionId: selectedOption.id,
        paymentId: optionsResponse.paymentId,
      ),
    );

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

    // Step 5: Collect data via WebView if required
    if (optionsResponse.collectData?.url != null) {
      // Show WebView and wait for IC_COMPLETE
      await showDataCollectionWebView(optionsResponse.collectData!.url);
    }

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

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

    return response;
  }

  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

Method	Description
Future<bool> init()	Initializes the SDK. Returns true on success or throw PayInitializeError on error
Future<PaymentOptionsResponse> getPaymentOptions({required GetPaymentOptionsRequest request})	Retrieves available payment options
Future<List<Action>> getRequiredPaymentActions({required GetRequiredPaymentActionsRequest request})	Gets the required wallet actions for a selected option (to be called if the selected option does not have actions included)
Future<ConfirmPaymentResponse> confirmPayment({required ConfirmPaymentRequest request})	Confirms a payment

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,
  List<CollectDataFieldResult>? collectedData,
  int? maxPollMs,
})

ConfirmPaymentResponse

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

PaymentStatus

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

Action & WalletRpcAction

class Action {
  final WalletRpcAction walletRpc;
}

class WalletRpcAction {
  final String chainId;   // CAIP-2 chain ID (e.g., "eip155:8453")
  final String method;    // RPC method (e.g., "eth_signTypedData_v4", "eth_sendTransaction")
  final String params;    // JSON-encoded parameters
}

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 {
  await payClient.init();
} on PayInitializeError catch (e) {
  print('Initialization failed: ${e.code} - ${e.message}');
}

try {
  final response = await payClient.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. Initialize once: Call init() only once, typically during app startup

2. Account Format: Always use CAIP-10 format for accounts: eip155:{chainId}:{address}

3. Multiple Chains: Provide accounts for all supported chains to maximize payment options

4. Signature Order: Maintain the same order of signatures as the actions array

5. Error Handling: Always handle errors gracefully and show appropriate user feedback

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

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

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

9. 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, see the reown_walletkit example.