# 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


```bash
npm install @banxa/react-native-sdk
```

or


```bash
yarn add @banxa/react-native-sdk
```

## Getting Started

### Basic Setup


```typescript
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' or 'sandbox' (default: 'production')
- `baseUrl` (optional): Custom base URL (overrides environment setting)


## API Modules

### Orders

Create and manage orders:


```typescript
// Create a new order
const order = await banxa.orders.createOrder({
  account_reference: 'user-123',
  source: 'USD',
  target: 'BTC',
  source_amount: '100',
  payment_method_id: 1,
  wallet_address: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa',
  return_url_on_success: 'https://yourapp.com/success',
  return_url_on_failure: 'https://yourapp.com/failure',
});

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

// Check if the user is eligible to complete an order (same params as createOrder)
const orderRequest = {
  account_reference: 'user-123',
  source: 'USD',
  target: 'BTC',
  source_amount: '100',
  payment_method_id: 1,
  wallet_address: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa',
};
const eligibility = await banxa.orders.checkOrderEligibility(orderRequest);
if (!eligibility.eligible) {
  // Show eligibility.message or disable checkout
  console.log('Not eligible:', eligibility.message);
} else if (eligibility.paymentReady) {
  // Use Primer order flow (in-app checkout)
  const order = await banxa.orders.createOrderAndShowPrimerCheckout(orderRequest);
} else {
  // Use WebView flow: create order then show CheckoutWebView with order.checkout_url
  const order = await banxa.orders.createOrder(orderRequest);
  const webViewProps = banxa.orders.initializeCheckoutWebView(order, { ... });
  // render <CheckoutWebView {...webViewProps} />
}

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

// Get orders by account reference
const userOrders = await banxa.orders.getOrdersByAccount('user-123');

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

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

const webViewProps = banxa.orders.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 order and show Primer checkout

When the Banxa create order API returns a `payment_token` (e.g. for card/Primer flows), you can create an order and present Primer Universal Checkout in one call. Requires `@primer-io/react-native` (included as a dependency).


```typescript
// Primer options are initialised inside the function. For custom callbacks (e.g. onCheckoutComplete, onError), call Primer.configure() at app startup.
const order = await banxa.orders.createOrderAndShowPrimerCheckout({
  account_reference: 'user-123',
  source: 'USD',
  target: 'BTC',
  source_amount: '100',
  payment_method_id: 1,
  wallet_address: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa',
});
```

If the order response does not include `payment_token`, the method throws; use `createOrder()` and `initializeCheckoutWebView()` with `checkout_url` instead.

### Prices

Get price quotes for currency pairs:


```typescript
// Get a price quote
const price = await banxa.prices.getPrice({
  source: 'USD',
  target: 'BTC',
  source_amount: '100',
});

console.log('Price:', price.spot_price);
console.log('Fee:', price.fee);
console.log('Valid until:', price.valid_until);

// Get buy price
const buyPrice = await banxa.prices.getBuyPrice('USD', 'BTC', '100');

// Get sell price
const sellPrice = await banxa.prices.getSellPrice('BTC', 'USD', '0.001');
```

### Payment Methods

Retrieve available payment methods:


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


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

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

### Currencies

Get supported currencies:


```typescript
// Get all currencies
const currencies = await banxa.currencies.getCurrencies();

// Get fiat currencies only
const fiatCurrencies = await banxa.currencies.getFiatCurrencies();

// Get crypto currencies only
const cryptoCurrencies = await banxa.currencies.getCryptoCurrencies();

// Get a specific currency
const currency = await banxa.currencies.getCurrency('BTC');
```

### Customer Identity

Register and manage customer identity for KYC:


```typescript
// Register customer identity
const identity = await banxa.customerIdentity.registerCustomerIdentity({
  account_reference: 'user-123',
  email: 'user@example.com',
  mobile: '+1234567890',
  given_name: 'John',
  surname: 'Doe',
  date_of_birth: '1990-01-01',
  address: {
    address_line_1: '123 Main St',
    city: 'New York',
    state: 'NY',
    post_code: '10001',
    country_code: 'US',
  },
  kyc_level: 1,
});

// Get customer identity
const customerIdentity = await banxa.customerIdentity.getCustomerIdentity('user-123');
```

## Error Handling

The SDK throws `BanxaError` objects for API errors:


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

try {
  const order = await banxa.orders.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:


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

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

// All methods are fully typed
const order: Order = await banxa.orders.createOrder({...});
const price: Price = await banxa.prices.getPrice({...});
```

## React Native Compatibility

This SDK uses the standard `fetch` API which is available in React Native. The WebView component requires `react-native-webview` as a peer dependency.

### Installing WebView Dependency


```bash
npm install react-native-webview
# or
yarn add react-native-webview
```

For iOS, you may need to run:


```bash
cd ios && pod install
```