Android SDK Reference

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

The Banxa Android SDK (BanxaPaymentSDK) is the payment execution layer of Banxa Native for native Android apps. It is the Kotlin 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.

The Android SDK is published to Maven Central. Add the dependency to your module's Gradle build file.

dependencies {
    implementation("com.banxa.nativepaymentssdk:android-payments-sdk:1.0.0")
}

Build a BanxaConfig and initialise the SDK once at app launch.

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

Banxa.initialize(config)

Sandbox and production credentials are separate and are not interchangeable.

StartPayment is a composable. Render it when the customer confirms, and supply the callback lambdas you need.

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.
        println("Paid: ${result.paymentId ?: result.rawQuery ?: "-"}")
    },
    banxaDidFail = { error ->
        // Any failure: API, validation, network, decoding, or checkout error.
        println("Failed: $error")
    },
    banxaDidDismiss = {
        // The customer closed the checkout UI without completing.
    }
)

StartPayment runs the full pipeline: it checks eligibility, creates the order, and presents the native payment sheet when a payment token is available. All callbacks have a default no-op implementation, so supply only what you need.

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.

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

Pass a PrimerTheme to the config builder to override the payment sheet colour tokens.

val primerTheme = PrimerTheme(
    lightColorTokens = object : LightColorTokens() {
        override val primerColorBrand: Color = Color(0xFF6C5CE7)
        override val primerColorTextPrimary: Color = Color(0xFFD32E2E)
        override val primerColorBackground: Color = Color(0xFF9CFFA1)
    },
)

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

Banxa.initialize(config)

Theming is optional. Without it, the payment sheet uses the default token set.

These helpers return a Result and require an initialised SDK. In a Banxa Native integration, prefer the equivalent Native API endpoints so that configuration stays on the HMAC-authenticated surface.

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

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

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

The country list is the same for buy and sell.

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

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.

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

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

When your Android app presents Google Pay, Google requires app-level approval before you can process live payments. Banxa's own approval does not cover payments presented inside your app. Start the approval process early: it is the most common cause of a delayed Android launch. See the Google Pay guide.

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

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