StataPay Developer Platform

StataPay API Documentation

StataPay is a mobile money payment platform for Zambian businesses. Use the StataPay API to collect payments, send payouts, issue refunds, look up account names, and receive signed webhook events for MTN MoMo, Airtel Money, Zamtel Kwacha, and card collections. All merchant requests use HTTPS at https://api.statapay.com/api/v1 and authenticate with a wallet secret key in the Authorization: Bearer header.

The interactive API console, searchable endpoint navigation, and sandbox number explorer require JavaScript. This page contains the complete reference in plain HTML so search engines and AI assistants can read it.

Environments and authentication

The API key selects the environment. A sec_test_ key operates on your sandbox wallet and supports deterministic test numbers. A sec_live_ key operates on your live wallet and always contacts the real mobile money provider. There is no separate test-mode flag and no environment parameter on payment requests. Keep secret keys on your server and never ship them in browser or mobile client code.

Sandbox test numbers

Test numbers are matched only for sandbox transactions. Live keys and live wallets never simulate test numbers, even when the recipient number matches one below. Numbers can be sent in local 09... or international 260... form.

Test number	Scenario	Final outcome
0966615440	success	successful
0966615441	failed	failed
0966615442	cancelled	cancelled
0966615443	insufficient_funds	failed
0966615444	invalid_phone	failed
0966615445	declined	failed
0966615446	expired	expired
0966615447	timeout	expired
0966615448	processing	pending until callback
0966615449	unknown_error	failed

Any other valid Zambian number: in a sandbox wallet, collections succeed immediately. Sandbox payouts succeed when the wallet has enough available balance; otherwise they fail with an insufficient balance reason.

Processing: the processing number stays pending until you resolve it with POST /api/v1/sandbox/simulate/callback using action approve, decline, or timeout. The timeout test number is finalised as expired, so no transaction remains pending after a final outcome.

Core endpoints

POST /api/v1/collections — request a mobile money or card payment.
GET /api/v1/collections/{transaction}/status — read the current collection state.
POST /api/v1/refunds — refund all or part of a successful collection.
POST /api/v1/disbursements — send a payout to a mobile wallet.
POST /api/v1/disbursements/batch — send up to 100 payouts in one request.
GET /api/v1/wallet — read the wallet bound to your API key.
GET /api/v1/balance — read aggregate and per-wallet balances.
GET /api/v1/wallet/ledger — list immutable wallet ledger entries.
GET /api/v1/lookups/mobile-account — resolve a registered account holder name.
GET /api/v1/webhooks/deliveries — inspect webhook attempts and retries.
POST /api/v1/transactions/{transaction}/webhooks/resend — resend a transaction webhook.
POST /api/v1/sandbox/top-up — add virtual balance to a sandbox wallet.

Transaction statuses

The engine uses 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; a provider timeout is finalised as expired.

Webhooks

StataPay sends signed HTTPS POST events when a transaction reaches a final status. Every webhook includes an X-StatPay-Signature header in the form t=timestamp,v1=signature. The signature is HMAC-SHA256 over the string timestamp.rawBody using your webhook secret. Reject timestamps older than five minutes and make your handler idempotent using the event ID or transaction ID. Respond with any 2xx status within 15 seconds. Failed deliveries are retried with backoff and can be inspected or resent through the API.

Frequently asked questions

Do sandbox test numbers work with live API keys?

No. Test numbers are matched only for sandbox wallets. A live key sends every number to the real mobile money provider, even if it matches a test number.

What happens if I use a number that is not a sandbox test number?

In a sandbox wallet, any other valid Zambian number simulates a successful collection immediately. Payouts succeed when the sandbox wallet has enough available balance; otherwise they fail with insufficient balance.

How do I test a payment that stays pending?

Use the processing test number 0966615448. It stays pending until you resolve it with POST /api/v1/sandbox/simulate/callback using action approve, decline, or timeout.

What is the difference between sandbox and live?

The API key selects the environment. sec_test_ keys operate on sandbox wallets and support deterministic test numbers. sec_live_ keys operate on live wallets and call real mobile money providers.

How are StataPay webhooks signed?

Every webhook includes an X-StatPay-Signature header in the form t=timestamp,v1=signature. The signature is HMAC-SHA256 over the string timestamp.rawBody using your webhook secret. Reject timestamps older than five minutes and make your handler idempotent.

Which transaction statuses are final?

successful, failed, cancelled, and expired are final. pending and requires_action are not settled. A provider timeout is finalised as expired, so transactions never remain pending after a final outcome.

Can I retry a failed webhook?

Yes. POST /api/v1/transactions/{transaction}/webhooks/resend queues an immediate redelivery. Delivery attempts and response codes are available at GET /api/v1/webhooks/deliveries.

Which currency and mobile money rails are supported?

ZMW is the settlement currency. MTN MoMo, Airtel Money, and Zamtel Kwacha are supported for collections and payouts. Cards are available for collections with a hosted checkout redirect.

Start building

Create a StataPay account, open a sandbox wallet, and generate a sec_test_ API key. The API console on this page can send real sandbox requests using a key you enter; the key is kept only in your browser tab session.

Create an account · Sign in · Open the interactive documentation