Get started with Jaza in minutes

This guide takes you from zero to a working prepaid flow. Choose your backend and frontend below — the narrative is the same for every stack.

Jaza collects Mobile Money across supported African markets and settles USD to you. You do not create an aggregator account or manage multi-currency settlement yourself.

Prerequisites

A Jaza developer account
Node.js 18+
A React Native (Expo) or React web app
Sandbox API keys from the dashboard

1. Create an app and copy keys

In the dashboard:

Create an app and enable Countries (Mobile Money markets)
Add at least one feature (e.g. SEND_MESSAGE) and one bundle
Open API keys and copy sandbox keys

Key	Where it lives	Example prefix
Secret	Server only (`JAZA_SECRET_KEY`)	`jz_test_sk_…`
Publishable	Client app	`jz_test_pk_…`

React Native
React

Use EXPO_PUBLIC_JAZA_PUBLISHABLE_KEY (or your bundler’s public env) for the publishable key.

Use NEXT_PUBLIC_JAZA_PUBLISHABLE_KEY (or VITE_… / equivalent) for the publishable key.

Never ship the secret key in a mobile binary, web bundle, or public repo.

When you switch from sandbox to live keys, create a new customerId under live and overwrite it in your user database — test wallets do not carry over. See Authentication → Going live.

2. Install the backend SDK

Node

npm install @jazadev/node

Create a shared server client:

import { Jaza } from '@jazadev/node';

export const jaza = new Jaza({
  secretKey: process.env.JAZA_SECRET_KEY!, // jz_test_sk_…
  publicKey: process.env.JAZA_PUBLIC_KEY!, // jz_test_pk_…
});

3. Create a customer

Call once when your user signs up; store customer.id on your user record.

const customer = await jaza.createCustomer({
  name: 'Amina Okello',
  email: 'amina@example.com', // and/or phoneNumber
});

// persist customer.id → your DB

4. Expose a host init route

Your app needs a client session from your backend. Map the signed-in user → Jaza customerId → jaza.init.

// POST /api/jaza/init  (require your app session)
app.post('/api/jaza/init', async (req, res) => {
  const result = await jaza.init({
    customerId: req.user.jazaCustomerId,
  });
  res.json(result); // sessionToken + wallet/features snapshot
});

The app never calls Jaza with the secret key. It calls your BFF; you call the Node SDK. See Handshake for getSession vs authEndpoint and 401 re-auth.

5. Install the frontend SDK

React Native
React

npm install @jazadev/react-native

Peer dependencies (Expo):

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

Ensure Android resizes with the keyboard (app.json):

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

npm install @jazadev/react

Peer dependencies: react, react-dom, and @base-ui/react (for the top-up drawer).

6. Wrap the app with `JazaProvider`

Pass getSession so the SDK loads the client session from your init route. Top-up JWTs are minted internally — no host onRequestToken.

React Native
React

// app/_layout.tsx
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>
  );
}

// app/providers.tsx (Next.js App Router) or root layout
'use client';

import { JazaProvider, type InitResult } from '@jazadev/react';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <JazaProvider
      publishableKey={process.env.NEXT_PUBLIC_JAZA_PUBLISHABLE_KEY!}
      getSession={async () => {
        const res = await fetch('/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"
    >
      {children}
    </JazaProvider>
  );
}

7. Balance, top-up, ledger, and gated actions

React Native
React

import { View } from 'react-native';
import {
  JazaBalance,
  JazaTopUpButton,
  JazaLedger,
  JazaActionButton,
} from '@jazadev/react-native';

const API_BASE = process.env.EXPO_PUBLIC_API_URL!;

export default function HomeScreen() {
  return (
    <View style={{ padding: 20, gap: 16 }}>
      <JazaBalance />
      <JazaTopUpButton label="Top up credits" />
      <JazaLedger mode="preview" limit={5} />
      <JazaActionButton
        featureCode="SEND_MESSAGE"
        label="Send message"
        onPress={async () => {
          await fetch(`${API_BASE}/api/jaza/actions`, {
            method: 'POST',
            credentials: 'include',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ featureCode: 'SEND_MESSAGE' }),
          });
        }}
      />
    </View>
  );
}

'use client';

import {
  JazaBalance,
  JazaTopUpButton,
  JazaLedger,
  JazaActionButton,
} from '@jazadev/react';

export default function HomePage() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
      <JazaBalance />
      <JazaTopUpButton label="Top up credits" />
      <JazaLedger mode="preview" limit={5} />
      <JazaActionButton
        featureCode="SEND_MESSAGE"
        label="Send message"
        onPress={async () => {
          await fetch('/api/jaza/actions', {
            method: 'POST',
            credentials: 'include',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ featureCode: 'SEND_MESSAGE' }),
          });
        }}
      />
    </div>
  );
}

JazaBalance — credits from the session snapshot / client wallet refresh
JazaTopUpButton — opens MoMo checkout; SDK mints the top-up JWT from the session
JazaLedger — recent movements (preview or scroll)
JazaActionButton — gate only; opens top-up when balance is too low; never debits

8. Meter a feature on the host

JazaActionButton is UX. Real enforcement is always jaza.consume on your backend with the secret key.

// POST /api/jaza/actions  (or your feature route)
await jaza.consume({
  customerId: req.user.jazaCustomerId,
  featureCode: 'SEND_MESSAGE', // configured in the dashboard
  idempotencyKey: `msg_${messageId}`,
});

For variable usage (e.g. AI tokens), pass both featureCode and credits to override the dashboard default while still attributing the feature. See Consume credits.

Optional: merchant webhooks

Register HTTPS endpoints under App Settings → Webhooks, then verify payloads with jaza.webhooks.constructEvent. See Webhooks.

What you just shipped

Client session handshake (no secret in the app)
Credit wallet UI + MoMo top-ups without running an aggregator
Feature gating in the UI and metering on your backend

Next: Handshake · Authentication · Top-up · Node SDK

Get started

Core concepts

Guides

SDKs

Reference

Get started with Jaza in minutes

Prerequisites

1. Create an app and copy keys

2. Install the backend SDK

3. Create a customer

4. Expose a host init route

5. Install the frontend SDK

6. Wrap the app with `JazaProvider`

7. Balance, top-up, ledger, and gated actions

8. Meter a feature on the host

Optional: merchant webhooks

What you just shipped

​Prerequisites

​1. Create an app and copy keys

​2. Install the backend SDK

​3. Create a customer

​4. Expose a host init route

​5. Install the frontend SDK

​6. Wrap the app with JazaProvider

​7. Balance, top-up, ledger, and gated actions

​8. Meter a feature on the host

​Optional: merchant webhooks

​What you just shipped

Prerequisites

1. Create an app and copy keys

2. Install the backend SDK

3. Create a customer

4. Expose a host init route

5. Install the frontend SDK

6. Wrap the app with `JazaProvider`

7. Balance, top-up, ledger, and gated actions

8. Meter a feature on the host

Optional: merchant webhooks

What you just shipped