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:

Sample Wallet - Kotlin

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:

dependencies {
    implementation("com.walletconnect:pay:1.0.0")
}

The version shown above may not be the latest. Check the GitHub 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:

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")

Initialization

Initialize the SDK in your Application class or before any payment operations:

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 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:<chainId>:<address>

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 -> Collect Data (if required) -> Get Actions -> Sign Actions -> Confirm Payment

1. Initialize the SDK

   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
   }
   
2. Get Payment Options

   When a user scans a payment QR code or opens a payment link, fetch available payment options:

   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)
   }
   
3. Collect User Data (If Required)

   After the user selects an option, check for collectData on it. If present, collect the data before fetching the required actions.

   Embedded Data Collection Form

   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.

   Recommended Flow

   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, load selectedOption.collectData.url in the embedded form
   5. 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.
   6. Listen for completion messages: IC_COMPLETE (success) or IC_ERROR (failure)
   7. 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

   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

   Form URL parameters

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

   Customizing the form appearance

   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.

   // 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()
           // Encode prefill as base64url (URL-safe, no padding)
           val prefillBase64 = Base64.encodeToString(
               prefillJson.toByteArray(),
               Base64.NO_WRAP or Base64.URL_SAFE or Base64.NO_PADDING
           )
           val webViewUrl = Uri.parse(url).buildUpon()
               .appendQueryParameter("prefill", prefillBase64)
               // Optional appearance params (see "Form URL parameters"):
               .appendQueryParameter("theme", "dark") // "light" | "dark"
               // themeVariables is a base64url string exported from the Pay Dashboard:
               // .appendQueryParameter("themeVariables", themeVariables)
               .build().toString()
   
           // Show WebView for this specific option — see Data Collection 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

4. Get Required Actions

   After the user selects a payment option (and any required data collection has completed), get the wallet RPC actions needed to complete the payment:

   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)
   }
   
5. Sign Actions

   Sign each action using your wallet’s signing implementation:

   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.

   Signatures must be in the same order as the actions array.

6. Confirm Payment

   Submit the signatures to complete the payment:

   val confirmResult = WalletConnectPay.confirmPayment(
       paymentId = paymentId,
       optionId = selectedOption.id,
       signatures = signatures
   )
   
   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)
   }
   

Data Collection Implementation

When selectedOption.collectData.url is present, display the URL in a WebView. The WebView handles form rendering, validation, and T&C acceptance.

Data Collection Best Practices

• 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 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 buildFormUrl(
    baseUrl: String,
    prefillData: Map<String, String> = emptyMap(),
    theme: String? = null,            // "light" or "dark"
    themeVariables: String? = null    // base64url string exported from the Pay Dashboard
): String {
    val builder = Uri.parse(baseUrl).buildUpon()
    if (prefillData.isNotEmpty()) {
        val prefill = Base64.encodeToString(
            JSONObject(prefillData).toString().toByteArray(),
            Base64.NO_WRAP or Base64.URL_SAFE or Base64.NO_PADDING
        )
        builder.appendQueryParameter("prefill", prefill)
    }
    theme?.let { builder.appendQueryParameter("theme", it) }
    themeVariables?.let { builder.appendQueryParameter("themeVariables", it) }
    return builder.build().toString()
}

Complete Example

Here’s a complete implementation example using a ViewModel:

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: Collect data if required for selected option (via WebView).
                // IC must happen BEFORE fetching the required actions — the WebView
                // submits the data directly to the backend.
                selectedOption.collectData?.url?.let { webViewUrl ->
                    // Show WebView and wait for IC_COMPLETE
                    showDataCollectionWebView(webViewUrl)
                    return@launch // Resume after WebView completes
                }

                // Step 3: Get required actions
                val actionsResult = WalletConnectPay.getRequiredPaymentActions(
                    paymentId = paymentId,
                    optionId = selectedOption.id
                )

                actionsResult.onSuccess { actions ->
                    // Step 4: Sign actions
                    val signatures = signActions(actions)

                    // 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<Pay.RequiredAction>): List<String> {
        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

data class PaymentOptionsResponse(
    val info: PaymentInfo?,              // Payment metadata
    val options: List<PaymentOption>,    // 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

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

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

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

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

sealed class RequiredAction {
    data class WalletRpc(val action: WalletRpcAction) : RequiredAction()
}

Pay.CollectDataAction

data class CollectDataAction(
    val url: String,               // WebView URL for data collection
    val schema: String?            // JSON schema describing required fields
)

Pay.ConfirmPaymentResponse

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

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.