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.
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. For an option that requires Information Capture, getRequiredPaymentActions fails with 400 IC data required until the data has been submitted.
The recommended approach is to display all payment options upfront, then handle data collection only when the user selects an option that requires it:
Call getPaymentOptions and display all available options to the user
Show a visual indicator (e.g., “Info required” badge) on options where option.collectData is present
When the user selects an option, check selectedOption.collectData
If present, load selectedOption.collectData.url in the embedded form
Optionally append query parameters to the form URL — prefill (known user data), theme, and themeVariables (appearance). See Form URL parameters below. Use proper URL building so existing query parameters are preserved.
Listen for completion messages: IC_COMPLETE (success) or IC_ERROR (failure)
On IC_COMPLETE, continue the flow — fetch the required actions, sign, and confirm the payment. Don’t pass collectedData to confirmPayment(); the form submits data directly to the backend
The form URL accepts the following optional query parameters. Append them to selectedOption.collectData.url before loading it, preserving any existing query parameters.
Parameter
Format
Description
prefill
base64url-encoded JSON
Pre-populates known user fields so the user doesn’t re-enter them. Keys must match the required fields from collectData.schema (e.g. fullName, dob, pobAddress).
theme
light or dark
Sets the form’s base color mode.
themeVariables
base64url-encoded JSON
Overrides design tokens to match your brand — font, font size, select colors, button border radius, and input border radius. Generate and export this value from the WalletConnect Pay Dashboard.
collectData.schema is a JSON schema string — parse it and read its required array to discover the field keys for prefill. For example, a required array of ["fullName", "dob", "pobAddress"] maps to a prefill object of {"fullName": "...", "dob": "...", "pobAddress": "..."}.
theme and themeVariables are optional and independent — pass either, both, or neither:
theme switches the form between light and dark base color modes. Match it to your wallet’s active mode for a seamless transition.
themeVariables applies brand-level overrides (font, font size, select colors, button border radius, and input border radius). Generate the theme in the WalletConnect Pay Dashboard, export it as a base64url string, and append it to the form URL verbatim — you don’t need to encode it at runtime.
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.
Do not pass collectedData to confirmPayment() when using the embedded form. The form handles data submission directly.
if (selectedOption.collectData?.url != null) { // Use the "required" list from selectedOption.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', }; // Encode prefill as base64url final prefillBase64 = base64Url.encode(utf8.encode(jsonEncode(prefillData))).replaceAll('=', ''); final uri = Uri.parse(selectedOption.collectData!.url); final webViewUrl = uri.replace( queryParameters: { ...uri.queryParameters, 'prefill': prefillBase64, // Optional appearance params (see "Form URL parameters"): 'theme': 'dark', // "light" | "dark" // themeVariables is a base64url string exported from the Pay Dashboard: // 'themeVariables': themeVariables, }, ).toString(); // Show WebView — see Data Collection Implementation section below showDataCollectionWebView(webViewUrl);}
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}
4
Sign Actions
Sign each action using your wallet’s signing implementation, dispatching on the RPC method:
// Sign each action based on its RPC methodfinal 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}'); }}
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.
Signatures must be in the same order as the actions array.
5
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!)); // Re-confirm or check status}
When using the WebView data-collection approach, you do not pass collectedData to confirmPayment. The WebView submits the collected data directly to the backend during the earlier Collect User Data step.
When selectedOption.collectData.url is present, display the URL in a WebView using the webview_flutter package (v4.10.0+). Add it to your pubspec.yaml:
Display prominently: Show the form full-screen or as a prominent modal so users can interact with it easily
Loading indicator: Show a loading indicator while the form loads
Handle errors: Listen for IC_ERROR messages and display a user-facing error message with an option to retry
External links: Open Terms & Conditions and Privacy Policy links in the system browser rather than navigating within the form
Domain restriction: Only allow navigation to WalletConnect pay domains and HTTPS URLs
Back navigation: Handle back/dismiss gracefully — confirm cancellation with the user before closing the form mid-flow
Keyboard behavior: Test that the soft keyboard appears and behaves correctly when users tap on form inputs
Theme to match your brand: Pass theme=light or theme=dark to match your wallet’s active color mode, and apply brand tokens with themeVariables exported from the WalletConnect Pay Dashboard. See Form URL parameters.
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 buildFormUrl( String baseUrl, { Map<String, String> prefillData = const {}, String? theme, // "light" or "dark" String? themeVariables, // base64url string exported from the Pay Dashboard}) { final uri = Uri.parse(baseUrl); final params = {...uri.queryParameters}; if (prefillData.isNotEmpty) { params['prefill'] = base64Url.encode(utf8.encode(jsonEncode(prefillData))).replaceAll('=', ''); } if (theme != null) params['theme'] = theme; if (themeVariables != null) params['themeVariables'] = themeVariables; return uri.replace(queryParameters: params).toString();}
The SDK throws specific exception types for different error scenarios. All errors extend the abstract PayError class, which itself extends PlatformException:
Initialize once: Call init() only once, typically during app startup
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 selectedOption.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.
