Docs menuRecipes

Build

Recipes

Every use case we know of, with the calls it takes.

Every use case we know of, with the calls it takes. Tags say when something depends on a later phase or on a legal sign-off; everything untagged works today. Every sample is in all nine languages: pick yours once and the page follows. Ids such as prg_… are yours to fill in; each call is in the reference. The samples use the client you make once:

Set up once

curl

export JUSA_SECRET_KEY=jusa_sk_test_…   # a test key: nothing real moves

Sell airtime, data and ZESA at a till or in your app

For POS software, shops and agent networks, mobile money and fintech apps.

Your customer pays you face value; Jusa debits your prepaid Jusa Credit, below face on the Dealer tier, and the airtime, bundle or token goes out in seconds. One key per till, the till's own sale number as the key so a dropped connection never sells twice, and a statement that ties to the cash drawer.

  1. Load the catalogue once a day; check the number or confirm the meter before the customer pays.
  2. POST /sends with client_reference and Idempotency-Key = the till's sale number.
  3. Show the status at the counter: delivered prints the receipt (and the ZESA token); failed_credited means refund the customer, the credit is already back with you.
  4. Close the day with GET /sends?api_key=… and the month with GET /statements.

curl

# The till's sale number keys it: sent twice, it is one sale.
curl https://jusa.localhost.co.zw/dev/v1/sends \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: sale-T4-000187" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "airtime-usd",
    "target": "0771230000",
    "amount": "2.00",
    "client_reference": "sale-T4-000187",
    "metadata": {"till": "4"}
  }'

# delivered: print the receipt. failed_credited: refund the customer; the credit is back.
curl https://jusa.localhost.co.zw/dev/v1/sends/snd_… \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY"

curl https://jusa.localhost.co.zw/dev/v1/sends/snd_…/receipt \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY"

Calls: products.list · lookups.phone · quotes.create · sends.create · sends.retrieve · sends.receipt · statements.retrieve

Reward a respondent for finishing a survey

For KoboToolbox or ODK back-ends, SurveyCTO, research agencies. seed

The seed use case. One program holds the budget and the rules; each completed survey is one reward, keyed on the submission so it is paid once, forever.

  1. Create a program with a budget, a default amount and per_recipient caps (or in the dashboard).
  2. When your survey tool reports a completion, POST /rewards with the respondent and completion_id = the submission id.
  3. Listen for reward.delivered and reward.failed; a failure has already returned the budget.
Survey done, respondent paidThe form is submitted, the submission id goes in as completion_id, and US$0.50 of airtime lands on the respondent's phone. The same submission never pays twice.

curl

# For each completed submission (the program is made once, in the dashboard or with programs.create):
curl https://jusa.localhost.co.zw/dev/v1/rewards \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: survey-8812" \
  -H "Content-Type: application/json" \
  -d '{
    "program": "prg_7Hq2…",
    "recipient": {"external_id": "resp-8812", "phone": "0771230000"},
    "delivery": "direct",
    "completion_id": "8812",
    "metadata": {"survey": "form-hh-q4"}
  }'

Calls: programs.create · rewards.create · programs.create_completion

Claim cards and QR codes for offline surveys

For NGOs with enumerators.

Print a link or QR per respondent. They claim it on their own phone later; an OTP binding stops a forwarded link being claimed by someone else.

  1. Mint a batch of links with a label per enumerator and an expiry.
  2. Hand out the url or the qr_png_url; the hosted page at /r/{token} does the rest.
  3. Watch reward_link.claimed and pull a spend report grouped by program.
Claim cards for offline surveysPrint a card per respondent. They scan it later on their own phone, a one-time code binds the claim to that number, and a forwarded card cannot be claimed by anyone else.

curl

# 200 links; each has a url and a qr_png_url to print.
curl https://jusa.localhost.co.zw/dev/v1/reward-links \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: claim-cards-enumerator-7" \
  -H "Content-Type: application/json" \
  -d '{
    "program": "prg_…",
    "count": 200,
    "label": "enumerator-7",
    "bind": "otp",
    "expires_at": "2026-12-31T23:59:59Z"
  }'

Calls: reward_links.create · reward_links.list · reports.spend · exports.create

