iOS SDK Integration Guide

This guide walks through a complete Banxa Hosted Checkout integration in a native iOS app using the Banxa iOS SDK. By the end you will have a working buy flow: configure the SDK once, start a payment with a single call, and confirm the final order status from your backend.

The iOS SDK is headless. There is no Banxa view controller to embed and no WebView for you to manage. You supply an order request and a host view controller, and the SDK presents checkout, handles the payment, and reports the outcome on a delegate.

For the full API surface, see the iOS SDK Reference.

• A native iOS app on iOS 13.1 or above, built with Xcode 16 and Swift 6.0 or above.
• Your Banxa partner reference and API key. Use sandbox for development, production after approval.
• A configured webhook endpoint. Optional but recommended for order status tracking.

Add the package in Xcode through File, Add Package Dependencies, or declare it in Package.swift:

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

Then add BanxaPaymentSDK to your target:

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

Configure once at app launch and set your delegate. Calling any SDK method before configure(config:) fails with APIError.sdkNotConfigured.

import BanxaPaymentSDK

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

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

Fetch live pricing before you show an amount to the customer. Call this close to when the price is displayed, because crypto rates move quickly and quotes are indicative.

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)

print("Receive:", quotes[0].cryptoAmount ?? "-")
print("Processing fee:", quotes[0].processingFee ?? "-")
print("Network fee:", quotes[0].networkFee ?? "-")

Provide either fiatAmount or cryptoAmount. If both are set, Banxa uses cryptoAmount. Quotes carry no quote id, so there is nothing to pass into the payment call.

fetchQuotes always returns an array, because Banxa returns multiple entries when discount codes apply.

Build a CreateOrderRequest and call startPayment(request:controller:) when the customer confirms. Pass the view controller that should host the checkout presentation.

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: self)

Pass externalCustomerID as well. It is your stable per-customer identifier, and Banxa uses it to recognise returning customers so they do not repeat KYC.

Conform to BanxaPaymentSDKDelegate. There are three methods, each with a default no-op implementation, so implement only what you need. All callbacks are delivered on the main actor.

import BanxaPaymentSDK

extension CheckoutViewController: BanxaPaymentSDKDelegate {

    func banxaDidCompleteCheckout(_ result: BanxaCheckoutResult) {
        // Payment succeeded. Confirm the authoritative state from your backend.
        showProcessingState()
    }

    func banxaDidFail(error: Error) {
        // API, validation, network, decoding, or checkout failure.
        showRetry(message: error.localizedDescription)
    }

    func banxaDidDismiss() {
        // The customer closed checkout without completing.
        returnToAmountEntry()
    }
}

banxaDidCompleteCheckout is a UI signal, not the authoritative order state. Do not credit the customer on it.

The SDK does not expose order lookup. Confirm the final state from your backend using the Banxa API.

Only terminal statuses are final. Do not credit the customer until the order reaches complete. For the full list, see Order Statuses, and for lookup see Order Lookup.

Webhooks fire on every order status change and are the reliable mechanism for order tracking. Configure your webhook URL in the merchant dashboard.

The typical pattern:

• Delegate success callback: optimistic UI update, "your order is processing".
• Webhook to your backend: authoritative order state.
• Backend pushes the update to the app, or the app re-fetches on resume.

See Webhooks for payload structure and signature verification. Webhook signatures are verified with your HMAC secret, not the v2 x-api-key.

Banxa-originated failures reach banxaDidFail(error:) as APIError. The cases you will meet most often during integration:

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

Banxa runs KYC inside the checkout the SDK presents. Add NSCameraUsageDescription to your Info.plist, and NSMicrophoneUsageDescription if your flow includes liveness capture. Without these keys, document capture fails silently and the customer cannot complete verification.

Use sandbox for all development:

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

Apple Pay cannot be tested on the iOS simulator. The simulator reaches the payment sheet and then fails at payment. Test on a real device with at least one card added to Wallet.

For test credentials, see Sandbox Test Data.

The SDK presents a native payment sheet for card, Apple Pay, and Google Pay when the customer is cleared for it, and falls back to Banxa checkout when they are not. Driving that behaviour explicitly, including reading the eligibility result and acting on outstanding requirements, is a Banxa Native capability for partners who verify their own users and run their own KYC. See Banxa Native, or talk to Banxa about whether it is relevant to your integration.

• iOS SDK Reference: full method, model, and error reference.
• Webhooks: configure webhook notifications.
• Order Statuses: full status reference.
• Sandbox Test Data: credentials and test values.