Flutter SDK Integration Guide

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

This guide walks through a complete Banxa Hosted Checkout integration in a Flutter app using the Banxa Flutter SDK (banxa_payments_flutter). By the end you will have a working buy flow: configure the SDK once, start a payment with a single call, and confirm the final order status from your backend.

The Flutter SDK is a hybrid of the other mobile SDKs. startPayment presents the native payment sheet when the order supports it, and hands you a BanxaHostedCheckoutView widget to render when it does not. You control where that widget sits in your navigation stack.

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

• A Flutter app on Flutter >=3.44.9 and Dart >=3.12.2 <4.0.0.
• iOS 15.0 and above, Android minSdk 24 and above. The plugin ships iOS and Android implementations only.
• 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.

dependencies:
  banxa_payments_flutter: 0.1.0

flutter pub add banxa_payments_flutter:0.1.0

Set the iOS deployment target to 15.0 in Xcode, then build once with Flutter before opening the iOS project:

flutter build ios --config-only

Without this, Xcode can still show a 13.0 minimum and fail to resolve the plugin.

Declare camera and photo library permissions in the host app, because KYC document capture runs inside checkout:

Missing iOS usage strings crash the app when capture starts.

Configure once at app launch. Any SDK method called before configure throws SdkNotConfiguredException.

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,
  ),
);

Requests go to {host}/{partnerId}/v2 with x-api-key. All partner-api traffic is issued from Dart, so it shows up in the DevTools network view. Pass your own http.Client as httpClient if you need to intercept or log it.

Subscribe before you start a payment. This one stream carries outcomes from both the native payment sheet and hosted checkout, so you only handle results in one place.

late final StreamSubscription<BanxaCheckoutEvent> _sub;

@override
void initState() {
  super.initState();
  _sub = BanxaPayments.checkoutEvents.listen((event) {
    switch (event) {
      case BanxaCheckoutCompleted(:final paymentId, :final orderId):
        showProcessingState();
      case BanxaCheckoutFailed(:final message):
        showRetry(message);
      case BanxaCheckoutDismissed():
        returnToAmountEntry();
    }
  });
}

@override
void dispose() {
  _sub.cancel();
  super.dispose();
}

BanxaCheckoutCompleted is a UI signal, not the authoritative order state. Do not credit the customer on it.

Primer may emit dismissed after completed or failed, so treat the events as distinct rather than mutually exclusive, and guard against handling a terminal outcome twice.

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.

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

debugPrint('Receive: ${quotes.first.cryptoAmount ?? "-"}');
debugPrint('Processing fee: ${quotes.first.processingFee ?? "-"}');
debugPrint('Network fee: ${quotes.first.networkFee ?? "-"}');

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

fetchQuotes always returns a list, because Banxa returns multiple entries when discount codes apply.

To populate your own currency and payment method pickers, use fetchCountries, fetchFiats, fetchCrypto, and fetchPaymentMethods. See the Flutter SDK Reference.

Build a CreateOrderRequest and call startPayment when the customer confirms. It creates the order and launches checkout in one call, returning 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',
  ),
);

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.

startPayment returns a sealed BanxaCheckoutLaunch. Switch on it exhaustively.

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

You get BanxaHostedCheckoutRequired when the order has no nativeToken, or when the requested method cannot run on the device: Apple Pay with no merchant identifier configured, on the simulator, or on a device with no card in Wallet; Apple Pay requested on Android; Google Pay without Google Play services.

If there is neither a usable native route nor a valid Banxa https checkout URL, startPayment throws NativeCheckoutNotEligibleException.

The widget never pops itself. It reports on checkoutEvents, and you decide when to dismiss the route.

• 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. Later navigations may leave Banxa for bank or wallet pages during 3DS, but stay https.
• There is no JavaScript bridge from the hosted UI into your app.

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

The typical pattern:

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

Apple Pay needs 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',
  ),
);

Without the merchant identifier, Apple Pay is disabled and orders fall back to hosted checkout.

For Google Pay on Android, Google requires app-level approval before you can process live payments. Banxa's own approval does not cover payments presented inside your app, so start that process early.

Every SDK failure is a subclass of the sealed BanxaPaymentsException. The ones you will meet most often during integration:

try {
  final launch = await BanxaPayments.startPayment(request);
  // ...
} on ValidationException catch (e) {
  for (final error in e.errors) {
    debugPrint('${error.field}: ${error.messages.join(', ')}');
  }
} on BanxaPaymentsException catch (e) {
  showRetry(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.

Use sandbox for all development:

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

Apple Pay cannot be tested on the iOS simulator. On the simulator, startPayment returns BanxaHostedCheckoutRequired rather than presenting the native sheet, so test the native path on a real device with at least one card added to Wallet.

For test credentials, see Sandbox Test Data.

The SDK presents a native payment sheet for card, Apple Pay, and Google Pay when the customer is cleared for it, and falls back to Banxa hosted 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.

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