A micro-task earnings pot

For Premise-style task apps. P3

Each task earns into a pot; the pot pays out as airtime once it reaches a threshold.

  1. Set a threshold rule on the program: earn per activity, pay_at the threshold.
  2. POST an activity for each finished task; activity_id dedupes it for good.
  3. Show the person their pot with /recipients/{id}/balance.
A micro-task earnings potEach finished task earns into the person's pot, deduplicated by your activity id. When the pot reaches the threshold it pays out as airtime, by itself.

curl

# Once: each task earns US$0.25, paid out as airtime at US$1.00.
curl -X PUT https://jusa.localhost.co.zw/dev/v1/programs/prg_…/rules \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      {"kind": "threshold", "activity": "task.done", "earn": "0.25", "pay_at": "1.00"}
    ]
  }'

curl https://jusa.localhost.co.zw/dev/v1/activities \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: task-task-5521" \
  -H "Content-Type: application/json" \
  -d '{"recipient": "ext:user_123", "name": "task.done", "activity_id": "task-5521"}'

curl https://jusa.localhost.co.zw/dev/v1/recipients/ext:user_123/balance \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY"

Calls: programs.set_rules · activities.create · recipients.balance

Reimburse SMS or USSD poll costs

For Pollsters.

Pay back what answering a poll cost each participant, in one batch at the end of the day.

  1. Collect the numbers that answered.
  2. Preview, then create one batch with a line each.
Pay back what a poll costCollect the numbers that answered. At the end of the day, preview and create one batch with a line per participant, and each one gets their cost back as airtime.

curl

curl https://jusa.localhost.co.zw/dev/v1/batches/preview \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "target": "0772123456",
        "amount": "0.10",
        "client_reference": "poll-7-0772123456"
      },
      {
        "target": "0712654321",
        "amount": "0.10",
        "client_reference": "poll-7-0712654321"
      }
    ]
  }'

curl https://jusa.localhost.co.zw/dev/v1/batches \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: poll-7-reimburse" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Poll 7 reimbursement",
    "items": [
      {
        "target": "0772123456",
        "amount": "0.10",
        "client_reference": "poll-7-0772123456"
      },
      {
        "target": "0712654321",
        "amount": "0.10",
        "client_reference": "poll-7-0712654321"
      }
    ]
  }'

Calls: batches.preview · batches.create · batches.retrieve

Reward in-app actions: sign-up, KYC, first transaction

For Fintech and e-commerce apps.

Reward what a user does, once per user, with sign-up rewards held in escrow until they stick.

  1. A program per action, with one_per_phone and per_recipient caps.
  2. Reward with your own external_id so caps follow the person across numbers.
  3. Hold sign-up rewards (hold=true) and release them after your own checks.
Reward what a user doesOne reward per action, capped per person by your own user id. A sign-up reward waits in escrow until your checks pass, then releases; if they do not, you void it.

curl

curl https://jusa.localhost.co.zw/dev/v1/rewards \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: signup-u-42" \
  -H "Content-Type: application/json" \
  -d '{
    "program": "prg_signup",
    "completion_id": "signup-u-42",
    "recipient": {"external_id": "u-42", "phone": "0771230000"},
    "hold": true
  }'

# … after 7 days of real use:
curl -X POST https://jusa.localhost.co.zw/dev/v1/rewards/rwd_…/release \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: release-signup-u-42"

Calls: rewards.create · rewards.release · rewards.void

Streak rewards

For Edtech, health and fitness apps. P3

Pay when someone does the thing N times in D days.

  1. Set a streak rule: activity, count, days, amount.
  2. POST an activity each time; the reward is made when the streak completes.
Streak rewardsPost an activity each time it happens. Nothing pays until the streak is complete; then the reward is made, by itself.

curl

# Once: five lessons within seven days earn US$1.00.
curl -X PUT https://jusa.localhost.co.zw/dev/v1/programs/prg_…/rules \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      {
        "kind": "streak",
        "activity": "lesson.completed",
        "count": 5,
        "days": 7,
        "amount": "1.00"
      }
    ]
  }'

