iOS SDK Reference

The Banxa iOS SDK (BanxaPaymentSDK) is a headless Swift interface to Banxa Hosted Checkout for native iOS apps. You configure it once and start a payment with a single call. The SDK checks eligibility, creates the order, presents checkout, and reports the outcome on a delegate.

For the end-to-end walkthrough, see the iOS SDK Integration Guide.

The public surface is @MainActor isolated and built on Swift concurrency.

dependencies: [
    .package(url: "https://github.com/BanxaOfficial/ios-payment-sdk", from: "1.0.0")
]

.target(
    name: "YourApp",
    dependencies: [
        .product(name: "BanxaPaymentSDK", package: "ios-payment-sdk")
    ]
)

1. Select File, Add Package Dependencies.
2. Enter the repository URL.
3. Select BanxaPaymentSDK and add it to your app target.

The SDK transitively pulls in the payment provider SDK. You do not import or reference it directly.

import BanxaPaymentSDK

let config = BanxaConfig(
    apiKey: "YOUR_API_KEY",
    partnerID: "your-partner-id",
    environment: .sandbox
)

BanxaPaymentSDK.shared.configure(config: config)
BanxaPaymentSDK.shared.delegate = self

Requests use x-api-key authentication.

The effective base URL is <host>/{partnerID}/v2. Sandbox and production credentials are separate and are not interchangeable.

BanxaPaymentSDK.shared.startPayment(request: request, controller: self)

startPayment creates the order and presents checkout in a single call. It returns nothing: results arrive on the delegate. Call it when the customer confirms, not in advance, because Banxa checkout must be loaded within one minute of order creation.

Requires a prior configure(config:) call. Otherwise it fails with APIError.sdkNotConfigured.

Three methods, each with a default no-op implementation. All callbacks are delivered on the main actor. All callback types are Banxa-owned: you never import or reference the underlying payment provider SDK.

extension MyViewController: BanxaPaymentSDKDelegate {

    func banxaDidCompleteCheckout(_ result: BanxaCheckoutResult) { }

    func banxaDidFail(error: Error) { }

    func banxaDidDismiss() { }
}

The success callback is a UI signal, not the authoritative order state. Confirm the final state from webhooks or Order Lookup before you credit a customer.

All configuration calls are async throws and require a configured SDK with non-blank credentials.

GET /{partnerID}/v2/countries. The list is the same for buy and sell.

let countries = try await BanxaPaymentSDK.shared.fetchCountries()

GET /{partnerID}/v2/fiats/{orderType}.

let fiats = try await BanxaPaymentSDK.shared.fetchFiats(orderType: .buy)

GET /{partnerID}/v2/crypto/{orderType}.

let assets = try await BanxaPaymentSDK.shared.fetchCrypto(orderType: .buy)

In unsupportedCountries, the key is a country code and the value is the restricted state codes. An empty list means the whole country is restricted.

GET /{partnerID}/v2/payment-methods/{orderType}. Optionally filter by fiat.

let methods = try await BanxaPaymentSDK.shared.fetchPaymentMethods(orderType: .buy)
let usdOnly = try await BanxaPaymentSDK.shared.fetchPaymentMethods(orderType: .buy, fiat: "USD")

GET /{partnerID}/v2/quotes/{orderType}. Do not cache: call immediately before showing a price.

let request = QuoteRequest(
    paymentMethodID: "debit-credit-card",
    crypto: "ETH",
    blockchain: "ETH",
    fiat: "USD",
    fiatAmount: "200"
)
let quotes = try await BanxaPaymentSDK.shared.fetchQuotes(orderType: .buy, request: request)

Provide either fiatAmount or cryptoAmount. If both are set, Banxa uses cryptoAmount. Banxa may return a single object or an array when discount codes apply, and fetchQuotes always returns [Quote].

Failures are surfaced through banxaDidFail(error:) as APIError. Each case provides a human-readable errorDescription.

Show user-facing messages only from validated error fields. Do not expose raw error strings that may include internal detail.

Register a URL scheme in your Info.plist and use it for redirectURL on CreateOrderRequest. This covers 3D Secure returns and the checkout return.

import SwiftUI
import BanxaPaymentSDK

@main
struct DemoApp: App {

    init() {
        let config = BanxaConfig(
            apiKey: ProcessInfo.processInfo.environment["BANXA_API_KEY"] ?? "",
            partnerID: "your-partner-id",
            environment: .sandbox
        )
        BanxaPaymentSDK.shared.configure(config: config)
    }

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

final class CheckoutCoordinator: NSObject, BanxaPaymentSDKDelegate {

    override init() {
        super.init()
        BanxaPaymentSDK.shared.delegate = self
    }

    func buy(from controller: UIViewController) {
        let request = CreateOrderRequest(
            crypto: "ETH",
            fiat: "EUR",
            fiatAmount: "40",
            walletAddress: "0x0000000000000000000000000000000000000000",
            email: "[email protected]",
            redirectURL: "your-app-scheme://banxa-return",
            paymentMethodID: "debit-credit-card"
        )
        BanxaPaymentSDK.shared.startPayment(request: request, controller: controller)
    }

    func banxaDidCompleteCheckout(_ result: BanxaCheckoutResult) {
        print("Payment complete:", result.paymentId ?? result.rawQuery ?? "-")
    }

    func banxaDidFail(error: Error) {
        print("Payment failed:", error.localizedDescription)
    }

    func banxaDidDismiss() {
        print("Customer dismissed checkout")
    }
}

Availability varies by partner, region, and order type. Treat fetchPaymentMethods as the source of truth. The table below is a static reference.

For the full list, see Supported Payment Methods.

• iOS SDK Integration Guide: end-to-end walkthrough.
• Webhooks: configure webhook notifications.
• Order Statuses: full status reference.