Jusa for Developers
Sell airtime, data and ZESA from your till, with one API.
Put Econet, NetOne and Telecel airtime, data bundles and ZESA tokens on your POS, your till or your app, in USD and ZiG. Your customer pays you; Jusa delivers in seconds from your prepaid Jusa Credit. Verified dealers buy below face, so the margin is yours on every sale. The same API rewards people too: a finished survey, a referral, a clinic visit.
Python
def sell_airtime_at_the_till(phone: str, sale_id: str, till_id: str) -> None:
try:
# The till's sale number keys it: sent twice, it is one sale.
send = jusa.Send.create(
product="airtime-usd",
target=phone,
amount="2.00",
client_reference=f"sale-{sale_id}",
metadata={"till": till_id},
idempotency_key=f"sale-{sale_id}",
)
print(send.id, send.status, send.cost)
except jusa.InsufficientCreditError:
top_up_and_try_later() # nothing was charged: retry with the same idempotency key
except jusa.JusaError as jusa_error:
logger.error("Jusa refused: %s [%s]", jusa_error.code, jusa_error.request_id)
raise
Node
import { InsufficientCreditError, JusaError } from '@jusa/node';
async function sellAirtimeAtTheTill(phone, saleId, tillId) {
try {
// The till's sale number keys it: sent twice, it is one sale.
const send = await jusa.sends.create({
product: 'airtime-usd',
target: phone,
amount: '2.00',
client_reference: `sale-${saleId}`,
metadata: { till: tillId },
}, { idempotencyKey: `sale-${saleId}` });
console.log(send.id, send.status, send.cost);
} catch (error) {
if (error instanceof InsufficientCreditError) {
await topUpAndTryLater(); // nothing was charged: retry with the same idempotency key
return;
}
if (error instanceof JusaError) {
console.error(`Jusa refused: ${error.code} [${error.requestId}]`);
}
throw error;
}
}
PHP
function sellAirtimeAtTheTill(\Jusa\JusaClient $jusa, string $phone, string $saleId, string $tillId): void
{
try {
// The till's sale number keys it: sent twice, it is one sale.
$send = $jusa->sends->create([
'product' => 'airtime-usd',
'target' => $phone,
'amount' => '2.00',
'client_reference' => "sale-{$saleId}",
'metadata' => ['till' => $tillId],
], ['idempotency_key' => "sale-{$saleId}"]);
echo $send->id, ' ', $send->status, ' ', $send->cost, "\n";
} catch (\Jusa\Exception\InsufficientCreditException) {
topUpAndTryLater(); // nothing was charged: retry with the same idempotency key
} catch (\Jusa\Exception\JusaException $jusaError) {
error_log("Jusa refused: {$jusaError->getErrorCode()} [{$jusaError->getRequestId()}]");
throw $jusaError;
}
}
Go
func sellAirtimeAtTheTill(ctx context.Context, phone, saleID, tillID string) error {
// The till's sale number keys it: sent twice, it is one sale.
sendResult, err := jusaClient.Sends.Create(ctx, jusa.Params{
"product": "airtime-usd",
"target": phone,
"amount": "2.00",
"client_reference": "sale-" + saleID,
"metadata": jusa.Params{"till": tillID},
}, jusa.WithIdempotencyKey("sale-"+saleID))
if err != nil {
var insufficientCredit *jusa.InsufficientCreditError
if errors.As(err, &insufficientCredit) {
topUpAndTryLater() // nothing was charged: retry with the same idempotency key
return nil
}
return fmt.Errorf("sends.create: %w", err)
}
send := sendResult.Send
fmt.Println(send.ID, send.Status, send.Cost)
return nil
}
Java
void sellAirtimeAtTheTill(String phone, String saleId, String tillId) throws JusaException {
try {
// The till's sale number keys it: sent twice, it is one sale.
var send = jusa.sends().create(Params.of(
"product", "airtime-usd",
"target", phone,
"amount", "2.00",
"client_reference", "sale-" + saleId,
"metadata", Map.of("till", tillId)
), RequestOptions.idempotencyKey("sale-" + saleId));
System.out.println(send.getId() + " " + send.getStatus() + " " + send.getCost());
} catch (InsufficientCreditException insufficientCredit) {
topUpAndTryLater(); // nothing was charged: retry with the same idempotency key
} catch (JusaException jusaError) {
LOGGER.severe("Jusa refused: " + jusaError.getCode() + " [" + jusaError.getRequestId() + "]");
throw jusaError;
}
}
C#
async Task SellAirtimeAtTheTillAsync(string phone, string saleId, string tillId)
{
try
{
// The till's sale number keys it: sent twice, it is one sale.
var sendResult = await jusa.Sends.CreateAsync(new
{
product = "airtime-usd",
target = phone,
amount = "2.00",
client_reference = $"sale-{saleId}",
metadata = new { till = tillId },
}, new RequestOptions { IdempotencyKey = $"sale-{saleId}" });
var send = sendResult.As<Send>();
Console.WriteLine($"{send.Id} {send.Status} {send.Cost}");
}
catch (InsufficientCreditException)
{
await TopUpAndTryLater(); // nothing was charged: retry with the same idempotency key
}
catch (JusaException jusaError)
{
logger.LogError(jusaError, "Jusa refused: {Code} [{RequestId}]", jusaError.Code, jusaError.RequestId);
throw;
}
}
Dart
Future<void> sellAirtimeAtTheTill(String phone, String saleId, String tillId) async {
try {
// The till's sale number keys it: sent twice, it is one sale.
final send = await jusa.sends.create({
'product': 'airtime-usd',
'target': phone,
'amount': '2.00',
'client_reference': 'sale-$saleId',
'metadata': {'till': tillId},
}, RequestOptions(idempotencyKey: 'sale-$saleId')) as Send;
print('${send.id} ${send.status} ${send.cost}');
} on InsufficientCreditException {
await topUpAndTryLater(); // nothing was charged: retry with the same idempotency key
} on JusaException catch (jusaError) {
stderr.writeln('Jusa refused: ${jusaError.code} [${jusaError.requestId}]');
rethrow;
}
}
Ruby
def sell_airtime_at_the_till(phone, sale_id, till_id)
# The till's sale number keys it: sent twice, it is one sale.
send = Jusa::Send.create({
product: "airtime-usd",
target: phone,
amount: "2.00",
client_reference: "sale-#{sale_id}",
metadata: { till: till_id },
}, idempotency_key: "sale-#{sale_id}")
puts "#{send.id} #{send.status} #{send.cost}"
rescue Jusa::InsufficientCreditError
top_up_and_try_later # nothing was charged: retry with the same idempotency key
rescue Jusa::JusaError => jusa_error
LOGGER.error("Jusa refused: #{jusa_error.code} [#{jusa_error.request_id}]")
raise
end
curl
# The till's sale number keys it: sent twice, it is one sale.
curl https://jusa.localhost.co.zw/dev/v1/sends \
--fail-with-body \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Idempotency-Key: sale-T4-000187" \
-H "Content-Type: application/json" \
-d '{
"product": "airtime-usd",
"target": "0771230000",
"amount": "2.00",
"client_reference": "sale-T4-000187",
"metadata": {"till": "4"}
}'
{
"id": "snd_…",
"object": "send",
"livemode": false,
"network": "econet",
"amount": "2.00",
"currency": "USD",
"cost": {"amount": "1.94", "currency": "USD"},
"dealer_discount": "3.00",
"status": "pending",
"client_reference": "sale-T4-000187"
}
When it lands, send.delivered reaches your webhook, signed: print the receipt.
A dealer's sale, in test mode, in any of nine languages: a US$2.00 sale debited at its dealer cost. How a sale works, from the catalogue to the cash drawer.
What one call can do
What is always true
Price
Dealer rates below faceA verified business on the Dealer tier buys below face, per network, at the moment of each sale. Everyone else pays face value with no per-send fees.Money
Prefunded Jusa CreditTop up any amount by card or bank transfer and go live at once; dealers fund by cash collection. USD and ZWG are separate balances.Safety
Idempotent moneyEvery POST that moves money takes an Idempotency-Key; client_reference and completion_id dedupe for good.Events
Signed webhooksEvery change is an event, signed with your endpoint's secret, retried for three days, replayable.Honesty
Settlement you can plan onEach state says what happens to the money and when. A send that might have landed is never resent.Sandbox
A real test modeYour own test Jusa Credit and numbers that act out every outcome, from delivered to late-delivered.What people build
POS software, shops and agent networks, mobile money and fintech apps
Sell airtime, data and ZESA at a till or in your appYour customer pays you face value; Jusa debits your prepaid Jusa Credit, below face on the Dealer tier, and the airtime, bundle …KoboToolbox or ODK back-ends, SurveyCTO, research agencies
Reward a respondent for finishing a surveyThe seed use case. One program holds the budget and the rules; each completed survey is one reward, keyed on the submission …NGOs with enumerators
Claim cards and QR codes for offline surveysPrint a link or QR per respondent. They claim it on their own phone later; an OTP binding stops a forwarded link …Premise-style task apps
A micro-task earnings potEach task earns into a pot; the pot pays out as airtime once it reaches a threshold.Pollsters
Reimburse SMS or USSD poll costsPay back what answering a poll cost each participant, in one batch at the end of the day.Fintech and e-commerce apps
Reward in-app actions: sign-up, KYC, first transactionReward what a user does, once per user, with sign-up rewards held in escrow until they stick.Start here
POS, tills and apps
Sell airtime, data and ZESACheck, sell, tell the cashier, print the receipt, close the day.Resellers
The Dealer tierApply with your company documents; buy below face; fund by card, bank or cash collection.10 minutes
Rewards quickstartReward a survey response in test mode, then go live.Reference
Every endpointGenerated from the OpenAPI document, with curl for each.Events
WebhooksVerify the signature, dedupe on the event id.Tools
SDKs, CLI and PostmanEight SDKs (Java covers Kotlin) from our own registries,jusa listen and a collection.