Docs menuSDKs and tools

Start

SDKs and tools

Python, Node, PHP, Go, Java, .NET, Dart and Ruby from our own registries; the jusa CLI, Postman, the OpenAPI document and MCP.

Install

Every SDK installs from Jusa's own registries under /sdk/, not from PyPI, npm, Packagist, Maven Central, NuGet, pub.dev or RubyGems: a package called jusa on a public registry is not ours. Each registry publishes the hash of every archive and your package manager checks it.

Install

Python

pip install --index-url https://jusa.localhost.co.zw/sdk/pypi/simple/ jusa

Every archive and its sha256 is listed at /sdk/files/. Every SDK has the same shape: a method per endpoint, named after the operation (rewards.create, webhookEndpoints.rollSecret), an Idempotency-Key made for you on every call that moves money and kept across that call's retries, typed errors, pagination, and Webhook.constructEvent. Retries: a 429 always; a connection error or a 5xx only on a read or a write that carries an idempotency key, so a write that may have happened is never sent twice.

Python: jusa

No dependencies beyond the standard library; Python 3.9 and later.

Shell
pip install --index-url https://jusa.localhost.co.zw/sdk/pypi/simple/ jusa

In requirements.txt, pin the archive itself, so no other index is ever asked for the name:

requirements.txt
jusa @ https://jusa.localhost.co.zw/sdk/files/jusa-1.0.3-py3-none-any.whl
Python
import logging
import os

import jusa

logger = logging.getLogger(__name__)
jusa.api_key = os.environ["JUSA_SECRET_KEY"]  # jusa_sk_test_… while you build


def send_order_airtime(order_id: str, phone: str) -> None:
    try:
        airtime_send = jusa.Send.create(product="airtime-usd", target=phone, amount="1.00",
                                        client_reference=f"order-{order_id}",
                                        idempotency_key=f"order-{order_id}")
    except jusa.InsufficientCreditError as insufficient_credit:
        logger.warning("Top up Jusa Credit [%s]", insufficient_credit.request_id)  # nothing was charged
        raise
    print(airtime_send.id, airtime_send.status)


def print_delivered_sends(since: str) -> None:
    jusa_client = jusa.Jusa(os.environ["JUSA_SECRET_KEY"])  # or one client per key
    delivered_sends = jusa_client.sends.list(status="delivered", created={"gte": since})
    for delivered_send in delivered_sends.auto_paging_iter():
        print(delivered_send.id, delivered_send.amount)
  • Every endpoint is a method: client.<resource>.<action>(ids…, **params), generated from the OpenAPI document. Each resource is also a class on the module: jusa.Reward.create(…).
  • Idempotency keys are automatic on every operation that takes one, and reused across that call's retries. They only protect retries inside one process: pass idempotency_key= (an order or submission id) to be safe across restarts.
  • Typed errors: InvalidRequestError, AuthenticationError, InsufficientCreditError, PermissionDeniedError, NotFoundError, ConflictError, IdempotencyError, RateLimitError, ProviderUnavailableError, APIError, APIConnectionError, all jusa.JusaError with code, param and request_id.
  • jusa.Webhook.construct_event(raw_body, signature_header, secret, tolerance=300) verifies and parses a delivery; event.id is what you dedupe on.
  • Parameters named like Python keywords take a trailing underscore: from_="2026-09-01".

Node and TypeScript: @jusa/node

Node 18 and later, no dependencies, typed from the OpenAPI document. Point the @jusa scope at our registry once, in .npmrc, and every @jusa/… package comes from us while everything else still comes from npm:

.npmrc
@jusa:registry=https://jusa.localhost.co.zw/sdk/npm/
Shell
npm install @jusa/node
Node
import Jusa, { InsufficientCreditError } from '@jusa/node';

const jusa = new Jusa(process.env.JUSA_SECRET_KEY); // jusa_sk_test_… while you build

async function sendOrderAirtime(orderId, phone) {
  try {
    const airtimeSend = await jusa.sends.create(
      { product: 'airtime-usd', target: phone, amount: '1.00', client_reference: `order-${orderId}` },
      { idempotencyKey: `order-${orderId}` },
    );
    console.log(airtimeSend.id, airtimeSend.status);
  } catch (error) {
    if (error instanceof InsufficientCreditError) {
      console.warn(`Top up Jusa Credit [${error.requestId}]`); // nothing was charged
    }
    throw error;
  }
}

