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.
Node
npm install @jusa/node --registry https://jusa.localhost.co.zw/sdk/npm/
PHP
composer config repositories.jusa composer https://jusa.localhost.co.zw/sdk/composer
composer require jusa/jusa-php:^1.0
Go
go env -w GOPRIVATE=jusa.localhost.co.zw
go get jusa.localhost.co.zw/sdk/go@v1.0.3
Java
// build.gradle.kts (Kotlin works too); Maven is on the SDKs page
repositories {
mavenCentral()
maven("https://jusa.localhost.co.zw/sdk/maven2/")
}
dependencies {
implementation("zw.co.localhost.jusa:jusa-java:1.0.3")
}
C#
dotnet add package Jusa --source https://jusa.localhost.co.zw/sdk/nuget/v3/index.json
Dart
dart pub add jusa --hosted-url https://jusa.localhost.co.zw/sdk/pub
Ruby
gem install jusa --source https://jusa.localhost.co.zw/sdk/gems/
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.
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:
jusa @ https://jusa.localhost.co.zw/sdk/files/jusa-1.0.3-py3-none-any.whl
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, alljusa.JusaErrorwithcode,paramandrequest_id. jusa.Webhook.construct_event(raw_body, signature_header, secret, tolerance=300)verifies and parses a delivery;event.idis 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:
@jusa:registry=https://jusa.localhost.co.zw/sdk/npm/
npm install @jusa/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:
{
"repositories": [
{"type": "composer", "url": "https://jusa.localhost.co.zw/sdk/composer"}
],
"require": {"jusa/jusa-php": "^1.0"}
}
<?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.
go env -w GOPRIVATE=jusa.localhost.co.zw
go get jusa.localhost.co.zw/sdk/go@v1.0.3
// 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:
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:
<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>
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:
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:
dotnet nuget add source https://jusa.localhost.co.zw/sdk/nuget/v3/index.json --name jusa
dotnet add package Jusa
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:
dependencies:
jusa:
hosted: https://jusa.localhost.co.zw/sdk/pub
version: ^1.0.3
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:
source "https://jusa.localhost.co.zw/sdk/gems/" do
gem "jusa", "~> 1.0"
end
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.
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
- OpenAPI 3.1 document: every endpoint, request body and object.
- Postman collection: set
apiKeyto a test key; every request that moves money carriesIdempotency-Key: {{$guid}}.
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).