Developer portal

Integration guide

The complete Wooble Pay Gateway API reference, sandbox details and go-live checklist.

Merchant API · Version 1.0 · November 2026. For registered merchants and their technical teams. Keep your API credentials confidential. Currency: TZS.

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.

SANDBOX

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.

LIVE (PRODUCTION)

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

OperationWhat happens in sandbox
Generate tokenWorks exactly as in live.
CollectionThe 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.
DisbursementThe request is validated and your sandbox disbursement balance is debited. No money is sent, and the payout cannot be looked up with Inquiry.
Name CheckReturns a fixed test name for valid Tigo/Airtel numbers.
CallbacksCallbacks are not sent in sandbox, because no mobile network is involved. Test your callback handler with the sample payloads in Section 11.
Keep environments separate. Sandbox and live credentials are different and are not interchangeable. Store them separately and make sure your live system never points to the sandbox URL, or the reverse.

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.
Tip. Call the API only from your back-end servers. Never call it directly from a browser or mobile app: that would expose your credentials and the request would come from your users' IP addresses.

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

POST/api/client/auth/generate-token
FieldTypeRequiredDescription
apiKeystringRequiredThe API key of the product you want to use.
apiSecretstringRequiredThe 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_in seconds (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-token again with your key and secret. (refresh_token is kept only for compatibility; there is no separate refresh endpoint.)
  • If a call returns 401 with code TOKEN_EXPIRED, TOKEN_INVALID or TOKEN_REVOKED, generate a new token and retry the request once.

5Request and response format

5.1 Headers

HeaderValue
Content-Typeapplication/json (for POST requests)
AuthorizationBearer <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

HTTPMeaningWhat to do
200Request accepted or succeeded (success: true).Continue with the flow.
400Invalid input: a required field is missing. data lists the fields and messages.Fix the request. Do not retry unchanged.
401Missing, invalid, expired or revoked token, or invalid credentials.Generate a new token and retry once.
403Request from an IP address that is not whitelisted.Call from a whitelisted server or ask us to add the IP.
501The 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.

POST/api/client/mno/checkout

Token: generated with your Collection credentials.

FieldTypeRequiredDescription
transactionIdstringRequiredYour 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.
phoneNumberstringRequiredThe customer's mobile money number, e.g. 255712345678. See Section 14 for accepted formats.
amountnumberRequiredAmount in TZS. Maximum 5,000,000 per transaction.
providerstringRequiredThe 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

  1. The customer receives a payment prompt on their phone and enters their PIN.
  2. When the network confirms, your collection balance is credited and a SUCCESS callback is posted to your Collection callback URL.
  3. If the customer cancels, has insufficient funds, or does not respond in time, you receive a FAILED callback.
  4. If you did not receive a callback, check the status with the Inquiry API (Section 8).
Charges. Your transaction charge is set in your agreement. Depending on that agreement, the charge is deducted from the amount credited to you, or added to the amount the customer is asked to pay, or shared between you and the customer.

7Disbursement (payout)

Send money from your disbursement balance to a customer's mobile wallet.

POST/api/client/mno/disburse

Token: generated with your Disbursement credentials.

FieldTypeRequiredDescription
transactionIdstringRequiredYour own unique reference for this payout. A repeated ID is rejected, which protects you from paying twice.
phoneNumberstringRequiredThe recipient's mobile money number, e.g. 255754123456.
amountnumberRequiredAmount in TZS. Maximum 5,000,000 per transaction.
providerstringRequiredThe recipient's mobile network: Mpesa, Tigo or Airtel.
fullNamestringRequiredThe recipient's full name.
Payout routing. We choose the channel that delivers each payout. Always send the recipient's own network in 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 balance and nothing is sent.
Never resend a payout that is PENDING. A payout whose status is PENDING may still complete. Sending it again with a new 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.

GET/api/client/mno/inquire/{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"
  }
}
FieldDescription
trxId / referenceYour transactionId.
statusSUCCESS, PENDING or FAILED. Use this field to decide. See Section 12.
isPaidtrue only when status is SUCCESS.
messageDescription of the status or failure reason.
paymentDoneByPhone number involved in the transaction, when available.
providerReceiptIdThe mobile network's receipt number, when available. Useful for customer queries.
providerTransactionIdOur 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 501 with Transaction does not exist.