async function printDeliveredSends(since) {
  const firstPage = await jusa.sends.list({ status: 'delivered', created: { gte: since } });
  for await (const deliveredSend of firstPage.autoPagingIterator()) {
    console.log(deliveredSend.id, deliveredSend.amount);
  }
}

// A webhook: the raw body as it arrived, its Jusa-Signature header, the endpoint's secret.
function verifiedWebhookEvent(rawBody, signatureHeader) {
  return Jusa.webhooks.constructEvent(rawBody, signatureHeader, process.env.JUSA_WHSEC);
}

PHP: jusa/jusa-php

PHP 8.1 and later, no dependencies. From the Composer repository, in composer.json:

composer.json
{
  "repositories": [
    {"type": "composer", "url": "https://jusa.localhost.co.zw/sdk/composer"}
  ],
  "require": {"jusa/jusa-php": "^1.0"}
}
PHP
<?php
require __DIR__ . '/vendor/autoload.php';

$jusa = new \Jusa\JusaClient(getenv('JUSA_SECRET_KEY')); // jusa_sk_test_… while you build

function sendOrderAirtime(\Jusa\JusaClient $jusa, string $orderId, string $phone): void
{
    try {
        $airtimeSend = $jusa->sends->create(
            ['product' => 'airtime-usd', 'target' => $phone, 'amount' => '1.00',
             'client_reference' => "order-{$orderId}"],
            ['idempotency_key' => "order-{$orderId}"],
        );
    } catch (\Jusa\Exception\InsufficientCreditException $insufficientCredit) {
        error_log("Top up Jusa Credit [{$insufficientCredit->getRequestId()}]"); // nothing was charged
        throw $insufficientCredit;
    }
    echo $airtimeSend->id, ' ', $airtimeSend->status, "\n";
}

function printDeliveredSends(\Jusa\JusaClient $jusa): void
{
    foreach ($jusa->sends->list(['status' => 'delivered'])->autoPagingIterator() as $deliveredSend) {
        echo $deliveredSend->id, ' ', $deliveredSend->amount, "\n";
    }
}

Go: jusa.localhost.co.zw/sdk/go

Go 1.21 and later, standard library only, and every call takes a context.Context. The module path answers go get itself and points it at our module proxy; GOPRIVATE keeps the public checksum database, which cannot see it, out of the way.

Shell
go env -w GOPRIVATE=jusa.localhost.co.zw
go get jusa.localhost.co.zw/sdk/go@v1.0.3
Go
// import jusa "jusa.localhost.co.zw/sdk/go"
// jusaClient := jusa.NewClient(os.Getenv("JUSA_SECRET_KEY"))

func sendOrderAirtime(ctx context.Context, orderID, phone string) error {
	sendResult, err := jusaClient.Sends.Create(ctx, jusa.Params{
		"product": "airtime-usd", "target": phone, "amount": "1.00", "client_reference": "order-" + orderID,
	}, jusa.WithIdempotencyKey("order-"+orderID))
	if err != nil {
		return fmt.Errorf("send airtime for order %s: %w", orderID, err)
	}
	if sendResult.AgentApproval != nil { // only for agent keys: a person approves it first
		fmt.Println("waiting for approval:", sendResult.AgentApproval.ApprovalURL)
		return nil
	}
	fmt.Println(sendResult.Send.ID, sendResult.Send.Status)
	return nil
}

func printDeliveredSends(ctx context.Context) error {
	const pageSize = 100
	firstPage, err := jusaClient.Sends.List(ctx, &jusa.SendsListParams{Status: "delivered", Limit: pageSize})
	if err != nil {
		return fmt.Errorf("list delivered sends: %w", err)
	}
	deliveredSends := firstPage.AutoPaging(ctx) // this page, then each page after it
	for deliveredSends.Next() {
		deliveredSend := deliveredSends.Current()
		fmt.Println(deliveredSend.ID, deliveredSend.Amount)
	}
	return deliveredSends.Err()
}

Java and Kotlin: zw.co.localhost.jusa:jusa-java

Java 11 and later, no dependencies, and it works from Kotlin. From the Maven repository; with Gradle:

