Flutter SDK Reference

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

The Banxa Flutter SDK (banxa_payments_flutter) is the payment execution layer of Banxa Native for Flutter apps. It is the Dart 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.

The plugin ships iOS and Android implementations only.

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

Add the dependency to pubspec.yaml:

dependencies:
  banxa_payments_flutter: 0.1.0

Or from the command line:

flutter pub add banxa_payments_flutter:0.1.0

Set the iOS deployment target to 15.0 in Xcode. After flutter pub get, build once with Flutter before opening the iOS project in Xcode:

flutter build ios --config-only

Skipping this can leave Xcode showing a 13.0 minimum, and plugin resolution fails.

Primer adds native binary size. Measure with flutter build appbundle --analyze-size and an iOS archive if binary size matters for your app.

The plugin merges INTERNET on Android. Hosted checkout and Primer may open the camera or photo library for KYC document capture, and those permissions must be declared in the host app.

Missing iOS usage strings crash the app when capture starts.

The SDK is TLS only (https) and does not certificate-pin.

Call configure once per process, before any other SDK method. Re-calling it replaces the HTTP client and rebinds checkout listeners.

import 'package:banxa_payments_flutter/banxa_payments_flutter.dart';

await BanxaPayments.configure(
  const BanxaConfig(
    apiKey: 'YOUR_API_KEY',
    partnerId: 'your-partner-id',
    environment: BanxaEnvironment.sandbox,
  ),
);

configure also takes an optional httpClient:

await BanxaPayments.configure(config, httpClient: myClient);

All partner-api traffic is issued from Dart, so it appears in the DevTools network view and can be intercepted, logged, or mocked with your own http.Client.

Requests go to {host}/{partnerId}/v2 with x-api-key and Content-Type: application/json. Sandbox and production credentials are separate and are not interchangeable.

startPayment creates the order and launches checkout in one call. It returns a sealed BanxaCheckoutLaunch telling you which route was taken.

final launch = await BanxaPayments.startPayment(
  const CreateOrderRequest(
    orderType: OrderType.buy,
    crypto: 'ETH',
    fiat: 'EUR',
    fiatAmount: '40',
    walletAddress: '0x0000000000000000000000000000000000000000',
    email: '[email protected]',
    redirectUrl: 'https://example.com/redirect',
    paymentMethodId: 'debit-credit-card',
    blockchain: 'ETH',
  ),
);

switch (launch) {
  case BanxaPrimerCheckoutLaunched():
    // Primer is on screen. Wait for checkoutEvents.
  case BanxaHostedCheckoutRequired():
    Navigator.of(context).push(
      MaterialPageRoute<void>(
        builder: (_) => Scaffold(
          appBar: AppBar(title: const Text('Checkout')),
          body: BanxaHostedCheckoutView(checkout: launch),
        ),
      ),
    );
}

Both types expose the created order as a CreateOrderResponse.

If the order has neither a usable native route nor a valid Banxa https checkout URL, startPayment throws NativeCheckoutNotEligibleException.

On iOS, Primer presents a single payment method (showPaymentMethod). On Android, Primer Checkout 3.x presents the methods from the client session; the requested Banxa method is still recorded natively.

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.

final order = await BanxaPayments.createOrder(request);

createOrder posts to /buy or /sell and returns the CreateOrderResponse without presenting any checkout UI.

Subscribe to BanxaPayments.checkoutEvents before calling startPayment. The stream carries outcomes from both native Primer checkout and BanxaHostedCheckoutView.

BanxaPayments.checkoutEvents.listen((event) {
  switch (event) {
    case BanxaCheckoutCompleted(:final paymentId, :final orderId, :final status):
      // Success.
    case BanxaCheckoutFailed(:final message):
      // Error.
    case BanxaCheckoutDismissed():
      // Sheet closed.
  }
});

status may be null on Android. Primer may emit dismissed after completed or failed, so treat the events as distinct rather than mutually exclusive.

Completion identifiers are read from Primer or from hosted-checkout query parameters (paymentId, orderId, status, plus payment_id and order_id aliases). Raw URLs are never surfaced to your app.

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

