iOS SDK Reference

For the complete documentation index, see llms.txt. Append .md to any page URL for its markdown version.

The Banxa iOS SDK (BanxaPaymentSDK) is the payment execution layer of Banxa Native for native iOS apps. It is the Swift counterpart to the React Native SDK: used alongside the Native API to present the native payment sheet for cards, Apple Pay, and Google Pay, the payment methods that cannot be handled through the API alone due to PCI requirements.

Bank transfers are handled directly by the Native API and do not involve the SDK. For the end-to-end integration walkthrough, see the Integration Guide.

You also need a Banxa partner account, which supplies the apiKey and partnerID used to configure the SDK.

Add the package to 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")
    ]
)

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 (>= 2.49.0). You do not import or reference it directly.

Configure the SDK once at app launch, for example in your App entry point or AppDelegate.

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

Calling any SDK method before configure(config:) fails with APIError.sdkNotConfigured. Blank credentials fail with APIError.missingCredentials.

Sandbox and production credentials are separate and are not interchangeable.

Build a CreateOrderRequest and call startPayment(request:controller:). 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)

startPayment runs the full pipeline in one call: it checks eligibility, creates the order, and presents the native payment sheet when a payment token is available. Results arrive on the delegate, not as a return value.

The SDK does not accept a quoteId. Use indicative pricing from GET /eapi/v0/price and re-price close to the point of payment to reduce rate drift.

Conform to BanxaPaymentSDKDelegate. All callback types are Banxa-owned: you never import or reference the underlying payment provider SDK. Every method has a default no-op implementation, so implement only what you need.

import BanxaPaymentSDK

extension MyViewController: BanxaPaymentSDKDelegate {

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

    func banxaDidFail(error: Error) {
        // Any failure: API, validation, network, decoding, or checkout error.
        // Banxa-originated failures are APIError.
        print("Failed:", error.localizedDescription)
    }

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

All delegate callbacks are delivered on the main actor.

Delegate callbacks are a UI signal, not the authoritative order state. Confirm the final state from webhooks before you credit a customer.

If you use redirect-based payment methods, register a URL scheme in your Info.plist and use the same scheme for redirectURL on CreateOrderRequest.

These helpers are async throws and require a configured SDK. In a Banxa Native integration, prefer the equivalent Native API endpoints so that configuration stays on the HMAC-authenticated surface.

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

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

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

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

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. Quotes carry no quote id and are not accepted by startPayment. Do not cache them: call immediately before showing a price.

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.

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

• Integration Guide: end-to-end walkthrough.
• Apple Pay: entitlements and platform setup.
• Cards: 3D Secure setup.
• Interpreting Eligibility: the requirements dictionary and remediation loop.