React Native SDK — @jazadev/react-native reference

Official React Native client for Jaza (Expo or bare RN). Use this in your mobile app with your publishable key (jz_*_pk_*) and a client session from your backend (jaza.init → getSession / authEndpoint). Never put your secret key in the app. Server-side: @jazadev/node — init for the handshake, consume for debits. The SDK mints short-lived top-up JWTs internally; apps do not implement onRequestToken on the happy path.

Source and examples live on GitHub: @jaza-react-native. The Expo sample under example/ mirrors the full sign-in → init → top-up → consume path.

Install

npm install @jazadev/react-native

Expo peers:

npx expo install react react-native react-native-reanimated react-native-gesture-handler react-native-safe-area-context react-native-screens @gorhom/bottom-sheet @expo/vector-icons @shopify/flash-list

Expo config

Keep the phone field visible when the keyboard opens on Android:

{
  "expo": {
    "android": {
      "softwareKeyboardLayoutMode": "resize"
    }
  }
}

Provider setup

Wrap the app outermost with GestureHandlerRootView, then JazaProvider. Prefer getSession (or authEndpoint).

import { Stack } from 'expo-router';
import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { JazaProvider, type InitResult } from '@jazadev/react-native';

const API_BASE = process.env.EXPO_PUBLIC_API_URL!;

export default function RootLayout() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <JazaProvider
        publishableKey={process.env.EXPO_PUBLIC_JAZA_PUBLISHABLE_KEY!}
        getSession={async () => {
          const res = await fetch(`${API_BASE}/api/jaza/init`, {
            method: 'POST',
            credentials: 'include',
          });
          if (!res.ok) throw new Error('Jaza init failed');
          return (await res.json()) as InitResult;
        }}
        onAuthError={() => console.warn('Jaza session expired')}
        onTopUpComplete={({ credits }) => {
          console.log('Top-up completed', credits);
        }}
        theme="system"
        locale="en"
      >
        <Stack />
      </JazaProvider>
    </GestureHandlerRootView>
  );
}

Provider props (high level)

Prop	Role
`publishableKey`	Required `jz__pk_`
`getSession`	Preferred: return `InitResult` from your host
`authEndpoint`	Alternative: SDK POSTs this URL for `InitResult`
`getBalance`	Legacy-only balance callback
`theme`	`'light' \| 'dark' \| 'system'`
`locale`	`'en' \| 'fr' \| 'sw' \| 'ln'`
`onAuthError`	Handshake / session failure
`onTopUpComplete`	Payment succeeded

See Handshake.

Widgets and customization

Default UI works out of the box. Pass a children render prop to wrap your own components while reusing SDK state.

`JazaBalance`

import { JazaBalance } from '@jazadev/react-native';

{/* Default */}
<JazaBalance />

{/* Custom */}
<JazaBalance>
  {({ balanceCredits, loading, error, refresh }) => (
    <Pressable onPress={() => refresh()}>
      <Text>{loading ? '…' : `${balanceCredits ?? 0} credits`}</Text>
      {error ? <Text>{error}</Text> : null}
    </Pressable>
  )}
</JazaBalance>

JazaBalanceWidget remains as a deprecated alias.

`JazaTopUpButton`

Opens the bottom sheet using a session-minted top-up JWT (no onRequestToken).

{/* Default */}
<JazaTopUpButton label="Top up credits" />

{/* Custom */}
<JazaTopUpButton label="Top up">
  {({ onPress, loading, disabled, label, error }) => (
    <Pressable onPress={onPress} disabled={disabled || loading}>
      <Text>{loading ? 'Opening…' : label}</Text>
      {error ? <Text>{error}</Text> : null}
    </Pressable>
  )}
</JazaTopUpButton>

`JazaLedger`

{/* Default */}
<JazaLedger mode="preview" limit={5} />
<JazaLedger mode="scroll" />

{/* Custom row */}
<JazaLedger
  mode="preview"
  limit={5}
  ItemComponent={({ title, subtitle, credits, direction }) => (
    <View>
      <Text>{title}</Text>
      <Text>{subtitle}</Text>
      <Text>
        {direction === 'CREDIT' ? '+' : '−'}
        {credits}
      </Text>
    </View>
  )}
/>

mode="scroll" needs peer @shopify/flash-list.

`JazaActionButton`

Gate only — never consume. See Gating actions.

{/* Default */}
<JazaActionButton
  featureCode="SEND_MESSAGE"
  label="Send message"
  onPress={async () => {
    await fetch(`${API}/api/messages`, { method: 'POST', credentials: 'include' });
  }}
/>

{/* Custom */}
<JazaActionButton featureCode="SEND_MESSAGE" onPress={doSend}>
  {({ onPress, canAfford, cost, loading, disabled, label }) => (
    <Pressable onPress={onPress} disabled={disabled || loading}>
      <Text>
        {label} ({cost ?? '…'} cr){canAfford ? '' : ' — top up'}
      </Text>
    </Pressable>
  )}
</JazaActionButton>

What happens after Top up

SDK calls POST /v1/client/top-ups with the session token
Sheet opens → bundles and balance
User picks bundle → phone, country, currency → quote
Confirm → Jaza collects via Mobile Money → SDK polls
Balance refreshes via GET /v1/client/wallet

You do not configure MoMo aggregators; Jaza handles collection and settlements.

Exports

Export	Description
`JazaProvider`	Context, theme, locale, sheet, client
`JazaBalance`	Credits balance card
`JazaBalanceWidget`	Deprecated alias of `JazaBalance`
`JazaTopUpButton`	Opens sheet via session-minted top-up
`JazaLedger`	Transaction list (`preview` / `scroll`)
`JazaActionButton`	Feature gate (never consume)
`useJaza`	Status, balance, features, paywall helpers
`PublicClient`	Low-level public / client API client

Full path

Follow the Quickstart for Node BFF + React Native end-to-end.

Get started

Core concepts

Guides

SDKs

Reference

React Native SDK — @jazadev/react-native reference

Install

Expo config

Provider setup

Provider props (high level)

Widgets and customization

`JazaBalance`

`JazaTopUpButton`

`JazaLedger`

`JazaActionButton`

What happens after Top up

Exports

Full path

​Install

​Expo config

​Provider setup

​Provider props (high level)

​Widgets and customization

​JazaBalance

​JazaTopUpButton

​JazaLedger

​JazaActionButton

​What happens after Top up

​Exports

​Full path

Install

Expo config

Provider setup

Provider props (high level)

Widgets and customization

`JazaBalance`

`JazaTopUpButton`

`JazaLedger`

`JazaActionButton`

What happens after Top up

Exports

Full path