Skip to main content
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.

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

Configuration

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-project-id",      // Your WalletConnect Project ID (optional)
        packageName = "com.your.app"    // Your app's package name
    )
)

Configuration Parameters

ParameterTypeRequiredDescription
apiKeyStringNo*Your WalletConnect Pay API key
appIdStringNo*Your WalletConnect Project ID
packageNameStringYesYour 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

WalletConnect Pay currently supports USDC payments on the following networks:
NetworkChain IDCAIP-2 Format
Ethereum1eip155:1
Base8453eip155:8453
Optimism10eip155:10
Polygon137eip155:137
Arbitrum42161eip155:42161
All account addresses must be provided in CAIP-10 format: eip155:<chainId>:<address>
Support for all EVM chains, Solana, and additional native and non-native assets is coming soon. 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
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-project-id",     // Your WalletConnect Project 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

Get Required Actions

After the user selects a payment option, 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)
}
4

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)
                else -> throw UnsupportedOperationException("Unsupported method: ${rpc.method}")
            }
        }
    }
}
Signatures must be in the same order as the actions array.
5

Collect User Data (If Required)

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.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 collectDataoption.collectDataBehavior
presentpresentOption requires IC — use option.collectData.url
presentnullOption does NOT require IC (others might) — skip IC for this option
nullnullNo 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.
// 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 TypePayloadDescription
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

PlatformBridge NameHandler
Kotlin (Android)AndroidWallet@JavascriptInterface onDataCollectionComplete(json: String)
Swift (iOS)payDataCollectionCompleteWKScriptMessageHandler.didReceive(message:)
FlutterReactNativeWebView (injected via JS bridge)JavaScriptChannel.onMessageReceived
React NativeReactNativeWebView (native)WebView.onMessage prop
6

Confirm Payment

Submit the signatures and collected data to complete the payment:
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.
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, String>): 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:
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-project-id",     // Your WalletConnect Project 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<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

PropertyTypeDescription
isInitializedBooleanWhether the SDK has been initialized

Methods

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

StatusDescription
REQUIRES_ACTIONAdditional action needed
PROCESSINGPayment in progress
SUCCEEDEDPayment completed
FAILEDPayment failed
EXPIREDPayment expired
CANCELLEDPayment cancelled by user

Error Handling

The SDK provides typed errors for different failure scenarios:

GetPaymentOptionsError

ErrorDescription
InvalidPaymentLinkInvalid payment link format
PaymentExpiredPayment has expired
PaymentNotFoundPayment ID doesn’t exist
InvalidRequestInvalid request parameters
InvalidAccountInvalid account format
ComplianceFailedCompliance check failed
HttpNetwork error
InternalErrorServer error

GetPaymentRequestError

ErrorDescription
OptionNotFoundSelected option doesn’t exist
PaymentNotFoundPayment ID doesn’t exist
InvalidAccountInvalid account format
HttpNetwork error

ConfirmPaymentError

ErrorDescription
PaymentNotFoundPayment ID doesn’t exist
PaymentExpiredPayment has expired
InvalidOptionInvalid option ID
InvalidSignatureSignature verification failed
RouteExpiredPayment route expired
HttpNetwork 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.