WalletConnect Pay SDK - Swift

Integrate WalletConnect Pay into your iOS 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 - Swift

A reference iOS wallet app demonstrating WalletConnect Pay integration.

Requirements

• iOS 13.0+
• Swift 5.7+
• Xcode 14.0+

Installation

Swift Package Manager

Add WalletConnectPay to your Package.swift:

dependencies: [
    .package(url: "https://github.com/reown-com/reown-swift", from: "1.0.0")
]

Then add WalletConnectPay to your target dependencies:

.target(
    name: "YourApp",
    dependencies: ["WalletConnectPay"]
)

The version shown above may not be the latest. Check the GitHub releases for the most recent version.

Configuration

Configure the Pay client during app initialization, typically in your AppDelegate or SceneDelegate:

import WalletConnectPay

func application(_ application: UIApplication, didFinishLaunchingWithOptions...) {
    // Option 1: With appId (recommended for wallets)
    WalletConnectPay.configure(
        appId: "your-wcp-id",
        logging: true
    )
    
    // Option 2: With API key
    WalletConnectPay.configure(
        apiKey: "your-pay-api-key"
    )
}

Configuration Parameters

Parameter	Type	Required	Default	Description
apiKey	String?	No*	nil	Your WalletConnect Pay API key
appId	String?	No*	nil	Your WCP ID
baseUrl	String	No	Production URL	Custom API URL
logging	Bool	No	false	Enable debug logging

At least one of apiKey or appId must be provided.

Don’t have a project ID? Create one at the WalletConnect Dashboard by signing up and creating a new project.

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}

Include accounts for all supported networks to maximize payment options for your users.

Detecting Payment Links

The isPaymentLink utility method detects WalletConnect Pay links by checking for:

• pay. hosts (e.g., pay.walletconnect.com)
• pay= parameter in WalletConnect URIs
• pay_ prefix in bare payment IDs

func isPaymentLink(_ string: String) -> Bool {
    let lower = string.lowercased()
    return lower.contains("pay.") ||
           lower.contains("pay=") ||
           lower.contains("pay_")
}

Payment Flow

The payment flow consists of four main steps:

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

1. Get Payment Options

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

   let paymentLink = "https://pay.walletconnect.com/?pid=pay_abc123..."
   
   // Provide all user's EVM accounts in CAIP-10 format
   let accounts = [
       "eip155:1:\(walletAddress)",      // Ethereum Mainnet
       "eip155:137:\(walletAddress)",    // Polygon
       "eip155:8453:\(walletAddress)",   // Base
       "eip155:42161:\(walletAddress)"   // Arbitrum
   ]
   
   do {
       let response = try await WalletConnectPay.instance.getPaymentOptions(
           paymentLink: paymentLink,
           accounts: accounts
       )
       
       // Display merchant info
       if let info = response.info {
           print("Merchant: \(info.merchant.name)")
           print("Amount: \(info.amount.display.assetSymbol) \(info.amount.value)")
       }
       
       // Show available payment options to user
       for option in response.options {
           print("Pay with \(option.amount.display.assetSymbol) on \(option.amount.display.networkName ?? "Unknown")")
       }
       
       // Check which options require data collection
       for option in response.options {
           if option.collectData != nil {
               print("Option \(option.id) requires info capture")
           }
       }
       
   } catch {
       print("Failed to get payment options: \(error)")
   }
   
2. Get Required Actions

   After the user selects a payment option, get the signing actions:

   let actions = try await WalletConnectPay.instance.getRequiredPaymentActions(
       paymentId: response.paymentId,
       optionId: selectedOption.id
   )
   