curl https://jusa.localhost.co.zw/dev/v1/activities \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: lesson-lesson-log-311" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "ext:learner-9",
    "name": "lesson.completed",
    "activity_id": "lesson-log-311"
  }'

Calls: programs.set_rules · activities.create

A two-sided referral chain

For Any app. P3

Pay the referrer (and optionally the referee) once the referee does something that counts. Depth 1, held in escrow by default.

  1. Set a referral rule with a qualifying_activity.
  2. Record the referral when they sign up.
  3. The referee's qualifying activity (or POST …/qualify) pays out.
A two-sided referralRecord the referral at sign-up. Once the referee does what counts, the held reward releases and pays the referrer, and the referee too if you choose.

curl

curl https://jusa.localhost.co.zw/dev/v1/referrals \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: referral-u-1-u-2" \
  -H "Content-Type: application/json" \
  -d '{
    "program": "prg_…",
    "referrer": {"external_id": "u-1", "phone": "0772123456"},
    "referee": {"external_id": "u-2", "phone": "0772654321"}
  }'

Calls: programs.set_rules · referrals.create · referrals.qualify

Loyalty points to airtime, data or ZESA

For Retailers, fuel stations, supermarkets. data: P2

Let members spend points on airtime or a ZESA token at face value.

  1. Show the catalog; for ZESA, quote first so the member sees the units.
  2. Send with the quote: it carries a confirmed meter.
Points to ZESA at face valueShow the catalog and quote first, so the member sees the units their points buy. The send carries the quote's confirmed meter, and the token goes straight to it.

curl

curl https://jusa.localhost.co.zw/dev/v1/quotes \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product": "zesa-usd", "amount": "10.00", "target": "37261502217"}'

curl https://jusa.localhost.co.zw/dev/v1/sends \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: redeem-9031" \
  -H "Content-Type: application/json" \
  -d '{
    "quote": "quo_…",
    "token_phone": "0772123456",
    "client_reference": "redeem-9031"
  }'

Calls: products.list · quotes.create · sends.create · meters.retrieve

Radio or brand giveaways with an audit trail

For Media. prize draws: P3, needs a licence

First-come links for listeners, with an export the auditor can check. Prize draws stay off until counsel signs them off.

  1. Mint the links; read them out or post them.
  2. Export the rewards for the audit.
Giveaways with an audit trailRead the links out or post them; the first listeners to claim are paid. Then export every reward, so the auditor can check who got what, and when.

curl

curl https://jusa.localhost.co.zw/dev/v1/reward-links \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: giveaway-breakfast-show" \
  -H "Content-Type: application/json" \
  -d '{"program": "prg_…", "count": 50, "label": "breakfast-show"}'

curl https://jusa.localhost.co.zw/dev/v1/exports \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: audit-export-2026-10" \
  -H "Content-Type: application/json" \
  -d '{"type": "rewards", "from": "2026-10-01"}'

Calls: reward_links.create · exports.create · exports.retrieve

Conditional adherence incentives

For Clinics, research trials. needs counsel: health data

Hold a reward and release it when a visit is confirmed. Sensitive-data programs stay off until Jusa approves them.

  1. A sensitive_data program with a lawful_basis, pseudonymous external_ids.
  2. Hold rewards; release or void them from your clinical system.
Conditional adherence incentivesThe reward is held from the start, under a pseudonymous id. Your clinical system releases it when the visit is confirmed, or voids it if the visit never happens.

curl

curl https://jusa.localhost.co.zw/dev/v1/rewards \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: visit-2207" \
  -H "Content-Type: application/json" \
  -d '{
    "program": "prg_trial",
    "completion_id": "visit-2207",
    "recipient": {"external_id": "P-0193", "phone": "0771230000"},
    "hold": true
  }'

# The visit did not happen:
curl -X POST https://jusa.localhost.co.zw/dev/v1/rewards/rwd_…/void \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: void-rwd_…"

Calls: rewards.create · rewards.release · rewards.void

Community health worker allowances

For Health NGOs. data: P2

A monthly allowance to every CHW, billed to the right cost centre.

  1. Recipients in a group, a cost centre with a GL code.
  2. A monthly schedule to the group.
Community health worker allowancesPut the CHWs in a group and a cost centre with your GL code. One monthly schedule pays each of them on the day, and the spend report bills it to that cost centre.

