1Introduction
The API lets your system collect payments from customers' mobile money wallets and send payouts to mobile wallets in Tanzania, using a single, secure REST interface. The products and endpoints are listed in the table at the top of this page.
1.3 Credentials are per product
Each product you are approved for (Collection, Disbursement, Name Check) has its own API key and API secret. A token generated with Collection credentials can only call the Collection endpoint, a token generated with Disbursement credentials can only call the Disbursement endpoint, and so on. The Wallet Balance endpoint accepts a token from any of your products.
2Environments
Develop and test in the sandbox first. When your integration is complete and approved, switch the base URL and credentials to live.
http://102.223.19.6:8010
For development and testing. No real money moves. Sandbox credentials are sent to you by email when your sandbox application is approved.
https://secure.payguard.tz
Real transactions with real money. Live credentials are issued after your account is approved for production.
All endpoint paths are relative to the base URL. For example, the live token endpoint is:
https://secure.payguard.tz/api/client/auth/generate-token
2.1 Sandbox behaviour
| Operation | What happens in sandbox |
|---|---|
| Generate token | Works exactly as in live. |
| Collection | The request is validated (phone number, network, duplicate ID, limits) and recorded. No USSD prompt is sent. The response data is null. An Inquiry on the transaction returns SUCCESS. |
| Disbursement | The request is validated and your sandbox disbursement balance is debited. No money is sent, and the payout cannot be looked up with Inquiry. |
| Name Check | Returns a fixed test name for valid Tigo/Airtel numbers. |
| Callbacks | Callbacks are not sent in sandbox, because no mobile network is involved. Test your callback handler with the sample payloads in Section 11. |
3Getting started
3.1 API credentials
You receive an API key and API secret for each approved product. The secret is shown only once; store it in a secure secrets store or environment variable, never in source code, mobile apps or web pages. If you believe a secret has been exposed, contact us immediately so it can be rotated; all tokens issued with the old secret then stop working.
3.2 IP whitelisting
API access can be restricted to the public IP addresses of your servers. Send the list of your server IP addresses (IPv4) during onboarding and whenever they change. When whitelisting is enforced for your account, requests from any other address are rejected:
- Token requests from a non-whitelisted IP fail with
401 Invalid credentials. - API requests from a non-whitelisted IP fail with
403 IP_NOT_ALLOWED.
3.3 Callback URL
Give us an HTTPS URL on your server that will receive transaction results (see Section 11). A separate callback URL can be configured for each product. The URL must be publicly reachable and should respond quickly with HTTP 200.
3.4 Funding your disbursement balance
Payouts are paid from your disbursement balance. Top up this balance before sending payouts. A payout is rejected if the balance cannot cover the amount plus any applicable charge.
4Authentication
Every API call (except token generation) must carry a valid Bearer access token in the Authorization header.
4.1 Generate an access token
| Field | Type | Required | Description |
|---|---|---|---|
apiKey | string | Required | The API key of the product you want to use. |
apiSecret | string | Required | The matching API secret. |
curl -X POST https://secure.payguard.tz/api/client/auth/generate-token \
-H "Content-Type: application/json" \
-d '{
"apiKey": "YOUR_API_KEY",
"apiSecret": "YOUR_API_SECRET"
}'
Response · 200 OK
{
"success": true,
"code": 200,
"message": "Token generated successfully",
"data": {
"token": "eyJhbGciOiJIUzI1NiJ9...",
"refresh_token": "eyJhbGciOiJIUzI1NiJ9...",
"token_type": "Bearer",
"expires_in": 900
}
}
Response · 401 Unauthorized
{ "success": false, "code": 401, "message": "Invalid credentials", "data": null }
For security, the same Invalid credentials message is returned for a wrong key, a wrong secret, a product that is not yet approved, or a request from a non-whitelisted IP address.
4.2 Use the token
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...
4.3 Token lifetime
- A token is valid for
expires_inseconds (currently 900 seconds = 15 minutes). - Cache the token and reuse it for all requests until shortly before it expires. Do not request a new token for every call.
- To renew, call
generate-tokenagain with your key and secret. (refresh_tokenis kept only for compatibility; there is no separate refresh endpoint.) - If a call returns
401with codeTOKEN_EXPIRED,TOKEN_INVALIDorTOKEN_REVOKED, generate a new token and retry the request once.
5Request and response format
5.1 Headers
| Header | Value |
|---|---|
Content-Type | application/json (for POST requests) |
Authorization | Bearer <token> (all endpoints except token generation) |
5.2 Response envelope
{
"success": true, // true if the request was accepted / succeeded
"code": 200, // same as the HTTP status code
"message": "...", // human-readable description
"data": { ... } // endpoint-specific result, or null
}
Security errors raised before your request reaches the endpoint (expired token, blocked IP) use a short form with a machine-readable code:
{ "success": false, "code": "TOKEN_EXPIRED", "message": "Token has expired" }
5.3 HTTP status codes
| HTTP | Meaning | What to do |
|---|---|---|
200 | Request accepted or succeeded (success: true). | Continue with the flow. |
400 | Invalid input: a required field is missing. data lists the fields and messages. | Fix the request. Do not retry unchanged. |
401 | Missing, invalid, expired or revoked token, or invalid credentials. | Generate a new token and retry once. |
403 | Request from an IP address that is not whitelisted. | Call from a whitelisted server or ask us to add the IP. |
501 | The request was understood but rejected by a business rule (e.g. duplicate transaction ID, insufficient balance). message explains why. | Read message; see Section 13. |
{
"success": false, "code": 400, "message": "Invalid input",
"data": { "phoneNumber": "Phone number is required", "amount": "Amount is required" }
}
Field names and enumeration values are case-sensitive. Amounts are numbers in TZS (Tanzanian Shillings).
6Collection (checkout)
Request a payment from a customer's mobile money wallet. The customer receives a USSD prompt on their phone and confirms with their PIN.
Token: generated with your Collection credentials.
| Field | Type | Required | Description |
|---|---|---|---|
transactionId | string | Required | Your own unique reference for this payment. Must be unique for your product; a repeated ID is rejected. You use this ID for inquiries and it is returned in callbacks. |
phoneNumber | string | Required | The customer's mobile money number, e.g. 255712345678. See Section 14 for accepted formats. |
amount | number | Required | Amount in TZS. Maximum 5,000,000 per transaction. |
provider | string | Required | The customer's mobile network: Mpesa, Tigo or Airtel. |
curl -X POST https://secure.payguard.tz/api/client/mno/checkout \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"transactionId": "INV-2026-000123",
"phoneNumber": "255712345678",
"amount": 15000,
"provider": "Mpesa"
}'
Response · 200 OK (request accepted)
{
"success": true,
"code": 200,
"message": "Request submitted success",
"data": {
"isSuccess": true,
"message": "Collection request submitted successfully",
"data": "17944583216784C1A9F2E0B3D" // internal transaction ID
}
}
Response · 501 (rejected)
{ "success": false, "code": 501, "message": "This transaction id is exists", "data": null }
6.2 What happens next
- The customer receives a payment prompt on their phone and enters their PIN.
- When the network confirms, your collection balance is credited and a SUCCESS callback is posted to your Collection callback URL.
- If the customer cancels, has insufficient funds, or does not respond in time, you receive a FAILED callback.
- If you did not receive a callback, check the status with the Inquiry API (Section 8).
7Disbursement (payout)
Send money from your disbursement balance to a customer's mobile wallet.
Token: generated with your Disbursement credentials.
| Field | Type | Required | Description |
|---|---|---|---|
transactionId | string | Required | Your own unique reference for this payout. A repeated ID is rejected, which protects you from paying twice. |
phoneNumber | string | Required | The recipient's mobile money number, e.g. 255754123456. |
amount | number | Required | Amount in TZS. Maximum 5,000,000 per transaction. |
provider | string | Required | The recipient's mobile network: Mpesa, Tigo or Airtel. |
fullName | string | Required | The recipient's full name. |
provider and the payout is delivered to that number.curl -X POST https://secure.payguard.tz/api/client/mno/disburse \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"transactionId": "PAYOUT-2026-004512",
"phoneNumber": "255754123456",
"amount": 50000,
"provider": "Mpesa",
"fullName": "Juma Hamisi"
}'
Response · 200 OK (request accepted)
{
"success": true,
"code": 200,
"message": "Disbursement request submitted successfully",
"data": {
"isSuccess": true,
"message": "Disbursement request submitted successfully",
"data": "PAYOUT-2026-004512" // your transactionId
}
}
7.2 Balance and refunds
- When the payout is accepted, the amount (plus your charge, where applicable) is reserved from your disbursement balance.
- If the payout fails, the reserved amount is returned to your disbursement balance automatically, and you receive a FAILED callback.
- If there is not enough balance, the request is rejected with
Insufficient disbursement balanceand nothing is sent.
transactionId can pay the recipient twice. Wait for the final status via callback or Inquiry. Retry with a new ID only after a confirmed FAILED.8Transaction inquiry
Get the current status of a transaction you created, using your own transactionId.
Token: generated with your Collection credentials.
curl https://secure.payguard.tz/api/client/mno/inquire/INV-2026-000123 \
-H "Authorization: Bearer $TOKEN"
{
"success": true,
"code": 200,
"message": "Transaction is paid",
"data": {
"trxId": "INV-2026-000123",
"isPaid": true,
"status": "SUCCESS",
"message": "This transaction is already paid",
"paymentDoneBy": "255712345678",
"providerReceiptId": "DKA7X2NP2L",
"reference": "INV-2026-000123",
"providerTransactionId": "17944583216784C1A9F2E0B3D"
}
}
| Field | Description |
|---|---|
trxId / reference | Your transactionId. |
status | SUCCESS, PENDING or FAILED. Use this field to decide. See Section 12. |
isPaid | true only when status is SUCCESS. |
message | Description of the status or failure reason. |
paymentDoneBy | Phone number involved in the transaction, when available. |
providerReceiptId | The mobile network's receipt number, when available. Useful for customer queries. |
providerTransactionId | Our internal transaction ID. Quote it when contacting support. |
8.2 When to call Inquiry
- Wait at least 2 minutes after submitting before the first inquiry. During the first 2 minutes the response is always PENDING, because the customer may still be entering their PIN.
- If the status is still PENDING, retry every few minutes (for example after 2, 5, 10 and 30 minutes). Do not poll more often than once a minute per transaction.
- A transaction that is not found returns
501withTransaction does not exist.
9Name check
Look up the registered name of a mobile wallet, for example to confirm the recipient before a payout.
Token: generated with your Name Check credentials. Each successful lookup uses one name-check credit from your name-check wallet.
| Field | Type | Required | Description |
|---|---|---|---|
phoneNumber | string | Required | The wallet number to look up. |
provider | string | Required | Tigo or Airtel (currently supported networks for name check). |
curl -X POST https://secure.payguard.tz/api/client/mno/name-checkout \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "phoneNumber": "255654123456", "provider": "Tigo" }'
// 200 OK
{ "success": true, "code": 200, "message": "...",
"data": { "firstName": "Asha", "lastName": "Mwinyi" } }
If your name-check wallet is empty, the request is rejected with Insufficient balance to perform name check.
10Wallet balance
Get your current collection and disbursement balances.
Token: generated with any of your product credentials.
curl https://secure.payguard.tz/api/client/mno/balance -H "Authorization: Bearer $TOKEN"
// 200 OK
{ "success": true, "code": 200, "message": "Wallet balance retrieved",
"data": { "collections": 1250000.00, "disbursements": 480000.00 } }
| Field | Description |
|---|---|
collections | Funds collected from customers that have not yet been settled to your bank account. |
disbursements | Funds available for payouts. |
11Callbacks (webhooks)
When a transaction reaches a result, we send an HTTP POST with a JSON body to the callback URL configured for the product.
POST https://your-server.example/payguard/callback
Content-Type: application/json
{
"transactionId": "INV-2026-000123",
"reference": "INV-2026-000123",
"status": "SUCCESS",
"success": true,
"message": "Transaction completed successfully",
"paymentDoneBy": "255712345678",
"providerReceiptId": "DKA7X2NP2L",
"providerTransactionId": "17944583216784C1A9F2E0B3D"
}
| Field | Description |
|---|---|
transactionId | Your transactionId from the original request. Use it to find the order or payout in your system. |
reference | Same as transactionId. |
status | SUCCESS, PENDING or FAILED. |
success | true only for SUCCESS. Kept for older integrations; prefer status. |
message | Result description, or the reason for failure. |
paymentDoneBy | Phone number involved, when available. |
providerReceiptId | Mobile network receipt number, when available. |
providerTransactionId | Our internal transaction ID. |
11.2 Interpreting the status
| Status | Meaning | Your action |
|---|---|---|
| SUCCESS | Money has moved. Collection: credited to your collection balance. Disbursement: delivered to the recipient. | Mark as paid and deliver the service. |
| PENDING | Still in progress. Another callback will follow. | Do nothing yet; wait for the final callback or use Inquiry. |
| FAILED | The transaction did not complete. For disbursements, the amount has been returned to your disbursement balance. | Mark as failed. You may start a new attempt with a new transactionId. |
"success": false and "status": null. Treat this as FAILED, and confirm with the Inquiry API if you need certainty.11.3 Handling callbacks correctly
- Respond fast. Return HTTP
200within a few seconds, and do any heavy work after responding. - Be idempotent. You may receive more than one callback for the same transaction (for example PENDING, then SUCCESS). Process each
transactionIdonly once per final status, and never deliver value twice. - Never move backwards. Once a transaction is SUCCESS in your system, ignore later non-success callbacks for it and contact support if they conflict.
- Do not depend on callbacks alone. Callbacks are delivered once. If your endpoint was down or returned an error, the callback is not resent. Use the Inquiry API to reconcile any transaction that is still PENDING in your system.
- Verify before high-value fulfilment. For high-value orders, confirm the result with the Inquiry API before delivering value.
12Transaction statuses
Every transaction ends in one final status. Your system should track it as follows: Submitted (your request is accepted with HTTP 200; treat it as PENDING), Processing (the mobile network processes it; callbacks or Inquiry may return PENDING), then Final: SUCCESS or FAILED. Final statuses do not change.
| Situation | Recommended handling |
|---|---|
| Request rejected (HTTP 400/501) | Nothing was created at the network. Fix the cause shown in message. You may retry; for a duplicate-ID rejection, use Inquiry on the original ID instead. |
| Network or timeout error while calling the API | You do not know if the request was accepted. Do not resend with a new ID. Call Inquiry with the same transactionId; if it does not exist, it is safe to resend with the same ID. |
| PENDING for a long time | Keep polling Inquiry at increasing intervals. Some network confirmations can take longer than usual. If a payout is still PENDING after 24 hours, contact support with the providerTransactionId. |
| SUCCESS | Final. Deliver value once. |
| FAILED | Final. For payouts, the funds are back in your disbursement balance. |
transactionId is rejected, resending with the same ID after an uncertain error can never create a second payment. Generating a new ID for the same order can.13Error reference
| HTTP | Message / code | Cause and action |
|---|---|---|
| 400 | Invalid input | A required field is missing. data lists each field. Fix the request. |
| 401 | Invalid credentials | Wrong key or secret, product not approved, or token request from a non-whitelisted IP. |
| 401 | TOKEN_EXPIRED | Token older than its lifetime. Generate a new token. |
| 401 | TOKEN_INVALID | Token is malformed or not an API token. Generate a new token. |
| 401 | TOKEN_REVOKED | Your credentials were rotated after the token was issued. Generate a new token with the new secret. |
| 401 | CLIENT_INACTIVE | Your product is no longer active. Contact support. |
| 403 | IP_NOT_ALLOWED | Request from an IP address that is not whitelisted. |
| 501 | This transaction id is exists | The transactionId was already used. Use Inquiry for the original, or a new ID for a new transaction. |
| 501 | Amount should be less than 5,000,000 | Amount above the per-transaction limit. Split into smaller transactions if allowed. |
| 501 | Invalid provider supplied | The provider value is not supported for this operation. See Section 14. |
| 501 | Invalid phone number | The phone number is not in an accepted format. |
| 501 | No matching tariff range for amount | No charge band is configured for this amount. Contact support. |
| 501 | Insufficient disbursement balance | Your disbursement balance does not cover the payout and charge. Top up and retry. |
| 501 | Insufficient balance to perform name check | Name-check wallet is empty. Top up name-check credits. |
| 501 | You don't allowed to access this product | The token belongs to a different product (e.g. a Disbursement token used for checkout). Use the matching credentials. |
| 501 | Product is not approved | The product is not active for this environment. Contact support. |
| 501 | Transaction does not exist | No transaction with this transactionId (Inquiry). |
14Reference data
14.1 Mobile networks (provider)
| Value | Network | Collection | Disbursement | Name check |
|---|---|---|---|---|
Mpesa | Vodacom M-Pesa | ✓ | ✓ | – |
Tigo | Yas (Tigo Pesa / Mixx) | ✓ | ✓ | ✓ |
Airtel | Airtel Money | ✓ | ✓ | ✓ |
Values are case-sensitive. For disbursements, we select the delivery channel.
14.2 Phone number formats
| Format | Example |
|---|---|
| International, no plus (recommended) | 255712345678 (12 digits) |
| International with plus | +255712345678 |
| Local with leading zero | 0712345678 (10 digits) |
| Local without zero | 712345678 (9 digits) |
14.3 Limits and rules
| Item | Value |
|---|---|
| Currency | TZS only |
| Maximum amount per collection / disbursement | TZS 5,000,000 |
| Access token lifetime | 900 seconds (15 minutes); see expires_in |
| Earliest useful inquiry | 2 minutes after submission |
transactionId | Unique per product; recommended: letters, digits, - and _, up to 50 characters |
| Time zone of timestamps | East Africa Time (UTC+03:00) |
15Best practices and go-live checklist
Security
- Keep API secrets on the server, in a secrets store or environment variables.
- Call the API only from whitelisted back-end servers over HTTPS (live).
- Restrict who in your team can see live credentials; ask for rotation when staff with access leave.
- Serve your callback URL over HTTPS.
Reliability
- Cache and reuse the access token; renew it before it expires.
- Use a unique
transactionIdper payment, and the same ID when retrying after an uncertain error. - Run a scheduled job that sends Inquiry for every transaction still PENDING in your system.
- Set request timeouts of at least 30 seconds.
- Log every request, response and callback with the
transactionId.