Banxa React Native SDK

A TypeScript-based React Native SDK for integrating with the Banxa API. This SDK provides a simple and type-safe interface for creating orders, retrieving prices, managing payment methods, and more.

Installation

npm install @banxaOfficial/react-native-sdk
npm install @primer-io/react-native

Getting Started

Basic Setup

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

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

Configuration Options

• apiKey (required): Your Banxa API key from the Partner Dashboard
• partner (required): Your partner identifier
• environment (optional): 'production', 'sandbox' (default: 'production')
• baseUrl (optional): Custom base URL (overrides environment setting)
• primerCallbacks (optional): Primer checkout callbacks (onCheckoutComplete, onError, onDismiss); when omitted, the SDK uses simple console.log defaults
• primerSettings (optional): Primer base settings (e.g. uiOptions, paymentMethodOptions) passed to all Primer flows

Primer customization (primerSettings)

Checkout UI is provided by @primer-io/react-native. Pass primerSettings on the Banxa constructor; the SDK merges them into Primer’s configure() for checkout flows. The TypeScript type is PrimerSettings from @primer-io/react-native (you typically pass Partial<PrimerSettings>).

Below are the customization-oriented fields (locale, UI, payment methods, debug, API). PrimerSettings also defines advanced payment and headless callbacks for direct Primer integrations; those are not listed here.

uiOptions

| Field | Type | Description | | --- | --- | --- | | appearanceMode | 'SYSTEM' \| 'LIGHT' \| 'DARK' | Light/dark appearance (or follow system). | | theme | See below | Colors for light and dark checkout UI. |

uiOptions.theme

theme has optional colors and darkModeColors. Each is a color set with the same optional keys. Every color is an IRgbaColor: { red, green, blue, alpha } with component values in the 0–255 range.

| Key | Role | | --- | --- | | mainColor | Primary brand / accent. | | contrastingColor | Contrasting surface to mainColor. | | background | Screen / sheet background. | | text | Primary text. | | contrastingText | Text on strong colored surfaces. | | borders | Borders and dividers. | | disabled | Disabled controls. | | error | Error state emphasis. |

paymentMethodOptions

Example (theme + UI flags)

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

const banxa = new Banxa({
  apiKey: 'your-api-key',
  partner: 'your-partner-id',
  environment: 'production',
  primerSettings: {
    uiOptions: {
      theme: {
        colors: {
          mainColor: { red: 7, green: 138, blue: 88, alpha: 255 },
          contrastingColor: { red: 255, green: 255, blue: 255, alpha: 255 },
          background: { red: 216, green: 242, blue: 240, alpha: 255 },
          text: { red: 7, green: 138, blue: 88, alpha: 255 },
          contrastingText: { red: 255, green: 255, blue: 255, alpha: 255 },
          borders: { red: 209, green: 96, blue: 209, alpha: 255 },
          disabled: { red: 100, green: 100, blue: 100, alpha: 255 },
          error: { red: 235, green: 126, blue: 16, alpha: 255 },
        },
        darkModeColors: {
          mainColor: { red: 1, green: 255, blue: 1, alpha: 255 },
          background: { red: 255, green: 1, blue: 255, alpha: 255 },
        },
      },
    },
  },
});

API Modules

Buy

Create and manage buy orders (fiat → crypto). Endpoints use the /buy path:

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

console.log('Order created:', order.id);
console.log('Checkout URL:', order.checkoutUrl);

Create orders with eligibility checks to allow for native payments on certain Payment Providers

// Call eligibility with the same params as createOrder; branch on paymentReady for checkout flow
const orderRequest = {
  externalCustomerId: 'user-123',
  fiat: 'USD',
  crypto: 'BTC',
  fiatAmount: '100',
  paymentMethodId: '1',
  walletAddress: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa',
  redirectUrl: 'https://yourapp.com/success',
};
const eligibility = await banxa.buy.checkEligibility(orderRequest);
// Use paymentReady from the eligibility response to choose Primer vs WebView checkout (do not rely on other fields for gating).
if (eligibility.paymentReady) {
  const checkoutResult = await banxa.buy.createOrderAndShowPrimerCheckout(orderRequest);
  // Primer: checkoutResult is Order; WebView fallback: { order, webViewProps }
} else {
  const order = await banxa.buy.createOrder(orderRequest);
  const webViewProps = banxa.buy.initializeCheckoutWebView(order, { ... });
  // render <CheckoutWebView {...webViewProps} />
}

Get order information

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

// Get buy orders by external customer ID
const userBuyOrders = await banxa.buy.getOrdersByAccount('user-123');

Initialize WebViews for checkout

// Initialize WebView for checkout
import { CheckoutWebView } from '@banxa/react-native-sdk';
import { useState } from 'react';