curl

curl https://jusa.localhost.co.zw/dev/v1/cost-centers \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: cost-center-chw" \
  -H "Content-Type: application/json" \
  -d '{"name": "CHW programme", "gl_code": "6100"}'

curl https://jusa.localhost.co.zw/dev/v1/groups \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: group-chws" \
  -H "Content-Type: application/json" \
  -d '{"name": "CHWs", "cost_center": "cc_…"}'

curl https://jusa.localhost.co.zw/dev/v1/schedules \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: schedule-chw-airtime" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CHW airtime",
    "cadence": "monthly",
    "day_of_month": 1,
    "hour": 8,
    "minute": 0,
    "group": "grp_…",
    "product": "airtime-usd",
    "amount": "5.00"
  }'

Calls: recipients.bulk · groups.create · cost_centers.create · schedules.create · reports.spend

In-kind ZESA assistance

For WFP-style programmes.

ZESA tokens to households in a batch, credit reserved up front, dry-run in test mode first.

  1. Each line carries the meter and a token_phone.
  2. Run it in test mode, then live.
In-kind ZESA assistanceOne batch, a line per household with its meter and a phone for the token. Credit is reserved up front, so the batch cannot run short, and you dry-run it in test mode before it goes live.

curl

curl https://jusa.localhost.co.zw/dev/v1/batches \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: assistance-2026-10-hh-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "October assistance",
    "items": [
      {
        "type": "zesa",
        "meter": "37261502217",
        "token_phone": "0772123456",
        "amount": "10.00",
        "client_reference": "assistance-2026-10-hh-0001"
      }
    ]
  }'

Calls: batches.preview · batches.create · statements.retrieve

Clinic or antenatal check-in

For Health. P3 needs counsel: health data

A reward link paid only by checking in at the clinic, inside its geofence and hours.

  1. A program with a geofence.
  2. The person checks in from the widget or your app.
Clinic or antenatal check-inThe reward link pays only when the person checks in inside the clinic's geofence, during its hours. Then the airtime lands on their phone.

curl

curl https://jusa.localhost.co.zw/dev/v1/checkins \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: checkin-lnk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "link": "lnk_…",
    "lat": -17.8252,
    "lng": 31.0522,
    "accuracy_m": 25,
    "phone": "0771230000",
    "choice": "airtime"
  }'

Calls: checkins.create · reward_links.create

Learn to earn data

For Edtech. data: P2 rules: P3

Finish lessons, earn data bundles. Live data bundles ship in P2; test mode has a simulated list.

  1. List a data product's bundles.
  2. Reward with type=data and a bundle_id.
Learn to earn dataFinish the lessons and your app rewards a data bundle by its bundle_id. The bundle reaches the learner's phone.

curl

# The bundles to choose from:
curl https://jusa.localhost.co.zw/dev/v1/products/econet-data-usd/bundles \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY"

curl https://jusa.localhost.co.zw/dev/v1/rewards \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: course-17" \
  -H "Content-Type: application/json" \
  -d '{
    "program": "prg_…",
    "completion_id": "course-17",
    "recipient": {"phone": "0771230000"},
    "type": "data",
    "bundle_id": "econet-1gb-30d"
  }'

Calls: products.list_bundles · rewards.create

Exam-season data stipends

For Schools and tutors. data: P2

A weekly stipend through exam season, stopped by deleting the schedule.

  1. A weekly schedule to the class group.
Exam-season data stipendsOne weekly schedule pays the whole class through exam season. Delete the schedule when the exams end and the payments stop.

curl

curl https://jusa.localhost.co.zw/dev/v1/schedules \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: schedule-exam-data" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Exam data",
    "cadence": "weekly",
    "day_of_week": 0,
    "hour": 7,
    "minute": 0,
    "group": "grp_…",
    "product": "airtime-usd",
    "amount": "2.00"
  }'

Calls: schedules.create · schedules.delete

A bursary split across data and ZESA

For Bursary funds. data: P2

Two schedules to the same people: airtime for data, ZESA to their meter.

  1. Recipients carry a meter and a token_phone.
  2. One airtime and one ZESA schedule.
