# Jusa

> One API to send Zimbabwean airtime, data bundles and ZESA electricity tokens from prefunded Jusa Credit, and to reward people for things they do (a finished survey, a trip, a referral). REST at https://jusa.localhost.co.zw/dev/v1, SDKs in eight languages, signed webhooks, a sandbox, and an MCP server for AI agents.

Things to know before writing code against it:

- A test key (`jusa_sk_test_…`) reaches the account's sandbox twin and never moves real money; a live key does. Build with the test key, then swap the key.
- Amounts are decimal strings (`"5.00"`) in USD or ZWG, separate balances, always at face value.
- Every POST that moves money needs an `Idempotency-Key`; `client_reference` (sends) and `completion_id` (rewards) dedupe for good.
- Sends settle in the background (`pending`, then `delivered` or `failed_credited`). Never resend a send in `unknown`. Card payments are never refunded to the card: failures come back as Jusa Credit.
- `failed_credited` is not quite final: if the network confirms the send late (within 48 hours), Jusa debits the Jusa Credit again, marks it `delivered` and fires `send.late_delivered`. Handle that event, and resend with a new `client_reference` only if your product accepts that risk.
- Webhooks: verify `Jusa-Signature` on the raw body, dedupe on the event id, answer 2xx within 10 seconds.
- Errors are one envelope with a stable `code`; the SDKs raise one class per error type.

## Docs

- [Jusa API docs](https://jusa.localhost.co.zw/developers/docs): Send airtime, data and ZESA tokens, and reward people, from one API.
- [Quickstart: reward a survey](https://jusa.localhost.co.zw/developers/docs/quickstart): Your first reward in ten minutes, in test mode.
- [Test mode](https://jusa.localhost.co.zw/developers/docs/test-mode): A sandbox with its own Jusa Credit and numbers that act out every outcome.
- [SDKs and tools](https://jusa.localhost.co.zw/developers/docs/sdks): Python, Node, PHP, Go, Java, .NET, Dart and Ruby from our own registries; the jusa CLI, Postman, the OpenAPI document and MCP.
- [Keys and authentication](https://jusa.localhost.co.zw/developers/docs/authentication): Four kinds of key, two modes, scopes and caps.
- [Errors](https://jusa.localhost.co.zw/developers/docs/errors): One envelope, stable codes, and why a send failed.
- [Idempotency](https://jusa.localhost.co.zw/developers/docs/idempotency): Retry anything that moves money without paying twice.
- [Webhooks](https://jusa.localhost.co.zw/developers/docs/webhooks): Signed events, how to verify them, and every type we send.
- [Settlement and money](https://jusa.localhost.co.zw/developers/docs/settlement): What happens to a send and its money, state by state.
- [Recipes](https://jusa.localhost.co.zw/developers/docs/recipes): Every use case we know of, with the calls it takes.
- [API reference](https://jusa.localhost.co.zw/developers/docs/reference): Every endpoint, generated from the OpenAPI document.
- [API Terms, Acceptable Use and DPA](https://jusa.localhost.co.zw/developers/docs/terms): What you accept with your first live key.
- [Changelog](https://jusa.localhost.co.zw/developers/changelog): what changed, by API version.

## Survey tools

- [KoboToolbox guide](https://jusa.localhost.co.zw/developers/docs/guides/kobotoolbox): REST Services post each submission to a small relay that rewards it.
- [SurveyCTO guide](https://jusa.localhost.co.zw/developers/docs/guides/surveycto): A form webhook posts each submission to a relay that rewards it.
- [Google Forms guide](https://jusa.localhost.co.zw/developers/docs/guides/google-forms): An Apps Script trigger rewards each response, no server of your own.
- [Typeform guide](https://jusa.localhost.co.zw/developers/docs/guides/typeform): A signed Typeform webhook, checked, then rewarded.

## API

- [OpenAPI 3.1 document](https://jusa.localhost.co.zw/dev/v1/openapi.json): every endpoint, request body and object; the source of truth for paths and fields.
- [Postman collection](https://jusa.localhost.co.zw/developers/postman.json): every request, with an Idempotency-Key on each one that moves money.
- [SDK registries](https://jusa.localhost.co.zw/sdk/): install the Python, Node, PHP, Go, Java, .NET, Dart and Ruby SDKs.

## AI agents

- [AI agents: Skill, llms.txt and MCP](https://jusa.localhost.co.zw/developers/ai): set up an agent to build with Jusa, or to act through the MCP server.
- [Jusa Agent Skill](https://jusa.localhost.co.zw/developers/ai/jusa-skill.zip): Integrate Jusa, the Zimbabwean airtime, data-bundle and ZESA electricity-token API, into code. Use when a task sends airtime, data or ZESA tokens; rewards survey respondents, app users, riders or workers from a program (completion_id); handles Jusa webhooks; calls https://jusa.localhost.co.zw/dev/v1 directly or through a Jusa SDK (Python jusa, Node @jusa/node, PHP jusa/jusa-php, Go, Java or Kotlin, .NET, Dart or Flutter, Ruby); sets up the Jusa MCP server or an agent key; or debugs a Jusa error code, failure_code, Idempotency-Key or webhook signature. Not for using the consumer Jusa app.
- [MCP server](https://jusa.localhost.co.zw/dev/v1/mcp): POST JSON-RPC 2.0 with an agent key (`jusa_ak_…`); tools to send airtime, buy ZESA, reward and look things up, with a person approving above a threshold.

## Optional

- [Every docs page as one Markdown file](https://jusa.localhost.co.zw/llms-full.txt): the docs above and the API reference, in full.