# React Native SDK Reference

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](/products/hosted-checkout/docs/sdk-integration/integration-guide).

## Installation


```bash
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


```typescript
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

| Option | Type | Required | Description |
|  --- | --- | --- | --- |
| `apiKey` | string | Yes | Your Banxa API key from the Partner Dashboard. |
| `partner` | string | Yes | Your partner identifier. |
| `environment` | `'sandbox'` | `'production'` | No | Defaults to `'production'`. |
| `baseUrl` | string | No | Custom base URL — overrides the environment-derived URL. |


## Buy

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

### createOrder

Create a new buy order.


```typescript
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.


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

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

### getOrdersByAccount

Retrieve buy orders associated with a specific `externalCustomerId`.


```typescript
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](/products/hosted-checkout/docs/api-integration/api-integration-overview) directly. The SDK only supports retrieval filtered by customer.


### initializeCheckoutWebView

Configure the props for the `CheckoutWebView` component.


```typescript
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'`).


```typescript
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.


```typescript
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.


```typescript
// 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.


```typescript
// 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.


```typescript
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.


```typescript
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](/products/hosted-checkout/docs/reference/supported-payment-methods).

For iOS KYC liveness checks, you may need to use `SFSafariViewController` instead of the standard WebView. → See [Embedded Checkout — Mobile](/products/hosted-checkout/docs/checkout-experience/iframe/webview-mobile).

## Error handling

The SDK throws `BanxaSDKError` objects for API and network failures.


```typescript
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

| Property | Description |
|  --- | --- |
| `message` | Human-readable error description. |
| `code` | Banxa error code for programmatic handling. |
| `statusCode` | HTTP 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.


```typescript
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](https://banxa-enterprise.redocly.app/enterprise-api/v0-beta). 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](/products/hosted-checkout/docs/api-integration/api-integration-overview) directly:

| Capability | Reason | Alternative |
|  --- | --- | --- |
| KYC data sharing (Sumsub token share) | Requires HMAC authentication, which the SDK does not support | [KYC Sharing](/products/hosted-checkout/docs/identity-compliance/kyc-sharing) |
| Full order list (all orders across all customers) | Not exposed in the SDK | `GET /{partnerRef}/v2/orders` |


## Next steps

- [SDK Integration Guide](/products/hosted-checkout/docs/sdk-integration/integration-guide) — end-to-end walkthrough.
- [Banxa API Reference](/products/hosted-checkout/docs/api-integration/api-integration-overview) — for capabilities not in the SDK.