WalletConnect Pay SDK - Swift - WalletConnect Pay Docs

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.](https://github.com/reown-com/reown-swift/tree/develop/Example/WalletApp)

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.

Initialization

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

At least one of apiKey or appId must be provided.

Supported Networks & Tokens

WalletConnect Pay currently supports the following tokens and networks:

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

Payment Link Detection

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

Call it wherever your wallet receives a link — from a deep link or a scanned QR code:

// Deep link opened from outside your app (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 payload
func handleScannedQR(_ content: String) {
    if isPaymentLink(content) {
        startPaymentFlow(paymentLink: content)
    }
}

Payment Flow

The payment flow consists of five main steps:Get Options -> Collect Data (if required) -> Get Actions -> Sign Actions -> Confirm Payment

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

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.

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

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.

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.

Data Collection Implementation

When selectedOption.collectData.url is present, display the URL in a WKWebView. 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 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)
        }
    }
}

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. Collect data via WebView if required (before fetching actions)
        if let collectData = selectedOption.collectData, let url = collectData.url {
            // Show WebView and wait for IC_COMPLETE message
            try await showDataCollectionWebView(url: url)
        }

// 4. Get required actions
        let actions = try await WalletConnectPay.instance.getRequiredPaymentActions(
            paymentId: optionsResponse.paymentId,
            optionId: selectedOption.id
        )

// 5. Sign all actions
        var signatures: [String] = []
        for action in actions {
            let signature = try await signAction(
                action: action,
                walletAddress: walletAddress,
                signer: signer
            )
            signatures.append(signature)
        }

// 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)
        }
    }
}

API Reference

WalletConnectPay Static configuration class for the Pay SDK.

PayClient Main client for payment operations.

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

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
}

Error Handling

The SDK throws specific error types for different failure scenarios:GetPaymentOptionsError

GetPaymentRequestError

ConfirmPaymentError

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.