When startPayment returns BanxaHostedCheckoutRequired, render BanxaHostedCheckoutView:

BanxaHostedCheckoutView(checkout: launch)

Behaviour to design around:

• The view reports on checkoutEvents and never pops itself. Dismiss it yourself when a terminal event arrives.
• Disposing it before a terminal URL emits BanxaCheckoutDismissed.
• A first page that has not loaded within 30 seconds emits BanxaCheckoutFailed.
• The first URL must be https on a Banxa-owned host: banxa.com, banxa-sandbox.com, or banxa-preprod.com, including subdomains. Later navigations may leave Banxa for bank or wallet pages during 3DS, but must stay https.
• JavaScript is enabled for the hosted UI. There is no JavaScript bridge into your app.

Apple Pay requires a merchant identifier and the matching com.apple.developer.in-app-payments entitlement, added in Xcode under Signing & Capabilities, Apple Pay.

await BanxaPayments.configure(
  const BanxaConfig(
    apiKey: 'YOUR_API_KEY',
    partnerId: 'your-partner-id',
    applePayMerchantIdentifier: 'merchant.com.yourcompany.yourapp',
    applePayMerchantName: 'Your Store',
  ),
);

startPayment returns BanxaHostedCheckoutRequired instead of presenting Primer when:

• No applePayMerchantIdentifier is configured.
• The app is running on the iOS simulator. Apple Pay does not run on the simulator.
• The device has no usable card in Wallet.
• The request is for Apple Pay on Android.
• Google Play services are missing, for Google Pay.

See Apple Pay and Google Pay for platform setup.

crypto, fiat, fiatAmount, walletAddress, email, and redirectUrl are validated locally before the request is sent. A blank value throws ValidationException with a FieldError per missing field.

These call partner-api v2 under x-api-key and require a configured SDK. In a Banxa Native integration, prefer the equivalent Native API endpoints so that configuration and pricing stay on the HMAC-authenticated surface.

final countries = await BanxaPayments.fetchCountries();
final fiats = await BanxaPayments.fetchFiats(orderType: OrderType.buy);
final cryptos = await BanxaPayments.fetchCrypto(orderType: OrderType.buy);
final methods = await BanxaPayments.fetchPaymentMethods(
  orderType: OrderType.buy,
  fiat: 'USD',
);

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.

final quotes = await BanxaPayments.fetchQuotes(
  orderType: OrderType.buy,
  request: const QuoteRequest(
    paymentMethodId: 'debit-credit-card',
    crypto: 'ETH',
    blockchain: 'ETH',
    fiat: 'AUD',
    fiatAmount: '200',
  ),
);

fetchQuotes returns a list because Banxa returns multiple entries when discount codes apply. Quotes carry no quote id and are not accepted by startPayment. Do not cache them: call immediately before showing a price.

final eligibility = await BanxaPayments.checkEligibility(request);
if (eligibility.paymentReady == true) {
  await BanxaPayments.startPayment(request);
}

checkEligibility posts the same body as createOrder to partner-api POST /eligibility and returns:

This is opt-in, and startPayment never calls it. For a Banxa Native integration, use POST /eapi/v0/eligibility from your backend instead: it returns the full requirements[] dictionary you need to drive remediation, on the HMAC-authenticated surface. See Interpreting Eligibility.

await BanxaPayments.updatePrimerSession(
  primerToken: 'PRIMER_CLIENT_TOKEN',
  savedCard: false,
);

updatePrimerSession posts to /primer/session for mid-flow session patches, and accepts an optional additionalFields map of String values. Most integrations do not need it.

Every SDK failure is a subclass of the sealed BanxaPaymentsException, which exposes a message. Catch the sealed type and switch on the subclass.

try {
  await BanxaPayments.startPayment(request);
} on ValidationException catch (e) {
  for (final error in e.errors) {
    debugPrint('${error.field}: ${error.messages.join(', ')}');
  }
} on BanxaPaymentsException catch (e) {
  debugPrint(e.message);
}

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

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 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: merchant identifier and entitlement setup.
• Google Pay: app approval and platform setup.
• Cards: 3D Secure setup.
• Interpreting Eligibility: the requirements dictionary and remediation loop.