build.gradle.kts
repositories {
    mavenCentral()
    maven("https://jusa.localhost.co.zw/sdk/maven2/")
}
dependencies {
    implementation("zw.co.localhost.jusa:jusa-java:1.0.3")
}

or Maven, in pom.xml:

pom.xml
<repositories>
  <repository>
    <id>jusa</id>
    <url>https://jusa.localhost.co.zw/sdk/maven2/</url>
  </repository>
</repositories>
<dependency>
  <groupId>zw.co.localhost.jusa</groupId>
  <artifactId>jusa-java</artifactId>
  <version>1.0.3</version>
</dependency>
Java
import java.util.logging.Logger;

public class Orders {
    private static final Logger LOGGER = Logger.getLogger(Orders.class.getName());
    private final Jusa jusa = new Jusa(System.getenv("JUSA_SECRET_KEY")); // jusa_sk_test_… while you build

    void sendOrderAirtime(String orderId, String phone) throws JusaException {
        try {
            Send airtimeSend = jusa.sends().create(
                    Params.of("product", "airtime-usd", "target", phone, "amount", "1.00",
                            "client_reference", "order-" + orderId),
                    RequestOptions.idempotencyKey("order-" + orderId));
            System.out.println(airtimeSend.getId() + " " + airtimeSend.getStatus());
        } catch (InsufficientCreditException insufficientCredit) {
            LOGGER.warning("Top up Jusa Credit [" + insufficientCredit.getRequestId() + "]"); // nothing was charged
            throw insufficientCredit;
        }
    }

    void printDeliveredSends() throws JusaException {
        for (Send deliveredSend : jusa.sends().list(Params.of("status", "delivered")).autoPagingIterable()) {
            System.out.println(deliveredSend.getId() + " " + deliveredSend.getAmount());
        }
    }
}

From Kotlin, the getters read as properties and there are no checked exceptions:

Kotlin
val jusa = Jusa(System.getenv("JUSA_SECRET_KEY"))

fun sendOrderAirtime(orderId: String, phone: String): Send = jusa.sends().create(
    Params.of("product", "airtime-usd", "target", phone, "amount", "1.00", "client_reference", "order-$orderId"),
    RequestOptions.idempotencyKey("order-$orderId"),
)

fun deliveredSendIds(): List<String> =
    jusa.sends().list(Params.of("status", "delivered")).autoPagingIterable().map { deliveredSend -> deliveredSend.id }

.NET: Jusa

.NET 8 and later, and anything on netstandard2.0. Add the NuGet feed once, then the package:

Shell
dotnet nuget add source https://jusa.localhost.co.zw/sdk/nuget/v3/index.json --name jusa
dotnet add package Jusa
C#
using Jusa;

var jusa = new JusaClient(Environment.GetEnvironmentVariable("JUSA_SECRET_KEY"));

async Task SendOrderAirtimeAsync(string orderId, string phone)
{
    var sendResult = await jusa.Sends.CreateAsync(
        new { product = "airtime-usd", target = phone, amount = "1.00", client_reference = $"order-{orderId}" },
        new RequestOptions { IdempotencyKey = $"order-{orderId}" });
    if (sendResult.ObjectType == "agent_approval")   // only for agent keys: a person approves it first
    {
        Console.WriteLine($"Waiting for approval: {sendResult.As<AgentApproval>().ApprovalUrl}");
        return;
    }
    var airtimeSend = sendResult.As<Send>();
    Console.WriteLine($"{airtimeSend.Id} {airtimeSend.Status}");
}

async Task PrintDeliveredSendsAsync(CancellationToken cancellationToken)
{
    const int pageSize = 100;
    var firstPage = await jusa.Sends.ListAsync(new { status = "delivered", limit = pageSize });
    await foreach (var deliveredSend in firstPage.AutoPagingAsync(cancellationToken))
        Console.WriteLine($"{deliveredSend.Id} {deliveredSend.Amount}");
}

Dart and Flutter: jusa

Dart 3, one dependency (package:http). From the pub repository, in pubspec.yaml:

pubspec.yaml
dependencies:
  jusa:
    hosted: https://jusa.localhost.co.zw/sdk/pub
    version: ^1.0.3
Dart
import 'dart:io';

import 'package:jusa/jusa.dart';

