Android SDK Reference

The Banxa Android SDK (BanxaPaymentSDK) is a headless Kotlin interface to Banxa Hosted Checkout for native Android apps. You initialise it once and render the StartPayment composable to run a payment. The SDK checks eligibility, creates the order, presents checkout, and reports the outcome through callback lambdas.

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

The SDK is distributed as an AAR. Copy it into your module's libs directory and reference it from your Gradle build file.

dependencies {
    implementation(files("libs/BanxaPayment-1.0.0.aar"))
}

val config = BanxaConfig.Builder()
    .apiKey("YOUR_API_KEY")
    .partnerID("your-partner-id")
    .environment(Environment.SANDBOX)
    .build()

Banxa.initialize(config)

Requests use x-api-key authentication.

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

StartPayment is a composable. Render it when the customer confirms.

StartPayment(
    createOrderRequest = CreateOrderRequest(
        fiat = "EUR",
        crypto = "ETH",
        fiatAmount = "40",
        cryptoAmount = null,
        walletAddress = "0x0000000000000000000000000000000000000000",
        redirectUrl = "your-app-scheme://banxa-return",
        paymentMethodId = "debit-credit-card",
        email = "[email protected]"
    ),
    banxaDidReceiveCheckout = { result ->
        println("Paid: ${result.paymentId ?: result.rawQuery ?: "-"}")
    },
    banxaDidFail = { error ->
        println("Failed: $error")
    },
    banxaDidDismiss = {
        println("Customer dismissed checkout")
    }
)

StartPayment creates the order and presents checkout together. Render it when the customer confirms, not in advance, because Banxa checkout must be loaded within one minute of order creation.

Requires a prior Banxa.initialize(config) call.

All callbacks have a default no-op implementation, so supply only what you need.

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.

Use these to populate payment method selectors and currency pickers at runtime instead of hardcoding values. Each returns a Result.

val repository = BanxaRepository(
    RetrofitClient.getApi(config.baseUrl, config.environment)
)

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

val result = repository.getPaymentMethods(
    partner = config.partner,
    apiKey = config.apiKey,
    orderType = "buy",
    fiat = "USD" // optional
)

result.onSuccess { methods ->
    methods.forEach { method ->
        println("${method.id}: ${method.name} to ${method.supportedFiats}")
    }
}

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

val result = repository.getCountries(
    partner = config.partner,
    apiKey = config.apiKey
)

states is empty when the country has no state breakdown.

GET /{partnerID}/v2/fiats/{orderType}. Includes payment method minimum and maximum limits.

val result = repository.getFiats(
    partner = config.partner,
    apiKey = config.apiKey,
    orderType = "buy"
)

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

val result = repository.getCrypto(
    partner = config.partner,
    apiKey = config.apiKey,
    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/quotes/{orderType}. Do not cache: call immediately before showing a price.

val result = repository.getQuote(
    partner = config.partner,
    apiKey = config.apiKey,
    orderType = "buy",
    request = QuoteRequest(
        fiat = "AUD",
        crypto = "ETH",
        blockchain = "ETH",
        paymentMethodId = "debit-credit-card",
        fiatAmount = "200"
    )
)

Failures are surfaced through banxaDidFail. Banxa-originated failures are APIError, covering invalid URL, non-2xx server response, unauthorised (401), decoding failure, no network connectivity, missing credentials, uninitialised SDK, checkout failure, and unknown.

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

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

For the full list, see Supported Payment Methods.

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