iOS / Swift SDK

CoverPaySDK is a native Swift package that provides a Plaid-style drop-in BNPL checkout for iOS applications. It supports both SwiftUI and UIKit, presenting a secure modal checkout backed by a WKWebView bridge.

Requirements

Installation

CoverPaySDK is distributed via Swift Package Manager (SPM). You can add it through Xcode or directly in your Package.swift.

Option 1: Xcode (Recommended)

Option 2: Package.swift

// Package.swift
dependencies: [
    .package(
        url: "https://github.com/jacksonhedge/coverpay-ios-sdk",
        from: "1.0.0"
    )
]

// Add to your target
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "CoverPaySDK", package: "coverpay-ios-sdk")
        ]
    )
]

Option 3: Local Package (Development)

// For development with a local copy of the SDK
dependencies: [
    .package(path: "../CoverPay/sdk/ios")
]

Configuration

Initialize CoverPaySDK once when your app launches. This prepares the SDK and pre-loads the checkout web view for faster presentation.

SwiftUI (App init)

import SwiftUI
import CoverPaySDK

@main
struct MyApp: App {
    init() {
        CoverPayLink.setup(CoverPayConfiguration(
            clientId: "your_client_id",
            environment: .sandbox  // or .production
        ))
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

UIKit (AppDelegate)

import UIKit
import CoverPaySDK

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        CoverPayLink.setup(CoverPayConfiguration(
            clientId: "your_client_id",
            environment: .sandbox
        ))
        return true
    }
}

SwiftUI Integration

Use the .coverPayLink() view modifier to present the checkout as a native iOS sheet.

import SwiftUI
import CoverPaySDK

struct CheckoutView: View {
    @State private var showCoverPay = false
    @State private var paymentResult: String?

    let amount: Int = 9999 // cents

    var body: some View {
        VStack(spacing: 16) {
            Text("Total: $\(String(format: "%.2f", Double(amount) / 100))")
                .font(.title2)

            Button("Pay with BNPL") {
                showCoverPay = true
            }
            .buttonStyle(.borderedProminent)

            if let result = paymentResult {
                Text(result)
                    .font(.caption)
                    .foregroundStyle(.secondary)
            }
        }
        .coverPayLink(
            isPresented: $showCoverPay,
            params: CoverPayLinkParams(
                amount: amount,
                merchantName: "My Store",
                customerEmail: "user@example.com"
            ),
            onResult: { result in
                switch result {
                case .success(let payment):
                    paymentResult = "Paid via \(payment.provider)"
                    confirmPayment(token: payment.paymentToken)
                case .failure(let error):
                    paymentResult = "Error: \(error.localizedDescription)"
                }
            }
        )
    }

    private func confirmPayment(token: String) {
        // Send token to your server
        Task {
            var request = URLRequest(url: URL(string: "https://api.example.com/confirm")!)
            request.httpMethod = "POST"
            request.setValue("application/json", forHTTPHeaderField: "Content-Type")
            request.httpBody = try? JSONEncoder().encode(["paymentToken": token])
            let (_, _) = try await URLSession.shared.data(for: request)
        }
    }
}

UIKit Integration

Use CoverPayLink.open() to present the checkout imperatively from any UIViewController.

import UIKit
import CoverPaySDK

class CheckoutViewController: UIViewController {

    @IBAction func payButtonTapped(_ sender: UIButton) {
        let params = CoverPayLinkParams(
            amount: 9999,
            merchantName: "My Store",
            customerEmail: "user@example.com"
        )

        CoverPayLink.open(
            params: params,
            from: self,
            onResult: { [weak self] result in
                switch result {
                case .success(let payment):
                    print("Token: \(payment.paymentToken)")
                    print("Provider: \(payment.provider)")
                    self?.confirmPayment(token: payment.paymentToken)

                case .failure(let error):
                    self?.showError(error)
                }
            }
        )
    }

