> ## 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 - Kotlin > Integrate WalletConnect Pay into your Android 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: A reference Android wallet app demonstrating WalletConnect Pay integration. ## Requirements * **Min SDK**: 23 (Android 6.0) * **Target SDK**: 36 * **JVM Target**: 11 ## Installation Add the WalletConnect Pay SDK to your project's `build.gradle.kts` file: ```kotlin theme={null} dependencies { implementation("com.walletconnect:pay:1.0.0") } ``` The version shown above may not be the latest. Check the [GitHub releases](https://github.com/reown-com/reown-kotlin/releases) for the most recent version. ### JNA Dependency Configuration If you encounter JNA-related errors (e.g., `UnsatisfiedLinkError` or class loading issues), explicitly configure the JNA dependency: ```kotlin theme={null} implementation("com.walletconnect:pay:1.0.0") { exclude(group = "net.java.dev.jna", module = "jna") } implementation("net.java.dev.jna:jna:5.17.0@aar") ``` ## Configuration Initialize the SDK in your `Application` class or before any payment operations: ```kotlin theme={null} import com.walletconnect.pay.Pay import com.walletconnect.pay.WalletConnectPay WalletConnectPay.initialize( Pay.SdkConfig( apiKey = "your-api-key", // Your WalletConnect Pay API key (optional) appId = "your-wcp-id", // Your WCP ID (optional) packageName = "com.your.app" // Your app's package name ) ) ``` ### Configuration Parameters | Parameter | Type | Required | Description | | ------------- | -------- | -------- | ------------------------------- | | `apiKey` | `String` | No\* | Your WalletConnect Pay API key | | `appId` | `String` | No\* | Your WCP ID | | `packageName` | `String` | Yes | Your application's package name | \*Either `apiKey` or `appId` is required for authentication. Don't have a project ID? Create one at the [WalletConnect Dashboard](https://dashboard.walletconnect.com) by signing up and creating a new project. The SDK will throw `IllegalStateException` if already initialized. Call `initialize()` only once. ## Supported Networks & Tokens WalletConnect Pay currently supports the following tokens and networks: | Token | Network | Chain ID | CAIP-2 Format | | ----- | -------- | -------- | -------------- | | USDC | Arbitrum | 42161 | `eip155:42161` | | USDC | Base | 8453 | `eip155:8453` | | USDC | Polygon | 137 | `eip155:137` | | USDC | Ethereum | 1 | `eip155:1` | | USDC | Optimism | 10 | `eip155:10` | | USDC | Monad | 143 | `eip155:143` | | USDC | Celo | 42220 | `eip155:42220` | | USDC | BSC | 56 | `eip155:56` | | EURC | Ethereum | 1 | `eip155:1` | | EURC | Base | 8453 | `eip155:8453` | | USDT0 | Arbitrum | 42161 | `eip155:42161` | | PYUSD | Ethereum | 1 | `eip155:1` | | PYUSD | Arbitrum | 42161 | `eip155:42161` | | USDG | Ethereum | 1 | `eip155:1` | | USDT | Ethereum | 1 | `eip155:1` | | USDT | Polygon | 137 | `eip155:137` | | USDT | BSC | 56 | `eip155:56` | All account addresses must be provided in CAIP-10 format: `eip155::
` Include accounts for all supported networks to maximize payment options for your users. ## Payment Flow The payment flow consists of five main steps: **Get Options -> Get Actions -> Sign Actions -> Collect Data (if required) -> 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 Selected option requires data collection Wallet->>WebView: Load selectedOption.collectData.url 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 ``` ```kotlin theme={null} import com.walletconnect.pay.Pay import com.walletconnect.pay.WalletConnectPay // In your Application class or before payment operations WalletConnectPay.initialize( Pay.SdkConfig( appId = "your-wcp-id", // Your WCP ID packageName = "com.your.app" ) ) // Check if initialized if (WalletConnectPay.isInitialized) { // SDK ready for use } ``` When a user scans a payment QR code or opens a payment link, fetch available payment options: ```kotlin theme={null} val result = WalletConnectPay.getPaymentOptions( paymentLink = "https://pay.walletconnect.com/pay_xxx", accounts = listOf( "eip155:1:0xYourAddress", // Ethereum "eip155:8453:0xYourAddress", // Base "eip155:10:0xYourAddress" // Optimism ) ) result.onSuccess { response -> // Payment metadata val paymentId = response.paymentId val paymentInfo = response.info // Merchant info, amount, expiry // Available payment options val options = response.options options.forEach { option -> println("Option: ${option.id}") println("Amount: ${option.amount.value} ${option.amount.unit}") println("Account: ${option.account}") println("Estimated transactions: ${option.estimatedTxs}") println("Requires IC: ${option.collectData != null}") } }.onFailure { error -> handleError(error) } ``` After the user selects a payment option, get the wallet RPC actions needed to complete the payment: ```kotlin theme={null} val actionsResult = WalletConnectPay.getRequiredPaymentActions( paymentId = paymentId, optionId = selectedOption.id ) actionsResult.onSuccess { actions -> actions.forEach { action -> when (action) { is Pay.RequiredAction.WalletRpc -> { val rpcAction = action.action // rpcAction.chainId - e.g., "eip155:8453" // rpcAction.method - e.g., "eth_signTypedData_v4" or "personal_sign" // rpcAction.params - JSON string with signing parameters } } } }.onFailure { error -> handleError(error) } ``` Sign each action using your wallet's signing implementation: ```kotlin theme={null} val signatures = actions.map { action -> when (action) { is Pay.RequiredAction.WalletRpc -> { val rpc = action.action when (rpc.method) { "eth_signTypedData_v4" -> wallet.signTypedData(rpc.chainId, rpc.params) "personal_sign" -> wallet.personalSign(rpc.chainId, rpc.params) "eth_sendTransaction" -> wallet.sendTransaction(rpc.chainId, rpc.params) else -> throw UnsupportedOperationException("Unsupported 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 `rpc.method` (or `action.action.method`) and dispatch to the appropriate handler. For full implementation guidance, see [USDT support](/payments/wallets/token-chain-support/usdt-support). Signatures must be in the same order as the actions array. Some payments require collecting additional user information. Check for `collectData` on the selected payment option: ## 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=` 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. ```kotlin theme={null} // Check per-option data collection requirement after user selects an option selectedOption.collectData?.let { collectAction -> val url = collectAction.url if (url != null) { // Build prefill URL with known user data // Use the "required" list from collectAction.schema to determine which fields to prefill val prefillJson = JSONObject().apply { put("fullName", "John Doe") put("dob", "1990-01-15") put("pobAddress", "123 Main St, New York, NY 10001") }.toString() val prefillBase64 = Base64.encodeToString( prefillJson.toByteArray(), Base64.NO_WRAP or Base64.URL_SAFE ) val webViewUrl = Uri.parse(url).buildUpon() .appendQueryParameter("prefill", prefillBase64) .build().toString() // Show WebView for this specific option — see WebView Implementation section below showWebView(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 | Submit the signatures and collected data to complete the payment: ```kotlin theme={null} val confirmResult = WalletConnectPay.confirmPayment( paymentId = paymentId, optionId = selectedOption.id, signatures = signatures, collectedData = collectedData // Optional, if collectDataAction was present ) confirmResult.onSuccess { response -> when (response.status) { Pay.PaymentStatus.SUCCEEDED -> { // Payment completed successfully } Pay.PaymentStatus.PROCESSING -> { // Payment is being processed // The SDK automatically polls until final status } Pay.PaymentStatus.FAILED -> { // Payment failed } Pay.PaymentStatus.EXPIRED -> { // Payment expired } Pay.PaymentStatus.REQUIRES_ACTION -> { // Additional action required } Pay.PaymentStatus.CANCELLED -> { // Payment cancelled by user } } }.onFailure { error -> handleError(error) } ``` ## WebView Implementation When a selected option has `collectData.url` present, display the URL in a WebView. The WebView handles form rendering, validation, and T\&C acceptance. ```kotlin theme={null} import android.webkit.JavascriptInterface import android.webkit.WebView import android.webkit.WebViewClient import android.webkit.WebResourceRequest import android.content.Intent import android.net.Uri import android.util.Base64 import androidx.compose.runtime.Composable import androidx.compose.ui.viewinterop.AndroidView import org.json.JSONObject @Composable fun PayDataCollectionWebView( url: String, onComplete: () -> Unit, onError: (String) -> Unit ) { AndroidView(factory = { context -> WebView(context).apply { settings.javaScriptEnabled = true settings.domStorageEnabled = true settings.allowFileAccess = false addJavascriptInterface( object { @JavascriptInterface fun onDataCollectionComplete(json: String) { val message = JSONObject(json) when (message.optString("type")) { "IC_COMPLETE" -> onComplete() "IC_ERROR" -> onError( message.optString("error", "Unknown error") ) } } }, "AndroidWallet" ) webViewClient = object : WebViewClient() { override fun shouldOverrideUrlLoading( view: WebView?, request: WebResourceRequest? ): Boolean { val requestUrl = request?.url?.toString() ?: return false // Open external links (T&C, Privacy Policy) in system browser if (!requestUrl.contains("pay.walletconnect.com")) { context.startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(requestUrl))) return true } return false } } loadUrl(url) } }) } fun buildPrefillUrl(baseUrl: String, prefillData: Map): String { if (prefillData.isEmpty()) return baseUrl val json = JSONObject(prefillData).toString() val base64 = Base64.encodeToString( json.toByteArray(), Base64.NO_WRAP or Base64.URL_SAFE ) return Uri.parse(baseUrl).buildUpon() .appendQueryParameter("prefill", base64) .build().toString() } ``` ## Complete Example Here's a complete implementation example using a ViewModel: ```kotlin theme={null} import com.walletconnect.pay.Pay import com.walletconnect.pay.WalletConnectPay import kotlinx.coroutines.launch class PaymentViewModel : ViewModel() { fun initializeSdk() { WalletConnectPay.initialize( Pay.SdkConfig( appId = "your-wcp-id", // Your WCP ID packageName = "com.your.app" ) ) } fun processPayment(paymentLink: String, walletAddress: String) { viewModelScope.launch { // Step 1: Get payment options val optionsResult = WalletConnectPay.getPaymentOptions( paymentLink = paymentLink, accounts = listOf( "eip155:1:$walletAddress", "eip155:8453:$walletAddress", "eip155:10:$walletAddress" ) ) optionsResult.onSuccess { response -> val paymentId = response.paymentId val selectedOption = response.options.first() // Step 2: Get required actions val actionsResult = WalletConnectPay.getRequiredPaymentActions( paymentId = paymentId, optionId = selectedOption.id ) actionsResult.onSuccess { actions -> // Step 3: Sign actions val signatures = signActions(actions) // Step 4: Collect data if required for selected option (via WebView) selectedOption.collectData?.url?.let { webViewUrl -> // Show WebView and wait for IC_COMPLETE showDataCollectionWebView(webViewUrl) return@launch // Resume after WebView completes } // Step 5: Confirm payment val confirmResult = WalletConnectPay.confirmPayment( paymentId = paymentId, optionId = selectedOption.id, signatures = signatures ) confirmResult.onSuccess { confirmation -> handlePaymentStatus(confirmation.status) }.onFailure { error -> handleError(error) } }.onFailure { error -> handleError(error) } }.onFailure { error -> handleError(error) } } } private suspend fun signActions(actions: List): List { return actions.map { action -> when (action) { is Pay.RequiredAction.WalletRpc -> { // Implement signing logic using your wallet signWithWallet(action.action) } } } } private fun handlePaymentStatus(status: Pay.PaymentStatus) { when (status) { Pay.PaymentStatus.SUCCEEDED -> showSuccess() Pay.PaymentStatus.PROCESSING -> showProcessing() Pay.PaymentStatus.FAILED -> showFailure() Pay.PaymentStatus.EXPIRED -> showExpired() Pay.PaymentStatus.REQUIRES_ACTION -> { /* Handle additional actions */ } Pay.PaymentStatus.CANCELLED -> showCancelled() } } } ``` ## API Reference ### WalletConnectPay Main entry point for the Pay SDK (singleton object). #### Properties | Property | Type | Description | | --------------- | --------- | ------------------------------------ | | `isInitialized` | `Boolean` | Whether the SDK has been initialized | #### Methods | Method | Description | | ------------------------------------------------- | -------------------------------- | | `initialize(config: Pay.SdkConfig)` | Initialize the SDK | | `getPaymentOptions(paymentLink, accounts)` | Get available payment options | | `getRequiredPaymentActions(paymentId, optionId)` | Get actions requiring signatures | | `confirmPayment(paymentId, optionId, signatures)` | Confirm and finalize payment | ## Data Models ### Pay.PaymentOptionsResponse ```kotlin theme={null} data class PaymentOptionsResponse( val info: PaymentInfo?, // Payment metadata val options: List, // Available payment options val paymentId: String, // Unique payment identifier val collectDataAction: CollectDataAction?, // Data collection requirements val resultInfo: PaymentResultInfo? // Transaction result details (present when payment already completed) ) data class PaymentResultInfo( val txId: String, // Transaction ID val optionAmount: Amount // Token amount details ) ``` ### Pay.PaymentInfo ```kotlin theme={null} data class PaymentInfo( val status: PaymentStatus, val amount: Amount, val expiresAt: Long, // Unix timestamp val merchant: MerchantInfo ) data class MerchantInfo( val name: String, val iconUrl: String? ) ``` ### Pay.PaymentOption ```kotlin theme={null} data class PaymentOption( val id: String, val amount: Amount, val account: String, // CAIP-10 account that can pay val estimatedTxs: Int?, // Estimated number of transactions val collectData: CollectDataAction? // Per-option data collection (null if not required) ) ``` ### Pay.Amount ```kotlin theme={null} data class Amount( val value: String, val unit: String, val display: AmountDisplay? ) data class AmountDisplay( val assetSymbol: String, val assetName: String, val decimals: Int, val iconUrl: String?, val networkName: String?, val networkIconUrl: String? ) ``` ### Pay.WalletRpcAction ```kotlin theme={null} data class WalletRpcAction( val chainId: String, // CAIP-2 chain ID (e.g., "eip155:8453") val method: String, // RPC method (e.g., "eth_signTypedData_v4", "eth_sendTransaction") val params: String // JSON-encoded parameters ) ``` ### Pay.RequiredAction ```kotlin theme={null} sealed class RequiredAction { data class WalletRpc(val action: WalletRpcAction) : RequiredAction() } ``` ### Pay.CollectDataAction ```kotlin theme={null} data class CollectDataAction( val url: String, // WebView URL for data collection val schema: String? // JSON schema describing required fields ) ``` ### Pay.ConfirmPaymentResponse ```kotlin theme={null} data class ConfirmPaymentResponse( val status: PaymentStatus, val isFinal: Boolean, val pollInMs: Long?, val info: PaymentResultInfo? // Transaction result details (present on success) ) ``` ### Pay.PaymentStatus | Status | Description | | ----------------- | ------------------------- | | `REQUIRES_ACTION` | Additional action needed | | `PROCESSING` | Payment in progress | | `SUCCEEDED` | Payment completed | | `FAILED` | Payment failed | | `EXPIRED` | Payment expired | | `CANCELLED` | Payment cancelled by user | ## Error Handling The SDK provides typed errors for different failure scenarios: ### GetPaymentOptionsError | Error | Description | | -------------------- | --------------------------- | | `InvalidPaymentLink` | Invalid payment link format | | `PaymentExpired` | Payment has expired | | `PaymentNotFound` | Payment ID doesn't exist | | `InvalidRequest` | Invalid request parameters | | `InvalidAccount` | Invalid account format | | `ComplianceFailed` | Compliance check failed | | `Http` | Network error | | `InternalError` | Server error | ### GetPaymentRequestError | Error | Description | | ----------------- | ----------------------------- | | `OptionNotFound` | Selected option doesn't exist | | `PaymentNotFound` | Payment ID doesn't exist | | `InvalidAccount` | Invalid account format | | `Http` | Network error | ### ConfirmPaymentError | Error | Description | | ------------------ | ----------------------------- | | `PaymentNotFound` | Payment ID doesn't exist | | `PaymentExpired` | Payment has expired | | `InvalidOption` | Invalid option ID | | `InvalidSignature` | Signature verification failed | | `RouteExpired` | Payment route expired | | `Http` | Network error | ### Example Error Handling ```kotlin theme={null} val result = WalletConnectPay.getPaymentOptions(paymentLink, accounts) result.onFailure { error -> when (error) { is Pay.GetPaymentOptionsError.InvalidPaymentLink -> { showError("Invalid payment link") } is Pay.GetPaymentOptionsError.PaymentExpired -> { showError("Payment has expired") } is Pay.GetPaymentOptionsError.PaymentNotFound -> { showError("Payment not found") } is Pay.GetPaymentOptionsError.InvalidAccount -> { showError("Invalid account address") } is Pay.GetPaymentOptionsError.ComplianceFailed -> { showError("Compliance check failed") } is Pay.GetPaymentOptionsError.Http -> { showError("Network error: ${error.message}") } else -> { showError("An error occurred: ${error.message}") } } } ``` ## Best Practices 1. **Initialize once**: Call `initialize()` only once, typically in `Application.onCreate()` 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. **Thread Safety**: Events are delivered on IO dispatcher; update UI on main thread 7. **WebView Data Collection**: When `selectedOption.collectData?.url` is present, display the URL in a WebView rather than building native forms. The WebView handles form rendering, validation, and T\&C acceptance. 8. **Per-Option Data Collection**: When displaying payment options, check each option's `collectData` field. Show a visual indicator (e.g., "Info required" badge) on options that require data collection. Only open the WebView when the user selects an option with `collectData` present — use the option's `collectData.url` which is already scoped to that option's account.