3. Sign Actions

   Each action contains a walletRpc describing the RPC call to execute. Your wallet must check the method field and dispatch accordingly — for example, a payment option may require an eth_sendTransaction to approve a token allowance followed by an eth_signTypedData_v4 to sign Permit2 typed data.

   var signatures: [String] = []
   
   for action in actions {
       let rpc = action.walletRpc
   
       // rpc.chainId - The chain to execute on (e.g., "eip155:8453")
       // rpc.method  - The RPC method (e.g., "eth_signTypedData_v4", "eth_sendTransaction")
       // rpc.params  - JSON string with method-specific parameters
   
       let result: String
       switch rpc.method {
       case "eth_signTypedData_v4":
           let paramsData = rpc.params.data(using: .utf8)!
           let params = try JSONSerialization.jsonObject(with: paramsData) as! [Any]
           let typedDataJson = params[1] as! String
           result = try await yourWallet.signTypedData(
               typedData: typedDataJson,
               address: walletAddress,
               chainId: rpc.chainId
           )
       case "eth_sendTransaction":
           result = try await yourWallet.sendTransaction(
               params: rpc.params,
               chainId: rpc.chainId
           )
       case "personal_sign":
           result = try await yourWallet.personalSign(
               params: rpc.params,
               chainId: rpc.chainId
           )
       default:
           throw PaymentError.unsupportedMethod(rpc.method)
       }
   
       signatures.append(result)
   }
   

   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.

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