A bursary split across data and ZESATwo schedules to the same students: airtime for data to their phone, and ZESA to the meter at home, on the same day.

curl

curl https://jusa.localhost.co.zw/dev/v1/schedules \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: schedule-bursary-zesa" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bursary ZESA",
    "cadence": "monthly",
    "day_of_month": 1,
    "hour": 8,
    "minute": 0,
    "recipients": ["rcp_…"],
    "product": "zesa-usd",
    "amount": "10.00"
  }'

Calls: recipients.create · schedules.create

Gig and rider allowances

For Delivery and ride apps.

Airtime per completed trip, capped per rider per day.

  1. A per-recipient daily cap on the rider.
  2. Reward each trip, keyed on the trip id.
Gig and rider allowancesAirtime for every completed trip, keyed on the trip id, up to the rider's daily cap.

curl

# Once per rider: at most US$3.00 a day.
curl -X PATCH https://jusa.localhost.co.zw/dev/v1/recipients/ext:rider-4 \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"daily_cap": "3.00"}'

curl https://jusa.localhost.co.zw/dev/v1/rewards \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: trip-77120" \
  -H "Content-Type: application/json" \
  -d '{
    "program": "prg_trips",
    "completion_id": "trip-77120",
    "recipient": "ext:rider-4",
    "amount": "0.50"
  }'

Calls: recipients.update · rewards.create

Employer ZESA as a benefit

For Employers.

Workforce as it is in the Jusa app: departments, plans, allocation and the GL journal.

  1. Allocate to people by department.
  2. Pull the journal for your GL.
Employer ZESA as a benefitAllocate ZESA to your people by department, as in the Jusa app's Workforce, and pull the journal straight into your general ledger.

curl

# The month's GL journal, as CSV for your accounting system:
curl -G https://jusa.localhost.co.zw/dev/v1/workforce/journal \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -d from=2026-09-01 \
  -d to=2026-09-30 \
  -d format=csv

Calls: workforce.allocate · workforce.journal · meters.retrieve

Pay per verified sale

For Field sales teams.

Escrow the commission until the return window closes; void it if the sale comes back.

  1. A program with hold.mode=escrow and auto_release_after.
  2. Void on a return.
Pay per verified saleThe commission waits in escrow until the return window closes, then releases to the seller. If the sale comes back first, you void it.

curl

curl https://jusa.localhost.co.zw/dev/v1/programs \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: program-sales-commission" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales commission",
    "default_amount": "1.00",
    "budget": "200.00",
    "hold": {"mode": "escrow", "auto_release_after": "14d"}
  }'

Calls: programs.create · rewards.create · rewards.void

Outage apology credit

For Banks and ISPs.

One batch to every affected customer, safe to retry with one Idempotency-Key.

  1. Build the items from your incident list.
  2. Create the batch with an idempotency key.
Outage apology creditOne batch to every customer the outage touched. Retry it with the same Idempotency-Key and nobody is paid twice.

curl

curl https://jusa.localhost.co.zw/dev/v1/batches \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: incident-2026-10-07" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Sorry for Tuesday",
    "items": [
      {
        "target": "0772123456",
        "amount": "1.00",
        "client_reference": "incident-2026-10-07-0772123456"
      },
      {
        "target": "0712654321",
        "amount": "1.00",
        "client_reference": "incident-2026-10-07-0712654321"
      }
    ]
  }'

Calls: batches.create

Diaspora: send ZESA or airtime home

For Remittance apps.

The sender pays by card on a checkout session; you get the attribution and the token. Recurring by card is not possible (there is no stored card): use your own Jusa Credit and a schedule.

  1. Create a checkout session; send the payer to its url.
  2. Hear checkout.session.fulfilled.
Diaspora: send ZESA or airtime homeThe sender pays by card on your checkout session. The token goes to the meter at home, and you hear checkout.session.fulfilled.

curl

curl https://jusa.localhost.co.zw/dev/v1/checkout-sessions \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: order-8812" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "zesa",
    "target": "37261502217",
    "amount": "20.00",
    "currency": "USD",
    "token_phone": "0772123456",
    "success_url": "https://app.example/thanks",
    "cancel_url": "https://app.example/basket",
    "client_reference": "order-8812"
  }'

