Skip to content
Last updated

The Banxa React Native SDK is a TypeScript-first interface to Banxa Hosted Checkout, designed for React Native mobile apps. It wraps the API in typed methods and provides a built-in WebView component for checkout presentation.

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

Installation

npm install @banxa-official/react-native-sdk react-native-webview

react-native-webview is a peer dependency. For iOS, run pod install after installing.

Creating a Banxa client

import { Banxa } from '@banxa-official/react-native-sdk';

const banxa = new Banxa({
  apiKey: 'YOUR_API_KEY',
  partner: 'your-partner-id',
  environment: 'sandbox', // or 'production'
});

Configuration options

OptionTypeRequiredDescription
apiKeystringYesYour Banxa API key from the Partner Dashboard.
partnerstringYesYour partner identifier.
environment'sandbox' | 'production'NoDefaults to 'production'.
baseUrlstringNoCustom base URL — overrides the environment-derived URL.

Buy

The banxa.buy module handles buy orders (fiat → crypto).

createOrder

Create a new buy order.

const order = await banxa.buy.createOrder({
  externalCustomerId: 'user-123',
  fiat: 'USD',
  crypto: 'BTC',
  fiatAmount: '100',
  paymentMethodId: '1',
  walletAddress: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa',
  redirectUrl: 'https://yourapp.com/success',
});

Maps to POST /{partnerRef}/v2/buy.

getOrder

Retrieve a single buy order by its Banxa order ID.

const orderDetails = await banxa.buy.getOrder(order.id);

Maps to GET /{partnerRef}/v2/orders/{orderId}.

getOrdersByAccount

Retrieve buy orders associated with a specific externalCustomerId.

const userBuyOrders = await banxa.buy.getOrdersByAccount('user-123');

For retrieving a full list of all orders across all customers (reconciliation, reporting), use the Banxa API directly. The SDK only supports retrieval filtered by customer.

initializeCheckoutWebView

Configure the props for the CheckoutWebView component.

const webViewProps = banxa.buy.initializeCheckoutWebView(order, {
  onClose: () => { /* user closed checkout */ },
  onSuccess: (url) => { /* checkout completed */ },
  onFailure: (url) => { /* checkout failed */ },
  returnUrlOnSuccess: 'https://yourapp.com/success',
  returnUrlOnFailure: 'https://yourapp.com/failure',
});

// In your component render:
{showCheckout && <CheckoutWebView {...webViewProps} />}

The WebView detects navigation to your return URLs automatically and triggers the appropriate callback.

Prices

The banxa.prices module retrieves live quotes. Either fiatAmount or cryptoAmount must be provided; paymentMethodId and blockchain are also required.

getQuote

Retrieve a quote for a specific order type ('buy' or 'sell').

const quote = await banxa.prices.getQuote('buy', {
  fiat: 'USD',
  crypto: 'BTC',
  fiatAmount: '100',
  paymentMethodId: '1',
  blockchain: 'bitcoin',
});

console.log('Crypto amount:', quote.cryptoAmount);
console.log('Fiat amount:', quote.fiatAmount);
console.log('Processing fee:', quote.processingFee);
console.log('Network fee:', quote.networkFee);

getBuyQuote

Convenience method for buy quotes.

const buyQuote = await banxa.prices.getBuyQuote({
  fiat: 'USD',
  crypto: 'BTC',
  fiatAmount: '100',
  paymentMethodId: '1',
  blockchain: 'bitcoin',
});

Payment Methods

The banxa.paymentMethods module retrieves supported payment methods.

// All payment methods
const paymentMethods = await banxa.paymentMethods.getPaymentMethods();

// Filtered by currency pair
const methods = await banxa.paymentMethods.getPaymentMethods('USD', 'BTC');

// Single payment method by ID
const method = await banxa.paymentMethods.getPaymentMethod(1);

Currencies

The banxa.currencies module retrieves supported fiat and crypto currencies. Fiat and crypto come from separate endpoints — availability can differ between buy and sell flows.

// Defaults to order type 'buy'
const fiatCurrencies = await banxa.currencies.getFiatCurrencies();
const cryptoCurrencies = await banxa.currencies.getCryptoCurrencies();

// Explicit order type — use 'sell' for sell flows
const sellFiats = await banxa.currencies.getFiats('sell');
const sellCrypto = await banxa.currencies.getCrypto('sell');

// No single-currency endpoint — look up from the list
const btc = cryptoCurrencies.find((c) => c.id === 'BTC');

Countries

The banxa.countries module retrieves supported countries.

const countries = await banxa.countries.getCountries();
const country = await banxa.countries.getCountry('US');

CheckoutWebView component

The CheckoutWebView React component renders the Banxa checkout inside your app.

import { CheckoutWebView } from '@banxa-official/react-native-sdk';

<CheckoutWebView {...webViewProps} />

Use banxa.buy.initializeCheckoutWebView(order, options) to generate the props. The component:

  • Loads the checkout URL in a WebView.
  • Detects navigation to your return URLs and triggers the appropriate callback.
  • Handles camera permissions for KYC document capture (requires platform-specific setup).

Some payment methods — iDEAL, Klarna, and PayPal — cannot complete inside a WebView and require the customer to be redirected outside the app. See Supported Payment Methods.

For iOS KYC liveness checks, you may need to use SFSafariViewController instead of the standard WebView. → See Embedded Checkout — Mobile.

Error handling

The SDK throws BanxaSDKError objects for API and network failures.

import { Banxa, BanxaSDKError } from '@banxa-official/react-native-sdk';

try {
  const order = await banxa.buy.createOrder({ /* ... */ });
} catch (error) {
  if (error instanceof BanxaSDKError) {
    console.error('Banxa API Error:', error.message);
    console.error('Error Code:', error.code);
    console.error('Status Code:', error.statusCode);
  } else {
    console.error('Unknown error:', error);
  }
}

BanxaSDKError properties

PropertyDescription
messageHuman-readable error description.
codeBanxa error code for programmatic handling.
statusCodeHTTP status code from the API response.

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

TypeScript support

The SDK is written in TypeScript and ships with type definitions.

import { Banxa, Order, Quote, PaymentMethod } from '@banxa-official/react-native-sdk';

const banxa = new Banxa({ /* ... */ });

const order: Order = await banxa.buy.createOrder({ /* ... */ });
const quote: Quote = await banxa.prices.getBuyQuote({ /* ... */ });

React Native compatibility

  • Uses the standard fetch API (available in React Native).
  • react-native-webview is a required peer dependency.
  • For iOS: run cd ios && pod install after installing.

Native payment sheet (Primer)

The SDK also supports a native payment sheet via Primer for card, Apple Pay, and Google Pay payments. This is an advanced integration for partners who verify their own users and run their own KYC — see Banxa Native. Talk to Banxa if you'd like to discuss whether this is relevant for your integration.

Not available in the SDK

For the following capabilities, use the Banxa API directly:

CapabilityReasonAlternative
KYC data sharing (Sumsub token share)Requires HMAC authentication, which the SDK does not supportKYC Sharing
Full order list (all orders across all customers)Not exposed in the SDKGET /{partnerRef}/v2/orders

Next steps

Integration Guide

Overview

© Banxa 2026