const [showCheckout, setShowCheckout] = useState(false);

const webViewProps = banxa.buy.initializeCheckoutWebView(order, {
  onClose: () => setShowCheckout(false),
  onSuccess: (url) => {
    console.log('Payment successful!', url);
    setShowCheckout(false);
  },
  onFailure: (url) => {
    console.log('Payment failed', url);
    setShowCheckout(false);
  },
  returnUrlOnSuccess: 'https://yourapp.com/success',
  returnUrlOnFailure: 'https://yourapp.com/failure',
});

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

Create buy order and show Primer checkout

When the Banxa create order API returns a nativeToken (e.g. for card/Primer flows), you can create a buy order and present Primer in one call. Pass paymentMethod to choose the flow (default is card).

import {
  isPrimerCheckoutWebViewResult,
  type PrimerCheckoutPaymentMethod,
} from '@banxa/react-native-sdk';

const result = await banxa.buy.createOrderAndShowPrimerCheckout(orderRequest);

if (isPrimerCheckoutWebViewResult(result)) {
  // No nativeToken but checkoutUrl — use WebView
  const { order, webViewProps } = result;
  // e.g. <CheckoutWebView {...webViewProps} />
} else {
  // Primer was shown; `result` is the Order
  const order = result;
}

// Or pick Primer flow explicitly: 'card' | 'applePay' | 'googlePay' | 'universal'
const method: PrimerCheckoutPaymentMethod = 'applePay';
await banxa.buy.createOrderAndShowPrimerCheckout(orderRequest, {
  paymentMethod: method,
  callbacks: { onCheckoutComplete: () => {}, onError: () => {}, onDismiss: () => {} },
  // When falling back to WebView, optional extras for CheckoutWebView:
  webViewProps: { returnUrlOnSuccess: 'https://yourapp.com/success', onClose: () => {} },
});

If the order has neither nativeToken nor checkoutUrl, the method throws.

Prices

Get quotes for buy or sell (GET /quotes/buy or /quotes/sell). Either fiatAmount or cryptoAmount must be provided; you must also include paymentMethodId and blockchain:

// Get a quote by 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);

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

Payment Methods

Retrieve available payment methods:

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

// Get payment methods for a specific currency pair
const methods = await banxa.paymentMethods.getPaymentMethods('USD', 'BTC');

// Get a specific payment method
const method = await banxa.paymentMethods.getPaymentMethod(1);

Countries

Get supported countries:

// Get all countries
const countries = await banxa.countries.getCountries();

// Get a specific country
const country = await banxa.countries.getCountry('US');

Currencies

Fiat and crypto lists come from separate endpoints (GET /fiats/{orderType} and GET /crypto/{orderType}). Availability can differ for buy vs sell:

// Fiat and crypto for buy (convenience wrappers default to order type "buy")
const fiatCurrencies = await banxa.currencies.getFiatCurrencies();
const cryptoCurrencies = await banxa.currencies.getCryptoCurrencies();

// Same data with an explicit order type (use 'sell' when listing for sell flows)
const sellFiats = await banxa.currencies.getFiats('sell');
const sellCrypto = await banxa.currencies.getCrypto('sell');

// Look up a crypto by id from the list (there is no single-currency endpoint)
const btc = cryptoCurrencies.find((c) => c.id === 'BTC');

Error Handling

The SDK throws BanxaSDKError for API and network failures (this class implements the BanxaError shape from the type definitions):

import { Banxa, BanxaSDKError } from '@banxa/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);
  }
}

TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

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

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

// All methods are fully typed
const order: Order = await banxa.buy.createOrder({...});
const quote: Quote = await banxa.prices.getBuyQuote({...});

React Native Compatibility

This SDK uses the standard fetch API which is available in React Native. Peer dependencies (see package.json): react-native-webview for CheckoutWebView, and @primer-io/react-native for Primer checkout flows.

Installing WebView Dependency

npm install react-native-webview @primer-io/react-native
# or
yarn add react-native-webview @primer-io/react-native

For iOS, you may need to run:

cd ios && pod install

Using the SDK from a local path (e.g. file:../react-native-sdk or npm link)

The package’s main entry is the built output in lib/. If you install from a local path, build the SDK first so lib/index.js exists:

cd /path/to/react-native-sdk && npm run build

Then install or link from your app as usual.

Testing

The SDK includes comprehensive test coverage. To run tests:

npm test

For more details, see TESTING.md.

License

MIT

Support

For API documentation, visit https://banxa-enterprise.redocly.app/enterprise-api/v0-beta/sdk/react/sdk-integration-guide

For issues and questions, please contact Banxa support or open an issue in the repository.