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
| Parameter | Type | Required | Description |
|---|
apiKey | String | No* | Your WalletConnect Pay API key |
appId | String | No* | Your WalletConnect Project ID |
packageName | String | Yes | Your application’s package name |
*Either apiKey or appId is required for authentication.
The SDK will throw IllegalStateException if already initialized. Call initialize() only once.
Supported Networks
WalletConnect Pay currently supports USDC payments on the following networks:
| Network | Chain ID | CAIP-2 Format |
|---|
| Ethereum | 1 | eip155:1 |
| Base | 8453 | eip155:8453 |
| Optimism | 10 | eip155:10 |
| Polygon | 137 | eip155:137 |
| Arbitrum | 42161 | eip155: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
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
}
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}")
}
// Check if data collection is required
val collectDataAction = response.collectDataAction
}.onFailure { error ->
handleError(error)
}
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)
}
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.
Collect User Data (If Required)
Some payments require collecting additional user information. Check for collectDataAction in the payment options response:response.collectDataAction?.let { collectAction ->
val collectedData = collectAction.fields.map { field ->
val value = when (field.fieldType) {
Pay.CollectDataFieldType.TEXT -> getUserTextInput(field.name)
Pay.CollectDataFieldType.DATE -> getUserDateInput(field.name) // Format: YYYY-MM-DD
}
Pay.CollectDataFieldResult(
id = field.id,
value = value
)
}
}
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
}
}
}.onFailure { error ->
handleError(error)
}
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
val collectedData = response.collectDataAction?.let {
collectUserData(it.fields)
}
// Step 5: Confirm payment
val confirmResult = WalletConnectPay.confirmPayment(
paymentId = paymentId,
optionId = selectedOption.id,
signatures = signatures,
collectedData = collectedData
)
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 */ }
}
}
}
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, collectedData?) | 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
)
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
)
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.ConfirmPaymentResponse
data class ConfirmPaymentResponse(
val status: PaymentStatus,
val isFinal: Boolean,
val pollInMs: Long?
)
Pay.PaymentStatus
| Status | Description |
|---|
REQUIRES_ACTION | Additional action needed |
PROCESSING | Payment in progress |
SUCCEEDED | Payment completed |
FAILED | Payment failed |
EXPIRED | Payment expired |
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
-
Initialize once: Call
initialize() only once, typically in Application.onCreate()
-
Account Format: Always use CAIP-10 format for accounts:
eip155:{chainId}:{address}
-
Multiple Chains: Provide accounts for all supported chains to maximize payment options
-
Signature Order: Maintain the same order of signatures as the actions array
-
Error Handling: Always handle errors gracefully and show appropriate user feedback
-
Thread Safety: Events are delivered on IO dispatcher; update UI on main thread