# StataPay

> StataPay is a mobile money payment platform for Zambian businesses. The StataPay API supports MTN MoMo, Airtel Money, and Zamtel Kwacha collections and payouts, refunds, account lookups, wallet balances, and signed webhook events. The settlement currency is ZMW.

## Developer documentation

- [API documentation](https://statapay.com/developers/docs): Complete reference with an interactive request console, generated cURL/JavaScript/Python/PHP examples, and a sandbox test-number explorer.
- [Sandbox test numbers](https://statapay.com/developers/docs#sandbox): Deterministic phone numbers for every payment outcome.
- [Collections](https://statapay.com/developers/docs#collections): Request a mobile money or card payment.
- [Payouts](https://statapay.com/developers/docs#disbursements): Send money from a wallet to a mobile money subscriber.
- [Refunds](https://statapay.com/developers/docs#refunds): Refund all or part of a successful collection.
- [Webhooks](https://statapay.com/developers/docs#webhooks): HMAC-SHA256 signatures, event types, retries, and idempotency.
- [Transaction statuses](https://statapay.com/developers/docs#statuses): Canonical status values and final-state rules.
- [Error responses](https://statapay.com/developers/docs#errors): HTTP status codes and error body shapes.

## Product

- [Features](https://statapay.com/features): Collections, payouts, payment links, wallets, ledger, and reporting.
- [White-label partnerships](https://statapay.com/partnerships): Offer StataPay mobile money payments under your own brand and set your own fees.
- [About StataPay](https://statapay.com/about): The company and its payments platform for Zambia.
- [Create an account](https://statapay.com/register): Open a merchant account and sandbox wallet.

## API essentials

- Base URL: `https://api.statapay.com/api/v1`
- Authentication: `Authorization: Bearer sec_test_...` for sandbox or `Authorization: Bearer sec_live_...` for live.
- Environment selection: the API key selects sandbox or live. There is no separate test-mode flag and no environment parameter on payment requests.
- Live keys never simulate test numbers. Every live request is sent to the real mobile money provider.
- Collections and single disbursements require an `Idempotency-Key` header between 8 and 128 characters.
- Content type: `application/json`. All responses are JSON.
- Currency: ZMW.

## Sandbox test numbers

Test numbers are intercepted only for sandbox wallets. Any other valid Zambian number in a sandbox wallet succeeds immediately for collections. Sandbox payouts succeed when the wallet has enough available balance; otherwise they fail with an insufficient balance reason.

| Local number | International number | Scenario | Outcome |
| --- | --- | --- | --- |
| 0966615440 | 260966615440 | success | successful |
| 0966615441 | 260966615441 | failed | failed |
| 0966615442 | 260966615442 | cancelled | cancelled |
| 0966615443 | 260966615443 | insufficient_funds | failed |
| 0966615444 | 260966615444 | invalid_phone | failed |
| 0966615445 | 260966615445 | declined | failed |
| 0966615446 | 260966615446 | expired | expired |
| 0966615447 | 260966615447 | timeout | expired |
| 0966615448 | 260966615448 | processing | pending until callback |
| 0966615449 | 260966615449 | unknown_error | failed |

The processing number stays pending until resolved with `POST /api/v1/sandbox/simulate/callback` using action `approve`, `decline`, or `timeout`. A provider timeout is finalised as `expired`, so no transaction remains pending after a final outcome.

## Core endpoints

- `POST /api/v1/collections` — create a collection.
- `GET /api/v1/collections/{transaction}/status` — read collection status.
- `POST /api/v1/refunds` — create a refund.
- `POST /api/v1/disbursements` — create a payout.
- `POST /api/v1/disbursements/batch` — create up to 100 payouts.
- `GET /api/v1/disbursements/{transaction}/status` — read payout status.
- `GET /api/v1/transactions` — list transactions.
- `GET /api/v1/transactions/{transaction}` — get one transaction.
- `GET /api/v1/wallet` — read the bound wallet.
- `GET /api/v1/balance` — read aggregate and per-wallet balances.
- `GET /api/v1/wallet/ledger` — list ledger entries.
- `GET /api/v1/lookups/mobile-account` — resolve a mobile account holder name.
- `GET /api/v1/webhooks/deliveries` — list webhook delivery attempts.
- `POST /api/v1/transactions/{transaction}/webhooks/resend` — resend a transaction webhook.
- `POST /api/v1/sandbox/top-up` — credit a sandbox wallet.
- `GET /api/v1/sandbox/test-numbers` — read the test-number map.

## Transaction statuses

`pending`, `requires_action`, `successful`, `failed`, `cancelled`, and `expired`. Only `successful` means funds settled. Final statuses never move backwards. The API does not use separate processing or timeout statuses.

## Webhooks

Every webhook includes `X-StatPay-Signature: t=timestamp,v1=signature`. The signature is HMAC-SHA256 over `timestamp.rawBody` using the webhook secret. Reject timestamps older than five minutes, respond with a 2xx status within 15 seconds, and make handlers idempotent using the event ID or transaction ID. Failed deliveries are retried with backoff.

## Contact

- Website: https://statapay.com
- Documentation: https://statapay.com/developers/docs
- Support: support@statapay.com