4. Collect User Data (If Required)

   If the selected option has collectData set, you must collect user information before confirming:

   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

   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
   if let collectData = selectedOption.collectData, let url = collectData.url {
       // Build prefill URL with known user data
       // Use the "required" list from collectData.schema to determine which fields to prefill
       let prefillData: [String: String] = [
           "fullName": "John Doe",
           "dob": "1990-01-15",
           "pobAddress": "123 Main St, New York, NY 10001"
       ]
       let jsonData = try JSONSerialization.data(withJSONObject: prefillData)
       let prefillBase64 = jsonData.base64EncodedString()
       var components = URLComponents(string: url)!
       var queryItems = components.queryItems ?? []
       queryItems.append(URLQueryItem(name: "prefill", value: prefillBase64))
       components.queryItems = queryItems
       let webViewUrl = components.string!
   
       // Show WebView for this specific option — see WebView Implementation section below
       showWebView(url: 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

5. Confirm Payment

   Submit the signatures and collected data to complete the payment:

   let result = try await WalletConnectPay.instance.confirmPayment(
       paymentId: response.paymentId,
       optionId: selectedOption.id,
       signatures: signatures,
       collectedData: collectedData,
       maxPollMs: 60000  // Wait up to 60 seconds for confirmation
   )
   
   switch result.status {
   case .succeeded:
       print("Payment successful!")
   case .processing:
       print("Payment is being processed...")
   case .failed:
       print("Payment failed")
   case .expired:
       print("Payment expired")
   case .requiresAction:
       print("Additional action required")
   case .cancelled:
       print("Payment cancelled")
   }
   

WebView Implementation

When a selected option has collectData.url present, display the URL in a WKWebView. The WebView handles form rendering, validation, and T&C acceptance.

import WebKit
import SwiftUI

struct PayDataCollectionWebView: UIViewRepresentable {
    let url: URL
    let onComplete: () -> Void
    let onError: (String) -> Void

    func makeCoordinator() -> Coordinator {
        Coordinator(onComplete: onComplete, onError: onError)
    }

    func makeUIView(context: Context) -> WKWebView {
        let config = WKWebViewConfiguration()
        config.userContentController.add(
            context.coordinator,
            name: "payDataCollectionComplete"
        )

        let webView = WKWebView(frame: .zero, configuration: config)
        webView.navigationDelegate = context.coordinator
        webView.load(URLRequest(url: url))
        return webView
    }

    func updateUIView(_ uiView: WKWebView, context: Context) {}

    class Coordinator: NSObject, WKScriptMessageHandler, WKNavigationDelegate {
        let onComplete: () -> Void
        let onError: (String) -> Void

        init(onComplete: @escaping () -> Void, onError: @escaping (String) -> Void) {
            self.onComplete = onComplete
            self.onError = onError
        }

        func userContentController(
            _ userContentController: WKUserContentController,
            didReceive message: WKScriptMessage
        ) {
            guard let body = message.body as? String,
                  let data = body.data(using: .utf8),
                  let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
                  let type = json["type"] as? String else { return }

            DispatchQueue.main.async {
                switch type {
                case "IC_COMPLETE":
                    self.onComplete()
                case "IC_ERROR":
                    let error = json["error"] as? String ?? "Unknown error"
                    self.onError(error)
                default:
                    break
                }
            }
        }

        func webView(
            _ webView: WKWebView,
            decidePolicyFor navigationAction: WKNavigationAction,
            decisionHandler: @escaping (WKNavigationActionPolicy) -> Void
        ) {
            guard let url = navigationAction.request.url else {
                decisionHandler(.allow)
                return
            }
            // Open external links (T&C, Privacy Policy) in Safari
            if let host = url.host, !host.contains("pay.walletconnect.com") {
                UIApplication.shared.open(url)
                decisionHandler(.cancel)
                return
            }
            decisionHandler(.allow)
        }
    }
}

func buildPrefillUrl(baseUrl: String, prefillData: [String: String]) -> String {
    guard !prefillData.isEmpty,
          let jsonData = try? JSONSerialization.data(withJSONObject: prefillData) else {
        return baseUrl
    }
    let base64 = jsonData.base64EncodedString()
    var components = URLComponents(string: baseUrl)!
    var queryItems = components.queryItems ?? []
    queryItems.append(URLQueryItem(name: "prefill", value: base64))
    components.queryItems = queryItems
    return components.string ?? baseUrl
}

Complete Example

Here’s a complete implementation example:

import WalletConnectPay

class PaymentManager {
    
    func processPayment(
        paymentLink: String,
        walletAddress: String,
        signer: YourSignerProtocol
    ) async throws {
        
        // 1. Get payment options
        let accounts = [
            "eip155:1:\(walletAddress)",
            "eip155:137:\(walletAddress)",
            "eip155:8453:\(walletAddress)"
        ]
        
        let optionsResponse = try await WalletConnectPay.instance.getPaymentOptions(
            paymentLink: paymentLink,
            accounts: accounts
        )
        
        guard !optionsResponse.options.isEmpty else {
            throw PaymentError.noOptionsAvailable
        }
        
        // 2. Let user select an option (simplified - use first option)
        let selectedOption = optionsResponse.options[0]
        
        // 3. Get required actions
        let actions = try await WalletConnectPay.instance.getRequiredPaymentActions(
            paymentId: optionsResponse.paymentId,
            optionId: selectedOption.id
        )
        
        // 4. Sign all actions
        var signatures: [String] = []
        for action in actions {
            let signature = try await signAction(
                action: action,
                walletAddress: walletAddress,
                signer: signer
            )
            signatures.append(signature)
        }
        
        // 5. Collect data via WebView if required for selected option
        if let collectData = selectedOption.collectData, let url = collectData.url {
            // Show WebView and wait for IC_COMPLETE message
            try await showDataCollectionWebView(url: url)
        }

        // 6. Confirm payment
        let result = try await WalletConnectPay.instance.confirmPayment(
            paymentId: optionsResponse.paymentId,
            optionId: selectedOption.id,
            signatures: signatures
        )
        
        switch result.status {
        case .succeeded:
            break // Success
        case .cancelled:
            throw PaymentError.paymentCancelled
        default:
            throw PaymentError.paymentFailed(result.status)
        }
    }

    private func signAction(
        action: Action,
        walletAddress: String,
        signer: YourSignerProtocol
    ) async throws -> String {
        let rpc = action.walletRpc

        switch rpc.method {
        case "eth_signTypedData_v4":
            guard let paramsData = rpc.params.data(using: .utf8),
                  let params = try JSONSerialization.jsonObject(with: paramsData) as? [Any],
                  params.count >= 2,
                  let typedDataJson = params[1] as? String else {
                throw PaymentError.invalidParams
            }
            return try await signer.signTypedData(
                data: typedDataJson,
                address: walletAddress
            )
        case "eth_sendTransaction":
            return try await signer.sendTransaction(
                params: rpc.params,
                chainId: rpc.chainId
            )
        case "personal_sign":
            return try await signer.personalSign(
                params: rpc.params,
                address: walletAddress
            )
        default:
            throw PaymentError.unsupportedMethod(rpc.method)
        }
    }
}

Deep Link Handling

To handle payment links opened from outside your app:

// In SceneDelegate or AppDelegate
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else { return }
    
    if isPaymentLink(url.absoluteString) {
        startPaymentFlow(paymentLink: url.absoluteString)
    }
}

QR Code Scanning

Payment links can be encoded as QR codes. Use the isPaymentLink utility for detection:

func handleScannedQR(_ content: String) {
    if isPaymentLink(content) {
        // WalletConnect Pay QR code
        startPaymentFlow(paymentLink: content)
    }
}

Error Handling

The SDK throws specific error types for different failure scenarios:

GetPaymentOptionsError

Error	Description
.paymentNotFound	Payment ID doesn’t exist
.paymentExpired	Payment has expired
.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

API Reference

WalletConnectPay

Static configuration class for the Pay SDK.

Method	Description
configure(apiKey:appId:baseUrl:logging:)	Initialize the SDK with your credentials
instance	Access the shared PayClient instance

PayClient

Main client for payment operations.

Method	Description
getPaymentOptions(paymentLink:accounts:includePaymentInfo:)	Fetch available payment options
getRequiredPaymentActions(paymentId:optionId:)	Get signing actions for a payment option
confirmPayment(paymentId:optionId:signatures:maxPollMs:)	Confirm and execute the payment

Data Types

PaymentOptionsResponse

struct PaymentOptionsResponse {
    let paymentId: String              // Unique payment identifier
    let info: PaymentInfo?             // Merchant and amount details
    let options: [PaymentOption]       // Available payment methods
    let collectData: CollectDataAction? // Required user data fields (travel rule)
    let resultInfo: PaymentResultInfo? // Transaction result details (present when payment already completed)
}

struct PaymentResultInfo {
    let txId: String                   // Transaction ID
    let optionAmount: PayAmount        // Token amount details
}

PaymentInfo

struct PaymentInfo {
    let status: PaymentStatus          // Current payment status
    let amount: PayAmount              // Requested payment amount
    let expiresAt: Int64               // Expiration timestamp
    let merchant: MerchantInfo         // Merchant details
    let buyer: BuyerInfo?              // Buyer info if available
}

PaymentOption

struct PaymentOption {
    let id: String                     // Option identifier
    let amount: PayAmount              // Amount in this asset
    let etaS: Int64                    // Estimated time to complete (seconds)
    let actions: [Action]              // Required signing actions
    let collectData: CollectDataAction? // Per-option data collection (nil if not required)
}

PayAmount

struct PayAmount {
    let unit: String                   // Asset unit (e.g., "USDC")
    let value: String                  // Raw value in smallest unit
    let display: AmountDisplay         // Human-readable display info
}

struct AmountDisplay {
    let assetSymbol: String            // Token symbol (e.g., "USDC")
    let assetName: String              // Token name (e.g., "USD Coin")
    let decimals: Int64                // Token decimals
    let iconUrl: String?               // Token icon URL
    let networkName: String?           // Network name (e.g., "Base")
}

Action & WalletRpcAction

struct Action {
    let walletRpc: WalletRpcAction     // RPC call to sign
}

struct WalletRpcAction {
    let chainId: String                // Chain ID (e.g., "eip155:8453")
    let method: String                 // RPC method (e.g., "eth_signTypedData_v4", "eth_sendTransaction")
    let params: String                 // JSON-encoded parameters
}

CollectDataAction & CollectDataField

struct CollectDataAction {
    let url: String                    // WebView URL for data collection
    let schema: String?                // JSON schema describing required fields
}

ConfirmPaymentResultResponse

struct ConfirmPaymentResultResponse {
    let status: PaymentStatus          // Final payment status
    let isFinal: Bool                  // Whether status is final
    let pollInMs: Int64?               // Suggested poll interval
    let info: PaymentResultInfo?       // Transaction result details (present on success)
}

enum PaymentStatus {
    case requiresAction                // Additional action needed
    case processing                    // Payment in progress
    case succeeded                     // Payment completed
    case failed                        // Payment failed
    case expired                       // Payment expired
    case cancelled                     // Payment cancelled by user
}

Best Practices

1. Account Format: Always use CAIP-10 format for accounts: eip155:{chainId}:{address}

2. Multiple Chains: Provide accounts for all supported chains to maximize payment options

3. Signature Order: Maintain the same order of signatures as the actions array

4. Error Handling: Always handle errors gracefully and show appropriate user feedback

5. Loading States: Show loading indicators during API calls and signing operations

6. Expiration: Check paymentInfo.expiresAt and warn users if time is running low

7. User Data: Only collect data when collectData is present on the selected payment option 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.

8. WebView Data Collection: When selectedOption.collectData?.url is present, display the URL in a WKWebView rather than building native forms. The WebView handles form rendering, validation, and T&C acceptance.

9. 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.