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

  • iOS 13.0+
  • Swift 5.7+
  • Xcode 14.0+
As a wallet provider, you would first need to obtain an API key from WalletConnect. You can do this by filling out this form and getting in touch with our team.

Installation

Swift Package Manager

Add WalletConnectPay to your Package.swift:
dependencies: [
    .package(url: "https://github.com/reown-com/reown-swift", from: "2.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...) {
    WalletConnectPay.configure(
        projectId: "your-walletconnect-project-id",
        apiKey: "your-pay-api-key",
        logging: true  // Enable for debugging
    )
}
Don’t have an API key? Fill out this form and get in touch with our team to obtain an API key.

Configuration Parameters

ParameterTypeRequiredDescription
projectIdStringYesYour WalletConnect Cloud project ID
apiKeyStringYesYour WalletConnect Pay API key
baseUrlStringNoCustom API URL (defaults to production)
loggingBoolNoEnable debug logging (default: false)
Don’t have a project ID? Create one at the WalletConnect Dashboard by signing up and creating a new project.

Supported Networks

WalletConnect Pay currently supports the following networks with USDC:
NetworkChain IDCAIP-10 Format
Ethereum1eip155:1:{address}
Base8453eip155:8453:{address}
Optimism10eip155:10:{address}
Polygon137eip155:137:{address}
Arbitrum42161eip155:42161:{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 four main steps: Get Options → Get Actions → Sign Permit → 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 if user data collection is required (travel rule)
    if let collectData = response.collectData {
        // Show UI to collect required user information
        for field in collectData.fields {
            print("Required field: \(field.name) (type: \(field.fieldType))")
        }
    }
    
} 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 the Permit

Each action contains a walletRpc with EIP-712 typed data that needs to be signed. The method is eth_signTypedData_v4.
var signatures: [String] = []

for action in actions {
    let rpc = action.walletRpc
    
    // rpc.chainId - The chain to sign on (e.g., "eip155:8453")
    // rpc.method  - "eth_signTypedData_v4"  
    // rpc.params  - JSON string: ["address", "{...typed data...}"]
    
    // Parse the params to extract typed data
    let paramsData = rpc.params.data(using: .utf8)!
    let params = try JSONSerialization.jsonObject(with: paramsData) as! [Any]
    let typedDataJson = params[1] as! String
    
    // Sign using your wallet's existing EIP-712 signing implementation
    let signature = try await yourWallet.signTypedData(
        typedData: typedDataJson,
        address: walletAddress,
        chainId: rpc.chainId
    )
    
    signatures.append(signature)
}
Signatures must be in the same order as the actions array.
4

Collect User Data (If Required)

If response.collectData is not nil, you must collect user information before confirming:
var collectedData: [CollectDataFieldResult]? = nil

if let collectDataAction = response.collectData {
    collectedData = []
    
    for field in collectDataAction.fields {
        // Show appropriate UI based on field.fieldType
        let value: String
        
        switch field.fieldType {
        case .text:
            // Show text input for name fields
            value = userInputtedValue
        case .date:
            // Show date picker for date of birth
            // Format: "YYYY-MM-DD"
            value = "1990-01-15"
        }
        
        collectedData?.append(CollectDataFieldResult(
            id: field.id,
            value: value
        ))
    }
}
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")
}

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 signTypedData(
                action: action,
                walletAddress: walletAddress,
                signer: signer
            )
            signatures.append(signature)
        }
        
        // 5. Collect user data if required
        var collectedData: [CollectDataFieldResult]? = nil
        if let collectData = optionsResponse.collectData {
            collectedData = try await collectUserData(fields: collectData.fields)
        }
        
        // 6. Confirm payment
        let result = try await WalletConnectPay.instance.confirmPayment(
            paymentId: optionsResponse.paymentId,
            optionId: selectedOption.id,
            signatures: signatures,
            collectedData: collectedData
        )
        
        guard result.status == .succeeded else {
            throw PaymentError.paymentFailed(result.status)
        }
    }
    
    private func signTypedData(
        action: Action,
        walletAddress: String,
        signer: YourSignerProtocol
    ) async throws -> String {
        let rpc = action.walletRpc
        
        // Parse params: ["address", "typedDataJson"]
        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
        }
        
        // Use your wallet's signing implementation
        return try await signer.signTypedData(
            data: typedDataJson,
            address: walletAddress
        )
    }
    
    private func collectUserData(
        fields: [CollectDataField]
    ) async throws -> [CollectDataFieldResult] {
        // Implement your UI to collect user data
        // This is typically done via a form/modal
        return fields.map { field in
            CollectDataFieldResult(
                id: field.id,
                value: getUserInput(for: field)
            )
        }
    }
}
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 let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
       components.queryItems?.contains(where: { $0.name == "pid" }) == true {
        // This is a WalletConnect Pay link
        let paymentLink = url.absoluteString
        startPaymentFlow(paymentLink: paymentLink)
    }
}

QR Code Scanning

Payment links can be encoded as QR codes. Detect Pay QR codes by checking for the pid query parameter:
func handleScannedQR(_ content: String) {
    guard let url = URL(string: content),
          let components = URLComponents(url: url, resolvingAgainstBaseURL: false) else {
        return
    }
    
    if components.queryItems?.contains(where: { $0.name == "pid" }) == true {
        // WalletConnect Pay QR code
        startPaymentFlow(paymentLink: content)
    }
}

Error Handling

The SDK throws specific error types for different failure scenarios:

GetPaymentOptionsError

ErrorDescription
.paymentNotFoundPayment ID doesn’t exist
.paymentExpiredPayment has expired
.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

API Reference

WalletConnectPay

Static configuration class for the Pay SDK.
MethodDescription
configure(projectId:apiKey:baseUrl:logging:)Initialize the SDK with your credentials
instanceAccess the shared PayClient instance

PayClient

Main client for payment operations.
MethodDescription
getPaymentOptions(paymentLink:accounts:includePaymentInfo:)Fetch available payment options
getRequiredPaymentActions(paymentId:optionId:)Get signing actions for a payment option
confirmPayment(paymentId:optionId:signatures:collectedData:maxPollMs:)Confirm and execute the payment

Data Types

PaymentOptionsResponse

PropertyTypeDescription
paymentIdStringUnique payment identifier
infoPaymentInfo?Merchant and amount details
options[PaymentOption]Available payment methods
collectDataCollectDataAction?Required user data fields (travel rule)

PaymentOption

PropertyTypeDescription
idStringOption identifier
amountPayAmountAmount in this asset
etaSInt64Estimated time to complete (seconds)
actions[Action]Required signing actions

PaymentStatus

StatusDescription
.requiresActionAdditional action needed
.processingPayment in progress
.succeededPayment completed
.failedPayment failed
.expiredPayment expired

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 in the response