> ## Documentation Index
> Fetch the complete documentation index at: https://walletconnect-pay-docs-wcagent-expires-at-seconds-warning-3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<Card title="Sample Wallet - Flutter" icon="github" href="https://github.com/reown-com/reown_flutter/tree/develop/packages/reown_walletkit/example">
  A reference Flutter wallet app demonstrating WalletConnect Pay integration.
</Card>

## Requirements

* Flutter 3.0+
* iOS 13.0+
* Android API 23+

## Installation

Add `walletconnect_pay` package to your `pubspec.yaml` or simply run:

```bash theme={null}
flutter pub add walletconnect_pay
```

## Configuration

Initialize the `WalletConnectPay` client with your WCP ID and client ID or API key:

```dart theme={null}
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) |

<Note>
  Either `apiKey` or `appId` must be provided for authentication.
</Note>

<Info>
  Don't have a project ID? Create one at the [WalletConnect Dashboard](https://dashboard.walletconnect.com) by signing up and creating a new project.
</Info>

## 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}`    |

<Note>
  Include accounts for all supported networks to maximize payment options for your users.
</Note>

## Payment Flow

The payment flow consists of four main steps:

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

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Wallet
    participant PaySDK as Pay SDK
    participant Backend as WalletConnect Pay
    participant WebView

    User->>Wallet: Scan QR / Open payment link
    Wallet->>PaySDK: getPaymentOptions(link, accounts)
    PaySDK->>Backend: Fetch payment options
    Backend-->>PaySDK: Payment options + merchant info
    PaySDK-->>Wallet: PaymentOptionsResponse
    Wallet->>User: Display payment options

    User->>Wallet: Select payment option
    Wallet->>PaySDK: getRequiredPaymentActions(paymentId, optionId)
    PaySDK->>Backend: Get signing actions
    Backend-->>PaySDK: Required wallet RPC actions
    PaySDK-->>Wallet: List of actions to sign

    Wallet->>User: Request signature(s)
    User->>Wallet: Approve & sign

    alt Data collection required
        Wallet->>WebView: Load collectDataAction.url in WebView
        WebView->>User: Display data collection form
        User->>WebView: Fill form & accept T&C
        WebView-->>Wallet: IC_COMPLETE message
    end

    Wallet->>PaySDK: confirmPayment(signatures, collectedData)
    PaySDK->>Backend: Submit payment
    Backend-->>PaySDK: Payment status
    PaySDK-->>Wallet: ConfirmPaymentResponse
    Wallet->>User: Show result
```

<Steps>
  <Step title="Get Payment Options" titleSize="h3">
    Retrieve available payment options for a payment link:

    ```dart theme={null}
    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');
    }
    ```
  </Step>

  <Step title="Get Required Payment Actions" titleSize="h3">
    Get the required wallet actions (e.g., transactions to sign) for a selected payment option:

    ```dart theme={null}
    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
    }
    ```

    <Note>
      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](/payments/wallets/token-chain-support/usdt-support).
    </Note>
  </Step>

  <Step title="Collect User Data (If Required)" titleSize="h3">
    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                                         |

    <Info>
      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": "..."}`.
    </Info>

    <Note>
      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.
    </Note>

    <Warning>
      When using the WebView approach, do **not** pass `collectedData` to `confirmPayment()`. The WebView handles data submission directly.
    </Warning>

    ```dart theme={null}
    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                                      |
  </Step>

  <Step title="Confirm Payment" titleSize="h3">
    Confirm a payment with signatures and optional collected data:

    ```dart theme={null}
    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
    }
    ```
  </Step>
</Steps>

## 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`:

```yaml theme={null}
dependencies:
  webview_flutter: ^4.10.0
  url_launcher: ^6.1.0
```

```dart theme={null}
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:

```dart theme={null}
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

```dart theme={null}
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

```dart theme={null}
GetPaymentOptionsRequest({
  required String paymentLink,
  required List<String> accounts,
  @Default(false) bool includePaymentInfo,
})
```

### PaymentOptionsResponse

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

### PaymentResultInfo

```dart theme={null}
class PaymentResultInfo {
  final String txId;               // Transaction ID
  final PayAmount optionAmount;    // Token amount details
}
```

### PaymentInfo

```dart theme={null}
PaymentInfo({
  required PaymentStatus status,
  required PayAmount amount,
  required int expiresAt,
  required MerchantInfo merchant,
  BuyerInfo? buyer,
})
```

### PaymentOption

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

### ConfirmPaymentRequest

```dart theme={null}
ConfirmPaymentRequest({
  required String paymentId,
  required String optionId,
  required List<String> signatures,
  List<CollectDataFieldResult>? collectedData,
  int? maxPollMs,
})
```

### ConfirmPaymentResponse

```dart theme={null}
ConfirmPaymentResponse({
  required PaymentStatus status,
  required bool isFinal,
  int? pollInMs,
})
```

### PaymentStatus

```dart theme={null}
enum PaymentStatus {
  requires_action,
  processing,
  succeeded,
  failed,
  expired,
}
```

### Action & WalletRpcAction

```dart theme={null}
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

```dart theme={null}
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`:

```dart theme={null}
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

```dart theme={null}
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](https://github.com/reown-com/reown_flutter/tree/master/packages/reown_walletkit/example/lib/walletconnect_pay).