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 a Dart interface to Banxa Hosted Checkout for Flutter apps. You configure it once and start a payment with a single call. The SDK creates the order, presents the native payment sheet when the order supports it, and otherwise hands you a WebView widget to render for hosted checkout. Outcomes from both routes arrive on one stream.

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

The plugin ships iOS and Android implementations only. It is TLS only (https) and does not certificate-pin.

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

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

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.

A blank apiKey or partnerId throws MissingCredentialsException.

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.

Every method is static on BanxaPayments. Calling any of them before configure throws SdkNotConfiguredException.

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():
    // Native sheet 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),
        ),
      ),
    );
}

startPayment creates the order, then presents the native payment sheet when the order carries a nativeToken and the requested method can run on the device. Otherwise it returns BanxaHostedCheckoutRequired.

BanxaCheckoutLaunch is a sealed class. Both variants expose the created order as a CreateOrderResponse.

checkoutUrl is always https on a Banxa-owned host.

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.

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

startPayment does not call POST /eligibility. Use checkEligibility explicitly if you want to gate checkout yourself.

BanxaPayments.checkoutEvents is a Stream<BanxaCheckoutEvent> carrying outcomes from both the native payment sheet and BanxaHostedCheckoutView. Subscribe before calling startPayment.

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 or Order Lookup before you credit a customer.

BanxaHostedCheckoutView(checkout: launch)

Behaviour to design around:

• The widget reports on checkoutEvents and never pops itself. Dismiss the route 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. An initial URL outside that set emits BanxaCheckoutFailed.
• Later navigations may leave Banxa for bank or wallet pages during 3DS, but must stay https. Non-https navigations are blocked.
• JavaScript is enabled for the hosted UI. There is no JavaScript bridge into your app.

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.

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.

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.

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

For the full list, see Supported Payment Methods.

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