Reference
API reference
Every endpoint, generated from the OpenAPI document.
Generated from the OpenAPI 3.1 document, which every response is tested
against. Base URL https://jusa.localhost.co.zw/dev/v1; every request carries Authorization: Bearer <key>
unless it says otherwise. Money is a decimal string, times are unix seconds, and every list pages with
limit, starting_after and ending_before.
Each operation's code is in all nine languages, with its required fields filled in; pick yours once. It calls the client you make once:
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
Node
import Jusa from '@jusa/node';
const jusa = new Jusa(process.env.JUSA_SECRET_KEY); // jusa_sk_test_… while you build
PHP
<?php
require __DIR__ . '/vendor/autoload.php';
$jusa = new \Jusa\JusaClient(getenv('JUSA_SECRET_KEY')); // jusa_sk_test_… while you build
Go
package main
import (
"context"
"fmt"
"log"
"os"
jusa "jusa.localhost.co.zw/sdk/go"
)
func main() {
apiKey, found := os.LookupEnv("JUSA_SECRET_KEY") // jusa_sk_test_… while you build
if !found {
log.Fatal("set JUSA_SECRET_KEY")
}
jusaClient := jusa.NewClient(apiKey)
if err := run(context.Background(), jusaClient); err != nil {
log.Fatal(err)
}
}
// run is where the samples go: each call returns its error, wrapped with what it was doing.
func run(ctx context.Context, jusaClient *jusa.Client) error {
fmt.Println("live mode:", jusaClient.IsLiveMode())
return nil
}
Java
import java.util.logging.Logger;
import zw.co.localhost.jusa.Jusa;
import zw.co.localhost.jusa.Params;
import zw.co.localhost.jusa.RequestOptions;
import zw.co.localhost.jusa.exception.InsufficientCreditException;
import zw.co.localhost.jusa.exception.JusaException;
// The samples' methods go in a class like this one. Calls throw a checked JusaException.
public class SurveyRewards {
private static final Logger LOGGER = Logger.getLogger(SurveyRewards.class.getName());
private final Jusa jusa = new Jusa(System.getenv("JUSA_SECRET_KEY")); // jusa_sk_test_… while you build
}
C#
using Jusa;
var app = WebApplication.CreateBuilder().Build();
var logger = app.Logger;
// jusa_sk_test_… while you build. Make one client and share it.
var jusa = new JusaClient(Environment.GetEnvironmentVariable("JUSA_SECRET_KEY"));
Dart
import 'dart:io';
import 'package:jusa/jusa.dart';
// jusa_sk_test_… while you build. On your server only, never in a Flutter app.
final jusa = Jusa(Platform.environment['JUSA_SECRET_KEY']);
Ruby
require "jusa"
require "logger"
LOGGER = Logger.new($stderr)
Jusa.api_key = ENV.fetch("JUSA_SECRET_KEY") # jusa_sk_test_… while you build
curl
export JUSA_SECRET_KEY=jusa_sk_test_… # a test key: nothing real moves
- Account
- Keys
- Logs
- Catalog
- Lookups
- Status
- Sends
- Disputes
- Batches
- Schedules
- Recipients
- Programs
- Rewards
- Reward links
- Reviews
- Rules
- Claims
- Agent approvals
- MCP
- Jusa Credit
- Dealer
- Checkout
- Workforce
- Family
- Reports
- Webhooks
- Test mode
- Utility
Account
Your organisation, members and the dashboard home.
Retrieve the account
Returns: 200 Account. Errors: the envelope.
Python
jusa.Account.retrieve()
Node
await jusa.account.retrieve();
PHP
$jusa->account->retrieve();
Go
_, err := jusaClient.Account.Retrieve(ctx, nil)
if err != nil {
return err
}
Java
jusa.account().retrieve();
C#
await jusa.Account.RetrieveAsync();
Dart
await jusa.account.retrieve();
Ruby
Jusa::Account.retrieve
curl
curl https://jusa.localhost.co.zw/dev/v1/account \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Update the account
Owners and admins only (a key counts as its maker). Scope: account:manage.
| Body (AccountUpdate) | Type | About |
|---|---|---|
name | string | |
contact_email | string | |
support_phone | string | A Zimbabwean mobile: 07XXXXXXXX, 2637XXXXXXXX or +2637XXXXXXXX. |
statement_descriptor | string | |
batch_approval_threshold | object | |
agent_live_enabled | boolean | Dashboard only: a person turns it on. |
Returns: 200 Account. Errors: the envelope.
Python
jusa.Account.update(statement_descriptor="ACME SURVEYS", support_phone="0772123456")
Node
await jusa.account.update({
statement_descriptor: 'ACME SURVEYS',
support_phone: '0772123456',
});
PHP
$jusa->account->update([
'statement_descriptor' => 'ACME SURVEYS',
'support_phone' => '0772123456',
]);
Go
_, err := jusaClient.Account.Update(ctx, jusa.Params{
"statement_descriptor": "ACME SURVEYS",
"support_phone": "0772123456",
})
if err != nil {
return err
}
Java
jusa.account().update(Params.of(
"statement_descriptor", "ACME SURVEYS",
"support_phone", "0772123456"
));
C#
await jusa.Account.UpdateAsync(new
{
statement_descriptor = "ACME SURVEYS",
support_phone = "0772123456",
});
Dart
await jusa.account.update({
'statement_descriptor': 'ACME SURVEYS',
'support_phone': '0772123456',
});
Ruby
Jusa::Account.update(statement_descriptor: "ACME SURVEYS", support_phone: "0772123456")
curl
curl -X PATCH https://jusa.localhost.co.zw/dev/v1/account \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"statement_descriptor": "ACME SURVEYS", "support_phone": "0772123456"}'
List pending invitations
Scope: account:manage.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
Returns: 200 InviteList. Errors: the envelope.
Python
jusa.Invite.list()
Node
await jusa.invites.list();
PHP
$jusa->invites->list();
Go
_, err := jusaClient.Invites.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.invites().list();
C#
await jusa.Invites.ListAsync();
Dart
await jusa.invites.list();
Ruby
Jusa::Invite.list
curl
curl https://jusa.localhost.co.zw/dev/v1/invites \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Retrieve an invitation
Scope: account:manage.
| Parameter | In | About |
|---|---|---|
invite_id required | path | inv_… |
Returns: 200 Invite. Errors: the envelope.
Python
jusa.Invite.retrieve("inv_…")
Node
await jusa.invites.retrieve('inv_…');
PHP
$jusa->invites->retrieve('inv_…');
Go
_, err := jusaClient.Invites.Retrieve(ctx, "inv_…", nil)
if err != nil {
return err
}
Java
jusa.invites().retrieve("inv_…");
C#
await jusa.Invites.RetrieveAsync("inv_…");
Dart
await jusa.invites.retrieve('inv_…');
Ruby
Jusa::Invite.retrieve("inv_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/invites/inv_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Revoke an invitation
Owners and admins only. Scope: account:manage.
| Parameter | In | About |
|---|---|---|
invite_id required | path | inv_… |
Returns: 200 Invite. Errors: the envelope.
Python
jusa.Invite.revoke("inv_…")
Node
await jusa.invites.revoke('inv_…');
PHP
$jusa->invites->revoke('inv_…');
Go
_, err := jusaClient.Invites.Revoke(ctx, "inv_…", nil)
if err != nil {
return err
}
Java
jusa.invites().revoke("inv_…");
C#
await jusa.Invites.RevokeAsync("inv_…");
Dart
await jusa.invites.revoke('inv_…');
Ruby
Jusa::Invite.revoke("inv_…")
curl
curl -X DELETE https://jusa.localhost.co.zw/dev/v1/invites/inv_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
List members
Scope: account:manage.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
role | query | Only members with this role. |
Returns: 200 MemberList. Errors: the envelope.
Python
jusa.Member.list()
Node
await jusa.members.list();
PHP
$jusa->members->list();
Go
_, err := jusaClient.Members.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.members().list();
C#
await jusa.Members.ListAsync();
Dart
await jusa.members.list();
Ruby
Jusa::Member.list
curl
curl https://jusa.localhost.co.zw/dev/v1/members \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Invite a member
An invitation, pending until the person signs in and accepts it from their dashboard (it lapses after 14 days). Until then they are not a member and see nothing of the account. Scope: account:manage.
| Body (MemberInvite) | Type | About |
|---|---|---|
phone | string | A Zimbabwean mobile: 07XXXXXXXX, 2637XXXXXXXX or +2637XXXXXXXX. |
email | string | |
role | "owner" | "admin" | "developer" | "viewer" |
Returns: 201 Invite. Errors: the envelope.
Python
jusa.Member.create(email="dev@example.com", role="developer")
Node
await jusa.members.create({ email: 'dev@example.com', role: 'developer' });
PHP
$jusa->members->create(['email' => 'dev@example.com', 'role' => 'developer']);
Go
_, err := jusaClient.Members.Create(ctx, jusa.Params{
"email": "dev@example.com",
"role": "developer",
})
if err != nil {
return err
}
Java
jusa.members().create(Params.of("email", "dev@example.com", "role", "developer"));
C#
await jusa.Members.CreateAsync(new { email = "dev@example.com", role = "developer" });
Dart
await jusa.members.create({'email': 'dev@example.com', 'role': 'developer'});
Ruby
Jusa::Member.create(email: "dev@example.com", role: "developer")
curl
curl https://jusa.localhost.co.zw/dev/v1/members \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "dev@example.com", "role": "developer"}'
Retrieve a member
Scope: account:manage.
| Parameter | In | About |
|---|---|---|
member_id required | path | mem_… |
Returns: 200 Member. Errors: the envelope.
Python
jusa.Member.retrieve("mem_…")
Node
await jusa.members.retrieve('mem_…');
PHP
$jusa->members->retrieve('mem_…');
Go
_, err := jusaClient.Members.Retrieve(ctx, "mem_…", nil)
if err != nil {
return err
}
Java
jusa.members().retrieve("mem_…");
C#
await jusa.Members.RetrieveAsync("mem_…");
Dart
await jusa.members.retrieve('mem_…');
Ruby
Jusa::Member.retrieve("mem_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/members/mem_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Change a member's role
Scope: account:manage.
| Parameter | In | About |
|---|---|---|
member_id required | path | mem_… |
| Body (MemberUpdate) | Type | About |
|---|---|---|
role required | "owner" | "admin" | "developer" | "viewer" |
Returns: 200 Member. Errors: the envelope.
Python
jusa.Member.update("mem_…", role="owner")
Node
await jusa.members.update('mem_…', { role: 'owner' });
PHP
$jusa->members->update('mem_…', ['role' => 'owner']);
Go
_, err := jusaClient.Members.Update(ctx, "mem_…", jusa.Params{"role": "owner"})
if err != nil {
return err
}
Java
jusa.members().update("mem_…", Params.of("role", "owner"));
C#
await jusa.Members.UpdateAsync("mem_…", new { role = "owner" });
Dart
await jusa.members.update('mem_…', {'role': 'owner'});
Ruby
Jusa::Member.update("mem_…", role: "owner")
curl
curl -X PATCH https://jusa.localhost.co.zw/dev/v1/members/mem_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"role": "owner"}'
Remove a member
Scope: account:manage.
| Parameter | In | About |
|---|---|---|
member_id required | path | mem_… |
Returns: 200 Member. Errors: the envelope.
Python
jusa.Member.delete("mem_…")
Node
await jusa.members.delete('mem_…');
PHP
$jusa->members->delete('mem_…');
Go
_, err := jusaClient.Members.Delete(ctx, "mem_…", nil)
if err != nil {
return err
}
Java
jusa.members().delete("mem_…");
C#
await jusa.Members.DeleteAsync("mem_…");
Dart
await jusa.members.delete('mem_…');
Ruby
Jusa::Member.delete("mem_…")
curl
curl -X DELETE https://jusa.localhost.co.zw/dev/v1/members/mem_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Your organisations
Dashboard only (a signed-in person): each organisation you belong to and whether it is a developer organisation.
Returns: 200 OrganisationList. Errors: the envelope.
curl
curl https://jusa.localhost.co.zw/dev/v1/organisations \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Create a developer organisation
Dashboard only (a signed-in person): makes the live org and its test-mode twin.
| Body (OrganisationCreate) | Type | About |
|---|---|---|
name | string |
Returns: 201 Account. Errors: the envelope.
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/organisations \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Invitations waiting for you
Dashboard only (a signed-in person).
Returns: 200 InviteList. Errors: the envelope.
curl
curl https://jusa.localhost.co.zw/dev/v1/organisations/invites \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Accept an invitation
Dashboard only: the person invited, signed in.
| Parameter | In | About |
|---|---|---|
invite_id required | path | inv_… |
Returns: 200 Organisation. Errors: the envelope.
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/organisations/invites/inv_…/accept \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Decline an invitation
Dashboard only: the person invited, signed in.
| Parameter | In | About |
|---|---|---|
invite_id required | path | inv_… |
Returns: 200 Invite. Errors: the envelope.
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/organisations/invites/inv_…/decline \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
The dashboard home
Jusa Credit with runway, sends today, success by network, webhook health and what needs attention. Sections the caller cannot read are null.
Returns: 200 Overview. Errors: the envelope.
Python
jusa.Overview.retrieve()
Node
await jusa.overview.retrieve();
PHP
$jusa->overview->retrieve();
Go
_, err := jusaClient.Overview.Retrieve(ctx, nil)
if err != nil {
return err
}
Java
jusa.overview().retrieve();
C#
await jusa.Overview.RetrieveAsync();
Dart
await jusa.overview.retrieve();
Ruby
Jusa::Overview.retrieve
curl
curl https://jusa.localhost.co.zw/dev/v1/overview \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Keys
API keys: sk secret, rk restricted, pk publishable, ak agent.
List API keys
Scope: account:manage.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
status | query | Only objects in this status. |
Returns: 200 ApiKeyList. Errors: the envelope.
Python
jusa.ApiKey.list()
Node
await jusa.keys.list();
PHP
$jusa->keys->list();
Go
_, err := jusaClient.Keys.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.keys().list();
C#
await jusa.Keys.ListAsync();
Dart
await jusa.keys.list();
Ruby
Jusa::ApiKey.list
curl
curl https://jusa.localhost.co.zw/dev/v1/keys \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Create an API key
The key is in secret, once. The first live key needs accept_terms: true (the API Terms, the Acceptable Use policy and the DPA). No Idempotency-Key: a replay would have to show the secret again. Scope: account:manage.
| Body (KeyCreate) | Type | About |
|---|---|---|
kind | "sk" | "rk" | "pk" | "ak" | |
label | string | |
scopes | array of "catalog:read" | "lookups:read" | "sends:read" | "sends:write" | "tokens:read" | "batches:write" | "schedules:write" | "credit:read" | "credit:topup" | "recipients:read" | "recipients:write" | "rewards:read" | "rewards:write" | "programs:manage" | "webhooks:manage" | "reports:read" | "workforce:admin" | "family:write" | "account:manage" | |
allowed_ips | array of string | |
expires_at | integer or string | Unix seconds or an ISO 8601 time. |
accept_terms | boolean | The first live key: accept the API Terms, AUP and DPA. |
allowed_products | array of string | |
allowed_networks | array of string | |
spend_caps | object | |
per_recipient_daily_cap | object | |
approval_threshold | object | |
recipient_allowlist | array of string | |
allowed_origins | array of string |
Returns: 201 ApiKey. Errors: the envelope.
Python
jusa.ApiKey.create(kind="rk", label="survey relay", scopes=["rewards:write"])
Node
await jusa.keys.create({
kind: 'rk',
label: 'survey relay',
scopes: ['rewards:write'],
});
PHP
$jusa->keys->create([
'kind' => 'rk',
'label' => 'survey relay',
'scopes' => ['rewards:write'],
]);
Go
_, err := jusaClient.Keys.Create(ctx, jusa.Params{
"kind": "rk",
"label": "survey relay",
"scopes": []string{"rewards:write"},
})
if err != nil {
return err
}
Java
jusa.keys().create(Params.of(
"kind", "rk",
"label", "survey relay",
"scopes", List.of("rewards:write")
));
C#
await jusa.Keys.CreateAsync(new
{
kind = "rk",
label = "survey relay",
scopes = new[] { "rewards:write" },
});
Dart
await jusa.keys.create({
'kind': 'rk',
'label': 'survey relay',
'scopes': ['rewards:write'],
});
Ruby
Jusa::ApiKey.create(kind: "rk", label: "survey relay", scopes: ["rewards:write"])
curl
curl https://jusa.localhost.co.zw/dev/v1/keys \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"kind": "rk", "label": "survey relay", "scopes": ["rewards:write"]}'
Retrieve an API key
With usage: what it has spent against its caps. Scope: account:manage.
| Parameter | In | About |
|---|---|---|
key_id required | path | key_… |
Returns: 200 ApiKey. Errors: the envelope.
Python
jusa.ApiKey.retrieve("key_…")
Node
await jusa.keys.retrieve('key_…');
PHP
$jusa->keys->retrieve('key_…');
Go
_, err := jusaClient.Keys.Retrieve(ctx, "key_…", nil)
if err != nil {
return err
}
Java
jusa.keys().retrieve("key_…");
C#
await jusa.Keys.RetrieveAsync("key_…");
Dart
await jusa.keys.retrieve('key_…');
Ruby
Jusa::ApiKey.retrieve("key_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/keys/key_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Update an API key
Scope: account:manage.
| Parameter | In | About |
|---|---|---|
key_id required | path | key_… |
| Body (KeyUpdate) | Type | About |
|---|---|---|
label | string | |
scopes | array of "catalog:read" | "lookups:read" | "sends:read" | "sends:write" | "tokens:read" | "batches:write" | "schedules:write" | "credit:read" | "credit:topup" | "recipients:read" | "recipients:write" | "rewards:read" | "rewards:write" | "programs:manage" | "webhooks:manage" | "reports:read" | "workforce:admin" | "family:write" | "account:manage" | |
allowed_ips | array of string | |
expires_at | integer or string | Unix seconds or an ISO 8601 time. |
allowed_products | array of string | |
allowed_networks | array of string | |
spend_caps | object | |
per_recipient_daily_cap | object | |
approval_threshold | object | |
recipient_allowlist | array of string | |
allowed_origins | array of string |
Returns: 200 ApiKey. Errors: the envelope.
Python
jusa.ApiKey.update("key_…")
Node
await jusa.keys.update('key_…');
PHP
$jusa->keys->update('key_…');
Go
_, err := jusaClient.Keys.Update(ctx, "key_…", nil)
if err != nil {
return err
}
Java
jusa.keys().update("key_…");
C#
await jusa.Keys.UpdateAsync("key_…");
Dart
await jusa.keys.update('key_…');
Ruby
Jusa::ApiKey.update("key_…")
curl
curl -X PATCH https://jusa.localhost.co.zw/dev/v1/keys/key_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Revoke an API key
Takes effect at once. Scope: account:manage.
| Parameter | In | About |
|---|---|---|
key_id required | path | key_… |
Returns: 200 ApiKey. Errors: the envelope.
Python
jusa.ApiKey.revoke("key_…")
Node
await jusa.keys.revoke('key_…');
PHP
$jusa->keys->revoke('key_…');
Go
_, err := jusaClient.Keys.Revoke(ctx, "key_…", nil)
if err != nil {
return err
}
Java
jusa.keys().revoke("key_…");
C#
await jusa.Keys.RevokeAsync("key_…");
Dart
await jusa.keys.revoke('key_…');
Ruby
Jusa::ApiKey.revoke("key_…")
curl
curl -X DELETE https://jusa.localhost.co.zw/dev/v1/keys/key_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Roll an API key
A new key in secret; the old one (in rolled) works for the grace period. Scope: account:manage.
| Parameter | In | About |
|---|---|---|
key_id required | path | key_… |
| Body (KeyRoll) | Type | About |
|---|---|---|
grace_period | "0" | "1h" | "24h" | "7d" | 0 | How long the old key keeps working. |
Returns: 201 ApiKey. Errors: the envelope.
Python
jusa.ApiKey.roll("key_…")
Node
await jusa.keys.roll('key_…');
PHP
$jusa->keys->roll('key_…');
Go
_, err := jusaClient.Keys.Roll(ctx, "key_…", nil)
if err != nil {
return err
}
Java
jusa.keys().roll("key_…");
C#
await jusa.Keys.RollAsync("key_…");
Dart
await jusa.keys.roll('key_…');
Ruby
Jusa::ApiKey.roll("key_…")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/keys/key_…/roll \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Logs
The request log and the audit log.
Recent account activity
What happened lately (events: sends, rewards, top-ups, batches …), newest first, and, with account:manage, who changed what (the audit log). Pages back with starting_after. Scope: reports:read.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
Returns: 200 AccountActivityList. Errors: the envelope.
Python
jusa.ActivityFeed.list()
Node
await jusa.activityFeed.list();
PHP
$jusa->activityFeed->list();
Go
_, err := jusaClient.ActivityFeed.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.activityFeed().list();
C#
await jusa.ActivityFeed.ListAsync();
Dart
await jusa.activityFeed.list();
Ruby
Jusa::ActivityFeed.list
curl
curl https://jusa.localhost.co.zw/dev/v1/activity \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
List audit events
Who (a key, a member, or Jusa staff viewing as you) changed what. Scope: account:manage.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
action | query | Only this action (send or reward; for the audit log, e.g. api_key.created). |
object | query | Events about this object, e.g. snd_… |
Returns: 200 AuditEventList. Errors: the envelope.
Python
jusa.AuditLog.list()
Node
await jusa.auditLog.list();
PHP
$jusa->auditLog->list();
Go
_, err := jusaClient.AuditLog.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.auditLog().list();
C#
await jusa.AuditLog.ListAsync();
Dart
await jusa.auditLog.list();
Ruby
Jusa::AuditLog.list
curl
curl https://jusa.localhost.co.zw/dev/v1/audit-log \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
List API requests
Kept 30 days. status is a code (402) or a class (4xx). Scope: account:manage.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
api_key | query | key_… |
status | query | Only objects in this status. |
path | query | Paths starting with this. |
method | query | GET, POST, … |
idempotency_key | query | Requests sent with this key. |
Returns: 200 RequestLogList. Errors: the envelope.
Python
jusa.RequestLog.list()
Node
await jusa.requests.list();
PHP
$jusa->requests->list();
Go
_, err := jusaClient.Requests.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.requests().list();
C#
await jusa.Requests.ListAsync();
Dart
await jusa.requests.list();
Ruby
Jusa::RequestLog.list
curl
curl https://jusa.localhost.co.zw/dev/v1/requests \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Retrieve an API request
With the masked request and response bodies. Scope: account:manage.
| Parameter | In | About |
|---|---|---|
request_id required | path | req_… |
Returns: 200 RequestLog. Errors: the envelope.
Python
jusa.RequestLog.retrieve("req_…")
Node
await jusa.requests.retrieve('req_…');
PHP
$jusa->requests->retrieve('req_…');
Go
_, err := jusaClient.Requests.Retrieve(ctx, "req_…", nil)
if err != nil {
return err
}
Java
jusa.requests().retrieve("req_…");
C#
await jusa.Requests.RetrieveAsync("req_…");
Dart
await jusa.requests.retrieve('req_…');
Ruby
Jusa::RequestLog.retrieve("req_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/requests/req_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Catalog
Products and networks. Face value on the standard tier; a verified dealer buys at its rates.
List networks
Scope: catalog:read. Publishable keys may call it (from a browser).
Returns: 200 NetworkList. Errors: the envelope.
Python
jusa.Network.list()
Node
await jusa.networks.list();
PHP
$jusa->networks->list();
Go
_, err := jusaClient.Networks.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.networks().list();
C#
await jusa.Networks.ListAsync();
Dart
await jusa.networks.list();
Ruby
Jusa::Network.list
curl
curl https://jusa.localhost.co.zw/dev/v1/networks \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
List products
Face value, always: there is no pricing endpoint. Scope: catalog:read. Publishable keys may call it (from a browser).
| Parameter | In | About |
|---|---|---|
type | query | Only this type. |
network | query | Only this network. |
currency | query | Only this currency. |
Returns: 200 ProductList. Errors: the envelope.
Python
jusa.Product.list()
Node
await jusa.products.list();
PHP
$jusa->products->list();
Go
_, err := jusaClient.Products.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.products().list();
C#
await jusa.Products.ListAsync();
Dart
await jusa.products.list();
Ruby
Jusa::Product.list
curl
curl https://jusa.localhost.co.zw/dev/v1/products \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Retrieve a product
Scope: catalog:read. Publishable keys may call it (from a browser).
| Parameter | In | About |
|---|---|---|
product_id required | path | A product slug. |
Returns: 200 Product. Errors: the envelope.
Python
jusa.Product.retrieve("airtime-usd")
Node
await jusa.products.retrieve('airtime-usd');
PHP
$jusa->products->retrieve('airtime-usd');
Go
_, err := jusaClient.Products.Retrieve(ctx, "airtime-usd", nil)
if err != nil {
return err
}
Java
jusa.products().retrieve("airtime-usd");
C#
await jusa.Products.RetrieveAsync("airtime-usd");
Dart
await jusa.products.retrieve('airtime-usd');
Ruby
Jusa::Product.retrieve("airtime-usd")
curl
curl https://jusa.localhost.co.zw/dev/v1/products/airtime-usd \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
List a data product's bundles
Test mode has a simulated list; live data bundles ship in P2. Scope: catalog:read. Publishable keys may call it (from a browser).
| Parameter | In | About |
|---|---|---|
product_id required | path | A product slug. |
Returns: 200 BundleList. Errors: the envelope.
Python
jusa.Product.list_bundles("airtime-usd")
Node
await jusa.products.listBundles('airtime-usd');
PHP
$jusa->products->listBundles('airtime-usd');
Go
_, err := jusaClient.Products.ListBundles(ctx, "airtime-usd", nil)
if err != nil {
return err
}
Java
jusa.products().listBundles("airtime-usd");
C#
await jusa.Products.ListBundlesAsync("airtime-usd");
Dart
await jusa.products.listBundles('airtime-usd');
Ruby
Jusa::Product.list_bundles("airtime-usd")
curl
curl https://jusa.localhost.co.zw/dev/v1/products/airtime-usd/bundles \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Lookups
Phone lookups, ZESA meter confirmation and quotes.
Look up a phone number
Its network and E.164 form. No provider is asked. Scope: lookups:read.
| Parameter | In | About |
|---|---|---|
phone | query | A phone number, any Zimbabwean format. |
currency | query | Only this currency. |
Returns: 200 PhoneLookup. Errors: the envelope.
Python
jusa.Lookup.phone()
Node
await jusa.lookups.phone();
PHP
$jusa->lookups->phone();
Go
_, err := jusaClient.Lookups.Phone(ctx, nil)
if err != nil {
return err
}
Java
jusa.lookups().phone();
C#
await jusa.Lookups.PhoneAsync();
Dart
await jusa.lookups.phone();
Ruby
Jusa::Lookup.phone
curl
curl https://jusa.localhost.co.zw/dev/v1/lookups/phone \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Confirm a ZESA meter
The name is masked and the address is the suburb. Rationed: 30 a minute per key and a daily quota per account. 503 zesa_unavailable when ZESA is down. Scope: lookups:read.
| Parameter | In | About |
|---|---|---|
number required | path | An 11-digit meter number. |
currency | query | Only this currency. |
Returns: 200 Meter. Errors: the envelope.
Python
jusa.Meter.retrieve("37261502217")
Node
await jusa.meters.retrieve('37261502217');
PHP
$jusa->meters->retrieve('37261502217');
Go
_, err := jusaClient.Meters.Retrieve(ctx, "37261502217", nil)
if err != nil {
return err
}
Java
jusa.meters().retrieve("37261502217");
C#
await jusa.Meters.RetrieveAsync("37261502217");
Dart
await jusa.meters.retrieve('37261502217');
Ruby
Jusa::Meter.retrieve("37261502217")
curl
curl https://jusa.localhost.co.zw/dev/v1/meters/37261502217 \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Quote a send
you_pay is always the face value. For ZESA: the units and band now and after the reset, and a strictly confirmed meter that a send carries by passing the quote. Scope: lookups:read.
| Body (QuoteCreate) | Type | About |
|---|---|---|
product | string | |
amount | string or number | A decimal amount, e.g. "5.00". |
currency | "USD" | "ZWG" | "usd" | "zwg" | USD or ZWG (either case). |
target | string | |
bundle_id | string |
Returns: 201 Quote. Errors: the envelope.
Python
jusa.Quote.create(product="zesa-usd", amount="10.00", target="37261502217")
Node
await jusa.quotes.create({
product: 'zesa-usd',
amount: '10.00',
target: '37261502217',
});
PHP
$jusa->quotes->create([
'product' => 'zesa-usd',
'amount' => '10.00',
'target' => '37261502217',
]);
Go
_, err := jusaClient.Quotes.Create(ctx, jusa.Params{
"product": "zesa-usd",
"amount": "10.00",
"target": "37261502217",
})
if err != nil {
return err
}
Java
jusa.quotes().create(Params.of(
"product", "zesa-usd",
"amount", "10.00",
"target", "37261502217"
));
C#
await jusa.Quotes.CreateAsync(new
{
product = "zesa-usd",
amount = "10.00",
target = "37261502217",
});
Dart
await jusa.quotes.create({
'product': 'zesa-usd',
'amount': '10.00',
'target': '37261502217',
});
Ruby
Jusa::Quote.create(product: "zesa-usd", amount: "10.00", target: "37261502217")
curl
curl https://jusa.localhost.co.zw/dev/v1/quotes \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"product": "zesa-usd", "amount": "10.00", "target": "37261502217"}'
Retrieve a quote
Scope: lookups:read.
| Parameter | In | About |
|---|---|---|
quote_id required | path | quo_… |
Returns: 200 Quote. Errors: the envelope.
Python
jusa.Quote.retrieve("quo_…")
Node
await jusa.quotes.retrieve('quo_…');
PHP
$jusa->quotes->retrieve('quo_…');
Go
_, err := jusaClient.Quotes.Retrieve(ctx, "quo_…", nil)
if err != nil {
return err
}
Java
jusa.quotes().retrieve("quo_…");
C#
await jusa.Quotes.RetrieveAsync("quo_…");
Dart
await jusa.quotes.retrieve('quo_…');
Ruby
Jusa::Quote.retrieve("quo_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/quotes/quo_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Status
ZESA and network availability.
ZESA and network status
Publishable keys may call it (from a browser).
Returns: 200 Status. Errors: the envelope.
Python
jusa.Status.retrieve()
Node
await jusa.status.retrieve();
PHP
$jusa->status->retrieve();
Go
_, err := jusaClient.Status.Retrieve(ctx, nil)
if err != nil {
return err
}
Java
jusa.status().retrieve();
C#
await jusa.Status.RetrieveAsync();
Dart
await jusa.status.retrieve();
Ruby
Jusa::Status.retrieve
curl
curl https://jusa.localhost.co.zw/dev/v1/status \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
ZESA uptime history
The last 7 days by default. Publishable keys may call it (from a browser).
| Parameter | In | About |
|---|---|---|
from | query | The start (inclusive). |
to | query | The end (inclusive). |
Returns: 200 StatusHistory. Errors: the envelope.
Python
jusa.Status.history()
Node
await jusa.status.history();
PHP
$jusa->status->history();
Go
_, err := jusaClient.Status.History(ctx, nil)
if err != nil {
return err
}
Java
jusa.status().history();
C#
await jusa.Status.HistoryAsync();
Dart
await jusa.status.history();
Ruby
Jusa::Status.history
curl
curl https://jusa.localhost.co.zw/dev/v1/status/history \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
The purchases behind Rate Watch
Anonymised and coarsened: no meter, no order. Scope: lookups:read.
| Parameter | In | About |
|---|---|---|
currency | query | Only this currency. |
days | query | How many days back (90 by default). |
limit | query | Rows per page. |
Returns: 200 ZesaObservations. Errors: the envelope.
Python
jusa.Zesa.observations()
Node
await jusa.zesa.observations();
PHP
$jusa->zesa->observations();
Go
_, err := jusaClient.Zesa.Observations(ctx, nil)
if err != nil {
return err
}
Java
jusa.zesa().observations();
C#
await jusa.Zesa.ObservationsAsync();
Dart
await jusa.zesa.observations();
Ruby
Jusa::Zesa.observations
curl
curl https://jusa.localhost.co.zw/dev/v1/zesa/observations \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
What an amount buys on ZESA
Units now versus after the reset on the 1st; with meter, from where that meter stands this month (a meter is rationed like a lookup). POST /v1/quotes also confirms the meter. Scope: lookups:read.
| Parameter | In | About |
|---|---|---|
currency | query | Only this currency. |
amount | query | A decimal amount, e.g. 10.00. |
meter | query | A meter number. |
Returns: 200 ZesaRate. Errors: the envelope.
Python
jusa.Zesa.quote()
Node
await jusa.zesa.quote();
PHP
$jusa->zesa->quote();
Go
_, err := jusaClient.Zesa.Quote(ctx, nil)
if err != nil {
return err
}
Java
jusa.zesa().quote();
C#
await jusa.Zesa.QuoteAsync();
Dart
await jusa.zesa.quote();
Ruby
Jusa::Zesa.quote
curl
curl https://jusa.localhost.co.zw/dev/v1/zesa/quote \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
ZESA Rate Watch
ZETDC's published bands, what real purchases show a kWh costs, and the cheapest-units rule (the bands reset on the 1st). Public data, the same in test and live mode. Scope: catalog:read.
| Parameter | In | About |
|---|---|---|
currency | query | Only this currency. |
Returns: 200 ZesaRate. Errors: the envelope.
Python
jusa.Zesa.rate()
Node
await jusa.zesa.rate();
PHP
$jusa->zesa->rate();
Go
_, err := jusaClient.Zesa.Rate(ctx, nil)
if err != nil {
return err
}
Java
jusa.zesa().rate();
C#
await jusa.Zesa.RateAsync();
Dart
await jusa.zesa.rate();
Ruby
Jusa::Zesa.rate
curl
curl https://jusa.localhost.co.zw/dev/v1/zesa/rate \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
ZESA rate series
The sparkline of the observed rate and where it changed. Scope: catalog:read.
| Parameter | In | About |
|---|---|---|
currency | query | Only this currency. |
Returns: 200 ZesaSeries. Errors: the envelope.
Python
jusa.Zesa.series()
Node
await jusa.zesa.series();
PHP
$jusa->zesa->series();
Go
_, err := jusaClient.Zesa.Series(ctx, nil)
if err != nil {
return err
}
Java
jusa.zesa().series();
C#
await jusa.Zesa.SeriesAsync();
Dart
await jusa.zesa.series();
Ruby
Jusa::Zesa.series
curl
curl https://jusa.localhost.co.zw/dev/v1/zesa/series \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Sends
Airtime, data and ZESA tokens, one at a time. Async: 202, then webhooks.
List sends
Scope: sends:read.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
status | query | Only objects in this status. |
type | query | Only this type. |
target | query | A phone (any format) or meter. |
client_reference | query | Your own reference. |
currency | query | Only this currency. |
needs_attention | query | unknown over 1h, requires_review, or queued past half its max_hold. |
recipient | query | rcp_… or ext:<external_id>. |
program | query | prg_… |
batch | query | bch_… |
cost_center | query | cc_… (Workforce: a department's id, or none for sends booked to none). |
api_key | query | key_… |
metadata[key] | query | metadata[<key>]=<value>: an exact match on one key. |
expand[] | query | Inline a related object in place of its id (repeat for more): recipient, program or batch on a send; recipient, program or send on a reward. |
Returns: 200 SendList. Errors: the envelope.
Python
jusa.Send.list()
Node
await jusa.sends.list();
PHP
$jusa->sends->list();
Go
_, err := jusaClient.Sends.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.sends().list();
C#
await jusa.Sends.ListAsync();
Dart
await jusa.sends.list();
Ruby
Jusa::Send.list
curl
curl https://jusa.localhost.co.zw/dev/v1/sends \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Create a send
Always async: the send is written and charged, then dispatched; webhooks and GET tell the rest. validate_only: true runs every check and writes nothing (200, no Idempotency-Key needed). A client_reference already used returns that send (200). An agent key over its threshold or to a new target gets 202 with an agent_approval instead. Scope: sends:write. Moves money: an Idempotency-Key is required.
| Body (SendCreate) | Type | About |
|---|---|---|
type | "airtime" | "data" | "zesa" | Inferred from product or target when left out. |
product | string | |
target | string | A phone (any Zimbabwean format) or an 11-digit meter. |
amount | string or number | A decimal amount, e.g. "5.00". |
currency | "USD" | "ZWG" | "usd" | "zwg" | USD or ZWG (either case). |
bundle_id | string | Data: the bundle to send. |
token_phone | string | ZESA: required. The token is texted here. |
token_email | string | |
notify_number | string | A Zimbabwean mobile: 07XXXXXXXX, 2637XXXXXXXX or +2637XXXXXXXX. |
confirm | "strict" | "best_effort" | ZESA meter confirmation. strict (default) refuses when ZESA cannot answer. |
on_zesa_down | "queue" | "fail" | |
max_hold | string or integer | Seconds, or "30m", "24h", "3d". |
recipient | string or object | rcp_… or ext:<external_id>. |
program | string | prg_…: attribution only (reports, filters). A send never draws on or is capped by a program's budget: pay a program's budget out with POST /v1/rewards. |
cost_center | string | |
sms_message | string | Merge fields: {sender}, {name}, {first_name}, {amount}, {currency}, {date}… Left out, airtime and data carry a default that names you (statement_descriptor). |
sms_locale | "en" | "sn" | "nd" | The default SMS's language: English, Shona or Ndebele. |
scheduled_for | integer or string | A later send, 90 seconds to 180 days ahead: charged now, status scheduled until then, cancellable until it goes. |
client_reference | string | |
quote | string | quo_…: carries a strict meter confirmation. |
validate_only | boolean | |
metadata | object | Up to 20 keys (letters, digits, _ . -, up to 40 characters) with values up to 500 characters. |
reason | string | Agent keys: shown to the person asked to approve. |
Returns: 200 Send or SendValidation · 202 Send or AgentApproval. Errors: the envelope.
Python
jusa.Send.create(
product="airtime-usd",
target="0772123456",
amount="1.00",
client_reference="order-8812",
idempotency_key="order-8812",
)
Node
await jusa.sends.create({
product: 'airtime-usd',
target: '0772123456',
amount: '1.00',
client_reference: 'order-8812',
}, { idempotencyKey: 'order-8812' });
PHP
$jusa->sends->create([
'product' => 'airtime-usd',
'target' => '0772123456',
'amount' => '1.00',
'client_reference' => 'order-8812',
], ['idempotency_key' => 'order-8812']);
Go
_, err := jusaClient.Sends.Create(ctx, jusa.Params{
"product": "airtime-usd",
"target": "0772123456",
"amount": "1.00",
"client_reference": "order-8812",
}, jusa.WithIdempotencyKey("order-8812"))
if err != nil {
return err
}
Java
jusa.sends().create(Params.of(
"product", "airtime-usd",
"target", "0772123456",
"amount", "1.00",
"client_reference", "order-8812"
), RequestOptions.idempotencyKey("order-8812"));
C#
await jusa.Sends.CreateAsync(new
{
product = "airtime-usd",
target = "0772123456",
amount = "1.00",
client_reference = "order-8812",
}, new RequestOptions { IdempotencyKey = "order-8812" });
Dart
await jusa.sends.create({
'product': 'airtime-usd',
'target': '0772123456',
'amount': '1.00',
'client_reference': 'order-8812',
}, RequestOptions(idempotencyKey: 'order-8812'));
Ruby
Jusa::Send.create({
product: "airtime-usd",
target: "0772123456",
amount: "1.00",
client_reference: "order-8812",
}, idempotency_key: "order-8812")
curl
curl https://jusa.localhost.co.zw/dev/v1/sends \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Idempotency-Key: order-8812" \
-H "Content-Type: application/json" \
-d '{
"product": "airtime-usd",
"target": "0772123456",
"amount": "1.00",
"client_reference": "order-8812"
}'
Retrieve a send
Scope: sends:read.
| Parameter | In | About |
|---|---|---|
send_id required | path | snd_… (or the bare hex of a legacy order). |
expand[] | query | Inline a related object in place of its id (repeat for more): recipient, program or batch on a send; recipient, program or send on a reward. |
Returns: 200 Send. Errors: the envelope.
Python
jusa.Send.retrieve("snd_…")
Node
await jusa.sends.retrieve('snd_…');
PHP
$jusa->sends->retrieve('snd_…');
Go
_, err := jusaClient.Sends.Retrieve(ctx, "snd_…", nil)
if err != nil {
return err
}
Java
jusa.sends().retrieve("snd_…");
C#
await jusa.Sends.RetrieveAsync("snd_…");
Dart
await jusa.sends.retrieve('snd_…');
Ruby
Jusa::Send.retrieve("snd_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/sends/snd_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
A send's attempts
When it went to the provider, and each time Hot Recharge was asked what it recorded (outcomes only). Scope: sends:read.
| Parameter | In | About |
|---|---|---|
send_id required | path | snd_… (or the bare hex of a legacy order). |
Returns: 200 SendAttemptList. Errors: the envelope.
Python
jusa.Send.list_attempts("snd_…")
Node
await jusa.sends.listAttempts('snd_…');
PHP
$jusa->sends->listAttempts('snd_…');
Go
_, err := jusaClient.Sends.ListAttempts(ctx, "snd_…", nil)
if err != nil {
return err
}
Java
jusa.sends().listAttempts("snd_…");
C#
await jusa.Sends.ListAttemptsAsync("snd_…");
Dart
await jusa.sends.listAttempts('snd_…');
Ruby
Jusa::Send.list_attempts("snd_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/sends/snd_…/attempts \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Cancel a send not yet sent
A scheduled send, or one still waiting to go: the credit comes back (cancelled_credited). 409 already_sent once it has gone. Scope: sends:write.
| Parameter | In | About |
|---|---|---|
send_id required | path | snd_… (or the bare hex of a legacy order). |
Returns: 200 Send. Errors: the envelope.
Python
jusa.Send.cancel("snd_…")
Node
await jusa.sends.cancel('snd_…');
PHP
$jusa->sends->cancel('snd_…');
Go
_, err := jusaClient.Sends.Cancel(ctx, "snd_…", nil)
if err != nil {
return err
}
Java
jusa.sends().cancel("snd_…");
C#
await jusa.Sends.CancelAsync("snd_…");
Dart
await jusa.sends.cancel('snd_…');
Ruby
Jusa::Send.cancel("snd_…")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/sends/snd_…/cancel \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Change a ZESA send's meter
Only while it has not gone out (queued while ZESA is down, or scheduled). The new meter is confirmed now when ZESA answers, else before the send goes out. Audited, and send.meter_changed goes to every endpoint. Scope: sends:write.
| Parameter | In | About |
|---|---|---|
send_id required | path | snd_… (or the bare hex of a legacy order). |
| Body (SendMeterChange) | Type | About |
|---|---|---|
meter required | string | An 11-digit ZESA prepaid meter number. |
Returns: 200 Send. Errors: the envelope.
Python
jusa.Send.change_meter("snd_…", meter="37261502217")
Node
await jusa.sends.changeMeter('snd_…', { meter: '37261502217' });
PHP
$jusa->sends->changeMeter('snd_…', ['meter' => '37261502217']);
Go
_, err := jusaClient.Sends.ChangeMeter(ctx, "snd_…", jusa.Params{
"meter": "37261502217",
})
if err != nil {
return err
}
Java
jusa.sends().changeMeter("snd_…", Params.of("meter", "37261502217"));
C#
await jusa.Sends.ChangeMeterAsync("snd_…", new { meter = "37261502217" });
Dart
await jusa.sends.changeMeter('snd_…', {'meter': '37261502217'});
Ruby
Jusa::Send.change_meter("snd_…", meter: "37261502217")
curl
curl https://jusa.localhost.co.zw/dev/v1/sends/snd_…/meter \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"meter": "37261502217"}'
A delivered send's receipt
JSON, or ?format=pdf for the same receipt as a PDF. The token is masked without tokens:read. Scope: sends:read.
| Parameter | In | About |
|---|---|---|
send_id required | path | snd_… (or the bare hex of a legacy order). |
format | query | json (default); csv for reports and the Workforce files (the ledger also takes csv-json, the file inside JSON); pdf for a receipt. |
Returns: 200 Receipt. Errors: the envelope.
Python
jusa.Send.receipt("snd_…")
Node
await jusa.sends.receipt('snd_…');
PHP
$jusa->sends->receipt('snd_…');
Go
_, err := jusaClient.Sends.Receipt(ctx, "snd_…", nil)
if err != nil {
return err
}
Java
jusa.sends().receipt("snd_…");
C#
await jusa.Sends.ReceiptAsync("snd_…");
Dart
await jusa.sends.receipt('snd_…');
Ruby
Jusa::Send.receipt("snd_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/sends/snd_…/receipt \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Text a ZESA token again
Only to the phone and email it went to first. Rate-limited. Scope: sends:write.
| Parameter | In | About |
|---|---|---|
send_id required | path | snd_… (or the bare hex of a legacy order). |
Returns: 202 TokenResend. Errors: the envelope.
Python
jusa.Send.resend_token("snd_…")
Node
await jusa.sends.resendToken('snd_…');
PHP
$jusa->sends->resendToken('snd_…');
Go
_, err := jusaClient.Sends.ResendToken(ctx, "snd_…", nil)
if err != nil {
return err
}
Java
jusa.sends().resendToken("snd_…");
C#
await jusa.Sends.ResendTokenAsync("snd_…");
Dart
await jusa.sends.resendToken('snd_…');
Ruby
Jusa::Send.resend_token("snd_…")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/sends/snd_…/resend-token \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Retry a failed send
A terminal failed send (failed_credited or failed) only, sent again as a new send charged now, with retry_of. Hot Recharge is asked about the first send before anything is resent: delivered after all is 409 send_delivered_late, no answer is 503 provider_unavailable. 409 send_not_retryable from any other state, for a card checkout's send, and for a send already retried. Scope: sends:write. Moves money: an Idempotency-Key is required.
| Parameter | In | About |
|---|---|---|
send_id required | path | snd_… (or the bare hex of a legacy order). |
Returns: 202 Send. Errors: the envelope.
Python
jusa.Send.retry("snd_…", idempotency_key="retry-order-8812-1")
Node
await jusa.sends.retry('snd_…', {}, { idempotencyKey: 'retry-order-8812-1' });
PHP
$jusa->sends->retry('snd_…', [], ['idempotency_key' => 'retry-order-8812-1']);
Go
_, err := jusaClient.Sends.Retry(ctx, "snd_…", nil, jusa.WithIdempotencyKey("retry-order-8812-1"))
if err != nil {
return err
}
Java
jusa.sends().retry("snd_…", RequestOptions.idempotencyKey("retry-order-8812-1"));
C#
await jusa.Sends.RetryAsync("snd_…", options: new RequestOptions { IdempotencyKey = "retry-order-8812-1" });
Dart
await jusa.sends.retry('snd_…', {}, RequestOptions(idempotencyKey: 'retry-order-8812-1'));
Ruby
Jusa::Send.retry("snd_…", {}, idempotency_key: "retry-order-8812-1")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/sends/snd_…/retry \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Idempotency-Key: retry-order-8812-1"
Disputes
A send your user says did not arrive.
List disputes
Scope: sends:read.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
status | query | Only objects in this status. |
send | query | snd_… |
metadata[key] | query | metadata[<key>]=<value>: an exact match on one key. |
Returns: 200 DisputeList. Errors: the envelope.
Python
jusa.Dispute.list()
Node
await jusa.disputes.list();
PHP
$jusa->disputes->list();
Go
_, err := jusaClient.Disputes.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.disputes().list();
C#
await jusa.Disputes.ListAsync();
Dart
await jusa.disputes.list();
Ruby
Jusa::Dispute.list
curl
curl https://jusa.localhost.co.zw/dev/v1/disputes \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Open a dispute
Opens a staff case. A delivered send is never reversed. Scope: sends:write.
| Body (DisputeCreate) | Type | About |
|---|---|---|
send required | string | |
reason required | "token_not_received" | "wrong_number" | "not_delivered" | "other" | |
evidence | string | |
metadata | object | Up to 20 keys (letters, digits, _ . -, up to 40 characters) with values up to 500 characters. |
Returns: 201 Dispute. Errors: the envelope.
Python
jusa.Dispute.create(
send="snd_…",
reason="token_not_received",
evidence="Customer says no SMS came.",
)
Node
await jusa.disputes.create({
send: 'snd_…',
reason: 'token_not_received',
evidence: 'Customer says no SMS came.',
});
PHP
$jusa->disputes->create([
'send' => 'snd_…',
'reason' => 'token_not_received',
'evidence' => 'Customer says no SMS came.',
]);
Go
_, err := jusaClient.Disputes.Create(ctx, jusa.Params{
"send": "snd_…",
"reason": "token_not_received",
"evidence": "Customer says no SMS came.",
})
if err != nil {
return err
}
Java
jusa.disputes().create(Params.of(
"send", "snd_…",
"reason", "token_not_received",
"evidence", "Customer says no SMS came."
));
C#
await jusa.Disputes.CreateAsync(new
{
send = "snd_…",
reason = "token_not_received",
evidence = "Customer says no SMS came.",
});
Dart
await jusa.disputes.create({
'send': 'snd_…',
'reason': 'token_not_received',
'evidence': 'Customer says no SMS came.',
});
Ruby
Jusa::Dispute.create(
send: "snd_…",
reason: "token_not_received",
evidence: "Customer says no SMS came.",
)
curl
curl https://jusa.localhost.co.zw/dev/v1/disputes \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"send": "snd_…",
"reason": "token_not_received",
"evidence": "Customer says no SMS came."
}'
Retrieve a dispute
Scope: sends:read.
| Parameter | In | About |
|---|---|---|
dispute_id required | path | dsp_… |
Returns: 200 Dispute. Errors: the envelope.
Python
jusa.Dispute.retrieve("dsp_…")
Node
await jusa.disputes.retrieve('dsp_…');
PHP
$jusa->disputes->retrieve('dsp_…');
Go
_, err := jusaClient.Disputes.Retrieve(ctx, "dsp_…", nil)
if err != nil {
return err
}
Java
jusa.disputes().retrieve("dsp_…");
C#
await jusa.Disputes.RetrieveAsync("dsp_…");
Dart
await jusa.disputes.retrieve('dsp_…');
Ruby
Jusa::Dispute.retrieve("dsp_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/disputes/dsp_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Batches
Up to 10,000 sends at once.
List batches
Scope: sends:read.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
status | query | Only objects in this status. |
metadata[key] | query | metadata[<key>]=<value>: an exact match on one key. |
Returns: 200 BatchList. Errors: the envelope.
Python
jusa.Batch.list()
Node
await jusa.batches.list();
PHP
$jusa->batches->list();
Go
_, err := jusaClient.Batches.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.batches().list();
C#
await jusa.Batches.ListAsync();
Dart
await jusa.batches.list();
Ruby
Jusa::Batch.list
curl
curl https://jusa.localhost.co.zw/dev/v1/batches \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Create a batch
Up to 10,000 items (JSON or CSV). Credit is reserved at once by default; above the account's approval threshold it waits for a second person. Scope: batches:write. Moves money: an Idempotency-Key is required.
| Body (BatchCreate) | Type | About |
|---|---|---|
items | array of object | |
csv | string | Or a CSV with a header row. |
title | string | |
sms_message | string | |
cost_center | string | |
on_invalid | "reject" | "skip" | |
reserve_credit | boolean | |
on_insufficient | "stop" | "continue" | |
currency | "USD" | "ZWG" | "usd" | "zwg" | USD or ZWG (either case). |
metadata | object | Up to 20 keys (letters, digits, _ . -, up to 40 characters) with values up to 500 characters. |
Returns: 202 Batch. Errors: the envelope.
Python
jusa.Batch.create(
title="October allowance",
items=[
{"target": "0772123456", "amount": "5.00"},
{"target": "0712345678", "amount": "5.00"},
],
idempotency_key="payroll-2026-10",
)
Node
await jusa.batches.create({
title: 'October allowance',
items: [
{ target: '0772123456', amount: '5.00' },
{ target: '0712345678', amount: '5.00' },
],
}, { idempotencyKey: 'payroll-2026-10' });
PHP
$jusa->batches->create([
'title' => 'October allowance',
'items' => [
['target' => '0772123456', 'amount' => '5.00'],
['target' => '0712345678', 'amount' => '5.00'],
],
], ['idempotency_key' => 'payroll-2026-10']);
Go
_, err := jusaClient.Batches.Create(ctx, jusa.Params{
"title": "October allowance",
"items": []jusa.Params{
jusa.Params{"target": "0772123456", "amount": "5.00"},
jusa.Params{"target": "0712345678", "amount": "5.00"},
},
}, jusa.WithIdempotencyKey("payroll-2026-10"))
if err != nil {
return err
}
Java
jusa.batches().create(Params.of(
"title", "October allowance",
"items", List.of(
Map.of("target", "0772123456", "amount", "5.00"),
Map.of("target", "0712345678", "amount", "5.00")
)
), RequestOptions.idempotencyKey("payroll-2026-10"));
C#
await jusa.Batches.CreateAsync(new
{
title = "October allowance",
items = new object[]
{
new { target = "0772123456", amount = "5.00" },
new { target = "0712345678", amount = "5.00" },
},
}, new RequestOptions { IdempotencyKey = "payroll-2026-10" });
Dart
await jusa.batches.create({
'title': 'October allowance',
'items': [
{'target': '0772123456', 'amount': '5.00'},
{'target': '0712345678', 'amount': '5.00'},
],
}, RequestOptions(idempotencyKey: 'payroll-2026-10'));
Ruby
Jusa::Batch.create({
title: "October allowance",
items: [
{ target: "0772123456", amount: "5.00" },
{ target: "0712345678", amount: "5.00" },
],
}, idempotency_key: "payroll-2026-10")
curl
curl https://jusa.localhost.co.zw/dev/v1/batches \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Idempotency-Key: payroll-2026-10" \
-H "Content-Type: application/json" \
-d '{
"title": "October allowance",
"items": [
{"target": "0772123456", "amount": "5.00"},
{"target": "0712345678", "amount": "5.00"}
]
}'
Retrieve a batch
Scope: sends:read.
| Parameter | In | About |
|---|---|---|
batch_id required | path | bch_… |
Returns: 200 Batch. Errors: the envelope.
Python
jusa.Batch.retrieve("bch_…")
Node
await jusa.batches.retrieve('bch_…');
PHP
$jusa->batches->retrieve('bch_…');
Go
_, err := jusaClient.Batches.Retrieve(ctx, "bch_…", nil)
if err != nil {
return err
}
Java
jusa.batches().retrieve("bch_…");
C#
await jusa.Batches.RetrieveAsync("bch_…");
Dart
await jusa.batches.retrieve('bch_…');
Ruby
Jusa::Batch.retrieve("bch_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/batches/bch_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Approve a batch
By an owner or admin other than the batch's maker. Scope: batches:write. Moves money: an Idempotency-Key is required.
| Parameter | In | About |
|---|---|---|
batch_id required | path | bch_… |
Returns: 200 Batch. Errors: the envelope.
Python
jusa.Batch.approve("bch_…", idempotency_key="approve-payroll-2026-10")
Node
await jusa.batches.approve('bch_…', {}, { idempotencyKey: 'approve-payroll-2026-10' });
PHP
$jusa->batches->approve('bch_…', [], ['idempotency_key' => 'approve-payroll-2026-10']);
Go
_, err := jusaClient.Batches.Approve(ctx, "bch_…", nil, jusa.WithIdempotencyKey("approve-payroll-2026-10"))
if err != nil {
return err
}
Java
jusa.batches().approve("bch_…", RequestOptions.idempotencyKey("approve-payroll-2026-10"));
C#
await jusa.Batches.ApproveAsync("bch_…", options: new RequestOptions { IdempotencyKey = "approve-payroll-2026-10" });
Dart
await jusa.batches.approve('bch_…', {}, RequestOptions(idempotencyKey: 'approve-payroll-2026-10'));
Ruby
Jusa::Batch.approve("bch_…", {}, idempotency_key: "approve-payroll-2026-10")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/batches/bch_…/approve \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Idempotency-Key: approve-payroll-2026-10"
Cancel a batch
Items not yet sent are cancelled; unspent reserved credit is released. Scope: batches:write.
| Parameter | In | About |
|---|---|---|
batch_id required | path | bch_… |
Returns: 200 Batch. Errors: the envelope.
Python
jusa.Batch.cancel("bch_…")
Node
await jusa.batches.cancel('bch_…');
PHP
$jusa->batches->cancel('bch_…');
Go
_, err := jusaClient.Batches.Cancel(ctx, "bch_…", nil)
if err != nil {
return err
}
Java
jusa.batches().cancel("bch_…");
C#
await jusa.Batches.CancelAsync("bch_…");
Dart
await jusa.batches.cancel('bch_…');
Ruby
Jusa::Batch.cancel("bch_…")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/batches/bch_…/cancel \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
List a batch's items
Scope: sends:read.
| Parameter | In | About |
|---|---|---|
batch_id required | path | bch_… |
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
status | query | Only objects in this status. |
metadata[key] | query | metadata[<key>]=<value>: an exact match on one key. |
Returns: 200 BatchItemList. Errors: the envelope.
Python
jusa.Batch.list_items("bch_…")
Node
await jusa.batches.listItems('bch_…');
PHP
$jusa->batches->listItems('bch_…');
Go
_, err := jusaClient.Batches.ListItems(ctx, "bch_…", nil)
if err != nil {
return err
}
Java
jusa.batches().listItems("bch_…");
C#
await jusa.Batches.ListItemsAsync("bch_…");
Dart
await jusa.batches.listItems('bch_…');
Ruby
Jusa::Batch.list_items("bch_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/batches/bch_…/items \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Download a batch's results
Scope: sends:read.
| Parameter | In | About |
|---|---|---|
batch_id required | path | bch_… |
Returns: 200 CSV. Errors: the envelope.
Python
jusa.Batch.results_csv("bch_…")
Node
await jusa.batches.resultsCsv('bch_…');
PHP
$jusa->batches->resultsCsv('bch_…');
Go
_, err := jusaClient.Batches.ResultsCSV(ctx, "bch_…", nil)
if err != nil {
return err
}
Java
jusa.batches().resultsCsv("bch_…");
C#
await jusa.Batches.ResultsCsvAsync("bch_…");
Dart
await jusa.batches.resultsCsv('bch_…');
Ruby
Jusa::Batch.results_csv("bch_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/batches/bch_…/results.csv \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Retry a batch's failed items
A new batch, charged again. Each failed item is retried once. Scope: batches:write. Moves money: an Idempotency-Key is required.
| Parameter | In | About |
|---|---|---|
batch_id required | path | bch_… |
| Body (BatchRetryFailed) | Type | About |
|---|---|---|
reserve_credit | boolean |
Returns: 202 Batch. Errors: the envelope.
Python
jusa.Batch.retry_failed("bch_…", idempotency_key="retry-payroll-2026-10-1")
Node
await jusa.batches.retryFailed('bch_…', {}, { idempotencyKey: 'retry-payroll-2026-10-1' });
PHP
$jusa->batches->retryFailed('bch_…', [], ['idempotency_key' => 'retry-payroll-2026-10-1']);
Go
_, err := jusaClient.Batches.RetryFailed(ctx, "bch_…", nil, jusa.WithIdempotencyKey("retry-payroll-2026-10-1"))
if err != nil {
return err
}
Java
jusa.batches().retryFailed("bch_…", RequestOptions.idempotencyKey("retry-payroll-2026-10-1"));
C#
await jusa.Batches.RetryFailedAsync("bch_…", options: new RequestOptions { IdempotencyKey = "retry-payroll-2026-10-1" });
Dart
await jusa.batches.retryFailed('bch_…', {}, RequestOptions(idempotencyKey: 'retry-payroll-2026-10-1'));
Ruby
Jusa::Batch.retry_failed("bch_…", {}, idempotency_key: "retry-payroll-2026-10-1")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/batches/bch_…/retry-failed \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Idempotency-Key: retry-payroll-2026-10-1"
Preview a batch
Per-line validity, totals, whether the credit and the provider float suffice. Scope: batches:write.
| Body (BatchCreate) | Type | About |
|---|---|---|
items | array of object | |
csv | string | Or a CSV with a header row. |
title | string | |
sms_message | string | |
cost_center | string | |
on_invalid | "reject" | "skip" | |
reserve_credit | boolean | |
on_insufficient | "stop" | "continue" | |
currency | "USD" | "ZWG" | "usd" | "zwg" | USD or ZWG (either case). |
metadata | object | Up to 20 keys (letters, digits, _ . -, up to 40 characters) with values up to 500 characters. |
Returns: 200 BatchPreview. Errors: the envelope.
Python
jusa.Batch.preview(
title="October allowance",
items=[
{"target": "0772123456", "amount": "5.00"},
{"target": "0712345678", "amount": "5.00"},
],
)
Node
await jusa.batches.preview({
title: 'October allowance',
items: [
{ target: '0772123456', amount: '5.00' },
{ target: '0712345678', amount: '5.00' },
],
});
PHP
$jusa->batches->preview([
'title' => 'October allowance',
'items' => [
['target' => '0772123456', 'amount' => '5.00'],
['target' => '0712345678', 'amount' => '5.00'],
],
]);
Go
_, err := jusaClient.Batches.Preview(ctx, jusa.Params{
"title": "October allowance",
"items": []jusa.Params{
jusa.Params{"target": "0772123456", "amount": "5.00"},
jusa.Params{"target": "0712345678", "amount": "5.00"},
},
})
if err != nil {
return err
}
Java
jusa.batches().preview(Params.of(
"title", "October allowance",
"items", List.of(
Map.of("target", "0772123456", "amount", "5.00"),
Map.of("target", "0712345678", "amount", "5.00")
)
));
C#
await jusa.Batches.PreviewAsync(new
{
title = "October allowance",
items = new object[]
{
new { target = "0772123456", amount = "5.00" },
new { target = "0712345678", amount = "5.00" },
},
});
Dart
await jusa.batches.preview({
'title': 'October allowance',
'items': [
{'target': '0772123456', 'amount': '5.00'},
{'target': '0712345678', 'amount': '5.00'},
],
});
Ruby
Jusa::Batch.preview(
title: "October allowance",
items: [
{ target: "0772123456", amount: "5.00" },
{ target: "0712345678", amount: "5.00" },
],
)
curl
curl https://jusa.localhost.co.zw/dev/v1/batches/preview \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "October allowance",
"items": [
{"target": "0772123456", "amount": "5.00"},
{"target": "0712345678", "amount": "5.00"}
]
}'
Schedules
Recurring sends.
List schedules
Scope: sends:read.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
active | query | Active or not. |
metadata[key] | query | metadata[<key>]=<value>: an exact match on one key. |
Returns: 200 ScheduleList. Errors: the envelope.
Python
jusa.Schedule.list()
Node
await jusa.schedules.list();
PHP
$jusa->schedules->list();
Go
_, err := jusaClient.Schedules.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.schedules().list();
C#
await jusa.Schedules.ListAsync();
Dart
await jusa.schedules.list();
Ruby
Jusa::Schedule.list
curl
curl https://jusa.localhost.co.zw/dev/v1/schedules \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Create a schedule
Scope: schedules:write.
| Body (ScheduleCreate) | Type | About |
|---|---|---|
name | string | |
cadence | "daily" | "weekly" | "biweekly" | "monthly" | "yearly" | "payday" | "last_day" | |
hour | integer | |
minute | integer | |
day_of_week | integer | |
day_of_month | integer | |
month_of_year | integer | |
anchor_date | string | YYYY-MM-DD, Harare time. |
group | string | |
recipients | array of string | |
product | string | |
type | "airtime" | "data" | "zesa" | |
currency | "USD" | "ZWG" | "usd" | "zwg" | USD or ZWG (either case). |
amount | string or number | A decimal amount, e.g. "5.00". |
sms_message | string | |
custom_sms | string | |
cost_center | string | |
meter | string | An 11-digit ZESA prepaid meter number. |
token_phone | string | A Zimbabwean mobile: 07XXXXXXXX, 2637XXXXXXXX or +2637XXXXXXXX. |
active | boolean | |
precheck_credit | boolean | |
on_insufficient | "skip" | "retry_after_topup" | |
metadata | object | Up to 20 keys (letters, digits, _ . -, up to 40 characters) with values up to 500 characters. |
Returns: 201 Schedule. Errors: the envelope.
Python
jusa.Schedule.create(
name="Monthly allowance",
cadence="monthly",
day_of_month=1,
hour=8,
minute=0,
group="grp_…",
product="airtime-usd",
amount="5.00",
)
Node
await jusa.schedules.create({
name: 'Monthly allowance',
cadence: 'monthly',
day_of_month: 1,
hour: 8,
minute: 0,
group: 'grp_…',
product: 'airtime-usd',
amount: '5.00',
});
PHP
$jusa->schedules->create([
'name' => 'Monthly allowance',
'cadence' => 'monthly',
'day_of_month' => 1,
'hour' => 8,
'minute' => 0,
'group' => 'grp_…',
'product' => 'airtime-usd',
'amount' => '5.00',
]);
Go
_, err := jusaClient.Schedules.Create(ctx, jusa.Params{
"name": "Monthly allowance",
"cadence": "monthly",
"day_of_month": 1,
"hour": 8,
"minute": 0,
"group": "grp_…",
"product": "airtime-usd",
"amount": "5.00",
})
if err != nil {
return err
}
Java
jusa.schedules().create(Params.of(
"name", "Monthly allowance",
"cadence", "monthly",
"day_of_month", 1,
"hour", 8,
"minute", 0,
"group", "grp_…",
"product", "airtime-usd",
"amount", "5.00"
));
C#
await jusa.Schedules.CreateAsync(new
{
name = "Monthly allowance",
cadence = "monthly",
day_of_month = 1,
hour = 8,
minute = 0,
group = "grp_…",
product = "airtime-usd",
amount = "5.00",
});
Dart
await jusa.schedules.create({
'name': 'Monthly allowance',
'cadence': 'monthly',
'day_of_month': 1,
'hour': 8,
'minute': 0,
'group': 'grp_…',
'product': 'airtime-usd',
'amount': '5.00',
});
Ruby
Jusa::Schedule.create(
name: "Monthly allowance",
cadence: "monthly",
day_of_month: 1,
hour: 8,
minute: 0,
group: "grp_…",
product: "airtime-usd",
amount: "5.00",
)
curl
curl https://jusa.localhost.co.zw/dev/v1/schedules \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Monthly allowance",
"cadence": "monthly",
"day_of_month": 1,
"hour": 8,
"minute": 0,
"group": "grp_…",
"product": "airtime-usd",
"amount": "5.00"
}'
Retrieve a schedule
Scope: sends:read.
| Parameter | In | About |
|---|---|---|
schedule_id required | path | sch_… |
Returns: 200 Schedule. Errors: the envelope.
Python
jusa.Schedule.retrieve("sch_…")
Node
await jusa.schedules.retrieve('sch_…');
PHP
$jusa->schedules->retrieve('sch_…');
Go
_, err := jusaClient.Schedules.Retrieve(ctx, "sch_…", nil)
if err != nil {
return err
}
Java
jusa.schedules().retrieve("sch_…");
C#
await jusa.Schedules.RetrieveAsync("sch_…");
Dart
await jusa.schedules.retrieve('sch_…');
Ruby
Jusa::Schedule.retrieve("sch_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/schedules/sch_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Update a schedule
Scope: schedules:write.
| Parameter | In | About |
|---|---|---|
schedule_id required | path | sch_… |
| Body (ScheduleCreate) | Type | About |
|---|---|---|
name | string | |
cadence | "daily" | "weekly" | "biweekly" | "monthly" | "yearly" | "payday" | "last_day" | |
hour | integer | |
minute | integer | |
day_of_week | integer | |
day_of_month | integer | |
month_of_year | integer | |
anchor_date | string | YYYY-MM-DD, Harare time. |
group | string | |
recipients | array of string | |
product | string | |
type | "airtime" | "data" | "zesa" | |
currency | "USD" | "ZWG" | "usd" | "zwg" | USD or ZWG (either case). |
amount | string or number | A decimal amount, e.g. "5.00". |
sms_message | string | |
custom_sms | string | |
cost_center | string | |
meter | string | An 11-digit ZESA prepaid meter number. |
token_phone | string | A Zimbabwean mobile: 07XXXXXXXX, 2637XXXXXXXX or +2637XXXXXXXX. |
active | boolean | |
precheck_credit | boolean | |
on_insufficient | "skip" | "retry_after_topup" | |
metadata | object | Up to 20 keys (letters, digits, _ . -, up to 40 characters) with values up to 500 characters. |
Returns: 200 Schedule. Errors: the envelope.
Python
jusa.Schedule.update(
"sch_…",
name="Monthly allowance",
cadence="monthly",
day_of_month=1,
hour=8,
minute=0,
group="grp_…",
product="airtime-usd",
amount="5.00",
)
Node
await jusa.schedules.update('sch_…', {
name: 'Monthly allowance',
cadence: 'monthly',
day_of_month: 1,
hour: 8,
minute: 0,
group: 'grp_…',
product: 'airtime-usd',
amount: '5.00',
});
PHP
$jusa->schedules->update('sch_…', [
'name' => 'Monthly allowance',
'cadence' => 'monthly',
'day_of_month' => 1,
'hour' => 8,
'minute' => 0,
'group' => 'grp_…',
'product' => 'airtime-usd',
'amount' => '5.00',
]);
Go
_, err := jusaClient.Schedules.Update(ctx, "sch_…", jusa.Params{
"name": "Monthly allowance",
"cadence": "monthly",
"day_of_month": 1,
"hour": 8,
"minute": 0,
"group": "grp_…",
"product": "airtime-usd",
"amount": "5.00",
})
if err != nil {
return err
}
Java
jusa.schedules().update("sch_…", Params.of(
"name", "Monthly allowance",
"cadence", "monthly",
"day_of_month", 1,
"hour", 8,
"minute", 0,
"group", "grp_…",
"product", "airtime-usd",
"amount", "5.00"
));
C#
await jusa.Schedules.UpdateAsync("sch_…", new
{
name = "Monthly allowance",
cadence = "monthly",
day_of_month = 1,
hour = 8,
minute = 0,
group = "grp_…",
product = "airtime-usd",
amount = "5.00",
});
Dart
await jusa.schedules.update('sch_…', {
'name': 'Monthly allowance',
'cadence': 'monthly',
'day_of_month': 1,
'hour': 8,
'minute': 0,
'group': 'grp_…',
'product': 'airtime-usd',
'amount': '5.00',
});
Ruby
Jusa::Schedule.update(
"sch_…",
name: "Monthly allowance",
cadence: "monthly",
day_of_month: 1,
hour: 8,
minute: 0,
group: "grp_…",
product: "airtime-usd",
amount: "5.00",
)
curl
curl -X PATCH https://jusa.localhost.co.zw/dev/v1/schedules/sch_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Monthly allowance",
"cadence": "monthly",
"day_of_month": 1,
"hour": 8,
"minute": 0,
"group": "grp_…",
"product": "airtime-usd",
"amount": "5.00"
}'
Delete a schedule
Scope: schedules:write.
| Parameter | In | About |
|---|---|---|
schedule_id required | path | sch_… |
Returns: 200 DeletedSchedule. Errors: the envelope.
Python
jusa.Schedule.delete("sch_…")
Node
await jusa.schedules.delete('sch_…');
PHP
$jusa->schedules->delete('sch_…');
Go
_, err := jusaClient.Schedules.Delete(ctx, "sch_…", nil)
if err != nil {
return err
}
Java
jusa.schedules().delete("sch_…");
C#
await jusa.Schedules.DeleteAsync("sch_…");
Dart
await jusa.schedules.delete('sch_…');
Ruby
Jusa::Schedule.delete("sch_…")
curl
curl -X DELETE https://jusa.localhost.co.zw/dev/v1/schedules/sch_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
List upcoming runs
From today to 60 days on by default (YYYY-MM-DD). Scope: sends:read.
| Parameter | In | About |
|---|---|---|
schedule_id required | path | sch_… |
from | query | The start (inclusive). |
to | query | The end (inclusive). |
Returns: 200 ScheduleOccurrenceList. Errors: the envelope.
Python
jusa.Schedule.list_occurrences("sch_…")
Node
await jusa.schedules.listOccurrences('sch_…');
PHP
$jusa->schedules->listOccurrences('sch_…');
Go
_, err := jusaClient.Schedules.ListOccurrences(ctx, "sch_…", nil)
if err != nil {
return err
}
Java
jusa.schedules().listOccurrences("sch_…");
C#
await jusa.Schedules.ListOccurrencesAsync("sch_…");
Dart
await jusa.schedules.listOccurrences('sch_…');
Ruby
Jusa::Schedule.list_occurrences("sch_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/schedules/sch_…/occurrences \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Retrieve one run
ran with its batch once it has gone out. Scope: sends:read.
| Parameter | In | About |
|---|---|---|
schedule_id required | path | sch_… |
day required | path | The run's date, YYYY-MM-DD. |
Returns: 200 ScheduleOccurrence. Errors: the envelope.
Python
jusa.Schedule.retrieve_occurrence("sch_…", "2026-10-01")
Node
await jusa.schedules.retrieveOccurrence('sch_…', '2026-10-01');
PHP
$jusa->schedules->retrieveOccurrence('sch_…', '2026-10-01');
Go
_, err := jusaClient.Schedules.RetrieveOccurrence(ctx, "sch_…", "2026-10-01", nil)
if err != nil {
return err
}
Java
jusa.schedules().retrieveOccurrence("sch_…", "2026-10-01");
C#
await jusa.Schedules.RetrieveOccurrenceAsync("sch_…", "2026-10-01");
Dart
await jusa.schedules.retrieveOccurrence('sch_…', '2026-10-01');
Ruby
Jusa::Schedule.retrieve_occurrence("sch_…", "2026-10-01")
curl
curl https://jusa.localhost.co.zw/dev/v1/schedules/sch_…/occurrences/2026-10-01 \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Change one run's amount
Scope: schedules:write.
| Parameter | In | About |
|---|---|---|
schedule_id required | path | sch_… |
day required | path | The run's date, YYYY-MM-DD. |
| Body (OccurrenceUpdate) | Type | About |
|---|---|---|
amount_override | string or number | A decimal amount, e.g. "5.00". |
note | string |
Returns: 200 ScheduleOccurrence. Errors: the envelope.
Python
jusa.Schedule.update_occurrence("sch_…", "2026-10-01")
Node
await jusa.schedules.updateOccurrence('sch_…', '2026-10-01');
PHP
$jusa->schedules->updateOccurrence('sch_…', '2026-10-01');
Go
_, err := jusaClient.Schedules.UpdateOccurrence(ctx, "sch_…", "2026-10-01", nil)
if err != nil {
return err
}
Java
jusa.schedules().updateOccurrence("sch_…", "2026-10-01");
C#
await jusa.Schedules.UpdateOccurrenceAsync("sch_…", "2026-10-01");
Dart
await jusa.schedules.updateOccurrence('sch_…', '2026-10-01');
Ruby
Jusa::Schedule.update_occurrence("sch_…", "2026-10-01")
curl
curl -X PATCH https://jusa.localhost.co.zw/dev/v1/schedules/sch_…/occurrences/2026-10-01 \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Combine one run into another
The other run (this schedule's on into, or schedule's) sends both amounts in one recharge per person, and this one is combined. Same people, currency and cost centre only. Reset undoes it. Scope: schedules:write.
| Parameter | In | About |
|---|---|---|
schedule_id required | path | sch_… |
day required | path | The run's date, YYYY-MM-DD. |
| Body (OccurrenceCombine) | Type | About |
|---|---|---|
into required | string | YYYY-MM-DD, Harare time. |
schedule | string | sch_…; this schedule by default. |
Returns: 200 ScheduleOccurrence. Errors: the envelope.
Python
jusa.Schedule.combine_occurrence("sch_…", "2026-10-01", into="2026-11-02")
Node
await jusa.schedules.combineOccurrence('sch_…', '2026-10-01', { into: '2026-11-02' });
PHP
$jusa->schedules->combineOccurrence('sch_…', '2026-10-01', ['into' => '2026-11-02']);
Go
_, err := jusaClient.Schedules.CombineOccurrence(ctx, "sch_…", "2026-10-01", jusa.Params{
"into": "2026-11-02",
})
if err != nil {
return err
}
Java
jusa.schedules().combineOccurrence("sch_…", "2026-10-01", Params.of(
"into", "2026-11-02"
));
C#
await jusa.Schedules.CombineOccurrenceAsync("sch_…", "2026-10-01", new
{
into = "2026-11-02",
});
Dart
await jusa.schedules.combineOccurrence('sch_…', '2026-10-01', {'into': '2026-11-02'});
Ruby
Jusa::Schedule.combine_occurrence("sch_…", "2026-10-01", into: "2026-11-02")
curl
curl https://jusa.localhost.co.zw/dev/v1/schedules/sch_…/occurrences/2026-10-01/combine \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"into": "2026-11-02"}'
Move one run
Scope: schedules:write.
| Parameter | In | About |
|---|---|---|
schedule_id required | path | sch_… |
day required | path | The run's date, YYYY-MM-DD. |
| Body (OccurrenceMove) | Type | About |
|---|---|---|
to required | string | YYYY-MM-DD, Harare time. |
Returns: 200 ScheduleOccurrence. Errors: the envelope.
Python
jusa.Schedule.move_occurrence("sch_…", "2026-10-01", to="string")
Node
await jusa.schedules.moveOccurrence('sch_…', '2026-10-01', { to: 'string' });
PHP
$jusa->schedules->moveOccurrence('sch_…', '2026-10-01', ['to' => 'string']);
Go
_, err := jusaClient.Schedules.MoveOccurrence(ctx, "sch_…", "2026-10-01", jusa.Params{
"to": "string",
})
if err != nil {
return err
}
Java
jusa.schedules().moveOccurrence("sch_…", "2026-10-01", Params.of("to", "string"));
C#
await jusa.Schedules.MoveOccurrenceAsync("sch_…", "2026-10-01", new { to = "string" });
Dart
await jusa.schedules.moveOccurrence('sch_…', '2026-10-01', {'to': 'string'});
Ruby
Jusa::Schedule.move_occurrence("sch_…", "2026-10-01", to: "string")
curl
curl https://jusa.localhost.co.zw/dev/v1/schedules/sch_…/occurrences/2026-10-01/move \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"to": "string"}'
Undo a skip, move or amount change
Scope: schedules:write.
| Parameter | In | About |
|---|---|---|
schedule_id required | path | sch_… |
day required | path | The run's date, YYYY-MM-DD. |
Returns: 200 ScheduleOccurrence. Errors: the envelope.
Python
jusa.Schedule.reset_occurrence("sch_…", "2026-10-01")
Node
await jusa.schedules.resetOccurrence('sch_…', '2026-10-01');
PHP
$jusa->schedules->resetOccurrence('sch_…', '2026-10-01');
Go
_, err := jusaClient.Schedules.ResetOccurrence(ctx, "sch_…", "2026-10-01", nil)
if err != nil {
return err
}
Java
jusa.schedules().resetOccurrence("sch_…", "2026-10-01");
C#
await jusa.Schedules.ResetOccurrenceAsync("sch_…", "2026-10-01");
Dart
await jusa.schedules.resetOccurrence('sch_…', '2026-10-01');
Ruby
Jusa::Schedule.reset_occurrence("sch_…", "2026-10-01")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/schedules/sch_…/occurrences/2026-10-01/reset \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Skip one run
Scope: schedules:write.
| Parameter | In | About |
|---|---|---|
schedule_id required | path | sch_… |
day required | path | The run's date, YYYY-MM-DD. |
Returns: 200 ScheduleOccurrence. Errors: the envelope.
Python
jusa.Schedule.skip_occurrence("sch_…", "2026-10-01")
Node
await jusa.schedules.skipOccurrence('sch_…', '2026-10-01');
PHP
$jusa->schedules->skipOccurrence('sch_…', '2026-10-01');
Go
_, err := jusaClient.Schedules.SkipOccurrence(ctx, "sch_…", "2026-10-01", nil)
if err != nil {
return err
}
Java
jusa.schedules().skipOccurrence("sch_…", "2026-10-01");
C#
await jusa.Schedules.SkipOccurrenceAsync("sch_…", "2026-10-01");
Dart
await jusa.schedules.skipOccurrence('sch_…', '2026-10-01');
Ruby
Jusa::Schedule.skip_occurrence("sch_…", "2026-10-01")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/schedules/sch_…/occurrences/2026-10-01/skip \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Run a schedule now
A run is a batch: it reserves its total and may wait for approval. Scope: schedules:write. Moves money: an Idempotency-Key is required.
| Parameter | In | About |
|---|---|---|
schedule_id required | path | sch_… |
| Body (ScheduleRunNow) | Type | About |
|---|---|---|
again | boolean | Run even if it already ran today. |
Returns: 202 Batch. Errors: the envelope.
Python
jusa.Schedule.run_now("sch_…", idempotency_key="allowance-2026-10")
Node
await jusa.schedules.runNow('sch_…', {}, { idempotencyKey: 'allowance-2026-10' });
PHP
$jusa->schedules->runNow('sch_…', [], ['idempotency_key' => 'allowance-2026-10']);
Go
_, err := jusaClient.Schedules.RunNow(ctx, "sch_…", nil, jusa.WithIdempotencyKey("allowance-2026-10"))
if err != nil {
return err
}
Java
jusa.schedules().runNow("sch_…", RequestOptions.idempotencyKey("allowance-2026-10"));
C#
await jusa.Schedules.RunNowAsync("sch_…", options: new RequestOptions { IdempotencyKey = "allowance-2026-10" });
Dart
await jusa.schedules.runNow('sch_…', {}, RequestOptions(idempotencyKey: 'allowance-2026-10'));
Ruby
Jusa::Schedule.run_now("sch_…", {}, idempotency_key: "allowance-2026-10")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/schedules/sch_…/run-now \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Idempotency-Key: allowance-2026-10"
Preview running now
Scope: schedules:write.
| Parameter | In | About |
|---|---|---|
schedule_id required | path | sch_… |
Returns: 200 ScheduleRunPreview. Errors: the envelope.
Python
jusa.Schedule.preview_run_now("sch_…")
Node
await jusa.schedules.previewRunNow('sch_…');
PHP
$jusa->schedules->previewRunNow('sch_…');
Go
_, err := jusaClient.Schedules.PreviewRunNow(ctx, "sch_…", nil)
if err != nil {
return err
}
Java
jusa.schedules().previewRunNow("sch_…");
C#
await jusa.Schedules.PreviewRunNowAsync("sch_…");
Dart
await jusa.schedules.previewRunNow('sch_…');
Ruby
Jusa::Schedule.preview_run_now("sch_…")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/schedules/sch_…/run-now/preview \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Recipients
The people you send to, their groups and cost centres.
List cost centres
Scope: recipients:read.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
is_active | query | Active or not. |
Returns: 200 CostCenterList. Errors: the envelope.
Python
jusa.CostCenter.list()
Node
await jusa.costCenters.list();
PHP
$jusa->costCenters->list();
Go
_, err := jusaClient.CostCenters.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.costCenters().list();
C#
await jusa.CostCenters.ListAsync();
Dart
await jusa.costCenters.list();
Ruby
Jusa::CostCenter.list
curl
curl https://jusa.localhost.co.zw/dev/v1/cost-centers \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Create a cost centre
Scope: recipients:write.
| Body (CostCenterWrite) | Type | About |
|---|---|---|
name | string | |
gl_code | string | |
monthly_budget | string or number | A decimal amount, e.g. "5.00". |
currency | "USD" | "ZWG" | "usd" | "zwg" | USD or ZWG (either case). |
is_active | boolean |
Returns: 201 CostCenter. Errors: the envelope.
Python
jusa.CostCenter.create(name="Marketing", gl_code="6100", monthly_budget="250.00")
Node
await jusa.costCenters.create({
name: 'Marketing',
gl_code: '6100',
monthly_budget: '250.00',
});
PHP
$jusa->costCenters->create([
'name' => 'Marketing',
'gl_code' => '6100',
'monthly_budget' => '250.00',
]);
Go
_, err := jusaClient.CostCenters.Create(ctx, jusa.Params{
"name": "Marketing",
"gl_code": "6100",
"monthly_budget": "250.00",
})
if err != nil {
return err
}
Java
jusa.costCenters().create(Params.of(
"name", "Marketing",
"gl_code", "6100",
"monthly_budget", "250.00"
));
C#
await jusa.CostCenters.CreateAsync(new
{
name = "Marketing",
gl_code = "6100",
monthly_budget = "250.00",
});
Dart
await jusa.costCenters.create({
'name': 'Marketing',
'gl_code': '6100',
'monthly_budget': '250.00',
});
Ruby
Jusa::CostCenter.create(name: "Marketing", gl_code: "6100", monthly_budget: "250.00")
curl
curl https://jusa.localhost.co.zw/dev/v1/cost-centers \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Marketing", "gl_code": "6100", "monthly_budget": "250.00"}'
Retrieve a cost centre
Scope: recipients:read.
| Parameter | In | About |
|---|---|---|
cost_center_id required | path | cc_… |
Returns: 200 CostCenter. Errors: the envelope.
Python
jusa.CostCenter.retrieve("cc_…")
Node
await jusa.costCenters.retrieve('cc_…');
PHP
$jusa->costCenters->retrieve('cc_…');
Go
_, err := jusaClient.CostCenters.Retrieve(ctx, "cc_…", nil)
if err != nil {
return err
}
Java
jusa.costCenters().retrieve("cc_…");
C#
await jusa.CostCenters.RetrieveAsync("cc_…");
Dart
await jusa.costCenters.retrieve('cc_…');
Ruby
Jusa::CostCenter.retrieve("cc_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/cost-centers/cc_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Update a cost centre
Scope: recipients:write.
| Parameter | In | About |
|---|---|---|
cost_center_id required | path | cc_… |
| Body (CostCenterWrite) | Type | About |
|---|---|---|
name | string | |
gl_code | string | |
monthly_budget | string or number | A decimal amount, e.g. "5.00". |
currency | "USD" | "ZWG" | "usd" | "zwg" | USD or ZWG (either case). |
is_active | boolean |
Returns: 200 CostCenter. Errors: the envelope.
Python
jusa.CostCenter.update(
"cc_…",
name="Marketing",
gl_code="6100",
monthly_budget="250.00",
)
Node
await jusa.costCenters.update('cc_…', {
name: 'Marketing',
gl_code: '6100',
monthly_budget: '250.00',
});
PHP
$jusa->costCenters->update('cc_…', [
'name' => 'Marketing',
'gl_code' => '6100',
'monthly_budget' => '250.00',
]);
Go
_, err := jusaClient.CostCenters.Update(ctx, "cc_…", jusa.Params{
"name": "Marketing",
"gl_code": "6100",
"monthly_budget": "250.00",
})
if err != nil {
return err
}
Java
jusa.costCenters().update("cc_…", Params.of(
"name", "Marketing",
"gl_code", "6100",
"monthly_budget", "250.00"
));
C#
await jusa.CostCenters.UpdateAsync("cc_…", new
{
name = "Marketing",
gl_code = "6100",
monthly_budget = "250.00",
});
Dart
await jusa.costCenters.update('cc_…', {
'name': 'Marketing',
'gl_code': '6100',
'monthly_budget': '250.00',
});
Ruby
Jusa::CostCenter.update(
"cc_…",
name: "Marketing",
gl_code: "6100",
monthly_budget: "250.00",
)
curl
curl -X PATCH https://jusa.localhost.co.zw/dev/v1/cost-centers/cc_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Marketing", "gl_code": "6100", "monthly_budget": "250.00"}'
A cost centre's spend
Scope: recipients:read.
| Parameter | In | About |
|---|---|---|
cost_center_id required | path | cc_… |
from | query | The start (inclusive). |
to | query | The end (inclusive). |
Returns: 200 CostCenterSpend. Errors: the envelope.
Python
jusa.CostCenter.spend("cc_…")
Node
await jusa.costCenters.spend('cc_…');
PHP
$jusa->costCenters->spend('cc_…');
Go
_, err := jusaClient.CostCenters.Spend(ctx, "cc_…", nil)
if err != nil {
return err
}
Java
jusa.costCenters().spend("cc_…");
C#
await jusa.CostCenters.SpendAsync("cc_…");
Dart
await jusa.costCenters.spend('cc_…');
Ruby
Jusa::CostCenter.spend("cc_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/cost-centers/cc_…/spend \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
List groups
Scope: recipients:read.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
Returns: 200 GroupList. Errors: the envelope.
Python
jusa.Group.list()
Node
await jusa.groups.list();
PHP
$jusa->groups->list();
Go
_, err := jusaClient.Groups.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.groups().list();
C#
await jusa.Groups.ListAsync();
Dart
await jusa.groups.list();
Ruby
Jusa::Group.list
curl
curl https://jusa.localhost.co.zw/dev/v1/groups \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Create a group
Scope: recipients:write.
| Body (GroupWrite) | Type | About |
|---|---|---|
name | string | |
description | string | |
cost_center | string | |
members | array of string |
Returns: 201 Group. Errors: the envelope.
Python
jusa.Group.create(name="Field team")
Node
await jusa.groups.create({ name: 'Field team' });
PHP
$jusa->groups->create(['name' => 'Field team']);
Go
_, err := jusaClient.Groups.Create(ctx, jusa.Params{"name": "Field team"})
if err != nil {
return err
}
Java
jusa.groups().create(Params.of("name", "Field team"));
C#
await jusa.Groups.CreateAsync(new { name = "Field team" });
Dart
await jusa.groups.create({'name': 'Field team'});
Ruby
Jusa::Group.create(name: "Field team")
curl
curl https://jusa.localhost.co.zw/dev/v1/groups \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Field team"}'
Retrieve a group
Scope: recipients:read.
| Parameter | In | About |
|---|---|---|
group_id required | path | grp_… |
Returns: 200 Group. Errors: the envelope.
Python
jusa.Group.retrieve("grp_…")
Node
await jusa.groups.retrieve('grp_…');
PHP
$jusa->groups->retrieve('grp_…');
Go
_, err := jusaClient.Groups.Retrieve(ctx, "grp_…", nil)
if err != nil {
return err
}
Java
jusa.groups().retrieve("grp_…");
C#
await jusa.Groups.RetrieveAsync("grp_…");
Dart
await jusa.groups.retrieve('grp_…');
Ruby
Jusa::Group.retrieve("grp_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/groups/grp_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Update a group
Scope: recipients:write.
| Parameter | In | About |
|---|---|---|
group_id required | path | grp_… |
| Body (GroupWrite) | Type | About |
|---|---|---|
name | string | |
description | string | |
cost_center | string | |
members | array of string |
Returns: 200 Group. Errors: the envelope.
Python
jusa.Group.update("grp_…", name="Field team")
Node
await jusa.groups.update('grp_…', { name: 'Field team' });
PHP
$jusa->groups->update('grp_…', ['name' => 'Field team']);
Go
_, err := jusaClient.Groups.Update(ctx, "grp_…", jusa.Params{"name": "Field team"})
if err != nil {
return err
}
Java
jusa.groups().update("grp_…", Params.of("name", "Field team"));
C#
await jusa.Groups.UpdateAsync("grp_…", new { name = "Field team" });
Dart
await jusa.groups.update('grp_…', {'name': 'Field team'});
Ruby
Jusa::Group.update("grp_…", name: "Field team")
curl
curl -X PATCH https://jusa.localhost.co.zw/dev/v1/groups/grp_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Field team"}'
Delete a group
Scope: recipients:write.
| Parameter | In | About |
|---|---|---|
group_id required | path | grp_… |
Returns: 200 DeletedGroup. Errors: the envelope.
Python
jusa.Group.delete("grp_…")
Node
await jusa.groups.delete('grp_…');
PHP
$jusa->groups->delete('grp_…');
Go
_, err := jusaClient.Groups.Delete(ctx, "grp_…", nil)
if err != nil {
return err
}
Java
jusa.groups().delete("grp_…");
C#
await jusa.Groups.DeleteAsync("grp_…");
Dart
await jusa.groups.delete('grp_…');
Ruby
Jusa::Group.delete("grp_…")
curl
curl -X DELETE https://jusa.localhost.co.zw/dev/v1/groups/grp_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Add recipients to a group
Scope: recipients:write.
| Parameter | In | About |
|---|---|---|
group_id required | path | grp_… |
| Body (GroupMembers) | Type | About |
|---|---|---|
recipients required | array of string |
Returns: 200 Group. Errors: the envelope.
Python
jusa.Group.add_members("grp_…", recipients=[])
Node
await jusa.groups.addMembers('grp_…', { recipients: [] });
PHP
$jusa->groups->addMembers('grp_…', ['recipients' => []]);
Go
_, err := jusaClient.Groups.AddMembers(ctx, "grp_…", jusa.Params{"recipients": []any{}})
if err != nil {
return err
}
Java
jusa.groups().addMembers("grp_…", Params.of("recipients", List.of()));
C#
await jusa.Groups.AddMembersAsync("grp_…", new { recipients = new object[] { } });
Dart
await jusa.groups.addMembers('grp_…', {'recipients': []});
Ruby
Jusa::Group.add_members("grp_…", recipients: [])
curl
curl https://jusa.localhost.co.zw/dev/v1/groups/grp_…/members \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"recipients": []}'
Take recipients out of a group
Scope: recipients:write.
| Parameter | In | About |
|---|---|---|
group_id required | path | grp_… |
| Body (GroupMembers) | Type | About |
|---|---|---|
recipients required | array of string |
Returns: 200 Group. Errors: the envelope.
Python
jusa.Group.remove_members("grp_…", recipients=[])
Node
await jusa.groups.removeMembers('grp_…', { recipients: [] });
PHP
$jusa->groups->removeMembers('grp_…', ['recipients' => []]);
Go
_, err := jusaClient.Groups.RemoveMembers(ctx, "grp_…", jusa.Params{
"recipients": []any{},
})
if err != nil {
return err
}
Java
jusa.groups().removeMembers("grp_…", Params.of("recipients", List.of()));
C#
await jusa.Groups.RemoveMembersAsync("grp_…", new { recipients = new object[] { } });
Dart
await jusa.groups.removeMembers('grp_…', {'recipients': []});
Ruby
Jusa::Group.remove_members("grp_…", recipients: [])
curl
curl -X DELETE https://jusa.localhost.co.zw/dev/v1/groups/grp_…/members \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"recipients": []}'
List recipients
Scope: recipients:read.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
external_id | query | Your id for the person. |
phone | query | A phone number, any Zimbabwean format. |
meter | query | A meter number. |
group | query | grp_… |
cost_center | query | cc_… (Workforce: a department's id, or none for sends booked to none). |
blocked | query | Blocked or not. |
is_active | query | Active or not. |
erased | query | Erased or not. |
metadata[key] | query | metadata[<key>]=<value>: an exact match on one key. |
Returns: 200 RecipientList. Errors: the envelope.
Python
jusa.Recipient.list()
Node
await jusa.recipients.list();
PHP
$jusa->recipients->list();
Go
_, err := jusaClient.Recipients.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.recipients().list();
C#
await jusa.Recipients.ListAsync();
Dart
await jusa.recipients.list();
Ruby
Jusa::Recipient.list
curl
curl https://jusa.localhost.co.zw/dev/v1/recipients \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Create or update a recipient
Upserts on external_id, then phone: 201 when made, 200 when updated. Scope: recipients:write.
| Body (RecipientWrite) | Type | About |
|---|---|---|
external_id | string | |
phone | string | A Zimbabwean mobile: 07XXXXXXXX, 2637XXXXXXXX or +2637XXXXXXXX. |
meter | string | An 11-digit ZESA prepaid meter number. |
token_phone | string | A Zimbabwean mobile: 07XXXXXXXX, 2637XXXXXXXX or +2637XXXXXXXX. |
name | string | |
payroll_id | string | |
cost_center | string | |
notes | string | |
is_active | boolean | |
is_pinned | boolean | |
network_hint | string | |
daily_cap | string or number | A decimal amount, e.g. "5.00". |
weekly_cap | string or number | A decimal amount, e.g. "5.00". |
monthly_cap | string or number | A decimal amount, e.g. "5.00". |
lifetime_cap | string or number | A decimal amount, e.g. "5.00". |
blocked | boolean | |
blocked_reason | string | |
metadata | object | Up to 20 keys (letters, digits, _ . -, up to 40 characters) with values up to 500 characters. |
Returns: 200 Recipient · 201 Recipient. Errors: the envelope.
Python
jusa.Recipient.create(external_id="user_123", name="Tendai Moyo", phone="0772123456")
Node
await jusa.recipients.create({
external_id: 'user_123',
name: 'Tendai Moyo',
phone: '0772123456',
});
PHP
$jusa->recipients->create([
'external_id' => 'user_123',
'name' => 'Tendai Moyo',
'phone' => '0772123456',
]);
Go
_, err := jusaClient.Recipients.Create(ctx, jusa.Params{
"external_id": "user_123",
"name": "Tendai Moyo",
"phone": "0772123456",
})
if err != nil {
return err
}
Java
jusa.recipients().create(Params.of(
"external_id", "user_123",
"name", "Tendai Moyo",
"phone", "0772123456"
));
C#
await jusa.Recipients.CreateAsync(new
{
external_id = "user_123",
name = "Tendai Moyo",
phone = "0772123456",
});
Dart
await jusa.recipients.create({
'external_id': 'user_123',
'name': 'Tendai Moyo',
'phone': '0772123456',
});
Ruby
Jusa::Recipient.create(
external_id: "user_123",
name: "Tendai Moyo",
phone: "0772123456",
)
curl
curl https://jusa.localhost.co.zw/dev/v1/recipients \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"external_id": "user_123", "name": "Tendai Moyo", "phone": "0772123456"}'
Retrieve a recipient
Scope: recipients:read.
| Parameter | In | About |
|---|---|---|
recipient_id required | path | rcp_… or ext:<external_id>. |
Returns: 200 Recipient. Errors: the envelope.
Python
jusa.Recipient.retrieve("rcp_…")
Node
await jusa.recipients.retrieve('rcp_…');
PHP
$jusa->recipients->retrieve('rcp_…');
Go
_, err := jusaClient.Recipients.Retrieve(ctx, "rcp_…", nil)
if err != nil {
return err
}
Java
jusa.recipients().retrieve("rcp_…");
C#
await jusa.Recipients.RetrieveAsync("rcp_…");
Dart
await jusa.recipients.retrieve('rcp_…');
Ruby
Jusa::Recipient.retrieve("rcp_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/recipients/rcp_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Update a recipient
Scope: recipients:write.
| Parameter | In | About |
|---|---|---|
recipient_id required | path | rcp_… or ext:<external_id>. |
| Body (RecipientWrite) | Type | About |
|---|---|---|
external_id | string | |
phone | string | A Zimbabwean mobile: 07XXXXXXXX, 2637XXXXXXXX or +2637XXXXXXXX. |
meter | string | An 11-digit ZESA prepaid meter number. |
token_phone | string | A Zimbabwean mobile: 07XXXXXXXX, 2637XXXXXXXX or +2637XXXXXXXX. |
name | string | |
payroll_id | string | |
cost_center | string | |
notes | string | |
is_active | boolean | |
is_pinned | boolean | |
network_hint | string | |
daily_cap | string or number | A decimal amount, e.g. "5.00". |
weekly_cap | string or number | A decimal amount, e.g. "5.00". |
monthly_cap | string or number | A decimal amount, e.g. "5.00". |
lifetime_cap | string or number | A decimal amount, e.g. "5.00". |
blocked | boolean | |
blocked_reason | string | |
metadata | object | Up to 20 keys (letters, digits, _ . -, up to 40 characters) with values up to 500 characters. |
Returns: 200 Recipient. Errors: the envelope.
Python
jusa.Recipient.update(
"rcp_…",
external_id="user_123",
name="Tendai Moyo",
phone="0772123456",
)
Node
await jusa.recipients.update('rcp_…', {
external_id: 'user_123',
name: 'Tendai Moyo',
phone: '0772123456',
});
PHP
$jusa->recipients->update('rcp_…', [
'external_id' => 'user_123',
'name' => 'Tendai Moyo',
'phone' => '0772123456',
]);
Go
_, err := jusaClient.Recipients.Update(ctx, "rcp_…", jusa.Params{
"external_id": "user_123",
"name": "Tendai Moyo",
"phone": "0772123456",
})
if err != nil {
return err
}
Java
jusa.recipients().update("rcp_…", Params.of(
"external_id", "user_123",
"name", "Tendai Moyo",
"phone", "0772123456"
));
C#
await jusa.Recipients.UpdateAsync("rcp_…", new
{
external_id = "user_123",
name = "Tendai Moyo",
phone = "0772123456",
});
Dart
await jusa.recipients.update('rcp_…', {
'external_id': 'user_123',
'name': 'Tendai Moyo',
'phone': '0772123456',
});
Ruby
Jusa::Recipient.update(
"rcp_…",
external_id: "user_123",
name: "Tendai Moyo",
phone: "0772123456",
)
curl
curl -X PATCH https://jusa.localhost.co.zw/dev/v1/recipients/rcp_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"external_id": "user_123", "name": "Tendai Moyo", "phone": "0772123456"}'
Deactivate or erase a recipient
Deactivates. With erase=true, erases their data and keeps the history masked; refused (409 erasure_deferred) while a send is in flight or a schedule is active. Scope: recipients:write.
| Parameter | In | About |
|---|---|---|
recipient_id required | path | rcp_… or ext:<external_id>. |
erase | query | true: erase the person's data (deferred while anything is in flight). |
Returns: 200 DeletedRecipient or Recipient. Errors: the envelope.
Python
jusa.Recipient.delete("rcp_…")
Node
await jusa.recipients.delete('rcp_…');
PHP
$jusa->recipients->delete('rcp_…');
Go
_, err := jusaClient.Recipients.Delete(ctx, "rcp_…", nil)
if err != nil {
return err
}
Java
jusa.recipients().delete("rcp_…");
C#
await jusa.Recipients.DeleteAsync("rcp_…");
Dart
await jusa.recipients.delete('rcp_…');
Ruby
Jusa::Recipient.delete("rcp_…")
curl
curl -X DELETE https://jusa.localhost.co.zw/dev/v1/recipients/rcp_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
A recipient's earnings pots
Scope: recipients:read.
| Parameter | In | About |
|---|---|---|
recipient_id required | path | rcp_… or ext:<external_id>. |
Returns: 200 RecipientBalance. Errors: the envelope.
Python
jusa.Recipient.balance("rcp_…")
Node
await jusa.recipients.balance('rcp_…');
PHP
$jusa->recipients->balance('rcp_…');
Go
_, err := jusaClient.Recipients.Balance(ctx, "rcp_…", nil)
if err != nil {
return err
}
Java
jusa.recipients().balance("rcp_…");
C#
await jusa.Recipients.BalanceAsync("rcp_…");
Dart
await jusa.recipients.balance('rcp_…');
Ruby
Jusa::Recipient.balance("rcp_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/recipients/rcp_…/balance \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
List a recipient's sends
Scope: sends:read.
| Parameter | In | About |
|---|---|---|
recipient_id required | path | rcp_… or ext:<external_id>. |
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
metadata[key] | query | metadata[<key>]=<value>: an exact match on one key. |
Returns: 200 SendList. Errors: the envelope.
Python
jusa.Recipient.list_sends("rcp_…")
Node
await jusa.recipients.listSends('rcp_…');
PHP
$jusa->recipients->listSends('rcp_…');
Go
_, err := jusaClient.Recipients.ListSends(ctx, "rcp_…", nil)
if err != nil {
return err
}
Java
jusa.recipients().listSends("rcp_…");
C#
await jusa.Recipients.ListSendsAsync("rcp_…");
Dart
await jusa.recipients.listSends('rcp_…');
Ruby
Jusa::Recipient.list_sends("rcp_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/recipients/rcp_…/sends \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
A recipient's spend against their caps
Scope: recipients:read.
| Parameter | In | About |
|---|---|---|
recipient_id required | path | rcp_… or ext:<external_id>. |
Returns: 200 RecipientSpend. Errors: the envelope.
Python
jusa.Recipient.spend("rcp_…")
Node
await jusa.recipients.spend('rcp_…');
PHP
$jusa->recipients->spend('rcp_…');
Go
_, err := jusaClient.Recipients.Spend(ctx, "rcp_…", nil)
if err != nil {
return err
}
Java
jusa.recipients().spend("rcp_…");
C#
await jusa.Recipients.SpendAsync("rcp_…");
Dart
await jusa.recipients.spend('rcp_…');
Ruby
Jusa::Recipient.spend("rcp_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/recipients/rcp_…/spend \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
A person's statement
Everything sent to them in a period (this month by default; YYYY-MM-DD, inclusive), totalled by currency and outcome, with each send (up to 500). Scope: recipients:read.
| Parameter | In | About |
|---|---|---|
recipient_id required | path | rcp_… or ext:<external_id>. |
from | query | The start (inclusive). |
to | query | The end (inclusive). |
Returns: 200 RecipientStatement. Errors: the envelope.
Python
jusa.Recipient.statement("rcp_…")
Node
await jusa.recipients.statement('rcp_…');
PHP
$jusa->recipients->statement('rcp_…');
Go
_, err := jusaClient.Recipients.Statement(ctx, "rcp_…", nil)
if err != nil {
return err
}
Java
jusa.recipients().statement("rcp_…");
C#
await jusa.Recipients.StatementAsync("rcp_…");
Dart
await jusa.recipients.statement('rcp_…');
Ruby
Jusa::Recipient.statement("rcp_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/recipients/rcp_…/statement \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Import recipients
Up to 5,000, as JSON rows or CSV. Scope: recipients:write.
| Body (RecipientBulk) | Type | About |
|---|---|---|
recipients | array of any | Recipient rows (as POST /recipients); a bad row is reported in its place. |
csv | string |
Returns: 200 RecipientImport. Errors: the envelope.
Python
jusa.Recipient.bulk()
Node
await jusa.recipients.bulk();
PHP
$jusa->recipients->bulk();
Go
_, err := jusaClient.Recipients.Bulk(ctx, nil)
if err != nil {
return err
}
Java
jusa.recipients().bulk();
C#
await jusa.Recipients.BulkAsync();
Dart
await jusa.recipients.bulk();
Ruby
Jusa::Recipient.bulk
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/recipients/bulk \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Programs
Reward programs: budget, caps, fraud rules.
List programs
Scope: rewards:read.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
status | query | Only objects in this status. |
metadata[key] | query | metadata[<key>]=<value>: an exact match on one key. |
Returns: 200 ProgramList. Errors: the envelope.
Python
jusa.Program.list()
Node
await jusa.programs.list();
PHP
$jusa->programs->list();
Go
_, err := jusaClient.Programs.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.programs().list();
C#
await jusa.Programs.ListAsync();
Dart
await jusa.programs.list();
Ruby
Jusa::Program.list
curl
curl https://jusa.localhost.co.zw/dev/v1/programs \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Create a program
The completions HMAC secret is shown once, here. A reserve program sets its whole budget aside (402 when the credit is short). Scope: programs:manage.
| Body (ProgramCreate) | Type | About |
|---|---|---|
name required | string | |
slug | string | Lowercase letters, digits and hyphens, 1 to 60. Optional: made from the name if left out. |
description | string | |
currency | "USD" | "ZWG" | "usd" | "zwg" | USD or ZWG (either case). |
default_amount required | string or number | A decimal amount, e.g. "5.00". |
budget required | string or number | A decimal amount, e.g. "5.00". |
funding | "draw" | "reserve" | |
choices | array of "airtime" | "data" | "zesa" | |
status | "draft" | "active" | |
sources | array of "api" | "completions" | "links" | |
one_per_phone | boolean | |
per_recipient | object | |
require_network | string | |
throttle_per_hour | integer | |
min_account_age | string or integer | Seconds, or "30m", "24h", "3d". |
hold | object | |
on_zesa_down | "queue" | "fail" | |
max_hold | string or integer | Seconds, or "30m", "24h", "3d". |
sms_message | string | |
branding | object | |
lawful_basis | string | |
sensitive_data | boolean | |
metadata | object | Up to 20 keys (letters, digits, _ . -, up to 40 characters) with values up to 500 characters. |
geofence | object |
Returns: 201 Program. Errors: the envelope.
Python
jusa.Program.create(
name="Household survey Q4",
currency="USD",
default_amount="0.50",
budget="500.00",
funding="reserve",
per_recipient={"lifetime": 1},
)
Node
await jusa.programs.create({
name: 'Household survey Q4',
currency: 'USD',
default_amount: '0.50',
budget: '500.00',
funding: 'reserve',
per_recipient: { lifetime: 1 },
});
PHP
$jusa->programs->create([
'name' => 'Household survey Q4',
'currency' => 'USD',
'default_amount' => '0.50',
'budget' => '500.00',
'funding' => 'reserve',
'per_recipient' => ['lifetime' => 1],
]);
Go
_, err := jusaClient.Programs.Create(ctx, jusa.Params{
"name": "Household survey Q4",
"currency": "USD",
"default_amount": "0.50",
"budget": "500.00",
"funding": "reserve",
"per_recipient": jusa.Params{"lifetime": 1},
})
if err != nil {
return err
}
Java
jusa.programs().create(Params.of(
"name", "Household survey Q4",
"currency", "USD",
"default_amount", "0.50",
"budget", "500.00",
"funding", "reserve",
"per_recipient", Map.of("lifetime", 1)
));
C#
await jusa.Programs.CreateAsync(new
{
name = "Household survey Q4",
currency = "USD",
default_amount = "0.50",
budget = "500.00",
funding = "reserve",
per_recipient = new { lifetime = 1 },
});
Dart
await jusa.programs.create({
'name': 'Household survey Q4',
'currency': 'USD',
'default_amount': '0.50',
'budget': '500.00',
'funding': 'reserve',
'per_recipient': {'lifetime': 1},
});
Ruby
Jusa::Program.create(
name: "Household survey Q4",
currency: "USD",
default_amount: "0.50",
budget: "500.00",
funding: "reserve",
per_recipient: { lifetime: 1 },
)
curl
curl https://jusa.localhost.co.zw/dev/v1/programs \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Household survey Q4",
"currency": "USD",
"default_amount": "0.50",
"budget": "500.00",
"funding": "reserve",
"per_recipient": {"lifetime": 1}
}'
Retrieve a program
Scope: rewards:read.
| Parameter | In | About |
|---|---|---|
program_id required | path | prg_… |
Returns: 200 Program. Errors: the envelope.
Python
jusa.Program.retrieve("prg_…")
Node
await jusa.programs.retrieve('prg_…');
PHP
$jusa->programs->retrieve('prg_…');
Go
_, err := jusaClient.Programs.Retrieve(ctx, "prg_…", nil)
if err != nil {
return err
}
Java
jusa.programs().retrieve("prg_…");
C#
await jusa.Programs.RetrieveAsync("prg_…");
Dart
await jusa.programs.retrieve('prg_…');
Ruby
Jusa::Program.retrieve("prg_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/programs/prg_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Update a program
Scope: programs:manage.
| Parameter | In | About |
|---|---|---|
program_id required | path | prg_… |
| Body (ProgramUpdate) | Type | About |
|---|---|---|
name | string | |
slug | string | Lowercase letters, digits and hyphens, 1 to 60. Optional: made from the name if left out. |
description | string | |
default_amount | string or number | A decimal amount, e.g. "5.00". |
budget | string or number | A decimal amount, e.g. "5.00". |
choices | array of "airtime" | "data" | "zesa" | |
sources | array of "api" | "completions" | "links" | |
one_per_phone | boolean | |
per_recipient | object | |
require_network | string | |
throttle_per_hour | integer | |
min_account_age | string or integer | Seconds, or "30m", "24h", "3d". |
hold | object | |
on_zesa_down | "queue" | "fail" | |
max_hold | string or integer | Seconds, or "30m", "24h", "3d". |
sms_message | string | |
branding | object | |
lawful_basis | string | |
sensitive_data | boolean | |
metadata | object | Up to 20 keys (letters, digits, _ . -, up to 40 characters) with values up to 500 characters. |
geofence | object |
Returns: 200 Program. Errors: the envelope.
Python
jusa.Program.update("prg_…")
Node
await jusa.programs.update('prg_…');
PHP
$jusa->programs->update('prg_…');
Go
_, err := jusaClient.Programs.Update(ctx, "prg_…", nil)
if err != nil {
return err
}
Java
jusa.programs().update("prg_…");
C#
await jusa.Programs.UpdateAsync("prg_…");
Dart
await jusa.programs.update('prg_…');
Ruby
Jusa::Program.update("prg_…")
curl
curl -X PATCH https://jusa.localhost.co.zw/dev/v1/programs/prg_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Close a program
The same as POST …/close. Scope: programs:manage.
| Parameter | In | About |
|---|---|---|
program_id required | path | prg_… |
Returns: 200 Program. Errors: the envelope.
Python
jusa.Program.delete("prg_…")
Node
await jusa.programs.delete('prg_…');
PHP
$jusa->programs->delete('prg_…');
Go
_, err := jusaClient.Programs.Delete(ctx, "prg_…", nil)
if err != nil {
return err
}
Java
jusa.programs().delete("prg_…");
C#
await jusa.Programs.DeleteAsync("prg_…");
Dart
await jusa.programs.delete('prg_…');
Ruby
Jusa::Program.delete("prg_…")
curl
curl -X DELETE https://jusa.localhost.co.zw/dev/v1/programs/prg_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Activate a draft program
Scope: programs:manage.
| Parameter | In | About |
|---|---|---|
program_id required | path | prg_… |
Returns: 200 Program. Errors: the envelope.
Python
jusa.Program.activate("prg_…")
Node
await jusa.programs.activate('prg_…');
PHP
$jusa->programs->activate('prg_…');
Go
_, err := jusaClient.Programs.Activate(ctx, "prg_…", nil)
if err != nil {
return err
}
Java
jusa.programs().activate("prg_…");
C#
await jusa.Programs.ActivateAsync("prg_…");
Dart
await jusa.programs.activate('prg_…');
Ruby
Jusa::Program.activate("prg_…")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/programs/prg_…/activate \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Close a program
Scope: programs:manage.
| Parameter | In | About |
|---|---|---|
program_id required | path | prg_… |
Returns: 200 Program. Errors: the envelope.
Python
jusa.Program.close("prg_…")
Node
await jusa.programs.close('prg_…');
PHP
$jusa->programs->close('prg_…');
Go
_, err := jusaClient.Programs.Close(ctx, "prg_…", nil)
if err != nil {
return err
}
Java
jusa.programs().close("prg_…");
C#
await jusa.Programs.CloseAsync("prg_…");
Dart
await jusa.programs.close('prg_…');
Ruby
Jusa::Program.close("prg_…")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/programs/prg_…/close \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Report a completion (signed)
For survey tools that can sign a webhook but hold no key: Jusa-Signature: t=<unix>,v1=<hex HMAC-SHA256(program secret, "{t}.{raw body}")>, within 5 minutes. completion_id (or ref) is required; a repeat returns the first reward (200).
| Parameter | In | About |
|---|---|---|
program_id required | path | prg_… |
| Body (Completion) | Type | About |
|---|---|---|
completion_id | string | |
ref | string | Alias of completion_id. |
recipient | string or object | rcp_… or ext:<external_id>. |
phone | string | A Zimbabwean mobile: 07XXXXXXXX, 2637XXXXXXXX or +2637XXXXXXXX. |
target | string | A Zimbabwean mobile: 07XXXXXXXX, 2637XXXXXXXX or +2637XXXXXXXX. |
meter | string | An 11-digit ZESA prepaid meter number. |
token_phone | string | A Zimbabwean mobile: 07XXXXXXXX, 2637XXXXXXXX or +2637XXXXXXXX. |
amount | string or number | A decimal amount, e.g. "5.00". |
metadata | object | Up to 20 keys (letters, digits, _ . -, up to 40 characters) with values up to 500 characters. |
Returns: 200 Reward · 201 Reward. Errors: the envelope.
Python
jusa.Program.create_completion("prg_…")
Node
await jusa.programs.createCompletion('prg_…');
PHP
$jusa->programs->createCompletion('prg_…');
Go
_, err := jusaClient.Programs.CreateCompletion(ctx, "prg_…", nil)
if err != nil {
return err
}
Java
jusa.programs().createCompletion("prg_…");
C#
await jusa.Programs.CreateCompletionAsync("prg_…");
Dart
await jusa.programs.createCompletion('prg_…');
Ruby
Jusa::Program.create_completion("prg_…")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/programs/prg_…/completions \
-H "Jusa-Signature: t=$TIMESTAMP,v1=$SIGNATURE"
Take budget back
Without an amount: everything no escrow or unclaimed link has earmarked. Scope: programs:manage. Moves money: an Idempotency-Key is required.
| Parameter | In | About |
|---|---|---|
program_id required | path | prg_… |
| Body (ProgramDefund) | Type | About |
|---|---|---|
amount | string or number | A decimal amount, e.g. "5.00". |
Returns: 200 Program. Errors: the envelope.
Python
jusa.Program.defund("prg_…", idempotency_key="defund-survey-q4-2026")
Node
await jusa.programs.defund('prg_…', {}, { idempotencyKey: 'defund-survey-q4-2026' });
PHP
$jusa->programs->defund('prg_…', [], ['idempotency_key' => 'defund-survey-q4-2026']);
Go
_, err := jusaClient.Programs.Defund(ctx, "prg_…", nil, jusa.WithIdempotencyKey("defund-survey-q4-2026"))
if err != nil {
return err
}
Java
jusa.programs().defund("prg_…", RequestOptions.idempotencyKey("defund-survey-q4-2026"));
C#
await jusa.Programs.DefundAsync("prg_…", options: new RequestOptions { IdempotencyKey = "defund-survey-q4-2026" });
Dart
await jusa.programs.defund('prg_…', {}, RequestOptions(idempotencyKey: 'defund-survey-q4-2026'));
Ruby
Jusa::Program.defund("prg_…", {}, idempotency_key: "defund-survey-q4-2026")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/programs/prg_…/defund \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Idempotency-Key: defund-survey-q4-2026"
Add budget (and reserved credit)
Scope: programs:manage. Moves money: an Idempotency-Key is required.
| Parameter | In | About |
|---|---|---|
program_id required | path | prg_… |
| Body (ProgramFund) | Type | About |
|---|---|---|
amount required | string or number | A decimal amount, e.g. "5.00". |
Returns: 200 Program. Errors: the envelope.
Python
jusa.Program.fund("prg_…", amount="5.00", idempotency_key="fund-survey-q4-2026")
Node
await jusa.programs.fund('prg_…', {
amount: '5.00',
}, { idempotencyKey: 'fund-survey-q4-2026' });
PHP
$jusa->programs->fund('prg_…', [
'amount' => '5.00',
], ['idempotency_key' => 'fund-survey-q4-2026']);
Go
_, err := jusaClient.Programs.Fund(ctx, "prg_…", jusa.Params{
"amount": "5.00",
}, jusa.WithIdempotencyKey("fund-survey-q4-2026"))
if err != nil {
return err
}
Java
jusa.programs().fund("prg_…", Params.of(
"amount", "5.00"
), RequestOptions.idempotencyKey("fund-survey-q4-2026"));
C#
await jusa.Programs.FundAsync("prg_…", new
{
amount = "5.00",
}, new RequestOptions { IdempotencyKey = "fund-survey-q4-2026" });
Dart
await jusa.programs.fund('prg_…', {
'amount': '5.00',
}, RequestOptions(idempotencyKey: 'fund-survey-q4-2026'));
Ruby
Jusa::Program.fund("prg_…", { amount: "5.00" }, idempotency_key: "fund-survey-q4-2026")
curl
curl https://jusa.localhost.co.zw/dev/v1/programs/prg_…/fund \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Idempotency-Key: fund-survey-q4-2026" \
-H "Content-Type: application/json" \
-d '{"amount": "5.00"}'
Pause a program
Scope: programs:manage.
| Parameter | In | About |
|---|---|---|
program_id required | path | prg_… |
Returns: 200 Program. Errors: the envelope.
Python
jusa.Program.pause("prg_…")
Node
await jusa.programs.pause('prg_…');
PHP
$jusa->programs->pause('prg_…');
Go
_, err := jusaClient.Programs.Pause(ctx, "prg_…", nil)
if err != nil {
return err
}
Java
jusa.programs().pause("prg_…");
C#
await jusa.Programs.PauseAsync("prg_…");
Dart
await jusa.programs.pause('prg_…');
Ruby
Jusa::Program.pause("prg_…")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/programs/prg_…/pause \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Resume a paused program
Scope: programs:manage.
| Parameter | In | About |
|---|---|---|
program_id required | path | prg_… |
Returns: 200 Program. Errors: the envelope.
Python
jusa.Program.resume("prg_…")
Node
await jusa.programs.resume('prg_…');
PHP
$jusa->programs->resume('prg_…');
Go
_, err := jusaClient.Programs.Resume(ctx, "prg_…", nil)
if err != nil {
return err
}
Java
jusa.programs().resume("prg_…");
C#
await jusa.Programs.ResumeAsync("prg_…");
Dart
await jusa.programs.resume('prg_…');
Ruby
Jusa::Program.resume("prg_…")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/programs/prg_…/resume \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Roll the completions secret
The old secret keeps working for 24 hours. Scope: programs:manage.
| Parameter | In | About |
|---|---|---|
program_id required | path | prg_… |
Returns: 200 Program. Errors: the envelope.
Python
jusa.Program.roll_secret("prg_…")
Node
await jusa.programs.rollSecret('prg_…');
PHP
$jusa->programs->rollSecret('prg_…');
Go
_, err := jusaClient.Programs.RollSecret(ctx, "prg_…", nil)
if err != nil {
return err
}
Java
jusa.programs().rollSecret("prg_…");
C#
await jusa.Programs.RollSecretAsync("prg_…");
Dart
await jusa.programs.rollSecret('prg_…');
Ruby
Jusa::Program.roll_secret("prg_…")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/programs/prg_…/roll-secret \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Rewards
The seed primitive: reward a person for something they did.
List rewards
Scope: rewards:read.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
status | query | Only objects in this status. |
program | query | prg_… |
recipient | query | rcp_… or ext:<external_id>. |
completion_id | query | The completion it answers. |
external_id | query | Your id for the person. |
expand[] | query | Inline a related object in place of its id (repeat for more): recipient, program or batch on a send; recipient, program or send on a reward. |
metadata[key] | query | metadata[<key>]=<value>: an exact match on one key. |
Returns: 200 RewardList. Errors: the envelope.
Python
jusa.Reward.list()
Node
await jusa.rewards.list();
PHP
$jusa->rewards->list();
Go
_, err := jusaClient.Rewards.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.rewards().list();
C#
await jusa.Rewards.ListAsync();
Dart
await jusa.rewards.list();
Ruby
Jusa::Reward.list
curl
curl https://jusa.localhost.co.zw/dev/v1/rewards \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Reward someone
The seed primitive: caps, fraud rules and budget under one lock, then a send or a link. The same completion_id again returns the first reward (200). A refusal writes nothing, so it can be retried. Scope: rewards:write. Moves money: an Idempotency-Key is required.
| Body (RewardCreate) | Type | About |
|---|---|---|
program required | string | |
recipient required | string or object | rcp_… or ext:<external_id>. |
amount | string or number | A decimal amount, e.g. "5.00". |
delivery | "direct" | "link" | "choice" | |
type | "airtime" | "data" | "zesa" | |
product | string | |
bundle_id | string | |
meter | string | An 11-digit ZESA prepaid meter number. |
token_phone | string | A Zimbabwean mobile: 07XXXXXXXX, 2637XXXXXXXX or +2637XXXXXXXX. |
completion_id required | string | Required: one reward per completion, for good. |
hold | boolean | |
metadata | object | Up to 20 keys (letters, digits, _ . -, up to 40 characters) with values up to 500 characters. |
link | object | |
reason | string |
Returns: 200 Reward · 201 Reward · 202 AgentApproval. Errors: the envelope.
Python
jusa.Reward.create(
program="prg_…",
recipient={"external_id": "resp-8812", "phone": "0771230000"},
completion_id="8812",
metadata={"survey": "form-hh-q4"},
idempotency_key="survey-8812",
)
Node
await jusa.rewards.create({
program: 'prg_…',
recipient: { external_id: 'resp-8812', phone: '0771230000' },
completion_id: '8812',
metadata: { survey: 'form-hh-q4' },
}, { idempotencyKey: 'survey-8812' });
PHP
$jusa->rewards->create([
'program' => 'prg_…',
'recipient' => ['external_id' => 'resp-8812', 'phone' => '0771230000'],
'completion_id' => '8812',
'metadata' => ['survey' => 'form-hh-q4'],
], ['idempotency_key' => 'survey-8812']);
Go
_, err := jusaClient.Rewards.Create(ctx, jusa.Params{
"program": "prg_…",
"recipient": jusa.Params{"external_id": "resp-8812", "phone": "0771230000"},
"completion_id": "8812",
"metadata": jusa.Params{"survey": "form-hh-q4"},
}, jusa.WithIdempotencyKey("survey-8812"))
if err != nil {
return err
}
Java
jusa.rewards().create(Params.of(
"program", "prg_…",
"recipient", Map.of("external_id", "resp-8812", "phone", "0771230000"),
"completion_id", "8812",
"metadata", Map.of("survey", "form-hh-q4")
), RequestOptions.idempotencyKey("survey-8812"));
C#
await jusa.Rewards.CreateAsync(new
{
program = "prg_…",
recipient = new { external_id = "resp-8812", phone = "0771230000" },
completion_id = "8812",
metadata = new { survey = "form-hh-q4" },
}, new RequestOptions { IdempotencyKey = "survey-8812" });
Dart
await jusa.rewards.create({
'program': 'prg_…',
'recipient': {'external_id': 'resp-8812', 'phone': '0771230000'},
'completion_id': '8812',
'metadata': {'survey': 'form-hh-q4'},
}, RequestOptions(idempotencyKey: 'survey-8812'));
Ruby
Jusa::Reward.create({
program: "prg_…",
recipient: { external_id: "resp-8812", phone: "0771230000" },
completion_id: "8812",
metadata: { survey: "form-hh-q4" },
}, idempotency_key: "survey-8812")
curl
curl https://jusa.localhost.co.zw/dev/v1/rewards \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Idempotency-Key: survey-8812" \
-H "Content-Type: application/json" \
-d '{
"program": "prg_…",
"recipient": {"external_id": "resp-8812", "phone": "0771230000"},
"completion_id": "8812",
"metadata": {"survey": "form-hh-q4"}
}'
Retrieve a reward
Scope: rewards:read.
| Parameter | In | About |
|---|---|---|
reward_id required | path | rwd_… |
expand[] | query | Inline a related object in place of its id (repeat for more): recipient, program or batch on a send; recipient, program or send on a reward. |
Returns: 200 Reward. Errors: the envelope.
Python
jusa.Reward.retrieve("rwd_…")
Node
await jusa.rewards.retrieve('rwd_…');
PHP
$jusa->rewards->retrieve('rwd_…');
Go
_, err := jusaClient.Rewards.Retrieve(ctx, "rwd_…", nil)
if err != nil {
return err
}
Java
jusa.rewards().retrieve("rwd_…");
C#
await jusa.Rewards.RetrieveAsync("rwd_…");
Dart
await jusa.rewards.retrieve('rwd_…');
Ruby
Jusa::Reward.retrieve("rwd_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/rewards/rwd_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Release an escrowed reward
Optionally for less. Scope: rewards:write. Moves money: an Idempotency-Key is required.
| Parameter | In | About |
|---|---|---|
reward_id required | path | rwd_… |
| Body (RewardRelease) | Type | About |
|---|---|---|
amount | string or number | A decimal amount, e.g. "5.00". |
Returns: 200 Reward. Errors: the envelope.
Python
jusa.Reward.release("rwd_…", idempotency_key="release-signup-8812")
Node
await jusa.rewards.release('rwd_…', {}, { idempotencyKey: 'release-signup-8812' });
PHP
$jusa->rewards->release('rwd_…', [], ['idempotency_key' => 'release-signup-8812']);
Go
_, err := jusaClient.Rewards.Release(ctx, "rwd_…", nil, jusa.WithIdempotencyKey("release-signup-8812"))
if err != nil {
return err
}
Java
jusa.rewards().release("rwd_…", RequestOptions.idempotencyKey("release-signup-8812"));
C#
await jusa.Rewards.ReleaseAsync("rwd_…", options: new RequestOptions { IdempotencyKey = "release-signup-8812" });
Dart
await jusa.rewards.release('rwd_…', {}, RequestOptions(idempotencyKey: 'release-signup-8812'));
Ruby
Jusa::Reward.release("rwd_…", {}, idempotency_key: "release-signup-8812")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/rewards/rwd_…/release \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Idempotency-Key: release-signup-8812"
Void a reward
Its budget goes back to the program. Scope: rewards:write.
| Parameter | In | About |
|---|---|---|
reward_id required | path | rwd_… |
Returns: 200 Reward. Errors: the envelope.
Python
jusa.Reward.void("rwd_…")
Node
await jusa.rewards.void('rwd_…');
PHP
$jusa->rewards->void('rwd_…');
Go
_, err := jusaClient.Rewards.Void(ctx, "rwd_…", nil)
if err != nil {
return err
}
Java
jusa.rewards().voidReward("rwd_…");
C#
await jusa.Rewards.VoidAsync("rwd_…");
Dart
await jusa.rewards.voidReward('rwd_…');
Ruby
Jusa::Reward.void("rwd_…")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/rewards/rwd_…/void \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Reward links
Links and QR codes a person claims.
List reward links
Scope: rewards:read.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
status | query | Only objects in this status. |
label | query | Only links with this label. |
program | query | prg_… |
metadata[key] | query | metadata[<key>]=<value>: an exact match on one key. |
Returns: 200 RewardLinkList. Errors: the envelope.
Python
jusa.RewardLink.list()
Node
await jusa.rewardLinks.list();
PHP
$jusa->rewardLinks->list();
Go
_, err := jusaClient.RewardLinks.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.rewardLinks().list();
C#
await jusa.RewardLinks.ListAsync();
Dart
await jusa.rewardLinks.list();
Ruby
Jusa::RewardLink.list
curl
curl https://jusa.localhost.co.zw/dev/v1/reward-links \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Create reward links
One link, or a list when count is over 1 (up to 500). Each has a url, a token and a QR code. Scope: rewards:write.
| Body (RewardLinkCreate) | Type | About |
|---|---|---|
program required | string | |
count | integer | |
recipient | string or object | rcp_… or ext:<external_id>. |
amount | string or number | A decimal amount, e.g. "5.00". |
label | string | |
expires_at | integer or string | Unix seconds or an ISO 8601 time. |
bind | "none" | "otp" | |
phone_hint | string | A Zimbabwean mobile: 07XXXXXXXX, 2637XXXXXXXX or +2637XXXXXXXX. |
choices | array of "airtime" | "data" | "zesa" | |
metadata | object | Up to 20 keys (letters, digits, _ . -, up to 40 characters) with values up to 500 characters. |
Returns: 201 RewardLink or RewardLinkList. Errors: the envelope.
Python
jusa.RewardLink.create(program="prg_…", count=10, bind="otp", label="enumerator-7")
Node
await jusa.rewardLinks.create({
program: 'prg_…',
count: 10,
bind: 'otp',
label: 'enumerator-7',
});
PHP
$jusa->rewardLinks->create([
'program' => 'prg_…',
'count' => 10,
'bind' => 'otp',
'label' => 'enumerator-7',
]);
Go
_, err := jusaClient.RewardLinks.Create(ctx, jusa.Params{
"program": "prg_…",
"count": 10,
"bind": "otp",
"label": "enumerator-7",
})
if err != nil {
return err
}
Java
jusa.rewardLinks().create(Params.of(
"program", "prg_…",
"count", 10,
"bind", "otp",
"label", "enumerator-7"
));
C#
await jusa.RewardLinks.CreateAsync(new
{
program = "prg_…",
count = 10,
bind = "otp",
label = "enumerator-7",
});
Dart
await jusa.rewardLinks.create({
'program': 'prg_…',
'count': 10,
'bind': 'otp',
'label': 'enumerator-7',
});
Ruby
Jusa::RewardLink.create(program: "prg_…", count: 10, bind: "otp", label: "enumerator-7")
curl
curl https://jusa.localhost.co.zw/dev/v1/reward-links \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"program": "prg_…", "count": 10, "bind": "otp", "label": "enumerator-7"}'
Retrieve a reward link
Scope: rewards:read.
| Parameter | In | About |
|---|---|---|
link_id required | path | lnk_… |
Returns: 200 RewardLink. Errors: the envelope.
Python
jusa.RewardLink.retrieve("lnk_…")
Node
await jusa.rewardLinks.retrieve('lnk_…');
PHP
$jusa->rewardLinks->retrieve('lnk_…');
Go
_, err := jusaClient.RewardLinks.Retrieve(ctx, "lnk_…", nil)
if err != nil {
return err
}
Java
jusa.rewardLinks().retrieve("lnk_…");
C#
await jusa.RewardLinks.RetrieveAsync("lnk_…");
Dart
await jusa.rewardLinks.retrieve('lnk_…');
Ruby
Jusa::RewardLink.retrieve("lnk_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/reward-links/lnk_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Revoke a reward link
Scope: rewards:write.
| Parameter | In | About |
|---|---|---|
link_id required | path | lnk_… |
Returns: 200 RewardLink. Errors: the envelope.
Python
jusa.RewardLink.revoke("lnk_…")
Node
await jusa.rewardLinks.revoke('lnk_…');
PHP
$jusa->rewardLinks->revoke('lnk_…');
Go
_, err := jusaClient.RewardLinks.Revoke(ctx, "lnk_…", nil)
if err != nil {
return err
}
Java
jusa.rewardLinks().revoke("lnk_…");
C#
await jusa.RewardLinks.RevokeAsync("lnk_…");
Dart
await jusa.rewardLinks.revoke('lnk_…');
Ruby
Jusa::RewardLink.revoke("lnk_…")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/reward-links/lnk_…/revoke \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Reviews
Rewards held by a fraud rule, and your blocklist.
List blocked numbers and meters
Scope: rewards:read.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
target | query | A phone (any format) or meter. |
Returns: 200 BlockedTargetList. Errors: the envelope.
Python
jusa.Blocklist.list()
Node
await jusa.blocklist.list();
PHP
$jusa->blocklist->list();
Go
_, err := jusaClient.Blocklist.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.blocklist().list();
C#
await jusa.Blocklist.ListAsync();
Dart
await jusa.blocklist.list();
Ruby
Jusa::Blocklist.list
curl
curl https://jusa.localhost.co.zw/dev/v1/blocklist \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Block a number or meter
Live mode only. Scope: account:manage.
| Body (BlockCreate) | Type | About |
|---|---|---|
target required | string | |
reason | string |
Returns: 201 BlockedTarget. Errors: the envelope.
Python
jusa.Blocklist.create(target="string")
Node
await jusa.blocklist.create({ target: 'string' });
PHP
$jusa->blocklist->create(['target' => 'string']);
Go
_, err := jusaClient.Blocklist.Create(ctx, jusa.Params{"target": "string"})
if err != nil {
return err
}
Java
jusa.blocklist().create(Params.of("target", "string"));
C#
await jusa.Blocklist.CreateAsync(new { target = "string" });
Dart
await jusa.blocklist.create({'target': 'string'});
Ruby
Jusa::Blocklist.create(target: "string")
curl
curl https://jusa.localhost.co.zw/dev/v1/blocklist \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"target": "string"}'
Retrieve a block
Scope: rewards:read.
| Parameter | In | About |
|---|---|---|
entry_id required | path | blk_… |
Returns: 200 BlockedTarget. Errors: the envelope.
Python
jusa.Blocklist.retrieve("blk_…")
Node
await jusa.blocklist.retrieve('blk_…');
PHP
$jusa->blocklist->retrieve('blk_…');
Go
_, err := jusaClient.Blocklist.Retrieve(ctx, "blk_…", nil)
if err != nil {
return err
}
Java
jusa.blocklist().retrieve("blk_…");
C#
await jusa.Blocklist.RetrieveAsync("blk_…");
Dart
await jusa.blocklist.retrieve('blk_…');
Ruby
Jusa::Blocklist.retrieve("blk_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/blocklist/blk_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Unblock
Scope: account:manage.
| Parameter | In | About |
|---|---|---|
entry_id required | path | blk_… |
Returns: 200 BlockedTarget. Errors: the envelope.
Python
jusa.Blocklist.delete("blk_…")
Node
await jusa.blocklist.delete('blk_…');
PHP
$jusa->blocklist->delete('blk_…');
Go
_, err := jusaClient.Blocklist.Delete(ctx, "blk_…", nil)
if err != nil {
return err
}
Java
jusa.blocklist().delete("blk_…");
C#
await jusa.Blocklist.DeleteAsync("blk_…");
Dart
await jusa.blocklist.delete('blk_…');
Ruby
Jusa::Blocklist.delete("blk_…")
curl
curl -X DELETE https://jusa.localhost.co.zw/dev/v1/blocklist/blk_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
List fraud reviews
Scope: rewards:read.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
status | query | Only objects in this status. |
program | query | prg_… |
Returns: 200 ReviewList. Errors: the envelope.
Python
jusa.Review.list()
Node
await jusa.reviews.list();
PHP
$jusa->reviews->list();
Go
_, err := jusaClient.Reviews.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.reviews().list();
C#
await jusa.Reviews.ListAsync();
Dart
await jusa.reviews.list();
Ruby
Jusa::Review.list
curl
curl https://jusa.localhost.co.zw/dev/v1/reviews \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Retrieve a review
Scope: rewards:read.
| Parameter | In | About |
|---|---|---|
review_id required | path | rev_… |
Returns: 200 Review. Errors: the envelope.
Python
jusa.Review.retrieve("rev_…")
Node
await jusa.reviews.retrieve('rev_…');
PHP
$jusa->reviews->retrieve('rev_…');
Go
_, err := jusaClient.Reviews.Retrieve(ctx, "rev_…", nil)
if err != nil {
return err
}
Java
jusa.reviews().retrieve("rev_…");
C#
await jusa.Reviews.RetrieveAsync("rev_…");
Dart
await jusa.reviews.retrieve('rev_…');
Ruby
Jusa::Review.retrieve("rev_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/reviews/rev_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Approve a held reward
Re-checks the caps and budget under lock, then sends. Scope: programs:manage. Moves money: an Idempotency-Key is required.
| Parameter | In | About |
|---|---|---|
review_id required | path | rev_… |
| Body (ReviewDecision) | Type | About |
|---|---|---|
note | string |
Returns: 200 Review. Errors: the envelope.
Python
jusa.Review.approve("rev_…", idempotency_key="approve-order-8812")
Node
await jusa.reviews.approve('rev_…', {}, { idempotencyKey: 'approve-order-8812' });
PHP
$jusa->reviews->approve('rev_…', [], ['idempotency_key' => 'approve-order-8812']);
Go
_, err := jusaClient.Reviews.Approve(ctx, "rev_…", nil, jusa.WithIdempotencyKey("approve-order-8812"))
if err != nil {
return err
}
Java
jusa.reviews().approve("rev_…", RequestOptions.idempotencyKey("approve-order-8812"));
C#
await jusa.Reviews.ApproveAsync("rev_…", options: new RequestOptions { IdempotencyKey = "approve-order-8812" });
Dart
await jusa.reviews.approve('rev_…', {}, RequestOptions(idempotencyKey: 'approve-order-8812'));
Ruby
Jusa::Review.approve("rev_…", {}, idempotency_key: "approve-order-8812")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/reviews/rev_…/approve \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Idempotency-Key: approve-order-8812"
Reject a held reward
Scope: programs:manage.
| Parameter | In | About |
|---|---|---|
review_id required | path | rev_… |
| Body (ReviewDecision) | Type | About |
|---|---|---|
note | string |
Returns: 200 Review. Errors: the envelope.
Python
jusa.Review.reject("rev_…")
Node
await jusa.reviews.reject('rev_…');
PHP
$jusa->reviews->reject('rev_…');
Go
_, err := jusaClient.Reviews.Reject(ctx, "rev_…", nil)
if err != nil {
return err
}
Java
jusa.reviews().reject("rev_…");
C#
await jusa.Reviews.RejectAsync("rev_…");
Dart
await jusa.reviews.reject('rev_…');
Ruby
Jusa::Review.reject("rev_…")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/reviews/rev_…/reject \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Rules
Earnings pots, streaks, referrals and geofenced check-ins.
List activities
Scope: rewards:read.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
name | query | Only activities with this name. |
recipient | query | rcp_… or ext:<external_id>. |
metadata[key] | query | metadata[<key>]=<value>: an exact match on one key. |
Returns: 200 ActivityList. Errors: the envelope.
Python
jusa.Activity.list()
Node
await jusa.activities.list();
PHP
$jusa->activities->list();
Go
_, err := jusaClient.Activities.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.activities().list();
C#
await jusa.Activities.ListAsync();
Dart
await jusa.activities.list();
Ruby
Jusa::Activity.list
curl
curl https://jusa.localhost.co.zw/dev/v1/activities \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Record an activity
Feeds the program rules; matches says what it triggered. activity_id dedupes for good (200). Scope: rewards:write.
| Body (ActivityCreate) | Type | About |
|---|---|---|
recipient required | string or object | rcp_… or ext:<external_id>. |
name required | string | |
activity_id required | string | |
occurred_at | integer or string | Unix seconds or an ISO 8601 time. |
value | string or number | A decimal amount, e.g. "5.00". |
program | string | |
metadata | object | Up to 20 keys (letters, digits, _ . -, up to 40 characters) with values up to 500 characters. |
Returns: 200 Activity · 201 Activity. Errors: the envelope.
Python
jusa.Activity.create(
recipient="ext:user_123",
name="lesson.completed",
activity_id="log-9981",
)
Node
await jusa.activities.create({
recipient: 'ext:user_123',
name: 'lesson.completed',
activity_id: 'log-9981',
});
PHP
$jusa->activities->create([
'recipient' => 'ext:user_123',
'name' => 'lesson.completed',
'activity_id' => 'log-9981',
]);
Go
_, err := jusaClient.Activities.Create(ctx, jusa.Params{
"recipient": "ext:user_123",
"name": "lesson.completed",
"activity_id": "log-9981",
})
if err != nil {
return err
}
Java
jusa.activities().create(Params.of(
"recipient", "ext:user_123",
"name", "lesson.completed",
"activity_id", "log-9981"
));
C#
await jusa.Activities.CreateAsync(new
{
recipient = "ext:user_123",
name = "lesson.completed",
activity_id = "log-9981",
});
Dart
await jusa.activities.create({
'recipient': 'ext:user_123',
'name': 'lesson.completed',
'activity_id': 'log-9981',
});
Ruby
Jusa::Activity.create(
recipient: "ext:user_123",
name: "lesson.completed",
activity_id: "log-9981",
)
curl
curl https://jusa.localhost.co.zw/dev/v1/activities \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"recipient": "ext:user_123",
"name": "lesson.completed",
"activity_id": "log-9981"
}'
Retrieve an activity
Scope: rewards:read.
| Parameter | In | About |
|---|---|---|
activity_id required | path | act_… |
Returns: 200 Activity. Errors: the envelope.
Python
jusa.Activity.retrieve("act_…")
Node
await jusa.activities.retrieve('act_…');
PHP
$jusa->activities->retrieve('act_…');
Go
_, err := jusaClient.Activities.Retrieve(ctx, "act_…", nil)
if err != nil {
return err
}
Java
jusa.activities().retrieve("act_…");
C#
await jusa.Activities.RetrieveAsync("act_…");
Dart
await jusa.activities.retrieve('act_…');
Ruby
Jusa::Activity.retrieve("act_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/activities/act_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
List check-ins
Scope: rewards:read. Publishable keys may call it (from a browser).
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
status | query | Only objects in this status. |
Returns: 200 CheckinList. Errors: the envelope.
Python
jusa.Checkin.list()
Node
await jusa.checkins.list();
PHP
$jusa->checkins->list();
Go
_, err := jusaClient.Checkins.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.checkins().list();
C#
await jusa.Checkins.ListAsync();
Dart
await jusa.checkins.list();
Ruby
Jusa::Checkin.list
curl
curl https://jusa.localhost.co.zw/dev/v1/checkins \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Check in to claim a geofenced link
Publishable keys may call it from the browser. Publishable keys may call it (from a browser).
| Body (CheckinCreate) | Type | About |
|---|---|---|
link required | string | |
lat required | number or string | |
lng required | number or string | |
accuracy_m | number or string | |
attestation | string | |
phone required | string | A Zimbabwean mobile: 07XXXXXXXX, 2637XXXXXXXX or +2637XXXXXXXX. |
choice | "airtime" | "data" | "zesa" | |
meter | string | An 11-digit ZESA prepaid meter number. |
bundle_id | string | |
code | string | |
challenge_token | string | |
challenge_answer | string |
Returns: 201 Checkin. Errors: the envelope.
Python
jusa.Checkin.create(link="string", lat=1, lng=1, phone="0772123456")
Node
await jusa.checkins.create({ link: 'string', lat: 1, lng: 1, phone: '0772123456' });
PHP
$jusa->checkins->create([
'link' => 'string',
'lat' => 1,
'lng' => 1,
'phone' => '0772123456',
]);
Go
_, err := jusaClient.Checkins.Create(ctx, jusa.Params{
"link": "string",
"lat": 1,
"lng": 1,
"phone": "0772123456",
})
if err != nil {
return err
}
Java
jusa.checkins().create(Params.of(
"link", "string",
"lat", 1,
"lng", 1,
"phone", "0772123456"
));
C#
await jusa.Checkins.CreateAsync(new
{
link = "string",
lat = 1,
lng = 1,
phone = "0772123456",
});
Dart
await jusa.checkins.create({
'link': 'string',
'lat': 1,
'lng': 1,
'phone': '0772123456',
});
Ruby
Jusa::Checkin.create(link: "string", lat: 1, lng: 1, phone: "0772123456")
curl
curl https://jusa.localhost.co.zw/dev/v1/checkins \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"link": "string", "lat": 1, "lng": 1, "phone": "0772123456"}'
List a program's rules
Scope: rewards:read.
| Parameter | In | About |
|---|---|---|
program_id required | path | prg_… |
active | query | Active or not. |
Returns: 200 ProgramRuleList. Errors: the envelope.
Python
jusa.Program.list_rules("prg_…")
Node
await jusa.programs.listRules('prg_…');
PHP
$jusa->programs->listRules('prg_…');
Go
_, err := jusaClient.Programs.ListRules(ctx, "prg_…", nil)
if err != nil {
return err
}
Java
jusa.programs().listRules("prg_…");
C#
await jusa.Programs.ListRulesAsync("prg_…");
Dart
await jusa.programs.listRules('prg_…');
Ruby
Jusa::Program.list_rules("prg_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/programs/prg_…/rules \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Set a program's rules
The whole set: rules left out are switched off. lottery and prize_draw are refused. Scope: programs:manage.
| Parameter | In | About |
|---|---|---|
program_id required | path | prg_… |
| Body (ProgramRules) | Type | About |
|---|---|---|
rules required | array of object |
Returns: 200 ProgramRuleList. Errors: the envelope.
Python
jusa.Program.set_rules("prg_…", rules=[])
Node
await jusa.programs.setRules('prg_…', { rules: [] });
PHP
$jusa->programs->setRules('prg_…', ['rules' => []]);
Go
_, err := jusaClient.Programs.SetRules(ctx, "prg_…", jusa.Params{"rules": []any{}})
if err != nil {
return err
}
Java
jusa.programs().setRules("prg_…", Params.of("rules", List.of()));
C#
await jusa.Programs.SetRulesAsync("prg_…", new { rules = new object[] { } });
Dart
await jusa.programs.setRules('prg_…', {'rules': []});
Ruby
Jusa::Program.set_rules("prg_…", rules: [])
curl
curl -X PUT https://jusa.localhost.co.zw/dev/v1/programs/prg_…/rules \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"rules": []}'
List referrals
Scope: rewards:read.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
status | query | Only objects in this status. |
program | query | prg_… |
metadata[key] | query | metadata[<key>]=<value>: an exact match on one key. |
Returns: 200 ReferralList. Errors: the envelope.
Python
jusa.Referral.list()
Node
await jusa.referrals.list();
PHP
$jusa->referrals->list();
Go
_, err := jusaClient.Referrals.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.referrals().list();
C#
await jusa.Referrals.ListAsync();
Dart
await jusa.referrals.list();
Ruby
Jusa::Referral.list
curl
curl https://jusa.localhost.co.zw/dev/v1/referrals \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Record a referral
Scope: rewards:write.
| Body (ReferralCreate) | Type | About |
|---|---|---|
program required | string | |
referrer required | string or object | rcp_… or ext:<external_id>. |
referee required | string or object | rcp_… or ext:<external_id>. |
metadata | object | Up to 20 keys (letters, digits, _ . -, up to 40 characters) with values up to 500 characters. |
Returns: 200 Referral · 201 Referral. Errors: the envelope.
Python
jusa.Referral.create(program="string", referrer="string", referee="string")
Node
await jusa.referrals.create({
program: 'string',
referrer: 'string',
referee: 'string',
});
PHP
$jusa->referrals->create([
'program' => 'string',
'referrer' => 'string',
'referee' => 'string',
]);
Go
_, err := jusaClient.Referrals.Create(ctx, jusa.Params{
"program": "string",
"referrer": "string",
"referee": "string",
})
if err != nil {
return err
}
Java
jusa.referrals().create(Params.of(
"program", "string",
"referrer", "string",
"referee", "string"
));
C#
await jusa.Referrals.CreateAsync(new
{
program = "string",
referrer = "string",
referee = "string",
});
Dart
await jusa.referrals.create({
'program': 'string',
'referrer': 'string',
'referee': 'string',
});
Ruby
Jusa::Referral.create(program: "string", referrer: "string", referee: "string")
curl
curl https://jusa.localhost.co.zw/dev/v1/referrals \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"program": "string", "referrer": "string", "referee": "string"}'
Retrieve a referral
Scope: rewards:read.
| Parameter | In | About |
|---|---|---|
referral_id required | path | ref_… |
Returns: 200 Referral. Errors: the envelope.
Python
jusa.Referral.retrieve("ref_…")
Node
await jusa.referrals.retrieve('ref_…');
PHP
$jusa->referrals->retrieve('ref_…');
Go
_, err := jusaClient.Referrals.Retrieve(ctx, "ref_…", nil)
if err != nil {
return err
}
Java
jusa.referrals().retrieve("ref_…");
C#
await jusa.Referrals.RetrieveAsync("ref_…");
Dart
await jusa.referrals.retrieve('ref_…');
Ruby
Jusa::Referral.retrieve("ref_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/referrals/ref_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Qualify a referral
Pays the direct referrer (depth 1), in escrow by default. Scope: rewards:write. Moves money: an Idempotency-Key is required.
| Parameter | In | About |
|---|---|---|
referral_id required | path | ref_… |
Returns: 200 Referral. Errors: the envelope.
Python
jusa.Referral.qualify("ref_…", idempotency_key="qualify-signup-8812")
Node
await jusa.referrals.qualify('ref_…', {}, { idempotencyKey: 'qualify-signup-8812' });
PHP
$jusa->referrals->qualify('ref_…', [], ['idempotency_key' => 'qualify-signup-8812']);
Go
_, err := jusaClient.Referrals.Qualify(ctx, "ref_…", nil, jusa.WithIdempotencyKey("qualify-signup-8812"))
if err != nil {
return err
}
Java
jusa.referrals().qualify("ref_…", RequestOptions.idempotencyKey("qualify-signup-8812"));
C#
await jusa.Referrals.QualifyAsync("ref_…", options: new RequestOptions { IdempotencyKey = "qualify-signup-8812" });
Dart
await jusa.referrals.qualify('ref_…', {}, RequestOptions(idempotencyKey: 'qualify-signup-8812'));
Ruby
Jusa::Referral.qualify("ref_…", {}, idempotency_key: "qualify-signup-8812")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/referrals/ref_…/qualify \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Idempotency-Key: qualify-signup-8812"
Claims
What a publishable key may do with a reward link.
Read a reward link by its token
For publishable keys (the widget). Publishable keys may call it (from a browser).
| Parameter | In | About |
|---|---|---|
token required | path | The link's token. |
Returns: 200 RewardLinkClaim. Errors: the envelope.
Python
jusa.Claim.retrieve("lnk_tok_…")
Node
await jusa.claims.retrieve('lnk_tok_…');
PHP
$jusa->claims->retrieve('lnk_tok_…');
Go
_, err := jusaClient.Claims.Retrieve(ctx, "lnk_tok_…", nil)
if err != nil {
return err
}
Java
jusa.claims().retrieve("lnk_tok_…");
C#
await jusa.Claims.RetrieveAsync("lnk_tok_…");
Dart
await jusa.claims.retrieve('lnk_tok_…');
Ruby
Jusa::Claim.retrieve("lnk_tok_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/claims/lnk_tok_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Claim a reward link
Publishable keys may call it (from a browser).
| Parameter | In | About |
|---|---|---|
token required | path | The link's token. |
| Body (Claim) | Type | About |
|---|---|---|
phone required | string | A Zimbabwean mobile: 07XXXXXXXX, 2637XXXXXXXX or +2637XXXXXXXX. |
choice | "airtime" | "data" | "zesa" | |
meter | string | An 11-digit ZESA prepaid meter number. |
bundle_id | string | |
code | string | |
challenge_token | string | |
challenge_answer | string |
Returns: 200 RewardLinkClaim · 201 RewardLinkClaim. Errors: the envelope.
Python
jusa.Claim.create("lnk_tok_…", phone="0772123456")
Node
await jusa.claims.create('lnk_tok_…', { phone: '0772123456' });
PHP
$jusa->claims->create('lnk_tok_…', ['phone' => '0772123456']);
Go
_, err := jusaClient.Claims.Create(ctx, "lnk_tok_…", jusa.Params{"phone": "0772123456"})
if err != nil {
return err
}
Java
jusa.claims().create("lnk_tok_…", Params.of("phone", "0772123456"));
C#
await jusa.Claims.CreateAsync("lnk_tok_…", new { phone = "0772123456" });
Dart
await jusa.claims.create('lnk_tok_…', {'phone': '0772123456'});
Ruby
Jusa::Claim.create("lnk_tok_…", phone: "0772123456")
curl
curl https://jusa.localhost.co.zw/dev/v1/claims/lnk_tok_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"phone": "0772123456"}'
Text the claim code (OTP-bound links)
Publishable keys may call it (from a browser).
| Parameter | In | About |
|---|---|---|
token required | path | The link's token. |
| Body (ClaimCodeRequest) | Type | About |
|---|---|---|
phone required | string | A Zimbabwean mobile: 07XXXXXXXX, 2637XXXXXXXX or +2637XXXXXXXX. |
challenge_token | string | |
challenge_answer | string |
Returns: 200 ClaimCode. Errors: the envelope.
Python
jusa.Claim.send_code("lnk_tok_…", phone="0772123456")
Node
await jusa.claims.sendCode('lnk_tok_…', { phone: '0772123456' });
PHP
$jusa->claims->sendCode('lnk_tok_…', ['phone' => '0772123456']);
Go
_, err := jusaClient.Claims.SendCode(ctx, "lnk_tok_…", jusa.Params{
"phone": "0772123456",
})
if err != nil {
return err
}
Java
jusa.claims().sendCode("lnk_tok_…", Params.of("phone", "0772123456"));
C#
await jusa.Claims.SendCodeAsync("lnk_tok_…", new { phone = "0772123456" });
Dart
await jusa.claims.sendCode('lnk_tok_…', {'phone': '0772123456'});
Ruby
Jusa::Claim.send_code("lnk_tok_…", phone: "0772123456")
curl
curl https://jusa.localhost.co.zw/dev/v1/claims/lnk_tok_…/code \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"phone": "0772123456"}'
Agent approvals
An agent key's request waiting for a person.
List agent approvals
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
status | query | Only objects in this status. |
action | query | Only this action (send or reward; for the audit log, e.g. api_key.created). |
Returns: 200 AgentApprovalList. Errors: the envelope.
Python
jusa.Approval.list()
Node
await jusa.approvals.list();
PHP
$jusa->approvals->list();
Go
_, err := jusaClient.Approvals.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.approvals().list();
C#
await jusa.Approvals.ListAsync();
Dart
await jusa.approvals.list();
Ruby
Jusa::Approval.list
curl
curl https://jusa.localhost.co.zw/dev/v1/approvals \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Retrieve an agent approval
| Parameter | In | About |
|---|---|---|
approval_id required | path | apr_… |
Returns: 200 AgentApproval. Errors: the envelope.
Python
jusa.Approval.retrieve("apr_…")
Node
await jusa.approvals.retrieve('apr_…');
PHP
$jusa->approvals->retrieve('apr_…');
Go
_, err := jusaClient.Approvals.Retrieve(ctx, "apr_…", nil)
if err != nil {
return err
}
Java
jusa.approvals().retrieve("apr_…");
C#
await jusa.Approvals.RetrieveAsync("apr_…");
Dart
await jusa.approvals.retrieve('apr_…');
Ruby
Jusa::Approval.retrieve("apr_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/approvals/apr_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Approve an agent's request
Dashboard only: an owner or admin, with their payment PIN.
| Parameter | In | About |
|---|---|---|
approval_id required | path | apr_… |
| Body (ApprovalDecision) | Type | About |
|---|---|---|
pin | string | Your payment PIN (dashboard only). |
Returns: 200 AgentApproval. Errors: the envelope.
Python
jusa.Approval.approve("apr_…")
Node
await jusa.approvals.approve('apr_…');
PHP
$jusa->approvals->approve('apr_…');
Go
_, err := jusaClient.Approvals.Approve(ctx, "apr_…", nil)
if err != nil {
return err
}
Java
jusa.approvals().approve("apr_…");
C#
await jusa.Approvals.ApproveAsync("apr_…");
Dart
await jusa.approvals.approve('apr_…');
Ruby
Jusa::Approval.approve("apr_…")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/approvals/apr_…/approve \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Reject an agent's request
Dashboard only.
| Parameter | In | About |
|---|---|---|
approval_id required | path | apr_… |
Returns: 200 AgentApproval. Errors: the envelope.
Python
jusa.Approval.reject("apr_…")
Node
await jusa.approvals.reject('apr_…');
PHP
$jusa->approvals->reject('apr_…');
Go
_, err := jusaClient.Approvals.Reject(ctx, "apr_…", nil)
if err != nil {
return err
}
Java
jusa.approvals().reject("apr_…");
C#
await jusa.Approvals.RejectAsync("apr_…");
Dart
await jusa.approvals.reject('apr_…');
Ruby
Jusa::Approval.reject("apr_…")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/approvals/apr_…/reject \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
MCP
The Model Context Protocol server for AI agents.
The MCP server (JSON-RPC 2.0)
Agent keys only. Tools: send_airtime, buy_zesa, confirm_meter, create_reward, get_balance, get_send, list_products. 202 with no body answers a notification; a message that is not JSON-RPC is a JSON-RPC error with status 400.
Returns: 200 JsonRpcResponse · 202 no body · 400 JsonRpcResponse. Errors: the envelope.
Python
jusa.MCP.call()
Node
await jusa.mcp.call();
PHP
$jusa->mcp->call();
Go
_, err := jusaClient.MCP.Call(ctx, nil)
if err != nil {
return err
}
Java
jusa.mcp().call();
C#
await jusa.Mcp.CallAsync();
Dart
await jusa.mcp.call();
Ruby
Jusa::MCP.call
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/mcp \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Jusa Credit
Your prepaid balance: transactions, top-ups, statements.
Jusa Credit balances
Scope: credit:read.
Returns: 200 Credit. Errors: the envelope.
Python
jusa.Credit.retrieve()
Node
await jusa.credit.retrieve();
PHP
$jusa->credit->retrieve();
Go
_, err := jusaClient.Credit.Retrieve(ctx, nil)
if err != nil {
return err
}
Java
jusa.credit().retrieve();
C#
await jusa.Credit.RetrieveAsync();
Dart
await jusa.credit.retrieve();
Ruby
Jusa::Credit.retrieve
curl
curl https://jusa.localhost.co.zw/dev/v1/credit \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Low-balance and shortfall alerts
Scope: credit:read.
Returns: 200 CreditAlerts. Errors: the envelope.
Python
jusa.Credit.retrieve_alerts()
Node
await jusa.credit.retrieveAlerts();
PHP
$jusa->credit->retrieveAlerts();
Go
_, err := jusaClient.Credit.RetrieveAlerts(ctx, nil)
if err != nil {
return err
}
Java
jusa.credit().retrieveAlerts();
C#
await jusa.Credit.RetrieveAlertsAsync();
Dart
await jusa.credit.retrieveAlerts();
Ruby
Jusa::Credit.retrieve_alerts
curl
curl https://jusa.localhost.co.zw/dev/v1/credit/alerts \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Set the alerts
Scope: account:manage.
| Body (CreditAlertsUpdate) | Type | About |
|---|---|---|
low_balance | object | |
shortfall_projection | boolean | |
shortfall_days | integer | |
channels | array of "webhook" | "email" | "sms" |
Returns: 200 CreditAlerts. Errors: the envelope.
Python
jusa.Credit.update_alerts()
Node
await jusa.credit.updateAlerts();
PHP
$jusa->credit->updateAlerts();
Go
_, err := jusaClient.Credit.UpdateAlerts(ctx, nil)
if err != nil {
return err
}
Java
jusa.credit().updateAlerts();
C#
await jusa.Credit.UpdateAlertsAsync();
Dart
await jusa.credit.updateAlerts();
Ruby
Jusa::Credit.update_alerts
curl
curl -X PUT https://jusa.localhost.co.zw/dev/v1/credit/alerts \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
List credit set aside
Scope: credit:read.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
status | query | Only objects in this status. |
currency | query | Only this currency. |
Returns: 200 CreditReservationList. Errors: the envelope.
Python
jusa.Credit.list_reservations()
Node
await jusa.credit.listReservations();
PHP
$jusa->credit->listReservations();
Go
_, err := jusaClient.Credit.ListReservations(ctx, nil)
if err != nil {
return err
}
Java
jusa.credit().listReservations();
C#
await jusa.Credit.ListReservationsAsync();
Dart
await jusa.credit.listReservations();
Ruby
Jusa::Credit.list_reservations
curl
curl https://jusa.localhost.co.zw/dev/v1/credit/reservations \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
List top-ups
Scope: credit:read.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
method | query | GET, POST, … |
status | query | Only objects in this status. |
Returns: 200 TopupList. Errors: the envelope.
Python
jusa.Credit.list_topups()
Node
await jusa.credit.listTopups();
PHP
$jusa->credit->listTopups();
Go
_, err := jusaClient.Credit.ListTopups(ctx, nil)
if err != nil {
return err
}
Java
jusa.credit().listTopups();
C#
await jusa.Credit.ListTopupsAsync();
Dart
await jusa.credit.listTopups();
Ruby
Jusa::Credit.list_topups
curl
curl https://jusa.localhost.co.zw/dev/v1/credit/topups \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Top up Jusa Credit
pesepay: send a person to redirect_url; the card fee is paid by the payer. bank_transfer: our bank details and a reference to quote. cash: dealers only, live (400 method_not_available otherwise; test mode lets anyone see the shape): Jusa staff collect it at address, and the credit posts for the amount they counted when they confirm it. Any amount; spendable once paid. Scope: credit:topup. Moves money: an Idempotency-Key is required.
| Body (TopupCreate) | Type | About |
|---|---|---|
method | "pesepay" | "bank_transfer" | "cash" | |
amount required | string or number | A decimal amount, e.g. "5.00". |
currency | "USD" | "ZWG" | "usd" | "zwg" | USD or ZWG (either case). |
description | string | |
address | string | cash: where Jusa staff collect it. |
contact_phone | string | cash: who staff call on the day. |
window | string | cash: when you would like them to come, e.g. "Tue 10-12". |
Returns: 201 Topup. Errors: the envelope.
Python
jusa.Credit.create_topup(
method="pesepay",
amount="100.00",
currency="USD",
idempotency_key="topup-invoice-2026-10",
)
Node
await jusa.credit.createTopup({
method: 'pesepay',
amount: '100.00',
currency: 'USD',
}, { idempotencyKey: 'topup-invoice-2026-10' });
PHP
$jusa->credit->createTopup([
'method' => 'pesepay',
'amount' => '100.00',
'currency' => 'USD',
], ['idempotency_key' => 'topup-invoice-2026-10']);
Go
_, err := jusaClient.Credit.CreateTopup(ctx, jusa.Params{
"method": "pesepay",
"amount": "100.00",
"currency": "USD",
}, jusa.WithIdempotencyKey("topup-invoice-2026-10"))
if err != nil {
return err
}
Java
jusa.credit().createTopup(Params.of(
"method", "pesepay",
"amount", "100.00",
"currency", "USD"
), RequestOptions.idempotencyKey("topup-invoice-2026-10"));
C#
await jusa.Credit.CreateTopupAsync(new
{
method = "pesepay",
amount = "100.00",
currency = "USD",
}, new RequestOptions { IdempotencyKey = "topup-invoice-2026-10" });
Dart
await jusa.credit.createTopup({
'method': 'pesepay',
'amount': '100.00',
'currency': 'USD',
}, RequestOptions(idempotencyKey: 'topup-invoice-2026-10'));
Ruby
Jusa::Credit.create_topup({
method: "pesepay",
amount: "100.00",
currency: "USD",
}, idempotency_key: "topup-invoice-2026-10")
curl
curl https://jusa.localhost.co.zw/dev/v1/credit/topups \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Idempotency-Key: topup-invoice-2026-10" \
-H "Content-Type: application/json" \
-d '{"method": "pesepay", "amount": "100.00", "currency": "USD"}'
Retrieve a top-up
Scope: credit:read.
| Parameter | In | About |
|---|---|---|
topup_id required | path | top_… |
Returns: 200 Topup. Errors: the envelope.
Python
jusa.Credit.retrieve_topup("top_…")
Node
await jusa.credit.retrieveTopup('top_…');
PHP
$jusa->credit->retrieveTopup('top_…');
Go
_, err := jusaClient.Credit.RetrieveTopup(ctx, "top_…", nil)
if err != nil {
return err
}
Java
jusa.credit().retrieveTopup("top_…");
C#
await jusa.Credit.RetrieveTopupAsync("top_…");
Dart
await jusa.credit.retrieveTopup('top_…');
Ruby
Jusa::Credit.retrieve_topup("top_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/credit/topups/top_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
List Jusa Credit transactions
Scope: credit:read.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
currency | query | Only this currency. |
type | query | Only this type. |
source | query | What it came from: snd_, top_, rwd_, bch_ or rsv_. |
Returns: 200 CreditTransactionList. Errors: the envelope.
Python
jusa.Credit.list_transactions()
Node
await jusa.credit.listTransactions();
PHP
$jusa->credit->listTransactions();
Go
_, err := jusaClient.Credit.ListTransactions(ctx, nil)
if err != nil {
return err
}
Java
jusa.credit().listTransactions();
C#
await jusa.Credit.ListTransactionsAsync();
Dart
await jusa.credit.listTransactions();
Ruby
Jusa::Credit.list_transactions
curl
curl https://jusa.localhost.co.zw/dev/v1/credit/transactions \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Retrieve a transaction
Scope: credit:read.
| Parameter | In | About |
|---|---|---|
transaction_id required | path | txn_… |
Returns: 200 CreditTransaction. Errors: the envelope.
Python
jusa.Credit.retrieve_transaction("txn_…")
Node
await jusa.credit.retrieveTransaction('txn_…');
PHP
$jusa->credit->retrieveTransaction('txn_…');
Go
_, err := jusaClient.Credit.RetrieveTransaction(ctx, "txn_…", nil)
if err != nil {
return err
}
Java
jusa.credit().retrieveTransaction("txn_…");
C#
await jusa.Credit.RetrieveTransactionAsync("txn_…");
Dart
await jusa.credit.retrieveTransaction('txn_…');
Ruby
Jusa::Credit.retrieve_transaction("txn_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/credit/transactions/txn_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
A monthly statement
Scope: credit:read.
| Parameter | In | About |
|---|---|---|
period | query | YYYY-MM; this month by default. |
currency | query | Only this currency. |
Returns: 200 Statement. Errors: the envelope.
Python
jusa.Statement.retrieve()
Node
await jusa.statements.retrieve();
PHP
$jusa->statements->retrieve();
Go
_, err := jusaClient.Statements.Retrieve(ctx, nil)
if err != nil {
return err
}
Java
jusa.statements().retrieve();
C#
await jusa.Statements.RetrieveAsync();
Dart
await jusa.statements.retrieve();
Ruby
Jusa::Statement.retrieve
curl
curl https://jusa.localhost.co.zw/dev/v1/statements \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
A monthly statement as CSV
Scope: credit:read.
| Parameter | In | About |
|---|---|---|
period | query | YYYY-MM; this month by default. |
currency | query | Only this currency. |
Returns: 200 CSV. Errors: the envelope.
Python
jusa.Statement.csv()
Node
await jusa.statements.csv();
PHP
$jusa->statements->csv();
Go
_, err := jusaClient.Statements.CSV(ctx, nil)
if err != nil {
return err
}
Java
jusa.statements().csv();
C#
await jusa.Statements.CsvAsync();
Dart
await jusa.statements.csv();
Ruby
Jusa::Statement.csv
curl
curl https://jusa.localhost.co.zw/dev/v1/statements.csv \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
A monthly statement as PDF
A dealer's prints its dealer lines (face value sold, credit drawn, discount earned). Scope: credit:read.
| Parameter | In | About |
|---|---|---|
period | query | YYYY-MM; this month by default. |
currency | query | Only this currency. |
Returns: 200 no body. Errors: the envelope.
Python
jusa.Statement.pdf()
Node
await jusa.statements.pdf();
PHP
$jusa->statements->pdf();
Go
_, err := jusaClient.Statements.PDF(ctx, nil)
if err != nil {
return err
}
Java
jusa.statements().pdf();
C#
await jusa.Statements.PdfAsync();
Dart
await jusa.statements.pdf();
Ruby
Jusa::Statement.pdf
curl
curl https://jusa.localhost.co.zw/dev/v1/statements.pdf \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Dealer
The dealer tier: a verified business buys at a discount off face and tops up in cash.
Your dealer application
The application that stands: the one under review, else the latest decided. 404 resource_missing when you never applied. A test key reads the live organisation's.
Returns: 200 DealerApplication. Errors: the envelope.
Python
jusa.Dealer.retrieve_application()
Node
await jusa.dealer.retrieveApplication();
PHP
$jusa->dealer->retrieveApplication();
Go
_, err := jusaClient.Dealer.RetrieveApplication(ctx, nil)
if err != nil {
return err
}
Java
jusa.dealer().retrieveApplication();
C#
await jusa.Dealer.RetrieveApplicationAsync();
Dart
await jusa.dealer.retrieveApplication();
Ruby
Jusa::Dealer.retrieve_application
curl
curl https://jusa.localhost.co.zw/dev/v1/dealer/application \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Apply for the dealer tier
The live organisation applies (a test key gets 409 sandbox_cannot_apply; an agent key cannot). One application under review at a time (409 dealer_application_open); a dealer does not apply again (409 already_dealer). Attach documents next, then staff review it; the decision fires dealer.application.decided and shows on GET /account. Scope: account:manage.
| Body (DealerApplicationCreate) | Type | About |
|---|---|---|
company_name required | string | |
registration_number required | string | |
tax_number | string | |
contact_name required | string | |
contact_phone required | string | |
address required | string | |
notes | string | Anything staff should know. |
Returns: 201 DealerApplication. Errors: the envelope.
Python
jusa.Dealer.apply(
company_name="Acme Trading (Pvt) Ltd",
registration_number="1234/2020",
contact_name="Tendai Moyo",
contact_phone="+263771234567",
address="12 Samora Machel Ave, Harare",
)
Node
await jusa.dealer.apply({
company_name: 'Acme Trading (Pvt) Ltd',
registration_number: '1234/2020',
contact_name: 'Tendai Moyo',
contact_phone: '+263771234567',
address: '12 Samora Machel Ave, Harare',
});
PHP
$jusa->dealer->apply([
'company_name' => 'Acme Trading (Pvt) Ltd',
'registration_number' => '1234/2020',
'contact_name' => 'Tendai Moyo',
'contact_phone' => '+263771234567',
'address' => '12 Samora Machel Ave, Harare',
]);
Go
_, err := jusaClient.Dealer.Apply(ctx, jusa.Params{
"company_name": "Acme Trading (Pvt) Ltd",
"registration_number": "1234/2020",
"contact_name": "Tendai Moyo",
"contact_phone": "+263771234567",
"address": "12 Samora Machel Ave, Harare",
})
if err != nil {
return err
}
Java
jusa.dealer().apply(Params.of(
"company_name", "Acme Trading (Pvt) Ltd",
"registration_number", "1234/2020",
"contact_name", "Tendai Moyo",
"contact_phone", "+263771234567",
"address", "12 Samora Machel Ave, Harare"
));
C#
await jusa.Dealer.ApplyAsync(new
{
company_name = "Acme Trading (Pvt) Ltd",
registration_number = "1234/2020",
contact_name = "Tendai Moyo",
contact_phone = "+263771234567",
address = "12 Samora Machel Ave, Harare",
});
Dart
await jusa.dealer.apply({
'company_name': 'Acme Trading (Pvt) Ltd',
'registration_number': '1234/2020',
'contact_name': 'Tendai Moyo',
'contact_phone': '+263771234567',
'address': '12 Samora Machel Ave, Harare',
});
Ruby
Jusa::Dealer.apply(
company_name: "Acme Trading (Pvt) Ltd",
registration_number: "1234/2020",
contact_name: "Tendai Moyo",
contact_phone: "+263771234567",
address: "12 Samora Machel Ave, Harare",
)
curl
curl https://jusa.localhost.co.zw/dev/v1/dealer/application \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"company_name": "Acme Trading (Pvt) Ltd",
"registration_number": "1234/2020",
"contact_name": "Tendai Moyo",
"contact_phone": "+263771234567",
"address": "12 Samora Machel Ave, Harare"
}'
Attach a document
multipart/form-data with kind and file (a PDF, JPEG or PNG up to 10 MB), onto the application under review. Answers with the application and its documents. Scope: account:manage.
Returns: 201 DealerApplication. Errors: the envelope.
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/dealer/application/documents \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Download a document
The file back, to the organisation that uploaded it (and Jusa staff). Its url is on the application.
| Parameter | In | About |
|---|---|---|
document_id required | path | The number at the end of a document's url on the dealer application. |
Returns: 200 no body. Errors: the envelope.
curl
curl https://jusa.localhost.co.zw/dev/v1/dealer/application/documents/document_id \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Withdraw the application
Only one under review moves (409 dealer_application_not_open otherwise). You may apply again. Scope: account:manage.
Returns: 200 DealerApplication. Errors: the envelope.
Python
jusa.Dealer.withdraw_application()
Node
await jusa.dealer.withdrawApplication();
PHP
$jusa->dealer->withdrawApplication();
Go
_, err := jusaClient.Dealer.WithdrawApplication(ctx, nil)
if err != nil {
return err
}
Java
jusa.dealer().withdrawApplication();
C#
await jusa.Dealer.WithdrawApplicationAsync();
Dart
await jusa.dealer.withdrawApplication();
Ruby
Jusa::Dealer.withdraw_application
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/dealer/application/withdraw \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Checkout
Your user pays by card; you get the attribution.
List checkout sessions
Scope: sends:read.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
status | query | Only objects in this status. |
client_reference | query | Your own reference. |
metadata[key] | query | metadata[<key>]=<value>: an exact match on one key. |
Returns: 200 CheckoutSessionList. Errors: the envelope.
Python
jusa.CheckoutSession.list()
Node
await jusa.checkoutSessions.list();
PHP
$jusa->checkoutSessions->list();
Go
_, err := jusaClient.CheckoutSessions.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.checkoutSessions().list();
C#
await jusa.CheckoutSessions.ListAsync();
Dart
await jusa.checkoutSessions.list();
Ruby
Jusa::CheckoutSession.list
curl
curl https://jusa.localhost.co.zw/dev/v1/checkout-sessions \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Create a checkout session
Your user pays by card on Pesepay (Jusa is the merchant of record and the card fee is the payer's); the send is booked to you. A repeated client_reference returns the first session (200). Scope: sends:write. Moves money: an Idempotency-Key is required.
| Body (CheckoutSessionCreate) | Type | About |
|---|---|---|
type | "airtime" | "data" | "zesa" | |
product | string | |
target required | string | |
amount required | string or number | A decimal amount, e.g. "5.00". |
currency | "USD" | "ZWG" | "usd" | "zwg" | USD or ZWG (either case). |
bundle_id | string | |
token_phone | string | A Zimbabwean mobile: 07XXXXXXXX, 2637XXXXXXXX or +2637XXXXXXXX. |
customer_phone | string | A Zimbabwean mobile: 07XXXXXXXX, 2637XXXXXXXX or +2637XXXXXXXX. |
success_url required | string | |
cancel_url required | string | |
client_reference | string | |
metadata | object | Up to 20 keys (letters, digits, _ . -, up to 40 characters) with values up to 500 characters. |
sms_message | string |
Returns: 200 CheckoutSession · 201 CheckoutSession. Errors: the envelope.
Python
jusa.CheckoutSession.create(
type="zesa",
target="37261502217",
amount="20.00",
currency="USD",
token_phone="0772123456",
success_url="https://example.com/thanks",
cancel_url="https://example.com/basket",
idempotency_key="checkout-order-8812",
)
Node
await jusa.checkoutSessions.create({
type: 'zesa',
target: '37261502217',
amount: '20.00',
currency: 'USD',
token_phone: '0772123456',
success_url: 'https://example.com/thanks',
cancel_url: 'https://example.com/basket',
}, { idempotencyKey: 'checkout-order-8812' });
PHP
$jusa->checkoutSessions->create([
'type' => 'zesa',
'target' => '37261502217',
'amount' => '20.00',
'currency' => 'USD',
'token_phone' => '0772123456',
'success_url' => 'https://example.com/thanks',
'cancel_url' => 'https://example.com/basket',
], ['idempotency_key' => 'checkout-order-8812']);
Go
_, err := jusaClient.CheckoutSessions.Create(ctx, jusa.Params{
"type": "zesa",
"target": "37261502217",
"amount": "20.00",
"currency": "USD",
"token_phone": "0772123456",
"success_url": "https://example.com/thanks",
"cancel_url": "https://example.com/basket",
}, jusa.WithIdempotencyKey("checkout-order-8812"))
if err != nil {
return err
}
Java
jusa.checkoutSessions().create(Params.of(
"type", "zesa",
"target", "37261502217",
"amount", "20.00",
"currency", "USD",
"token_phone", "0772123456",
"success_url", "https://example.com/thanks",
"cancel_url", "https://example.com/basket"
), RequestOptions.idempotencyKey("checkout-order-8812"));
C#
await jusa.CheckoutSessions.CreateAsync(new
{
type = "zesa",
target = "37261502217",
amount = "20.00",
currency = "USD",
token_phone = "0772123456",
success_url = "https://example.com/thanks",
cancel_url = "https://example.com/basket",
}, new RequestOptions { IdempotencyKey = "checkout-order-8812" });
Dart
await jusa.checkoutSessions.create({
'type': 'zesa',
'target': '37261502217',
'amount': '20.00',
'currency': 'USD',
'token_phone': '0772123456',
'success_url': 'https://example.com/thanks',
'cancel_url': 'https://example.com/basket',
}, RequestOptions(idempotencyKey: 'checkout-order-8812'));
Ruby
Jusa::CheckoutSession.create({
type: "zesa",
target: "37261502217",
amount: "20.00",
currency: "USD",
token_phone: "0772123456",
success_url: "https://example.com/thanks",
cancel_url: "https://example.com/basket",
}, idempotency_key: "checkout-order-8812")
curl
curl https://jusa.localhost.co.zw/dev/v1/checkout-sessions \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Idempotency-Key: checkout-order-8812" \
-H "Content-Type: application/json" \
-d '{
"type": "zesa",
"target": "37261502217",
"amount": "20.00",
"currency": "USD",
"token_phone": "0772123456",
"success_url": "https://example.com/thanks",
"cancel_url": "https://example.com/basket"
}'
Retrieve a checkout session
Scope: sends:read.
| Parameter | In | About |
|---|---|---|
session_id required | path | cs_… |
Returns: 200 CheckoutSession. Errors: the envelope.
Python
jusa.CheckoutSession.retrieve("cs_…")
Node
await jusa.checkoutSessions.retrieve('cs_…');
PHP
$jusa->checkoutSessions->retrieve('cs_…');
Go
_, err := jusaClient.CheckoutSessions.Retrieve(ctx, "cs_…", nil)
if err != nil {
return err
}
Java
jusa.checkoutSessions().retrieve("cs_…");
C#
await jusa.CheckoutSessions.RetrieveAsync("cs_…");
Dart
await jusa.checkoutSessions.retrieve('cs_…');
Ruby
Jusa::CheckoutSession.retrieve("cs_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/checkout-sessions/cs_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Fix the meter while it waits
Scope: sends:write.
| Parameter | In | About |
|---|---|---|
session_id required | path | cs_… |
| Body (CheckoutMeter) | Type | About |
|---|---|---|
meter required | string | An 11-digit ZESA prepaid meter number. |
Returns: 200 CheckoutSession. Errors: the envelope.
Python
jusa.CheckoutSession.update_meter("cs_…", meter="37261502217")
Node
await jusa.checkoutSessions.updateMeter('cs_…', { meter: '37261502217' });
PHP
$jusa->checkoutSessions->updateMeter('cs_…', ['meter' => '37261502217']);
Go
_, err := jusaClient.CheckoutSessions.UpdateMeter(ctx, "cs_…", jusa.Params{
"meter": "37261502217",
})
if err != nil {
return err
}
Java
jusa.checkoutSessions().updateMeter("cs_…", Params.of("meter", "37261502217"));
C#
await jusa.CheckoutSessions.UpdateMeterAsync("cs_…", new { meter = "37261502217" });
Dart
await jusa.checkoutSessions.updateMeter('cs_…', {'meter': '37261502217'});
Ruby
Jusa::CheckoutSession.update_meter("cs_…", meter: "37261502217")
curl
curl https://jusa.localhost.co.zw/dev/v1/checkout-sessions/cs_…/meter \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"meter": "37261502217"}'
Workforce
Employer allocation and GL, as the Jusa app has it.
What this key may do in Workforce
Scope: workforce:admin.
Returns: 200 WorkforceAccess. Errors: the envelope.
Python
jusa.Workforce.access()
Node
await jusa.workforce.access();
PHP
$jusa->workforce->access();
Go
_, err := jusaClient.Workforce.Access(ctx, nil)
if err != nil {
return err
}
Java
jusa.workforce().access();
C#
await jusa.Workforce.AccessAsync();
Dart
await jusa.workforce.access();
Ruby
Jusa::Workforce.access
curl
curl https://jusa.localhost.co.zw/dev/v1/workforce/access \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Allocate airtime or ZESA
Scope: workforce:admin.
| Body (WorkforceAllocate) | Type | About |
|---|---|---|
kind required | "airtime" | "zesa" | |
product_ref | string | |
cost_center_id | integer or string | A numeric id. |
title | string | |
custom_sms | string | |
idempotency_key | string | 8 to 64 of A-Z a-z 0-9 _ -. A repeat returns the send it made; the Idempotency-Key header does the same. |
acknowledge_over_budget | boolean or string | true or false. |
lines required | array of object |
Returns: 200 WorkforceSendResult. Errors: the envelope.
Python
jusa.Workforce.allocate(
kind="airtime",
product_ref="airtime-usd",
cost_center_id=3,
idempotency_key="stipend-2026-10",
lines=[{"recipient_id": 12, "amount": "2.00"}],
)
Node
await jusa.workforce.allocate({
kind: 'airtime',
product_ref: 'airtime-usd',
cost_center_id: 3,
idempotency_key: 'stipend-2026-10',
lines: [{ recipient_id: 12, amount: '2.00' }],
});
PHP
$jusa->workforce->allocate([
'kind' => 'airtime',
'product_ref' => 'airtime-usd',
'cost_center_id' => 3,
'idempotency_key' => 'stipend-2026-10',
'lines' => [['recipient_id' => 12, 'amount' => '2.00']],
]);
Go
_, err := jusaClient.Workforce.Allocate(ctx, jusa.Params{
"kind": "airtime",
"product_ref": "airtime-usd",
"cost_center_id": 3,
"idempotency_key": "stipend-2026-10",
"lines": []jusa.Params{jusa.Params{"recipient_id": 12, "amount": "2.00"}},
})
if err != nil {
return err
}
Java
jusa.workforce().allocate(Params.of(
"kind", "airtime",
"product_ref", "airtime-usd",
"cost_center_id", 3,
"idempotency_key", "stipend-2026-10",
"lines", List.of(Map.of("recipient_id", 12, "amount", "2.00"))
));
C#
await jusa.Workforce.AllocateAsync(new
{
kind = "airtime",
product_ref = "airtime-usd",
cost_center_id = 3,
idempotency_key = "stipend-2026-10",
lines = new object[] { new { recipient_id = 12, amount = "2.00" } },
});
Dart
await jusa.workforce.allocate({
'kind': 'airtime',
'product_ref': 'airtime-usd',
'cost_center_id': 3,
'idempotency_key': 'stipend-2026-10',
'lines': [{'recipient_id': 12, 'amount': '2.00'}],
});
Ruby
Jusa::Workforce.allocate(
kind: "airtime",
product_ref: "airtime-usd",
cost_center_id: 3,
idempotency_key: "stipend-2026-10",
lines: [{ recipient_id: 12, amount: "2.00" }],
)
curl
curl https://jusa.localhost.co.zw/dev/v1/workforce/allocate \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"kind": "airtime",
"product_ref": "airtime-usd",
"cost_center_id": 3,
"idempotency_key": "stipend-2026-10",
"lines": [{"recipient_id": 12, "amount": "2.00"}]
}'
Preview an allocation
Scope: workforce:admin.
| Body (WorkforceAllocate) | Type | About |
|---|---|---|
kind required | "airtime" | "zesa" | |
product_ref | string | |
cost_center_id | integer or string | A numeric id. |
title | string | |
custom_sms | string | |
idempotency_key | string | 8 to 64 of A-Z a-z 0-9 _ -. A repeat returns the send it made; the Idempotency-Key header does the same. |
acknowledge_over_budget | boolean or string | true or false. |
lines required | array of object |
Returns: 200 WorkforcePreview. Errors: the envelope.
Python
jusa.Workforce.preview_allocation(
kind="airtime",
product_ref="airtime-usd",
cost_center_id=3,
idempotency_key="stipend-2026-10",
lines=[{"recipient_id": 12, "amount": "2.00"}],
)
Node
await jusa.workforce.previewAllocation({
kind: 'airtime',
product_ref: 'airtime-usd',
cost_center_id: 3,
idempotency_key: 'stipend-2026-10',
lines: [{ recipient_id: 12, amount: '2.00' }],
});
PHP
$jusa->workforce->previewAllocation([
'kind' => 'airtime',
'product_ref' => 'airtime-usd',
'cost_center_id' => 3,
'idempotency_key' => 'stipend-2026-10',
'lines' => [['recipient_id' => 12, 'amount' => '2.00']],
]);
Go
_, err := jusaClient.Workforce.PreviewAllocation(ctx, jusa.Params{
"kind": "airtime",
"product_ref": "airtime-usd",
"cost_center_id": 3,
"idempotency_key": "stipend-2026-10",
"lines": []jusa.Params{jusa.Params{"recipient_id": 12, "amount": "2.00"}},
})
if err != nil {
return err
}
Java
jusa.workforce().previewAllocation(Params.of(
"kind", "airtime",
"product_ref", "airtime-usd",
"cost_center_id", 3,
"idempotency_key", "stipend-2026-10",
"lines", List.of(Map.of("recipient_id", 12, "amount", "2.00"))
));
C#
await jusa.Workforce.PreviewAllocationAsync(new
{
kind = "airtime",
product_ref = "airtime-usd",
cost_center_id = 3,
idempotency_key = "stipend-2026-10",
lines = new object[] { new { recipient_id = 12, amount = "2.00" } },
});
Dart
await jusa.workforce.previewAllocation({
'kind': 'airtime',
'product_ref': 'airtime-usd',
'cost_center_id': 3,
'idempotency_key': 'stipend-2026-10',
'lines': [{'recipient_id': 12, 'amount': '2.00'}],
});
Ruby
Jusa::Workforce.preview_allocation(
kind: "airtime",
product_ref: "airtime-usd",
cost_center_id: 3,
idempotency_key: "stipend-2026-10",
lines: [{ recipient_id: 12, amount: "2.00" }],
)
curl
curl https://jusa.localhost.co.zw/dev/v1/workforce/allocate/preview \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"kind": "airtime",
"product_ref": "airtime-usd",
"cost_center_id": 3,
"idempotency_key": "stipend-2026-10",
"lines": [{"recipient_id": 12, "amount": "2.00"}]
}'
Past allocations
Scope: workforce:admin.
| Parameter | In | About |
|---|---|---|
from | query | The start (inclusive). |
to | query | The end (inclusive). |
status | query | Only objects in this status. |
cost_center | query | cc_… (Workforce: a department's id, or none for sends booked to none). |
page | query | Workforce pages from 1. |
page_size | query | Workforce rows per page (batches up to 50, the ledger up to 100). |
Returns: 200 WorkforceBatchPage. Errors: the envelope.
Python
jusa.Workforce.list_batches()
Node
await jusa.workforce.listBatches();
PHP
$jusa->workforce->listBatches();
Go
_, err := jusaClient.Workforce.ListBatches(ctx, nil)
if err != nil {
return err
}
Java
jusa.workforce().listBatches();
C#
await jusa.Workforce.ListBatchesAsync();
Dart
await jusa.workforce.listBatches();
Ruby
Jusa::Workforce.list_batches
curl
curl https://jusa.localhost.co.zw/dev/v1/workforce/batches \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
One allocation
Scope: workforce:admin.
| Parameter | In | About |
|---|---|---|
reference required | path | A Workforce batch reference. |
Returns: 200 WorkforceBatch. Errors: the envelope.
Python
jusa.Workforce.retrieve_batch("order-8812")
Node
await jusa.workforce.retrieveBatch('order-8812');
PHP
$jusa->workforce->retrieveBatch('order-8812');
Go
_, err := jusaClient.Workforce.RetrieveBatch(ctx, "order-8812", nil)
if err != nil {
return err
}
Java
jusa.workforce().retrieveBatch("order-8812");
C#
await jusa.Workforce.RetrieveBatchAsync("order-8812");
Dart
await jusa.workforce.retrieveBatch('order-8812');
Ruby
Jusa::Workforce.retrieve_batch("order-8812")
curl
curl https://jusa.localhost.co.zw/dev/v1/workforce/batches/order-8812 \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Resend the failed lines
Scope: workforce:admin.
| Parameter | In | About |
|---|---|---|
reference required | path | A Workforce batch reference. |
| Body (WorkforceResend) | Type | About |
|---|---|---|
item_ids | array of integer or string | Only these lines (default: every line that can go again). |
idempotency_key | string | 8 to 64 of A-Z a-z 0-9 _ -. A repeat returns the send it made; the Idempotency-Key header does the same. |
acknowledge_over_budget | boolean or string | true or false. |
Returns: 200 WorkforceSendResult. Errors: the envelope.
Python
jusa.Workforce.resend("order-8812")
Node
await jusa.workforce.resend('order-8812');
PHP
$jusa->workforce->resend('order-8812');
Go
_, err := jusaClient.Workforce.Resend(ctx, "order-8812", nil)
if err != nil {
return err
}
Java
jusa.workforce().resend("order-8812");
C#
await jusa.Workforce.ResendAsync("order-8812");
Dart
await jusa.workforce.resend('order-8812');
Ruby
Jusa::Workforce.resend("order-8812")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/workforce/batches/order-8812/resend \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Preview resending the failed lines
Scope: workforce:admin.
| Parameter | In | About |
|---|---|---|
reference required | path | A Workforce batch reference. |
| Body (WorkforceResend) | Type | About |
|---|---|---|
item_ids | array of integer or string | Only these lines (default: every line that can go again). |
idempotency_key | string | 8 to 64 of A-Z a-z 0-9 _ -. A repeat returns the send it made; the Idempotency-Key header does the same. |
acknowledge_over_budget | boolean or string | true or false. |
Returns: 200 WorkforcePreview. Errors: the envelope.
Python
jusa.Workforce.preview_resend("order-8812")
Node
await jusa.workforce.previewResend('order-8812');
PHP
$jusa->workforce->previewResend('order-8812');
Go
_, err := jusaClient.Workforce.PreviewResend(ctx, "order-8812", nil)
if err != nil {
return err
}
Java
jusa.workforce().previewResend("order-8812");
C#
await jusa.Workforce.PreviewResendAsync("order-8812");
Dart
await jusa.workforce.previewResend('order-8812');
Ruby
Jusa::Workforce.preview_resend("order-8812")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/workforce/batches/order-8812/resend/preview \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Departments
Scope: workforce:admin.
Returns: 200 WorkforceDepartmentList. Errors: the envelope.
Python
jusa.Workforce.list_cost_centers()
Node
await jusa.workforce.listCostCenters();
PHP
$jusa->workforce->listCostCenters();
Go
_, err := jusaClient.Workforce.ListCostCenters(ctx, nil)
if err != nil {
return err
}
Java
jusa.workforce().listCostCenters();
C#
await jusa.Workforce.ListCostCentersAsync();
Dart
await jusa.workforce.listCostCenters();
Ruby
Jusa::Workforce.list_cost_centers
curl
curl https://jusa.localhost.co.zw/dev/v1/workforce/cost-centers \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Add a department
Scope: workforce:admin.
| Body (WorkforceDepartmentWrite) | Type | About |
|---|---|---|
name | string | |
code | string | The GL code. |
monthly_budget | string or number | A decimal amount, e.g. "5.00". |
currency | "USD" | "ZWG" | "usd" | "zwg" | USD or ZWG (either case). |
is_active | boolean or string | On a change: false archives it. |
Returns: 201 WorkforceDepartment. Errors: the envelope.
Python
jusa.Workforce.create_cost_center(
name="Field sales",
code="6100",
monthly_budget="250.00",
currency="USD",
)
Node
await jusa.workforce.createCostCenter({
name: 'Field sales',
code: '6100',
monthly_budget: '250.00',
currency: 'USD',
});
PHP
$jusa->workforce->createCostCenter([
'name' => 'Field sales',
'code' => '6100',
'monthly_budget' => '250.00',
'currency' => 'USD',
]);
Go
_, err := jusaClient.Workforce.CreateCostCenter(ctx, jusa.Params{
"name": "Field sales",
"code": "6100",
"monthly_budget": "250.00",
"currency": "USD",
})
if err != nil {
return err
}
Java
jusa.workforce().createCostCenter(Params.of(
"name", "Field sales",
"code", "6100",
"monthly_budget", "250.00",
"currency", "USD"
));
C#
await jusa.Workforce.CreateCostCenterAsync(new
{
name = "Field sales",
code = "6100",
monthly_budget = "250.00",
currency = "USD",
});
Dart
await jusa.workforce.createCostCenter({
'name': 'Field sales',
'code': '6100',
'monthly_budget': '250.00',
'currency': 'USD',
});
Ruby
Jusa::Workforce.create_cost_center(
name: "Field sales",
code: "6100",
monthly_budget: "250.00",
currency: "USD",
)
curl
curl https://jusa.localhost.co.zw/dev/v1/workforce/cost-centers \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Field sales",
"code": "6100",
"monthly_budget": "250.00",
"currency": "USD"
}'
Change a department
Scope: workforce:admin.
| Parameter | In | About |
|---|---|---|
cost_center_id required | path | cc_… |
| Body (WorkforceDepartmentWrite) | Type | About |
|---|---|---|
name | string | |
code | string | The GL code. |
monthly_budget | string or number | A decimal amount, e.g. "5.00". |
currency | "USD" | "ZWG" | "usd" | "zwg" | USD or ZWG (either case). |
is_active | boolean or string | On a change: false archives it. |
Returns: 200 WorkforceDepartment. Errors: the envelope.
Python
jusa.Workforce.update_cost_center(
"cc_…",
name="Field sales",
code="6100",
monthly_budget="250.00",
currency="USD",
)
Node
await jusa.workforce.updateCostCenter('cc_…', {
name: 'Field sales',
code: '6100',
monthly_budget: '250.00',
currency: 'USD',
});
PHP
$jusa->workforce->updateCostCenter('cc_…', [
'name' => 'Field sales',
'code' => '6100',
'monthly_budget' => '250.00',
'currency' => 'USD',
]);
Go
_, err := jusaClient.Workforce.UpdateCostCenter(ctx, "cc_…", jusa.Params{
"name": "Field sales",
"code": "6100",
"monthly_budget": "250.00",
"currency": "USD",
})
if err != nil {
return err
}
Java
jusa.workforce().updateCostCenter("cc_…", Params.of(
"name", "Field sales",
"code", "6100",
"monthly_budget", "250.00",
"currency", "USD"
));
C#
await jusa.Workforce.UpdateCostCenterAsync("cc_…", new
{
name = "Field sales",
code = "6100",
monthly_budget = "250.00",
currency = "USD",
});
Dart
await jusa.workforce.updateCostCenter('cc_…', {
'name': 'Field sales',
'code': '6100',
'monthly_budget': '250.00',
'currency': 'USD',
});
Ruby
Jusa::Workforce.update_cost_center(
"cc_…",
name: "Field sales",
code: "6100",
monthly_budget: "250.00",
currency: "USD",
)
curl
curl -X PATCH https://jusa.localhost.co.zw/dev/v1/workforce/cost-centers/cc_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Field sales",
"code": "6100",
"monthly_budget": "250.00",
"currency": "USD"
}'
A department's people
Scope: workforce:admin.
| Parameter | In | About |
|---|---|---|
cost_center_id required | path | cc_… |
Returns: 200 WorkforceDepartmentPeople. Errors: the envelope.
Python
jusa.Workforce.list_people("cc_…")
Node
await jusa.workforce.listPeople('cc_…');
PHP
$jusa->workforce->listPeople('cc_…');
Go
_, err := jusaClient.Workforce.ListPeople(ctx, "cc_…", nil)
if err != nil {
return err
}
Java
jusa.workforce().listPeople("cc_…");
C#
await jusa.Workforce.ListPeopleAsync("cc_…");
Dart
await jusa.workforce.listPeople('cc_…');
Ruby
Jusa::Workforce.list_people("cc_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/workforce/cost-centers/cc_…/people \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Move people into a department
Scope: workforce:admin.
| Parameter | In | About |
|---|---|---|
cost_center_id required | path | cc_… |
| Body (WorkforcePeopleChange) | Type | About |
|---|---|---|
add | array of integer or string | People to move into it. |
remove | array of integer or string | People to take out. |
new | array of object | People to add to the register and to it. |
Returns: 200 WorkforceDepartmentPeople. Errors: the envelope.
Python
jusa.Workforce.add_people(
"cc_…",
add=[12],
new=[{"name": "Rudo Moyo", "phone": "0772123456"}],
)
Node
await jusa.workforce.addPeople('cc_…', {
add: [12],
new: [{ name: 'Rudo Moyo', phone: '0772123456' }],
});
PHP
$jusa->workforce->addPeople('cc_…', [
'add' => [12],
'new' => [['name' => 'Rudo Moyo', 'phone' => '0772123456']],
]);
Go
_, err := jusaClient.Workforce.AddPeople(ctx, "cc_…", jusa.Params{
"add": []int{12},
"new": []jusa.Params{jusa.Params{"name": "Rudo Moyo", "phone": "0772123456"}},
})
if err != nil {
return err
}
Java
jusa.workforce().addPeople("cc_…", Params.of(
"add", List.of(12),
"new", List.of(Map.of("name", "Rudo Moyo", "phone", "0772123456"))
));
C#
await jusa.Workforce.AddPeopleAsync("cc_…", new
{
add = new[] { 12 },
@new = new object[] { new { name = "Rudo Moyo", phone = "0772123456" } },
});
Dart
await jusa.workforce.addPeople('cc_…', {
'add': [12],
'new': [{'name': 'Rudo Moyo', 'phone': '0772123456'}],
});
Ruby
Jusa::Workforce.add_people(
"cc_…",
add: [12],
new: [{ name: "Rudo Moyo", phone: "0772123456" }],
)
curl
curl https://jusa.localhost.co.zw/dev/v1/workforce/cost-centers/cc_…/people \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"add": [12], "new": [{"name": "Rudo Moyo", "phone": "0772123456"}]}'
A department's spend
Scope: workforce:admin.
| Parameter | In | About |
|---|---|---|
cost_center_id required | path | cc_… |
from | query | The start (inclusive). |
to | query | The end (inclusive). |
Returns: 200 WorkforceDepartmentSpend. Errors: the envelope.
Python
jusa.Workforce.cost_center_spend("cc_…")
Node
await jusa.workforce.costCenterSpend('cc_…');
PHP
$jusa->workforce->costCenterSpend('cc_…');
Go
_, err := jusaClient.Workforce.CostCenterSpend(ctx, "cc_…", nil)
if err != nil {
return err
}
Java
jusa.workforce().costCenterSpend("cc_…");
C#
await jusa.Workforce.CostCenterSpendAsync("cc_…");
Dart
await jusa.workforce.costCenterSpend('cc_…');
Ruby
Jusa::Workforce.cost_center_spend("cc_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/workforce/cost-centers/cc_…/spend \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
The GL journal
Scope: workforce:admin.
| Parameter | In | About |
|---|---|---|
from | query | The start (inclusive). |
to | query | The end (inclusive). |
cost_center | query | cc_… (Workforce: a department's id, or none for sends booked to none). |
format | query | json (default); csv for reports and the Workforce files (the ledger also takes csv-json, the file inside JSON); pdf for a receipt. |
Returns: 200 WorkforceJournal or CSV. Errors: the envelope.
Python
jusa.Workforce.journal()
Node
await jusa.workforce.journal();
PHP
$jusa->workforce->journal();
Go
_, err := jusaClient.Workforce.Journal(ctx, nil)
if err != nil {
return err
}
Java
jusa.workforce().journal();
C#
await jusa.Workforce.JournalAsync();
Dart
await jusa.workforce.journal();
Ruby
Jusa::Workforce.journal
curl
curl https://jusa.localhost.co.zw/dev/v1/workforce/journal \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
The ledger
Scope: workforce:admin.
| Parameter | In | About |
|---|---|---|
from | query | The start (inclusive). |
to | query | The end (inclusive). |
currency | query | Only this currency. |
kind | query | Only this kind of entry (topup, debit, refund, adjustment). |
q | query | Entries whose reference contains this. |
format | query | json (default); csv for reports and the Workforce files (the ledger also takes csv-json, the file inside JSON); pdf for a receipt. |
page | query | Workforce pages from 1. |
page_size | query | Workforce rows per page (batches up to 50, the ledger up to 100). |
Returns: 200 WorkforceLedger or WorkforceExport or CSV. Errors: the envelope.
Python
jusa.Workforce.ledger()
Node
await jusa.workforce.ledger();
PHP
$jusa->workforce->ledger();
Go
_, err := jusaClient.Workforce.Ledger(ctx, nil)
if err != nil {
return err
}
Java
jusa.workforce().ledger();
C#
await jusa.Workforce.LedgerAsync();
Dart
await jusa.workforce.ledger();
Ruby
Jusa::Workforce.ledger
curl
curl https://jusa.localhost.co.zw/dev/v1/workforce/ledger \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Meters on file
Scope: workforce:admin.
Returns: 200 WorkforceMeters. Errors: the envelope.
Python
jusa.Workforce.meters()
Node
await jusa.workforce.meters();
PHP
$jusa->workforce->meters();
Go
_, err := jusaClient.Workforce.Meters(ctx, nil)
if err != nil {
return err
}
Java
jusa.workforce().meters();
C#
await jusa.Workforce.MetersAsync();
Dart
await jusa.workforce.meters();
Ruby
Jusa::Workforce.meters
curl
curl https://jusa.localhost.co.zw/dev/v1/workforce/meters \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
What Workforce can send
Scope: workforce:admin.
Returns: 200 WorkforceProducts. Errors: the envelope.
Python
jusa.Workforce.products()
Node
await jusa.workforce.products();
PHP
$jusa->workforce->products();
Go
_, err := jusaClient.Workforce.Products(ctx, nil)
if err != nil {
return err
}
Java
jusa.workforce().products();
C#
await jusa.Workforce.ProductsAsync();
Dart
await jusa.workforce.products();
Ruby
Jusa::Workforce.products
curl
curl https://jusa.localhost.co.zw/dev/v1/workforce/products \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Add a person
Scope: workforce:admin.
| Body (WorkforcePersonCreate) | Type | About |
|---|---|---|
name required | string | |
phone required | string | A Zimbabwean mobile: 07XXXXXXXX, 2637XXXXXXXX or +2637XXXXXXXX. |
payroll_id | string | |
cost_center_id | integer or string | A numeric id. |
monthly_cap | string or number | A decimal amount, e.g. "5.00". |
Returns: 201 WorkforcePersonCreated. Errors: the envelope.
Python
jusa.Workforce.create_recipient(name="Rudo Moyo", phone="0772123456", cost_center_id=3)
Node
await jusa.workforce.createRecipient({
name: 'Rudo Moyo',
phone: '0772123456',
cost_center_id: 3,
});
PHP
$jusa->workforce->createRecipient([
'name' => 'Rudo Moyo',
'phone' => '0772123456',
'cost_center_id' => 3,
]);
Go
_, err := jusaClient.Workforce.CreateRecipient(ctx, jusa.Params{
"name": "Rudo Moyo",
"phone": "0772123456",
"cost_center_id": 3,
})
if err != nil {
return err
}
Java
jusa.workforce().createRecipient(Params.of(
"name", "Rudo Moyo",
"phone", "0772123456",
"cost_center_id", 3
));
C#
await jusa.Workforce.CreateRecipientAsync(new
{
name = "Rudo Moyo",
phone = "0772123456",
cost_center_id = 3,
});
Dart
await jusa.workforce.createRecipient({
'name': 'Rudo Moyo',
'phone': '0772123456',
'cost_center_id': 3,
});
Ruby
Jusa::Workforce.create_recipient(
name: "Rudo Moyo",
phone: "0772123456",
cost_center_id: 3,
)
curl
curl https://jusa.localhost.co.zw/dev/v1/workforce/recipients \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Rudo Moyo", "phone": "0772123456", "cost_center_id": 3}'
Change a person
Scope: workforce:admin.
| Parameter | In | About |
|---|---|---|
recipient_id required | path | rcp_… or ext:<external_id>. |
| Body (WorkforcePersonUpdate) | Type | About |
|---|---|---|
name | string | |
phone | string | A Zimbabwean mobile: 07XXXXXXXX, 2637XXXXXXXX or +2637XXXXXXXX. |
payroll_id | string | |
cost_center_id | integer or string | A numeric id. |
monthly_cap | string or number | A decimal amount, e.g. "5.00". |
notes | string |
Returns: 200 WorkforcePersonUpdated. Errors: the envelope.
Python
jusa.Workforce.update_recipient("rcp_…")
Node
await jusa.workforce.updateRecipient('rcp_…');
PHP
$jusa->workforce->updateRecipient('rcp_…');
Go
_, err := jusaClient.Workforce.UpdateRecipient(ctx, "rcp_…", nil)
if err != nil {
return err
}
Java
jusa.workforce().updateRecipient("rcp_…");
C#
await jusa.Workforce.UpdateRecipientAsync("rcp_…");
Dart
await jusa.workforce.updateRecipient('rcp_…');
Ruby
Jusa::Workforce.update_recipient("rcp_…")
curl
curl -X PATCH https://jusa.localhost.co.zw/dev/v1/workforce/recipients/rcp_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
A person's statement
Scope: workforce:admin.
| Parameter | In | About |
|---|---|---|
recipient_id required | path | rcp_… or ext:<external_id>. |
from | query | The start (inclusive). |
to | query | The end (inclusive). |
Returns: 200 WorkforceStatement. Errors: the envelope.
Python
jusa.Workforce.recipient_statement("rcp_…")
Node
await jusa.workforce.recipientStatement('rcp_…');
PHP
$jusa->workforce->recipientStatement('rcp_…');
Go
_, err := jusaClient.Workforce.RecipientStatement(ctx, "rcp_…", nil)
if err != nil {
return err
}
Java
jusa.workforce().recipientStatement("rcp_…");
C#
await jusa.Workforce.RecipientStatementAsync("rcp_…");
Dart
await jusa.workforce.recipientStatement('rcp_…');
Ruby
Jusa::Workforce.recipient_statement("rcp_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/workforce/recipients/rcp_…/statement \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Add a plan
Scope: workforce:admin.
| Body (WorkforcePlanCreate) | Type | About |
|---|---|---|
name required | string | |
frequency required | "daily" | "weekly" | "monthly" | |
hour | integer or string | |
minute | integer or string | |
day_of_week | integer or string | weekly: 0 (Monday) to 6. |
day_of_month | integer or string | monthly: 1 to 28. |
group_id | integer or string | A numeric id. |
product_ref | string | An airtime product; plans do not send ZESA. |
currency | "USD" | "ZWG" | "usd" | "zwg" | USD or ZWG (either case). |
amount_per_recipient required | string or number | A decimal amount, e.g. "5.00". |
custom_sms | string | |
cost_center_id | integer or string | The department it is booked to and sends to. |
Returns: 201 WorkforcePlan. Errors: the envelope.
Python
jusa.Workforce.create_schedule(
name="Month-end airtime",
frequency="monthly",
day_of_month=25,
hour=9,
amount_per_recipient="5.00",
cost_center_id=3,
)
Node
await jusa.workforce.createSchedule({
name: 'Month-end airtime',
frequency: 'monthly',
day_of_month: 25,
hour: 9,
amount_per_recipient: '5.00',
cost_center_id: 3,
});
PHP
$jusa->workforce->createSchedule([
'name' => 'Month-end airtime',
'frequency' => 'monthly',
'day_of_month' => 25,
'hour' => 9,
'amount_per_recipient' => '5.00',
'cost_center_id' => 3,
]);
Go
_, err := jusaClient.Workforce.CreateSchedule(ctx, jusa.Params{
"name": "Month-end airtime",
"frequency": "monthly",
"day_of_month": 25,
"hour": 9,
"amount_per_recipient": "5.00",
"cost_center_id": 3,
})
if err != nil {
return err
}
Java
jusa.workforce().createSchedule(Params.of(
"name", "Month-end airtime",
"frequency", "monthly",
"day_of_month", 25,
"hour", 9,
"amount_per_recipient", "5.00",
"cost_center_id", 3
));
C#
await jusa.Workforce.CreateScheduleAsync(new
{
name = "Month-end airtime",
frequency = "monthly",
day_of_month = 25,
hour = 9,
amount_per_recipient = "5.00",
cost_center_id = 3,
});
Dart
await jusa.workforce.createSchedule({
'name': 'Month-end airtime',
'frequency': 'monthly',
'day_of_month': 25,
'hour': 9,
'amount_per_recipient': '5.00',
'cost_center_id': 3,
});
Ruby
Jusa::Workforce.create_schedule(
name: "Month-end airtime",
frequency: "monthly",
day_of_month: 25,
hour: 9,
amount_per_recipient: "5.00",
cost_center_id: 3,
)
curl
curl https://jusa.localhost.co.zw/dev/v1/workforce/schedules \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Month-end airtime",
"frequency": "monthly",
"day_of_month": 25,
"hour": 9,
"amount_per_recipient": "5.00",
"cost_center_id": 3
}'
Change a plan
Scope: workforce:admin.
| Parameter | In | About |
|---|---|---|
schedule_id required | path | sch_… |
| Body (WorkforcePlanUpdate) | Type | About |
|---|---|---|
name | string | |
frequency | "daily" | "weekly" | "monthly" | |
hour | integer or string | |
minute | integer or string | |
day_of_week | integer or string | weekly: 0 (Monday) to 6. |
day_of_month | integer or string | monthly: 1 to 28. |
group_id | integer or string | A numeric id. |
product_ref | string | An airtime product; plans do not send ZESA. |
currency | "USD" | "ZWG" | "usd" | "zwg" | USD or ZWG (either case). |
amount_per_recipient | string or number | A decimal amount, e.g. "5.00". |
custom_sms | string | |
cost_center_id | integer or string | The department it is booked to and sends to. |
is_active | boolean or string | false pauses it. |
Returns: 200 WorkforcePlan. Errors: the envelope.
Python
jusa.Workforce.update_schedule("sch_…")
Node
await jusa.workforce.updateSchedule('sch_…');
PHP
$jusa->workforce->updateSchedule('sch_…');
Go
_, err := jusaClient.Workforce.UpdateSchedule(ctx, "sch_…", nil)
if err != nil {
return err
}
Java
jusa.workforce().updateSchedule("sch_…");
C#
await jusa.Workforce.UpdateScheduleAsync("sch_…");
Dart
await jusa.workforce.updateSchedule('sch_…');
Ruby
Jusa::Workforce.update_schedule("sch_…")
curl
curl -X PATCH https://jusa.localhost.co.zw/dev/v1/workforce/schedules/sch_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Remove a plan
Scope: workforce:admin.
| Parameter | In | About |
|---|---|---|
schedule_id required | path | sch_… |
Returns: 200 WorkforcePlanStopped. Errors: the envelope.
Python
jusa.Workforce.delete_schedule("sch_…")
Node
await jusa.workforce.deleteSchedule('sch_…');
PHP
$jusa->workforce->deleteSchedule('sch_…');
Go
_, err := jusaClient.Workforce.DeleteSchedule(ctx, "sch_…", nil)
if err != nil {
return err
}
Java
jusa.workforce().deleteSchedule("sch_…");
C#
await jusa.Workforce.DeleteScheduleAsync("sch_…");
Dart
await jusa.workforce.deleteSchedule('sch_…');
Ruby
Jusa::Workforce.delete_schedule("sch_…")
curl
curl -X DELETE https://jusa.localhost.co.zw/dev/v1/workforce/schedules/sch_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Run a plan now
Scope: workforce:admin.
| Parameter | In | About |
|---|---|---|
schedule_id required | path | sch_… |
| Body (WorkforcePlanRunNow) | Type | About |
|---|---|---|
idempotency_key | string | 8 to 64 of A-Z a-z 0-9 _ -. A repeat returns the send it made; the Idempotency-Key header does the same. |
again | boolean or string | Send again when it already went out today. |
acknowledge_over_budget | boolean or string | true or false. |
Returns: 200 WorkforcePlanRun. Errors: the envelope.
Python
jusa.Workforce.run_schedule_now("sch_…")
Node
await jusa.workforce.runScheduleNow('sch_…');
PHP
$jusa->workforce->runScheduleNow('sch_…');
Go
_, err := jusaClient.Workforce.RunScheduleNow(ctx, "sch_…", nil)
if err != nil {
return err
}
Java
jusa.workforce().runScheduleNow("sch_…");
C#
await jusa.Workforce.RunScheduleNowAsync("sch_…");
Dart
await jusa.workforce.runScheduleNow('sch_…');
Ruby
Jusa::Workforce.run_schedule_now("sch_…")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/workforce/schedules/sch_…/run-now \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Preview running a plan
Scope: workforce:admin.
| Parameter | In | About |
|---|---|---|
schedule_id required | path | sch_… |
Returns: 200 WorkforcePreview. Errors: the envelope.
Python
jusa.Workforce.preview_schedule_run("sch_…")
Node
await jusa.workforce.previewScheduleRun('sch_…');
PHP
$jusa->workforce->previewScheduleRun('sch_…');
Go
_, err := jusaClient.Workforce.PreviewScheduleRun(ctx, "sch_…", nil)
if err != nil {
return err
}
Java
jusa.workforce().previewScheduleRun("sch_…");
C#
await jusa.Workforce.PreviewScheduleRunAsync("sch_…");
Dart
await jusa.workforce.previewScheduleRun('sch_…');
Ruby
Jusa::Workforce.preview_schedule_run("sch_…")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/workforce/schedules/sch_…/run-now/preview \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
The period summary
Scope: workforce:admin.
| Parameter | In | About |
|---|---|---|
from | query | The start (inclusive). |
to | query | The end (inclusive). |
Returns: 200 WorkforceSummary. Errors: the envelope.
Python
jusa.Workforce.summary()
Node
await jusa.workforce.summary();
PHP
$jusa->workforce->summary();
Go
_, err := jusaClient.Workforce.Summary(ctx, nil)
if err != nil {
return err
}
Java
jusa.workforce().summary();
C#
await jusa.Workforce.SummaryAsync();
Dart
await jusa.workforce.summary();
Ruby
Jusa::Workforce.summary
curl
curl https://jusa.localhost.co.zw/dev/v1/workforce/summary \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Family
MyFamilyTime (needs OAuth user tokens; not available yet).
MyFamilyTime (not available yet)
Every /family route answers 501 not_yet_available: it needs OAuth user tokens. Use recipients and schedules for your own users.
Returns: an error. Errors: the envelope.
curl
curl https://jusa.localhost.co.zw/dev/v1/family \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
MyFamilyTime (not available yet)
Every /family route answers 501 not_yet_available: it needs OAuth user tokens. Use recipients and schedules for your own users.
Returns: an error. Errors: the envelope.
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/family \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
MyFamilyTime (not available yet)
Every /family route answers 501 not_yet_available: it needs OAuth user tokens. Use recipients and schedules for your own users.
Returns: an error. Errors: the envelope.
curl
curl -X PUT https://jusa.localhost.co.zw/dev/v1/family \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
MyFamilyTime (not available yet)
Every /family route answers 501 not_yet_available: it needs OAuth user tokens. Use recipients and schedules for your own users.
Returns: an error. Errors: the envelope.
curl
curl -X PATCH https://jusa.localhost.co.zw/dev/v1/family \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
MyFamilyTime (not available yet)
Every /family route answers 501 not_yet_available: it needs OAuth user tokens. Use recipients and schedules for your own users.
Returns: an error. Errors: the envelope.
curl
curl -X DELETE https://jusa.localhost.co.zw/dev/v1/family \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Reports
Spend, success rate, the GL journal and CSV exports.
List exports
Scope: reports:read.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
status | query | Only objects in this status. |
Returns: 200 ExportList. Errors: the envelope.
Python
jusa.Export.list()
Node
await jusa.exports.list();
PHP
$jusa->exports->list();
Go
_, err := jusaClient.Exports.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.exports().list();
C#
await jusa.Exports.ListAsync();
Dart
await jusa.exports.list();
Ruby
Jusa::Export.list
curl
curl https://jusa.localhost.co.zw/dev/v1/exports \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Export to CSV
Built in the background; GET it for a signed url (an hour). Tokens are always masked. Scope: reports:read.
| Body (ExportCreate) | Type | About |
|---|---|---|
type required | "sends" | "rewards" | "transactions" | "deliveries" | |
from | integer or string | Unix seconds or an ISO 8601 time. |
to | integer or string | Unix seconds or an ISO 8601 time. |
currency | "USD" | "ZWG" | "usd" | "zwg" | USD or ZWG (either case). |
status | string |
Returns: 202 Export. Errors: the envelope.
Python
jusa.Export.create(type="sends", from_="2026-09-01T00:00:00Z")
Node
await jusa.exports.create({ type: 'sends', from: '2026-09-01T00:00:00Z' });
PHP
$jusa->exports->create(['type' => 'sends', 'from' => '2026-09-01T00:00:00Z']);
Go
_, err := jusaClient.Exports.Create(ctx, jusa.Params{
"type": "sends",
"from": "2026-09-01T00:00:00Z",
})
if err != nil {
return err
}
Java
jusa.exports().create(Params.of("type", "sends", "from", "2026-09-01T00:00:00Z"));
C#
await jusa.Exports.CreateAsync(new { type = "sends", from = "2026-09-01T00:00:00Z" });
Dart
await jusa.exports.create({'type': 'sends', 'from': '2026-09-01T00:00:00Z'});
Ruby
Jusa::Export.create(type: "sends", from: "2026-09-01T00:00:00Z")
curl
curl https://jusa.localhost.co.zw/dev/v1/exports \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"type": "sends", "from": "2026-09-01T00:00:00Z"}'
Retrieve an export
Scope: reports:read.
| Parameter | In | About |
|---|---|---|
export_id required | path | exp_… |
Returns: 200 Export. Errors: the envelope.
Python
jusa.Export.retrieve("exp_…")
Node
await jusa.exports.retrieve('exp_…');
PHP
$jusa->exports->retrieve('exp_…');
Go
_, err := jusaClient.Exports.Retrieve(ctx, "exp_…", nil)
if err != nil {
return err
}
Java
jusa.exports().retrieve("exp_…");
C#
await jusa.Exports.RetrieveAsync("exp_…");
Dart
await jusa.exports.retrieve('exp_…');
Ruby
Jusa::Export.retrieve("exp_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/exports/exp_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Download an export
No key: the signed url is the credential.
| Parameter | In | About |
|---|---|---|
export_id required | path | exp_… |
token | query | The signed download token from the export's url. |
Returns: 200 CSV. Errors: the envelope.
Python
jusa.Export.download("exp_…")
Node
await jusa.exports.download('exp_…');
PHP
$jusa->exports->download('exp_…');
Go
_, err := jusaClient.Exports.Download(ctx, "exp_…", nil)
if err != nil {
return err
}
Java
jusa.exports().download("exp_…");
C#
await jusa.Exports.DownloadAsync("exp_…");
Dart
await jusa.exports.download('exp_…');
Ruby
Jusa::Export.download("exp_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/exports/exp_…/download
GL journal
Scope: reports:read.
| Parameter | In | About |
|---|---|---|
from | query | The start (inclusive). |
to | query | The end (inclusive). |
cost_center | query | cc_… (Workforce: a department's id, or none for sends booked to none). |
format | query | json (default); csv for reports and the Workforce files (the ledger also takes csv-json, the file inside JSON); pdf for a receipt. |
Returns: 200 Report or CSV. Errors: the envelope.
Python
jusa.Report.journal()
Node
await jusa.reports.journal();
PHP
$jusa->reports->journal();
Go
_, err := jusaClient.Reports.Journal(ctx, nil)
if err != nil {
return err
}
Java
jusa.reports().journal();
C#
await jusa.Reports.JournalAsync();
Dart
await jusa.reports.journal();
Ruby
Jusa::Report.journal
curl
curl https://jusa.localhost.co.zw/dev/v1/reports/journal \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Spend report
Delivered sends paid from Jusa Credit at face value; group_by day, network, product, program, cost_center or recipient. Scope: reports:read.
| Parameter | In | About |
|---|---|---|
from | query | The start (inclusive). |
to | query | The end (inclusive). |
currency | query | Only this currency. |
group_by | query | How rows are grouped. |
Returns: 200 Report. Errors: the envelope.
Python
jusa.Report.spend()
Node
await jusa.reports.spend();
PHP
$jusa->reports->spend();
Go
_, err := jusaClient.Reports.Spend(ctx, nil)
if err != nil {
return err
}
Java
jusa.reports().spend();
C#
await jusa.Reports.SpendAsync();
Dart
await jusa.reports.spend();
Ruby
Jusa::Report.spend
curl
curl https://jusa.localhost.co.zw/dev/v1/reports/spend \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Success-rate report
delivered ÷ (delivered + failed); group_by network or product. Scope: reports:read.
| Parameter | In | About |
|---|---|---|
from | query | The start (inclusive). |
to | query | The end (inclusive). |
currency | query | Only this currency. |
group_by | query | How rows are grouped. |
Returns: 200 Report. Errors: the envelope.
Python
jusa.Report.success_rate()
Node
await jusa.reports.successRate();
PHP
$jusa->reports->successRate();
Go
_, err := jusaClient.Reports.SuccessRate(ctx, nil)
if err != nil {
return err
}
Java
jusa.reports().successRate();
C#
await jusa.Reports.SuccessRateAsync();
Dart
await jusa.reports.successRate();
Ruby
Jusa::Report.success_rate
curl
curl https://jusa.localhost.co.zw/dev/v1/reports/success-rate \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Webhooks
Endpoints, events and deliveries.
List events
The catch-up feed, 30 days. type takes a family: send.* Scope: webhooks:manage.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
type | query | Only this type. |
object | query | Events about this object, e.g. snd_… |
Returns: 200 EventList. Errors: the envelope.
Python
jusa.Event.list()
Node
await jusa.events.list();
PHP
$jusa->events->list();
Go
_, err := jusaClient.Events.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.events().list();
C#
await jusa.Events.ListAsync();
Dart
await jusa.events.list();
Ruby
Jusa::Event.list
curl
curl https://jusa.localhost.co.zw/dev/v1/events \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Retrieve an event
Scope: webhooks:manage.
| Parameter | In | About |
|---|---|---|
event_id required | path | evt_… |
Returns: 200 Event. Errors: the envelope.
Python
jusa.Event.retrieve("evt_…")
Node
await jusa.events.retrieve('evt_…');
PHP
$jusa->events->retrieve('evt_…');
Go
_, err := jusaClient.Events.Retrieve(ctx, "evt_…", nil)
if err != nil {
return err
}
Java
jusa.events().retrieve("evt_…");
C#
await jusa.Events.RetrieveAsync("evt_…");
Dart
await jusa.events.retrieve('evt_…');
Ruby
Jusa::Event.retrieve("evt_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/events/evt_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Read a ZESA token from its link
The token_url in a send.delivered event: no key (the url is the credential), once, within 15 minutes.
| Parameter | In | About |
|---|---|---|
token required | path | The link's token. |
Returns: 200 SendToken. Errors: the envelope.
Python
jusa.SendToken.retrieve("lnk_tok_…")
Node
await jusa.sendTokens.retrieve('lnk_tok_…');
PHP
$jusa->sendTokens->retrieve('lnk_tok_…');
Go
_, err := jusaClient.SendTokens.Retrieve(ctx, "lnk_tok_…", nil)
if err != nil {
return err
}
Java
jusa.sendTokens().retrieve("lnk_tok_…");
C#
await jusa.SendTokens.RetrieveAsync("lnk_tok_…");
Dart
await jusa.sendTokens.retrieve('lnk_tok_…');
Ruby
Jusa::SendToken.retrieve("lnk_tok_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/send-tokens/lnk_tok_…
List webhook deliveries
Scope: webhooks:manage.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
endpoint | query | we_… |
event | query | evt_… |
type | query | Only this type. |
status | query | Only objects in this status. |
Returns: 200 WebhookDeliveryList. Errors: the envelope.
Python
jusa.WebhookDelivery.list()
Node
await jusa.webhookDeliveries.list();
PHP
$jusa->webhookDeliveries->list();
Go
_, err := jusaClient.WebhookDeliveries.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.webhookDeliveries().list();
C#
await jusa.WebhookDeliveries.ListAsync();
Dart
await jusa.webhookDeliveries.list();
Ruby
Jusa::WebhookDelivery.list
curl
curl https://jusa.localhost.co.zw/dev/v1/webhook-deliveries \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Retrieve a delivery
Scope: webhooks:manage.
| Parameter | In | About |
|---|---|---|
delivery_id required | path | whd_… |
Returns: 200 WebhookDelivery. Errors: the envelope.
Python
jusa.WebhookDelivery.retrieve("whd_…")
Node
await jusa.webhookDeliveries.retrieve('whd_…');
PHP
$jusa->webhookDeliveries->retrieve('whd_…');
Go
_, err := jusaClient.WebhookDeliveries.Retrieve(ctx, "whd_…", nil)
if err != nil {
return err
}
Java
jusa.webhookDeliveries().retrieve("whd_…");
C#
await jusa.WebhookDeliveries.RetrieveAsync("whd_…");
Dart
await jusa.webhookDeliveries.retrieve('whd_…');
Ruby
Jusa::WebhookDelivery.retrieve("whd_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/webhook-deliveries/whd_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Redeliver
Scope: webhooks:manage.
| Parameter | In | About |
|---|---|---|
delivery_id required | path | whd_… |
Returns: 202 WebhookDelivery. Errors: the envelope.
Python
jusa.WebhookDelivery.redeliver("whd_…")
Node
await jusa.webhookDeliveries.redeliver('whd_…');
PHP
$jusa->webhookDeliveries->redeliver('whd_…');
Go
_, err := jusaClient.WebhookDeliveries.Redeliver(ctx, "whd_…", nil)
if err != nil {
return err
}
Java
jusa.webhookDeliveries().redeliver("whd_…");
C#
await jusa.WebhookDeliveries.RedeliverAsync("whd_…");
Dart
await jusa.webhookDeliveries.redeliver('whd_…');
Ruby
Jusa::WebhookDelivery.redeliver("whd_…")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/webhook-deliveries/whd_…/redeliver \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
List webhook endpoints
Scope: webhooks:manage.
| Parameter | In | About |
|---|---|---|
limit | query | Rows per page. |
starting_after | query | An object id: the page after it (next_cursor). |
ending_before | query | An object id: the page before it. |
created[gte] | query | Unix seconds or ISO 8601. |
created[lte] | query | Unix seconds or ISO 8601. |
created[gt] | query | Unix seconds or ISO 8601. |
created[lt] | query | Unix seconds or ISO 8601. |
status | query | Only objects in this status. |
metadata[key] | query | metadata[<key>]=<value>: an exact match on one key. |
Returns: 200 WebhookEndpointList. Errors: the envelope.
Python
jusa.WebhookEndpoint.list()
Node
await jusa.webhookEndpoints.list();
PHP
$jusa->webhookEndpoints->list();
Go
_, err := jusaClient.WebhookEndpoints.List(ctx, nil)
if err != nil {
return err
}
Java
jusa.webhookEndpoints().list();
C#
await jusa.WebhookEndpoints.ListAsync();
Dart
await jusa.webhookEndpoints.list();
Ruby
Jusa::WebhookEndpoint.list
curl
curl https://jusa.localhost.co.zw/dev/v1/webhook-endpoints \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Add a webhook endpoint
https only, public addresses only. The signing secret is shown here. Up to 16 per mode. Scope: webhooks:manage.
| Body (WebhookEndpointCreate) | Type | About |
|---|---|---|
url required | string | |
enabled_events | array of string | "*", a family like "send.*", or types. |
description | string | |
api_version | string | |
include_tokens | boolean | |
token_links | boolean | Needs tokens:read. On by default when the caller has it. |
metadata | object | Up to 20 keys (letters, digits, _ . -, up to 40 characters) with values up to 500 characters. |
format | "jusa" | "legacy_airtime" |
Returns: 201 WebhookEndpoint. Errors: the envelope.
Python
jusa.WebhookEndpoint.create(
url="https://example.com/jusa/webhooks",
enabled_events=["send.*", "reward.*"],
)
Node
await jusa.webhookEndpoints.create({
url: 'https://example.com/jusa/webhooks',
enabled_events: ['send.*', 'reward.*'],
});
PHP
$jusa->webhookEndpoints->create([
'url' => 'https://example.com/jusa/webhooks',
'enabled_events' => ['send.*', 'reward.*'],
]);
Go
_, err := jusaClient.WebhookEndpoints.Create(ctx, jusa.Params{
"url": "https://example.com/jusa/webhooks",
"enabled_events": []string{"send.*", "reward.*"},
})
if err != nil {
return err
}
Java
jusa.webhookEndpoints().create(Params.of(
"url", "https://example.com/jusa/webhooks",
"enabled_events", List.of("send.*", "reward.*")
));
C#
await jusa.WebhookEndpoints.CreateAsync(new
{
url = "https://example.com/jusa/webhooks",
enabled_events = new[] { "send.*", "reward.*" },
});
Dart
await jusa.webhookEndpoints.create({
'url': 'https://example.com/jusa/webhooks',
'enabled_events': ['send.*', 'reward.*'],
});
Ruby
Jusa::WebhookEndpoint.create(
url: "https://example.com/jusa/webhooks",
enabled_events: ["send.*", "reward.*"],
)
curl
curl https://jusa.localhost.co.zw/dev/v1/webhook-endpoints \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/jusa/webhooks",
"enabled_events": ["send.*", "reward.*"]
}'
Retrieve a webhook endpoint
Scope: webhooks:manage.
| Parameter | In | About |
|---|---|---|
endpoint_id required | path | we_… |
Returns: 200 WebhookEndpoint. Errors: the envelope.
Python
jusa.WebhookEndpoint.retrieve("we_…")
Node
await jusa.webhookEndpoints.retrieve('we_…');
PHP
$jusa->webhookEndpoints->retrieve('we_…');
Go
_, err := jusaClient.WebhookEndpoints.Retrieve(ctx, "we_…", nil)
if err != nil {
return err
}
Java
jusa.webhookEndpoints().retrieve("we_…");
C#
await jusa.WebhookEndpoints.RetrieveAsync("we_…");
Dart
await jusa.webhookEndpoints.retrieve('we_…');
Ruby
Jusa::WebhookEndpoint.retrieve("we_…")
curl
curl https://jusa.localhost.co.zw/dev/v1/webhook-endpoints/we_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Update a webhook endpoint
Scope: webhooks:manage.
| Parameter | In | About |
|---|---|---|
endpoint_id required | path | we_… |
| Body (WebhookEndpointUpdate) | Type | About |
|---|---|---|
url | string | |
enabled_events | array of string | "*", a family like "send.*", or types. |
description | string | |
api_version | string | |
include_tokens | boolean | |
token_links | boolean | Needs tokens:read. On by default when the caller has it. |
metadata | object | Up to 20 keys (letters, digits, _ . -, up to 40 characters) with values up to 500 characters. |
format | "jusa" | "legacy_airtime" | |
status | "enabled" | "disabled" |
Returns: 200 WebhookEndpoint. Errors: the envelope.
Python
jusa.WebhookEndpoint.update("we_…")
Node
await jusa.webhookEndpoints.update('we_…');
PHP
$jusa->webhookEndpoints->update('we_…');
Go
_, err := jusaClient.WebhookEndpoints.Update(ctx, "we_…", nil)
if err != nil {
return err
}
Java
jusa.webhookEndpoints().update("we_…");
C#
await jusa.WebhookEndpoints.UpdateAsync("we_…");
Dart
await jusa.webhookEndpoints.update('we_…');
Ruby
Jusa::WebhookEndpoint.update("we_…")
curl
curl -X PATCH https://jusa.localhost.co.zw/dev/v1/webhook-endpoints/we_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Delete a webhook endpoint
Scope: webhooks:manage.
| Parameter | In | About |
|---|---|---|
endpoint_id required | path | we_… |
Returns: 200 WebhookEndpoint. Errors: the envelope.
Python
jusa.WebhookEndpoint.delete("we_…")
Node
await jusa.webhookEndpoints.delete('we_…');
PHP
$jusa->webhookEndpoints->delete('we_…');
Go
_, err := jusaClient.WebhookEndpoints.Delete(ctx, "we_…", nil)
if err != nil {
return err
}
Java
jusa.webhookEndpoints().delete("we_…");
C#
await jusa.WebhookEndpoints.DeleteAsync("we_…");
Dart
await jusa.webhookEndpoints.delete('we_…');
Ruby
Jusa::WebhookEndpoint.delete("we_…")
curl
curl -X DELETE https://jusa.localhost.co.zw/dev/v1/webhook-endpoints/we_… \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Replay events
Every stored event in a time range, again. Scope: webhooks:manage.
| Parameter | In | About |
|---|---|---|
endpoint_id required | path | we_… |
| Body (WebhookReplayCreate) | Type | About |
|---|---|---|
from required | integer or string | Unix seconds or an ISO 8601 time. |
to | integer or string | Unix seconds or an ISO 8601 time. |
types | array of string |
Returns: 202 WebhookReplay. Errors: the envelope.
Python
jusa.WebhookEndpoint.replay("we_…", from_=1)
Node
await jusa.webhookEndpoints.replay('we_…', { from: 1 });
PHP
$jusa->webhookEndpoints->replay('we_…', ['from' => 1]);
Go
_, err := jusaClient.WebhookEndpoints.Replay(ctx, "we_…", jusa.Params{"from": 1})
if err != nil {
return err
}
Java
jusa.webhookEndpoints().replay("we_…", Params.of("from", 1));
C#
await jusa.WebhookEndpoints.ReplayAsync("we_…", new { from = 1 });
Dart
await jusa.webhookEndpoints.replay('we_…', {'from': 1});
Ruby
Jusa::WebhookEndpoint.replay("we_…", from: 1)
curl
curl https://jusa.localhost.co.zw/dev/v1/webhook-endpoints/we_…/replay \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"from": 1}'
Roll the signing secret
The old secret signs alongside for the grace (two v1= values). Scope: webhooks:manage.
| Parameter | In | About |
|---|---|---|
endpoint_id required | path | we_… |
| Body (WebhookRollSecret) | Type | About |
|---|---|---|
grace | "0" | "1h" | "24h" |
Returns: 200 WebhookEndpoint. Errors: the envelope.
Python
jusa.WebhookEndpoint.roll_secret("we_…")
Node
await jusa.webhookEndpoints.rollSecret('we_…');
PHP
$jusa->webhookEndpoints->rollSecret('we_…');
Go
_, err := jusaClient.WebhookEndpoints.RollSecret(ctx, "we_…", nil)
if err != nil {
return err
}
Java
jusa.webhookEndpoints().rollSecret("we_…");
C#
await jusa.WebhookEndpoints.RollSecretAsync("we_…");
Dart
await jusa.webhookEndpoints.rollSecret('we_…');
Ruby
Jusa::WebhookEndpoint.roll_secret("we_…")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/webhook-endpoints/we_…/roll-secret \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Send a test event
Scope: webhooks:manage.
| Parameter | In | About |
|---|---|---|
endpoint_id required | path | we_… |
| Body (WebhookTest) | Type | About |
|---|---|---|
type | string |
Returns: 202 WebhookDelivery. Errors: the envelope.
Python
jusa.WebhookEndpoint.send_test("we_…")
Node
await jusa.webhookEndpoints.sendTest('we_…');
PHP
$jusa->webhookEndpoints->sendTest('we_…');
Go
_, err := jusaClient.WebhookEndpoints.SendTest(ctx, "we_…", nil)
if err != nil {
return err
}
Java
jusa.webhookEndpoints().sendTest("we_…");
C#
await jusa.WebhookEndpoints.SendTestAsync("we_…");
Dart
await jusa.webhookEndpoints.sendTest('we_…');
Ruby
Jusa::WebhookEndpoint.send_test("we_…")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/webhook-endpoints/we_…/test \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Test mode
Helpers for test keys only.
Approve (test mode)
Moves money: an Idempotency-Key is required. Test keys only: a live key gets 403 test_mode_only.
| Parameter | In | About |
|---|---|---|
approval_id required | path | apr_… |
Returns: 200 AgentApproval. Errors: the envelope.
Python
jusa.TestHelpers.approve_approval("apr_…", idempotency_key="approve-order-8812")
Node
await jusa.testHelpers.approveApproval('apr_…', {}, { idempotencyKey: 'approve-order-8812' });
PHP
$jusa->testHelpers->approveApproval('apr_…', [], ['idempotency_key' => 'approve-order-8812']);
Go
_, err := jusaClient.TestHelpers.ApproveApproval(ctx, "apr_…", nil, jusa.WithIdempotencyKey("approve-order-8812"))
if err != nil {
return err
}
Java
jusa.testHelpers().approveApproval("apr_…", RequestOptions.idempotencyKey("approve-order-8812"));
C#
await jusa.TestHelpers.ApproveApprovalAsync("apr_…", options: new RequestOptions { IdempotencyKey = "approve-order-8812" });
Dart
await jusa.testHelpers.approveApproval('apr_…', {}, RequestOptions(idempotencyKey: 'approve-order-8812'));
Ruby
Jusa::TestHelpers.approve_approval("apr_…", {}, idempotency_key: "approve-order-8812")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/test/approvals/apr_…/approve \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Idempotency-Key: approve-order-8812"
Reject (test mode)
Test keys only: a live key gets 403 test_mode_only.
| Parameter | In | About |
|---|---|---|
approval_id required | path | apr_… |
Returns: 200 AgentApproval. Errors: the envelope.
Python
jusa.TestHelpers.reject_approval("apr_…")
Node
await jusa.testHelpers.rejectApproval('apr_…');
PHP
$jusa->testHelpers->rejectApproval('apr_…');
Go
_, err := jusaClient.TestHelpers.RejectApproval(ctx, "apr_…", nil)
if err != nil {
return err
}
Java
jusa.testHelpers().rejectApproval("apr_…");
C#
await jusa.TestHelpers.RejectApprovalAsync("apr_…");
Dart
await jusa.testHelpers.rejectApproval('apr_…');
Ruby
Jusa::TestHelpers.reject_approval("apr_…")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/test/approvals/apr_…/reject \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Pay a test checkout
Scope: sends:write. Test keys only: a live key gets 403 test_mode_only.
| Parameter | In | About |
|---|---|---|
session_id required | path | cs_… |
| Body (TestCheckoutPay) | Type | About |
|---|---|---|
outcome | "paid" | "failed" |
Returns: 200 CheckoutSession. Errors: the envelope.
Python
jusa.TestHelpers.pay_checkout("cs_…")
Node
await jusa.testHelpers.payCheckout('cs_…');
PHP
$jusa->testHelpers->payCheckout('cs_…');
Go
_, err := jusaClient.TestHelpers.PayCheckout(ctx, "cs_…", nil)
if err != nil {
return err
}
Java
jusa.testHelpers().payCheckout("cs_…");
C#
await jusa.TestHelpers.PayCheckoutAsync("cs_…");
Dart
await jusa.testHelpers.payCheckout('cs_…');
Ruby
Jusa::TestHelpers.pay_checkout("cs_…")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/test/checkout-sessions/cs_…/pay \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Play staff on a held test checkout
Scope: sends:write. Test keys only: a live key gets 403 test_mode_only.
| Parameter | In | About |
|---|---|---|
session_id required | path | cs_… |
| Body (TestCheckoutReview) | Type | About |
|---|---|---|
action required | "send" | "credit" | |
note | string |
Returns: 200 CheckoutSession. Errors: the envelope.
Python
jusa.TestHelpers.review_checkout("cs_…", action="send")
Node
await jusa.testHelpers.reviewCheckout('cs_…', { action: 'send' });
PHP
$jusa->testHelpers->reviewCheckout('cs_…', ['action' => 'send']);
Go
_, err := jusaClient.TestHelpers.ReviewCheckout(ctx, "cs_…", jusa.Params{
"action": "send",
})
if err != nil {
return err
}
Java
jusa.testHelpers().reviewCheckout("cs_…", Params.of("action", "send"));
C#
await jusa.TestHelpers.ReviewCheckoutAsync("cs_…", new { action = "send" });
Dart
await jusa.testHelpers.reviewCheckout('cs_…', {'action': 'send'});
Ruby
Jusa::TestHelpers.review_checkout("cs_…", action: "send")
curl
curl https://jusa.localhost.co.zw/dev/v1/test/checkout-sessions/cs_…/review \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"action": "send"}'
Add test Jusa Credit
Scope: credit:topup. Test keys only: a live key gets 403 test_mode_only.
| Body (TestCreditCreate) | Type | About |
|---|---|---|
currency | "USD" | "ZWG" | "usd" | "zwg" | USD or ZWG (either case). |
amount required | string or number | A decimal amount, e.g. "5.00". |
Returns: 201 TestCredit. Errors: the envelope.
Python
jusa.TestHelpers.add_credit(currency="USD", amount="500.00")
Node
await jusa.testHelpers.addCredit({ currency: 'USD', amount: '500.00' });
PHP
$jusa->testHelpers->addCredit(['currency' => 'USD', 'amount' => '500.00']);
Go
_, err := jusaClient.TestHelpers.AddCredit(ctx, jusa.Params{
"currency": "USD",
"amount": "500.00",
})
if err != nil {
return err
}
Java
jusa.testHelpers().addCredit(Params.of("currency", "USD", "amount", "500.00"));
C#
await jusa.TestHelpers.AddCreditAsync(new { currency = "USD", amount = "500.00" });
Dart
await jusa.testHelpers.addCredit({'currency': 'USD', 'amount': '500.00'});
Ruby
Jusa::TestHelpers.add_credit(currency: "USD", amount: "500.00")
curl
curl https://jusa.localhost.co.zw/dev/v1/test/credit \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"currency": "USD", "amount": "500.00"}'
Fire a sample event
Scope: webhooks:manage. Test keys only: a live key gets 403 test_mode_only.
| Body (TestTrigger) | Type | About |
|---|---|---|
type required | string | An event type, e.g. send.delivered. |
Returns: 201 Event. Errors: the envelope.
Python
jusa.TestHelpers.trigger_event(type="string")
Node
await jusa.testHelpers.triggerEvent({ type: 'string' });
PHP
$jusa->testHelpers->triggerEvent(['type' => 'string']);
Go
_, err := jusaClient.TestHelpers.TriggerEvent(ctx, jusa.Params{"type": "string"})
if err != nil {
return err
}
Java
jusa.testHelpers().triggerEvent(Params.of("type", "string"));
C#
await jusa.TestHelpers.TriggerEventAsync(new { type = "string" });
Dart
await jusa.testHelpers.triggerEvent({'type': 'string'});
Ruby
Jusa::TestHelpers.trigger_event(type: "string")
curl
curl https://jusa.localhost.co.zw/dev/v1/test/events/trigger \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"type": "string"}'
Wipe test mode
Sends, rewards, batches, ledger and events go; keys, endpoints and recipients stay; credit is reset. Scope: account:manage. Test keys only: a live key gets 403 test_mode_only.
Returns: 200 TestReset. Errors: the envelope.
Python
jusa.TestHelpers.reset()
Node
await jusa.testHelpers.reset();
PHP
$jusa->testHelpers->reset();
Go
_, err := jusaClient.TestHelpers.Reset(ctx, nil)
if err != nil {
return err
}
Java
jusa.testHelpers().reset();
C#
await jusa.TestHelpers.ResetAsync();
Dart
await jusa.testHelpers.reset();
Ruby
Jusa::TestHelpers.reset
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/test/reset \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Claim a link, skipping the code
Scope: rewards:write. Test keys only: a live key gets 403 test_mode_only.
| Parameter | In | About |
|---|---|---|
link_id required | path | lnk_… |
| Body (TestLinkClaim) | Type | About |
|---|---|---|
phone required | string | A Zimbabwean mobile: 07XXXXXXXX, 2637XXXXXXXX or +2637XXXXXXXX. |
choice | "airtime" | "data" | "zesa" | |
meter | string | An 11-digit ZESA prepaid meter number. |
bundle_id | string |
Returns: 200 Reward · 201 Reward. Errors: the envelope.
Python
jusa.TestHelpers.claim_reward_link("lnk_…", phone="0772123456")
Node
await jusa.testHelpers.claimRewardLink('lnk_…', { phone: '0772123456' });
PHP
$jusa->testHelpers->claimRewardLink('lnk_…', ['phone' => '0772123456']);
Go
_, err := jusaClient.TestHelpers.ClaimRewardLink(ctx, "lnk_…", jusa.Params{
"phone": "0772123456",
})
if err != nil {
return err
}
Java
jusa.testHelpers().claimRewardLink("lnk_…", Params.of("phone", "0772123456"));
C#
await jusa.TestHelpers.ClaimRewardLinkAsync("lnk_…", new { phone = "0772123456" });
Dart
await jusa.testHelpers.claimRewardLink('lnk_…', {'phone': '0772123456'});
Ruby
Jusa::TestHelpers.claim_reward_link("lnk_…", phone: "0772123456")
curl
curl https://jusa.localhost.co.zw/dev/v1/test/reward-links/lnk_…/claim \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"phone": "0772123456"}'
Move a test send on
Without to: the next scripted step now. A move a live send could not make is 409. Scope: sends:write. Test keys only: a live key gets 403 test_mode_only.
| Parameter | In | About |
|---|---|---|
send_id required | path | snd_… (or the bare hex of a legacy order). |
| Body (TestAdvance) | Type | About |
|---|---|---|
to | "delivered" | "failed" | "late_delivered" |
Returns: 200 Send. Errors: the envelope.
Python
jusa.TestHelpers.advance_send("snd_…")
Node
await jusa.testHelpers.advanceSend('snd_…');
PHP
$jusa->testHelpers->advanceSend('snd_…');
Go
_, err := jusaClient.TestHelpers.AdvanceSend(ctx, "snd_…", nil)
if err != nil {
return err
}
Java
jusa.testHelpers().advanceSend("snd_…");
C#
await jusa.TestHelpers.AdvanceSendAsync("snd_…");
Dart
await jusa.testHelpers.advanceSend('snd_…');
Ruby
Jusa::TestHelpers.advance_send("snd_…")
curl
curl -X POST https://jusa.localhost.co.zw/dev/v1/test/sends/snd_…/advance \
-H "Authorization: Bearer $JUSA_SECRET_KEY"
Take ZESA down or up (test mode)
Scope: sends:write. Test keys only: a live key gets 403 test_mode_only.
| Body (TestZesa) | Type | About |
|---|---|---|
state required | "up" | "down" |
Returns: 200 ZesaAvailability. Errors: the envelope.
Python
jusa.TestHelpers.set_zesa_availability(state="up")
Node
await jusa.testHelpers.setZesaAvailability({ state: 'up' });
PHP
$jusa->testHelpers->setZesaAvailability(['state' => 'up']);
Go
_, err := jusaClient.TestHelpers.SetZesaAvailability(ctx, jusa.Params{"state": "up"})
if err != nil {
return err
}
Java
jusa.testHelpers().setZesaAvailability(Params.of("state", "up"));
C#
await jusa.TestHelpers.SetZesaAvailabilityAsync(new { state = "up" });
Dart
await jusa.testHelpers.setZesaAvailability({'state': 'up'});
Ruby
Jusa::TestHelpers.set_zesa_availability(state: "up")
curl
curl https://jusa.localhost.co.zw/dev/v1/test/zesa/availability \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"state": "up"}'
Utility
Health.
Check the API is up
No key needed.
Returns: 200 Health. Errors: the envelope.
Python
jusa.Health.retrieve()
Node
await jusa.health.retrieve();
PHP
$jusa->health->retrieve();
Go
_, err := jusaClient.Health.Retrieve(ctx, nil)
if err != nil {
return err
}
Java
jusa.health().retrieve();
C#
await jusa.Health.RetrieveAsync();
Dart
await jusa.health.retrieve();
Ruby
Jusa::Health.retrieve
curl
curl https://jusa.localhost.co.zw/dev/v1/health