Concepts
Settlement and money
What happens to a send and its money, state by state.
A send is written and charged at once, then goes out in the background: POST /sends always answers
202 with "status": "pending". Webhooks and GET /sends/{id} tell you the rest.
This page is what we promise about each state and its money.
Send statuses
| status | Means | Your Jusa Credit |
|---|---|---|
pending | Written and charged, about to go out. | Debited |
submitted | Handed to the network or ZESA; waiting for the answer. | Debited |
queued | ZESA is down; held until it is back or max_hold runs out (hold_until). | Debited |
retrying | The provider is out; tried again until the window closes (next_attempt_at). | Debited |
unknown | The provider did not say. We ask it every 2 minutes. | Debited |
requires_review | Still unknown after 12 hours: Jusa staff decide, within 2 business days. | Debited |
delivered | Done. Final and not reversible. | Spent |
failed_credited | Did not go through; the credit came back. | Returned |
cancelled_credited | You cancelled it before it went out. | Returned |
failed | Did not go through, and there was no Jusa Credit to return (a card-paid checkout send). | Not charged |
What we guarantee
| When | What happens | How long |
|---|---|---|
pending or submitted too long | A sweeper sends a never-sent one on its way, or moves a sent one to unknown. | About 2 minutes |
retrying | Retried until the window ends. Before any credit comes back, the provider is asked whether it has the send; only "nothing on record" credits it back. | Up to 6 hours |
queued | Held while ZESA is down; then failed_credited with zesa_hold_expired. Choose max_hold (default 24h, up to 72h) or on_zesa_down=fail. | max_hold |
unknown | Reconciled every 2 minutes; after 12 hours requires_review and a staff decision. | 12 hours, then 2 business days |
| A failure that was charged | failed_credited, once: a failure is never credited twice. | At once |
failed_credited, then the provider says it landed | Re-debited as late_success_debit (the balance may go negative, which stops new sends) and send.late_delivered fires. | When found |
| A card-paid checkout send fails | Resent once; if that fails too, the value becomes claimable Jusa Credit for the payer. | 24 hours |
delivered | Final. A dispute opens a staff case; a delivered send is never reversed. | n/a |
Never resend an unknown send. It may have landed: ZETDC has issued tokens the provider
had not recorded yet. Wait for it to settle; if you resend, you may pay twice.
What needs a look
GET /sends?needs_attention=true lists what is unknown for over an hour, flagged
requires_review, or queued past half of its max_hold. The dashboard home counts
them.
Python
def list_sends_needing_attention() -> None:
try:
jusa.Send.list(needs_attention=True, limit=50)
except jusa.JusaError as jusa_error:
logger.error("Jusa refused: %s [%s]", jusa_error.code, jusa_error.request_id)
raise
Node
import { JusaError } from '@jusa/node';
async function listSendsNeedingAttention() {
try {
await jusa.sends.list({ needs_attention: true, limit: 50 });
} catch (error) {
if (error instanceof JusaError) {
console.error(`Jusa refused: ${error.code} [${error.requestId}]`);
}
throw error;
}
}
PHP
function listSendsNeedingAttention(\Jusa\JusaClient $jusa): void
{
try {
$jusa->sends->list(['needs_attention' => true, 'limit' => 50]);
} catch (\Jusa\Exception\JusaException $jusaError) {
error_log("Jusa refused: {$jusaError->getErrorCode()} [{$jusaError->getRequestId()}]");
throw $jusaError;
}
}
Go
func listSendsNeedingAttention(ctx context.Context) error {
_, err := jusaClient.Sends.List(ctx, jusa.Params{"needs_attention": true, "limit": 50})
if err != nil {
return fmt.Errorf("sends.list: %w", err)
}
return nil
}
Java
void listSendsNeedingAttention() throws JusaException {
try {
jusa.sends().list(Params.of("needs_attention", true, "limit", 50));
} catch (JusaException jusaError) {
LOGGER.severe("Jusa refused: " + jusaError.getCode() + " [" + jusaError.getRequestId() + "]");
throw jusaError;
}
}
C#
async Task ListSendsNeedingAttentionAsync()
{
try
{
await jusa.Sends.ListAsync(new { needs_attention = true, limit = 50 });
}
catch (JusaException jusaError)
{
logger.LogError(jusaError, "Jusa refused: {Code} [{RequestId}]", jusaError.Code, jusaError.RequestId);
throw;
}
}
Dart
Future<void> listSendsNeedingAttention() async {
try {
await jusa.sends.list({'needs_attention': true, 'limit': 50});
} on JusaException catch (jusaError) {
stderr.writeln('Jusa refused: ${jusaError.code} [${jusaError.requestId}]');
rethrow;
}
}
Ruby
def list_sends_needing_attention
Jusa::Send.list(needs_attention: true, limit: 50)
rescue Jusa::JusaError => jusa_error
LOGGER.error("Jusa refused: #{jusa_error.code} [#{jusa_error.request_id}]")
raise
end
curl
curl -G https://jusa.localhost.co.zw/dev/v1/sends \
--fail-with-body \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-d needs_attention=true \
-d limit=50
Batches and programs follow their sends
A batch closes only when every line has settled: completed, partially_completed or
failed. A reward follows its send (delivered or failed), and a failed reward
returns its budget to the program; an exhausted program comes back to active when budget returns.
The money model
- Face value by default. A US$0.50 reward costs US$0.50, with no per-send fees and no pricing
endpoint. A verified business on the Dealer tier buys below
face at rates set for it on approval; every quote and send says its
costanddealer_discount("0.00"on the standard tier), and a failed send credits back the cost. - Prefunded Jusa Credit, per currency: USD and ZWG are separate balances, with no exchange.
- Top up any amount by card on Pesepay (the card fee is the payer's, as on the site) or by bank transfer with a reference. Card credit is spendable as soon as the payment is confirmed. A dealer can also ask for a cash collection: Jusa staff collect and count it, and the credit posts on their confirmation, for the counted amount.
- A closed loop. Jusa Credit cannot move between organisations or be cashed out, and card payments are never refunded to the card: a failure comes back as Jusa Credit.
- Reserved credit (a program's budget, an escrowed reward, a batch or a schedule run) is set aside
under the same lock as a send, so it cannot be spent twice.
GET /creditshows available and reserved. - Every ledger line is kept.
GET /statements?period=2026-09ties opening, top-ups, sends, credit-backs and closing.