9Name check

Look up the registered name of a mobile wallet, for example to confirm the recipient before a payout.

POST/api/client/mno/name-checkout

Token: generated with your Name Check credentials. Each successful lookup uses one name-check credit from your name-check wallet.

FieldTypeRequiredDescription
phoneNumberstringRequiredThe wallet number to look up.
providerstringRequiredTigo 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.

GET/api/client/mno/balance

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 } }
FieldDescription
collectionsFunds collected from customers that have not yet been settled to your bank account.
disbursementsFunds 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"
}
FieldDescription
transactionIdYour transactionId from the original request. Use it to find the order or payout in your system.
referenceSame as transactionId.
statusSUCCESS, PENDING or FAILED.
successtrue only for SUCCESS. Kept for older integrations; prefer status.
messageResult description, or the reason for failure.
paymentDoneByPhone number involved, when available.
providerReceiptIdMobile network receipt number, when available.
providerTransactionIdOur internal transaction ID.

11.2 Interpreting the status

StatusMeaningYour action
SUCCESSMoney has moved. Collection: credited to your collection balance. Disbursement: delivered to the recipient.Mark as paid and deliver the service.
PENDINGStill in progress. Another callback will follow.Do nothing yet; wait for the final callback or use Inquiry.
FAILEDThe 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.
Handle a missing status. If the request could not be delivered to the mobile network at all, the callback may arrive with "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 200 within 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 transactionId only 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.

SituationRecommended 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 APIYou 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 timeKeep 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.
SUCCESSFinal. Deliver value once.
FAILEDFinal. For payouts, the funds are back in your disbursement balance.
Using the same transactionId is your safety net. Because a repeated 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

HTTPMessage / codeCause and action
400Invalid inputA required field is missing. data lists each field. Fix the request.
401Invalid credentialsWrong key or secret, product not approved, or token request from a non-whitelisted IP.
401TOKEN_EXPIREDToken older than its lifetime. Generate a new token.
401TOKEN_INVALIDToken is malformed or not an API token. Generate a new token.
401TOKEN_REVOKEDYour credentials were rotated after the token was issued. Generate a new token with the new secret.
401CLIENT_INACTIVEYour product is no longer active. Contact support.
403IP_NOT_ALLOWEDRequest from an IP address that is not whitelisted.
501This transaction id is existsThe transactionId was already used. Use Inquiry for the original, or a new ID for a new transaction.
501Amount should be less than 5,000,000Amount above the per-transaction limit. Split into smaller transactions if allowed.
501Invalid provider suppliedThe provider value is not supported for this operation. See Section 14.
501Invalid phone numberThe phone number is not in an accepted format.
501No matching tariff range for amountNo charge band is configured for this amount. Contact support.
501Insufficient disbursement balanceYour disbursement balance does not cover the payout and charge. Top up and retry.
501Insufficient balance to perform name checkName-check wallet is empty. Top up name-check credits.
501You don't allowed to access this productThe token belongs to a different product (e.g. a Disbursement token used for checkout). Use the matching credentials.
501Product is not approvedThe product is not active for this environment. Contact support.
501Transaction does not existNo transaction with this transactionId (Inquiry).

14Reference data

14.1 Mobile networks (provider)

ValueNetworkCollectionDisbursementName check
MpesaVodacom M-Pesa✓✓–
TigoYas (Tigo Pesa / Mixx)✓✓✓
AirtelAirtel Money✓✓✓

Values are case-sensitive. For disbursements, we select the delivery channel.

14.2 Phone number formats

FormatExample
International, no plus (recommended)255712345678 (12 digits)
International with plus+255712345678
Local with leading zero0712345678 (10 digits)
Local without zero712345678 (9 digits)

14.3 Limits and rules

ItemValue
CurrencyTZS only
Maximum amount per collection / disbursementTZS 5,000,000
Access token lifetime900 seconds (15 minutes); see expires_in
Earliest useful inquiry2 minutes after submission
transactionIdUnique per product; recommended: letters, digits, - and _, up to 50 characters
Time zone of timestampsEast 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 transactionId per 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.

Go-live checklist