# Send the payer to the session's url.

Calls: checkout_sessions.create · checkout_sessions.retrieve · meters.retrieve

Landlord and tenant split-meter settlement

For Property apps.

Each tenant pays their share by card; the receipt proves what went to the meter.

  1. A checkout session per tenant.
  2. Share the receipt of the delivered send.
Landlord and tenant split-meter settlementEach tenant pays their share by card on their own checkout session. The receipt of the delivered send proves what went to the meter.

curl

# The meter, its owner and the units that went to it:
curl https://jusa.localhost.co.zw/dev/v1/sends/snd_…/receipt \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY"

Calls: checkout_sessions.create · sends.receipt

Checkout cashback as airtime

For E-commerce. data: P2

A percentage back as airtime after each order, from a program budget.

  1. Reward on order completion, keyed on the order id.
Checkout cashback as airtimeAfter each order, a percentage back as airtime from your program's budget, keyed on the order id so it is paid once.

curl

curl https://jusa.localhost.co.zw/dev/v1/rewards \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: cashback-order-8812" \
  -H "Content-Type: application/json" \
  -d '{
    "program": "prg_cashback",
    "completion_id": "order-8812",
    "recipient": {"phone": "0771230000"},
    "amount": "0.84"
  }'

Calls: rewards.create

Solar or IoT ZESA auto-buy

For Smart-plug and monitor vendors.

The device reads the token from the send.delivered webhook. token_phone is required: ZETDC needs a number to notify. Cap the device's key.

  1. A restricted key with tokens:read and a daily spend cap.
  2. Send ZESA when the monitor says so; read the token from the webhook.
Solar or IoT ZESA auto-buyWhen the battery runs low, the device buys ZESA on a capped key and reads the token from the send.delivered webhook. The meter takes it and the battery charges.

curl

curl https://jusa.localhost.co.zw/dev/v1/sends \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: auto-reading-9921" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "zesa",
    "target": "37261502217",
    "amount": "5.00",
    "token_phone": "0772123456",
    "client_reference": "auto-reading-9921"
  }'

Calls: keys.create · sends.create · webhook_endpoints.create

Availability-aware buying

For Any ZESA seller.

Check ZESA before promising a token now; queue with max_hold, or fail fast with on_zesa_down=fail.

  1. Read /status or hear zesa.availability.*.
  2. Choose on_zesa_down and max_hold per send.
Availability-aware buyingWhile ZESA is down the send waits in the queue, up to its max_hold. When ZESA answers again it goes, and the token reaches the meter.

curl

curl https://jusa.localhost.co.zw/dev/v1/status \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY"

# Queue it while ZESA is down, for up to 6 hours:
curl https://jusa.localhost.co.zw/dev/v1/sends \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: order-8812" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "zesa",
    "target": "37261502217",
    "amount": "10.00",
    "token_phone": "0772123456",
    "on_zesa_down": "queue",
    "max_hold": "6h",
    "client_reference": "order-8812"
  }'

Calls: status.retrieve · status.history · sends.create

Band-aware ZESA quotes

For Budgeting apps.

Show how many units the money buys now and after the monthly reset.

  1. Quote with the meter.
Quote the units before they buyZESA's bands reset each month, so once the cheaper bands are used up, US$10 buys fewer units now than after the reset. One quote with the meter shows both.

curl

curl https://jusa.localhost.co.zw/dev/v1/quotes \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product": "zesa-usd", "amount": "20.00", "target": "37261502217"}'

Calls: quotes.create

AI agent tool calls over MCP

For Assistants and chat bots.

Give an agent an ak key: it sends within a threshold and to known numbers; anything more asks a person, who approves with their payment PIN. Live agents are off until an owner turns them on.

  1. Create an agent key with a threshold.
  2. Point your MCP client at /dev/v1/mcp.
Let an agent call Jusa over MCPAn agent key sends on its own within its threshold and to known numbers. Anything more waits for a person, who approves with their payment PIN.

curl

curl https://jusa.localhost.co.zw/dev/v1/keys \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "ak", "label": "assistant", "approval_threshold": {"USD": "10.00"}}'