const deliveredPageSize = 100;

/// dart run send_airtime.dart <order id> <phone>
Future<void> main(List<String> arguments) async {
  final jusa = Jusa(Platform.environment['JUSA_SECRET_KEY']); // jusa_sk_test_… while you build
  final [orderId, phone] = arguments;
  try {
    final airtimeSend = await jusa.sends.create(
        {'product': 'airtime-usd', 'target': phone, 'amount': '1.00', 'client_reference': 'order-$orderId'},
        RequestOptions(idempotencyKey: 'order-$orderId')) as Send;
    print('${airtimeSend.id} ${airtimeSend.status}');

    final firstPage = await jusa.sends.list({'status': 'delivered', 'limit': deliveredPageSize});
    await for (final deliveredSend in firstPage.autoPagingIter()) {
      print('${deliveredSend.id} ${deliveredSend.amount}');
    }
  } on InsufficientCreditException catch (insufficientCredit) {
    stderr.writeln('Top up Jusa Credit [${insufficientCredit.requestId}]'); // nothing was charged
    exitCode = 1;
  } finally {
    jusa.close();
  }
}

A secret key spends your Jusa Credit: never build one into a Flutter app. Call Jusa from your back end.

Ruby: jusa

Ruby 2.6 and later, no dependencies. From the gem source, in a Gemfile:

Gemfile
source "https://jusa.localhost.co.zw/sdk/gems/" do
  gem "jusa", "~> 1.0"
end
Ruby
require "jusa"
require "logger"

LOGGER = Logger.new($stderr)
Jusa.api_key = ENV.fetch("JUSA_SECRET_KEY") # jusa_sk_test_… while you build

def send_order_airtime(order_id, phone)
  airtime_send = Jusa::Send.create({ product: "airtime-usd", target: phone, amount: "1.00",
                                     client_reference: "order-#{order_id}" },
                                   idempotency_key: "order-#{order_id}")
  puts "#{airtime_send.id} #{airtime_send.status}"
rescue Jusa::InsufficientCreditError => insufficient_credit
  LOGGER.warn("Top up Jusa Credit [#{insufficient_credit.request_id}]") # nothing was charged
  raise
end

def print_delivered_sends(since)
  jusa_client = Jusa::Client.new(ENV.fetch("JUSA_SECRET_KEY")) # or one client per key
  jusa_client.sends.list(status: "delivered", created: { gte: since }).auto_paging_each do |delivered_send|
    puts "#{delivered_send.id} #{delivered_send.amount}"
  end
end

The jusa CLI

Comes with the Python package.

Shell
jusa login                                        # store a key (a test key while you build)
jusa listen --forward-to localhost:8000/jusa/webhooks
jusa listen --events 'send.*,reward.*'            # only these
jusa trigger send.delivered                       # fire a sample event (test mode)
jusa logs tail                                    # your requests as they happen
jusa status                                       # ZESA and the networks

listen needs no public URL: it polls GET /events and forwards each new event to your local URL, signed with a whsec_cli_… secret it prints, so your handler verifies it exactly as it will verify Jusa's own deliveries.

Postman and OpenAPI

MCP for AI agents

An MCP server at https://jusa.localhost.co.zw/dev/v1/mcp (JSON-RPC 2.0 over HTTP, stateless) for agent keys (jusa_ak_…). Tools: send_airtime, buy_zesa, send_data (once live data bundles ship; simulated in test mode), confirm_meter, lookup_phone, quote_zesa, create_reward, get_balance, get_send, list_sends, cancel_send, resend_token, list_products, list_programs, list_recipients, get_status, zesa_status and search_docs; the key's scopes decide which it sees. An agent never mints reward links. An agent spends within its rolling 24-hour threshold and to numbers it knows; anything more waits for a person, who approves with their payment PIN. Live agent keys are off until an owner or admin turns them on. AI agents and MCP has each client's setup, the Agent Skill and llms.txt.

In the browser

Only publishable keys (jusa_pk_…) work from a web page: the catalog, status, reward-link claims and check-ins. Secret, restricted and agent keys sent from a browser are refused. The widget /static/developers/jusa.js claims a link (Jusa.claim(el, {publishableKey, token})) or picks a product for your server to sell with a checkout session (Jusa.buy).