    private func confirmPayment(token: String) {
        // Send token to your server
    }

    private func showError(_ error: CoverPayError) {
        let alert = UIAlertController(
            title: "Checkout Error",
            message: error.localizedDescription,
            preferredStyle: .alert
        )
        alert.addAction(UIAlertAction(title: "OK", style: .default))
        present(alert, animated: true)
    }
}

Result Handling

The checkout returns a Result<CoverPayResult, CoverPayError>. Handle all error cases for a robust integration.

Success Result

public struct CoverPayResult {
    public let paymentToken: String
    public let provider: String      // "klarna", "affirm", etc.
    public let plan: CoverPayPlan
}

public struct CoverPayPlan {
    public let type: PlanType        // .payIn4, .monthly, .custom
    public let installments: Int
    public let installmentAmount: Int // cents
    public let totalAmount: Int      // cents
    public let apr: Double
}

Error Cases

public enum CoverPayError: Error, LocalizedError {
    /// User dismissed the checkout
    case cancelled

    /// User is not eligible for BNPL
    case notEligible(reason: String)

    /// The BNPL provider returned an error
    case providerError(provider: String, message: String)

    /// Network request failed
    case networkError(underlying: Error)

    /// SDK not configured or invalid parameters
    case configurationError(message: String)

    public var errorDescription: String? {
        switch self {
        case .cancelled:
            return "Checkout was cancelled"
        case .notEligible(let reason):
            return "Not eligible: \(reason)"
        case .providerError(let provider, let message):
            return "\(provider) error: \(message)"
        case .networkError(let error):
            return "Network error: \(error.localizedDescription)"
        case .configurationError(let message):
            return "Configuration error: \(message)"
        }
    }
}

Exhaustive handling example:

switch result {
case .success(let payment):
    confirmPayment(token: payment.paymentToken)

case .failure(.cancelled):
    // User tapped X or swiped down — no action needed
    break

case .failure(.notEligible(let reason)):
    showAlert("You're not eligible for BNPL: \(reason)")

case .failure(.providerError(let provider, let message)):
    showAlert("\(provider) could not process your payment: \(message)")
    analytics.track("bnpl_provider_error", [
        "provider": provider,
        "message": message,
    ])

case .failure(.networkError):
    showAlert("Please check your internet connection and try again.")

case .failure(.configurationError(let message)):
    // This should not happen in production
    assertionFailure("CoverPay config error: \(message)")
}

Architecture

CoverPaySDK presents a hosted checkout via WKWebView. Communication between the native layer and the web checkout uses a postMessage bridge, similar to Plaid Link.

Bridge Events

SDK File Structure

CoverPaySDK/
├── Package.swift
├── README.md
├── Sources/
│   └── CoverPaySDK/
│       ├── CoverPayLink.swift           # Main entry point + setup
│       ├── CoverPayConfiguration.swift  # Config structs + params
│       ├── CoverPayResult.swift         # Success result types
│       ├── CoverPayError.swift          # Error enum
│       └── Internal/
│           ├── LinkViewController.swift # Modal presentation logic
│           └── WebViewHandler.swift     # WKWebView + JS bridge
└── Examples/
    └── ExampleApp.swift                 # SwiftUI & UIKit examples

Troubleshooting

Common build and runtime issues when integrating CoverPaySDK.

// Wrong
@StateObject private var link = CoverPayLink.shared

// Right — use the singleton directly
CoverPayLink.shared.open(params: ...) { result in
    // handle
}

CoverPayLinkParams Reference

CoverPayConfiguration Reference

public struct CoverPayConfiguration {
    /// Your CoverPay API client ID
    public let clientId: String

    /// API environment
    public let environment: Environment

    /// Base URL override (for testing)
    public let baseURL: URL?

    public enum Environment {
        case sandbox
        case production
    }

    public init(
        clientId: String,
        environment: Environment,
        baseURL: URL? = nil
    )
}