# The key is shown once: put it straight into the agent's secret store.
# MCP server: https://jusa.localhost.co.zw/dev/v1/mcp (Authorization: Bearer <the ak key>)

Calls: keys.create · mcp.call · approvals.list

WhatsApp chatbot commerce

For Bot builders.

Confirm the meter in the chat, send a checkout link, confirm delivery from the webhook.

  1. meters.retrieve for the name to confirm.
  2. A checkout session; reply with its url.
Sell in the chatYour bot confirms the meter's name, replies with a checkout link, and hears from the webhook when the token has gone, so it can say so in the chat.

curl

curl https://jusa.localhost.co.zw/dev/v1/meters/37261502217 \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY"

Calls: meters.retrieve · checkout_sessions.create

Escrowed conditional rewards

For Anyone.

The general primitive: reserve now, decide later. Held credit shows as credit.reserved.

  1. hold=true on the reward.
  2. release (optionally for less) or void.
Reserve now, decide laterA held reward reserves Jusa Credit. Release it, for less if you like, and it goes to the phone; void it and the credit comes back.

curl

curl https://jusa.localhost.co.zw/dev/v1/rewards \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: task-9" \
  -H "Content-Type: application/json" \
  -d '{
    "program": "prg_…",
    "completion_id": "task-9",
    "recipient": "ext:u-9",
    "hold": true
  }'

# Release it for less, or void it:
curl https://jusa.localhost.co.zw/dev/v1/rewards/rwd_…/release \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: release-task-9" \
  -H "Content-Type: application/json" \
  -d '{"amount": "0.40"}'

Calls: rewards.create · rewards.release · rewards.void · credit.list_reservations

Geofenced event check-in

For Ag shows, churches, retail. P3

Links that pay only at the venue, during the event.

  1. A program with a geofence and a window.
  2. Check-ins from the widget.
Pay at the venue, on the dayThe link pays only for a check-in inside the event's geofence and during its hours. From anywhere else, or after the gates close, it does not.

curl

curl https://jusa.localhost.co.zw/dev/v1/programs \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: program-ag-show" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ag show",
    "default_amount": "0.50",
    "budget": "100.00",
    "sources": ["links"],
    "geofence": {"lat": -17.8252, "lng": 31.0522, "radius_m": 300}
  }'

Calls: programs.create · checkins.create

Farmer extension incentives

For EcoFarmer-scale programmes.

Reward attendance and adoption, keyed on your farmer ids; batches for the season-end bonus.

  1. Reward per attendance.
  2. A batch at season end.
Reward attendance, then the seasonEach field day's attendance is a reward keyed on your own farmer id, so it pays once. At season end, one batch pays the bonus to everyone who qualified.

curl

curl https://jusa.localhost.co.zw/dev/v1/rewards \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: attend-s14-F-2231" \
  -H "Content-Type: application/json" \
  -d '{
    "program": "prg_extension",
    "completion_id": "attend-s14-F-2231",
    "recipient": {"external_id": "F-2231", "phone": "0771230000"}
  }'

Calls: rewards.create · batches.create

Programmatic family allowance

For Bank standing orders. OAuth family: P3

For your own customers' families: recipients plus a payday schedule. /family needs OAuth user tokens and answers 501 until then.

  1. The family members as recipients.
  2. A payday schedule.
A family allowance on paydayYour customer's family as recipients and a payday schedule: on the day, each one's airtime goes out as its own send, and you hear about each.

curl

curl https://jusa.localhost.co.zw/dev/v1/schedules \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: schedule-gogo-rcp_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gogo'\''s airtime",
    "cadence": "payday",
    "hour": 9,
    "minute": 0,
    "recipients": ["rcp_…"],
    "product": "airtime-usd",
    "amount": "5.00"
  }'

Calls: recipients.create · schedules.create

Bill-shock rescue

For Telco-adjacent fintech.

You spot a zero balance in your own systems (Jusa cannot see it) and send US$0.50, capped per person per day.

  1. A per-recipient daily cap.
  2. One send per rescue, keyed on your alert.
Rescue a zero balanceYour own systems spot that a customer has run out (Jusa cannot see their balance) and send US$0.50, keyed on your alert and capped per person per day.

curl

