Start
Test mode
A sandbox with its own Jusa Credit and numbers that act out every outcome.
Every organisation has a test-mode twin. A test key (jusa_sk_test_…, or the dashboard switched to
Test) reaches it, and nothing it does reaches Hot Recharge, Pesepay, SMS, email, push or finance. Objects
made in test mode say "livemode": false, and a live id passed with a test key is a
404, as if it did not exist.
Test Jusa Credit
US$1,000 and ZWG 25,000, topped back up every day to at least that: every sandbox holds both balances, and
quotes, sends, statements and top-ups work in ZWG as they do in USD. Add more with
POST /test/credit {"currency": "USD", "amount": "500.00"}. A test top-up is credited at once, a
cash pickup included (any organisation may ask for one in test mode; it confirms at once for the amount asked); a
test checkout session has a fake Pesepay page with Pay and Fail buttons, and its payment can only ever pay for a
test send. A dealer's tier and rates are mirrored onto its
sandbox, so a test key prices exactly as the organisation is offered live.
Magic phone numbers
Any valid number on any network (071, 073, 077, 078): the last four digits choose what happens. Use a plain number
such as 0772555001 for an ordinary send.
| Ends in | What happens |
|---|---|
…0000 | Delivered at once (also any suffix not listed here). |
…0001 | Delivered after 20 seconds: submitted, then delivered. |
…0002 | The network rejects it: failed_credited. |
…0003 | 400 invalid_target before anything is written. |
…0004 | 402 insufficient_credit, whatever the balance. |
…0005 | unknown, then delivered after 2 minutes (the reconcile path). |
…0006 | unknown, then failed and credited back. |
…0007 | retrying three times, then delivered. |
…0008 | retrying until the window closes (3 minutes in test mode), then failed_credited. |
…0009 | Provider float empty: retrying with provider_float_empty, delivered after 2 minutes. |
…0010 | A duplicate-SIM fraud signal: a reward is held for review; a checkout payer is held too. |
…0011 | failed_credited, then send.late_delivered after 2 minutes (Jusa Credit re-debited). |
…0012 | unknown past the (compressed) escalation window: requires_review. |
Magic meters
Any 11-digit meter: the last five digits choose.
| Ends in | What happens |
|---|---|
…00000 | Confirms as "SAMPLE CUSTOMER, Sandbox, Harare" and delivers a 20-digit token (also any meter not listed here). |
…00404 | Meter not found: 400 meter_not_found. |
…00423 | Meter blocked or inactive: 400 meter_blocked. |
…00503 | ZESA down: the send is queued, then released after 60 seconds. |
…00504 | The lookup times out: 503 zesa_unavailable with confirm=strict (the default); with confirm=best_effort the send goes ahead to the meter as typed. |
…00505 | ZESA down past max_hold (3 minutes in test mode): failed_credited with zesa_hold_expired. |
Data bundles
Test mode has a fixed list of bundles per network, each marked "simulated": true. Live data bundles
ship later (P2): until then a live data product says "available": false.
Test helpers
Test keys only; a live key gets 403 test_mode_only.
| Call | Does |
|---|---|
| POST /test/approvals/{approval_id}/approve | Approve (test mode) |
| POST /test/approvals/{approval_id}/reject | Reject (test mode) |
| POST /test/checkout-sessions/{session_id}/pay | Pay a test checkout |
| POST /test/checkout-sessions/{session_id}/review | Play staff on a held test checkout |
| POST /test/credit | Add test Jusa Credit |
| POST /test/events/trigger | Fire a sample event |
| POST /test/reset | Wipe test mode |
| POST /test/reward-links/{link_id}/claim | Claim a link, skipping the code |
| POST /test/sends/{send_id}/advance | Move a test send on |
| POST /test/zesa/availability | Take ZESA down or up (test mode) |
POST /test/sends/{id}/advancewithouttoplays the next scripted step now; with{"to": "delivered" | "failed" | "late_delivered"}it moves the send, and refuses (409 send_transition_invalid) a move a live send could not make.POST /test/zesa/availability {"state": "down"}takes ZESA down for your sandbox only and fires thezesa.availability.*events.POST /test/events/trigger {"type": "send.delivered"}fires a sample event to your endpoints (and tojusa listen). From the CLI:jusa trigger send.delivered.POST /test/resetwipes sends, rewards, batches, programs, checkout sessions, disputes, exports, events and the ledger, and resets the credit. Keys, webhook endpoints, recipients, groups, cost centres and schedules stay.
A test run
Add credit, send to a magic number, move it along, and fire an event at your endpoints:
Python
def play_a_test_send() -> None:
try:
jusa.TestHelpers.add_credit(
currency="USD",
amount="500.00",
idempotency_key="test-credit-500",
)
# …0007: retrying three times, then delivered.
test_send = jusa.Send.create(
product="airtime-usd",
target="0772550007",
amount="1.00",
idempotency_key="test-retrying",
)
# Or play it forward now.
jusa.TestHelpers.advance_send(test_send.id, to="delivered")
jusa.TestHelpers.trigger_event(type="send.delivered")
except jusa.InsufficientCreditError:
top_up_and_try_later() # nothing was charged: retry with the same idempotency key
except jusa.JusaError as jusa_error:
logger.error("Jusa refused: %s [%s]", jusa_error.code, jusa_error.request_id)
raise
Node
import { InsufficientCreditError, JusaError } from '@jusa/node';
async function playATestSend() {
try {
await jusa.testHelpers.addCredit({
currency: 'USD',
amount: '500.00',
}, { idempotencyKey: 'test-credit-500' });
// …0007: retrying three times, then delivered.
const testSend = await jusa.sends.create({
product: 'airtime-usd',
target: '0772550007',
amount: '1.00',
}, { idempotencyKey: 'test-retrying' });
// Or play it forward now.
await jusa.testHelpers.advanceSend(testSend.id, { to: 'delivered' });
await jusa.testHelpers.triggerEvent({ type: 'send.delivered' });
} catch (error) {
if (error instanceof InsufficientCreditError) {
await topUpAndTryLater(); // nothing was charged: retry with the same idempotency key
return;
}
if (error instanceof JusaError) {
console.error(`Jusa refused: ${error.code} [${error.requestId}]`);
}
throw error;
}
}
PHP
function playATestSend(\Jusa\JusaClient $jusa): void
{
try {
$jusa->testHelpers->addCredit([
'currency' => 'USD',
'amount' => '500.00',
], ['idempotency_key' => 'test-credit-500']);
// …0007: retrying three times, then delivered.
$testSend = $jusa->sends->create([
'product' => 'airtime-usd',
'target' => '0772550007',
'amount' => '1.00',
], ['idempotency_key' => 'test-retrying']);
// Or play it forward now.
$jusa->testHelpers->advanceSend($testSend->id, ['to' => 'delivered']);
$jusa->testHelpers->triggerEvent(['type' => 'send.delivered']);
} catch (\Jusa\Exception\InsufficientCreditException) {
topUpAndTryLater(); // nothing was charged: retry with the same idempotency key
} catch (\Jusa\Exception\JusaException $jusaError) {
error_log("Jusa refused: {$jusaError->getErrorCode()} [{$jusaError->getRequestId()}]");
throw $jusaError;
}
}
Go
func playATestSend(ctx context.Context) error {
_, err := jusaClient.TestHelpers.AddCredit(ctx, jusa.Params{
"currency": "USD",
"amount": "500.00",
}, jusa.WithIdempotencyKey("test-credit-500"))
if err != nil {
return fmt.Errorf("test_helpers.add_credit: %w", err)
}
// …0007: retrying three times, then delivered.
testSendResult, err := jusaClient.Sends.Create(ctx, jusa.Params{
"product": "airtime-usd",
"target": "0772550007",
"amount": "1.00",
}, jusa.WithIdempotencyKey("test-retrying"))
if err != nil {
var insufficientCredit *jusa.InsufficientCreditError
if errors.As(err, &insufficientCredit) {
topUpAndTryLater() // nothing was charged: retry with the same idempotency key
return nil
}
return fmt.Errorf("sends.create: %w", err)
}
testSend := testSendResult.Send
// Or play it forward now.
_, err = jusaClient.TestHelpers.AdvanceSend(ctx, testSend.ID, jusa.Params{
"to": "delivered",
})
if err != nil {
return fmt.Errorf("test_helpers.advance_send: %w", err)
}
_, err = jusaClient.TestHelpers.TriggerEvent(ctx, jusa.Params{
"type": "send.delivered",
})
if err != nil {
return fmt.Errorf("test_helpers.trigger_event: %w", err)
}
return nil
}
Java
void playATestSend() throws JusaException {
try {
jusa.testHelpers().addCredit(Params.of(
"currency", "USD",
"amount", "500.00"
), RequestOptions.idempotencyKey("test-credit-500"));
// …0007: retrying three times, then delivered.
var testSend = jusa.sends().create(Params.of(
"product", "airtime-usd",
"target", "0772550007",
"amount", "1.00"
), RequestOptions.idempotencyKey("test-retrying"));
// Or play it forward now.
jusa.testHelpers().advanceSend(testSend.getId(), Params.of("to", "delivered"));
jusa.testHelpers().triggerEvent(Params.of("type", "send.delivered"));
} catch (InsufficientCreditException insufficientCredit) {
topUpAndTryLater(); // nothing was charged: retry with the same idempotency key
} catch (JusaException jusaError) {
LOGGER.severe("Jusa refused: " + jusaError.getCode() + " [" + jusaError.getRequestId() + "]");
throw jusaError;
}
}
C#
async Task PlayATestSendAsync()
{
try
{
await jusa.TestHelpers.AddCreditAsync(new
{
currency = "USD",
amount = "500.00",
}, new RequestOptions { IdempotencyKey = "test-credit-500" });
// …0007: retrying three times, then delivered.
var testSendResult = await jusa.Sends.CreateAsync(new
{
product = "airtime-usd",
target = "0772550007",
amount = "1.00",
}, new RequestOptions { IdempotencyKey = "test-retrying" });
var testSend = testSendResult.As<Send>();
// Or play it forward now.
await jusa.TestHelpers.AdvanceSendAsync(testSend.Id, new { to = "delivered" });
await jusa.TestHelpers.TriggerEventAsync(new { type = "send.delivered" });
}
catch (InsufficientCreditException)
{
await TopUpAndTryLater(); // nothing was charged: retry with the same idempotency key
}
catch (JusaException jusaError)
{
logger.LogError(jusaError, "Jusa refused: {Code} [{RequestId}]", jusaError.Code, jusaError.RequestId);
throw;
}
}
Dart
Future<void> playATestSend() async {
try {
await jusa.testHelpers.addCredit({
'currency': 'USD',
'amount': '500.00',
}, RequestOptions(idempotencyKey: 'test-credit-500'));
// …0007: retrying three times, then delivered.
final testSend = await jusa.sends.create({
'product': 'airtime-usd',
'target': '0772550007',
'amount': '1.00',
}, RequestOptions(idempotencyKey: 'test-retrying')) as Send;
// Or play it forward now.
await jusa.testHelpers.advanceSend(testSend.id, {'to': 'delivered'});
await jusa.testHelpers.triggerEvent({'type': 'send.delivered'});
} on InsufficientCreditException {
await topUpAndTryLater(); // nothing was charged: retry with the same idempotency key
} on JusaException catch (jusaError) {
stderr.writeln('Jusa refused: ${jusaError.code} [${jusaError.requestId}]');
rethrow;
}
}
Ruby
def play_a_test_send
Jusa::TestHelpers.add_credit({
currency: "USD",
amount: "500.00",
}, idempotency_key: "test-credit-500")
# …0007: retrying three times, then delivered.
test_send = Jusa::Send.create({
product: "airtime-usd",
target: "0772550007",
amount: "1.00",
}, idempotency_key: "test-retrying")
# Or play it forward now.
Jusa::TestHelpers.advance_send(test_send.id, to: "delivered")
Jusa::TestHelpers.trigger_event(type: "send.delivered")
rescue Jusa::InsufficientCreditError
top_up_and_try_later # nothing was charged: retry with the same idempotency key
rescue Jusa::JusaError => jusa_error
LOGGER.error("Jusa refused: #{jusa_error.code} [#{jusa_error.request_id}]")
raise
end
curl
curl https://jusa.localhost.co.zw/dev/v1/test/credit \
--fail-with-body \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Idempotency-Key: test-credit-500" \
-H "Content-Type: application/json" \
-d '{"currency": "USD", "amount": "500.00"}'
# …0007: retrying three times, then delivered.
curl https://jusa.localhost.co.zw/dev/v1/sends \
--fail-with-body \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Idempotency-Key: test-retrying" \
-H "Content-Type: application/json" \
-d '{"product": "airtime-usd", "target": "0772550007", "amount": "1.00"}'
# Or play it forward now.
curl https://jusa.localhost.co.zw/dev/v1/test/sends/snd_…/advance \
--fail-with-body \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"to": "delivered"}'
curl https://jusa.localhost.co.zw/dev/v1/test/events/trigger \
--fail-with-body \
-H "Authorization: Bearer $JUSA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"type": "send.delivered"}'
Signatures
Test-mode deliveries are signed with the test endpoint's own secret, and carry "livemode": false, so a
handler can refuse test events in production.