Android SDK Integration Guide

This guide walks through a complete Banxa Hosted Checkout integration in a native Android app using the Banxa Android SDK. By the end you will have a working buy flow: initialise the SDK once, render the StartPayment composable when the customer confirms, and confirm the final order status from your backend.

The Android SDK is headless and Compose-first. There is no Banxa Activity to launch and no WebView for you to manage. You supply an order request and callback lambdas, and the SDK presents checkout and reports the outcome.

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

• A native Android app on API level 24 or above, using Kotlin 2.0 or above with the Compose Compiler Gradle plugin.
• Jetpack Compose enabled in your project. The SDK's payment entry point is a composable.
• 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.

The Android 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"))
}

Build a BanxaConfig and initialise once at app launch.

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

Banxa.initialize(config)

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.

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

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"
    )
)

result.onSuccess { quote ->
    println("Pay ${quote.fiatAmount}, receive ${quote.cryptoAmount}")
    println("Fees: processing=${quote.processingFee}, network=${quote.networkFee}")
}

Provide either fiatAmount or cryptoAmount. Quotes carry no quote id, so there is nothing to pass into the payment call.

Use the same repository to populate your currency and payment method selectors at runtime rather than hardcoding values. See the Android SDK Reference.

Render the StartPayment composable 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 ->
        // Payment succeeded. Confirm the authoritative state from your backend.
    },
    banxaDidFail = { error ->
        // API, validation, network, decoding, or checkout failure.
    },
    banxaDidDismiss = {
        // The customer closed checkout without completing.
    }
)

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.

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

banxaDidReceiveCheckout 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:

• 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.

When your Android app presents Google Pay, Google requires app-level approval before you can process live payments. Banxa holds Google Pay approval for its own website, and that approval applies only when the customer is redirected to an external browser or a Custom Chrome Tab, not when Google Pay is presented inside your app.

Start the approval process early. It is the most common cause of a delayed Android launch.

Banxa runs KYC inside the checkout the SDK presents. Declare android.permission.CAMERA in your manifest and request it at runtime before the customer reaches verification. Without it, document capture fails and the customer cannot complete KYC.

Use sandbox for all development:

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

Banxa.initialize(config)

Google Pay can be tested on a physical Android device or on an emulator with Google Play Services installed.

For test credentials, see Sandbox Test Data.

The SDK presents a native payment sheet for card 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.

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