curl https://jusa.localhost.co.zw/dev/v1/sends \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: rescue-alert-5120" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "0771230000",
    "amount": "0.50",
    "product": "airtime-usd",
    "recipient": "ext:cust-301",
    "client_reference": "rescue-alert-5120"
  }'

Calls: sends.create · recipients.update

Emergency power for medical devices

For Health IoT. needs counsel: health data

A monitor triggers a ZESA reward from the patient's own program: the program's budget is the cap, and on_zesa_down=fail on the program so a caregiver hears at once. (A send's program is attribution only: it draws on no budget.)

  1. A program per patient: choices ["zesa"], a budget, on_zesa_down="fail".
  2. A direct reward per alarm, keyed on it; listen to zesa.availability.* and reward.failed.
Keep the oxygen onA home oxygen monitor triggers a ZESA reward from the patient's own program, whose budget is the cap. If ZESA is down, it fails at once, so a caregiver hears straight away.

curl

curl https://jusa.localhost.co.zw/dev/v1/programs \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: program-patient-12" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Patient 12",
    "currency": "USD",
    "default_amount": "5.00",
    "budget": "60.00",
    "choices": ["zesa"],
    "on_zesa_down": "fail"
  }'

# One reward per alarm:
curl https://jusa.localhost.co.zw/dev/v1/rewards \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: alarm-880" \
  -H "Content-Type: application/json" \
  -d '{
    "program": "prg_patient_12",
    "completion_id": "alarm-880",
    "type": "zesa",
    "recipient": {
      "external_id": "patient-12",
      "meter": "37261502217",
      "token_phone": "0772123456"
    }
  }'

Calls: programs.create · rewards.create · status.retrieve

Crowdsourced price or outage reports

For Civic tech. P3

Each verified report is an activity; a threshold rule pays out.

  1. A threshold rule.
  2. An activity per verified report.
Pay for verified reportsEach verified price or outage report is an activity. When a reporter reaches the threshold, the rule pays them, once.

curl

curl https://jusa.localhost.co.zw/dev/v1/activities \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: report-4410" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "ext:reporter-3",
    "name": "report.verified",
    "activity_id": "report-4410"
  }'

Calls: activities.create · rewards.create

Data perk on ticket scan

For Promoters. data: P2

A link printed on the ticket, bound to the buyer's phone.

  1. A link per ticket, bind=otp with the buyer's phone_hint.
A data perk on the ticketEach ticket carries its own link, bound to the buyer's phone. Claiming it asks for a one-time code, so only the buyer gets the data.

curl

curl https://jusa.localhost.co.zw/dev/v1/reward-links \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: perk-TKT-00931" \
  -H "Content-Type: application/json" \
  -d '{
    "program": "prg_gig",
    "recipient": {"phone": "0771230000"},
    "bind": "otp",
    "phone_hint": "0771230000",
    "label": "TKT-00931"
  }'

Calls: reward_links.create

Fundraising thank-you airtime

For Churches and schools.

Thank each donor with a little airtime after their gift.

  1. Reward per donation, keyed on the gift.
Thank every donorEach gift is one reward keyed on the gift, so a little airtime thanks the donor once, and only once, however often the webhook arrives.

curl

curl https://jusa.localhost.co.zw/dev/v1/rewards \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Idempotency-Key: gift-1207" \
  -H "Content-Type: application/json" \
  -d '{
    "program": "prg_thanks",
    "completion_id": "gift-1207",
    "recipient": {"phone": "0771230000"},
    "amount": "0.50"
  }'

Calls: rewards.create

Payday ZESA nudge

For HR platforms.

ZESA units are banded and reset monthly: a quote shows what the money buys before and after the reset, so staff choose when to buy.

  1. Quote on payday.
  2. A payday schedule for those who opt in.
A payday ZESA nudgeOn payday, a quote shows each person what their money buys now and after the monthly reset. Those who opt in get a payday schedule, and the token goes straight to their meter.

curl

curl https://jusa.localhost.co.zw/dev/v1/quotes \
  --fail-with-body \
  -H "Authorization: Bearer $JUSA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product": "zesa-usd", "amount": "30.00", "target": "37261502217"}'

Calls: quotes.create · schedules.create