Unified Payment Gateway API

Collect money from Airtel Money and TNM Mpamba customers in Malawi, and pay money out to them, through one API and one wallet.

Authentication

Every request carries your API key as a Bearer token:

Authorization: Bearer <YOUR_API_KEY>

• Your key is shown once, when your account is created or when the key is regenerated. Store it in a server-side secret store.
• You can regenerate the key and set your webhook (callback) URL yourself, in the management portal under Integration. The old key stops working as soon as a new one is issued.
• Never put the key in a mobile app or browser code. Call the gateway from your own server.

Request rules

Send JSON with Content-Type: application/json. All amounts are Malawi Kwacha (MWK).

Money in responses is always a string with two decimals, such as "1500.00". Parse it as a decimal, never as a float.

Transaction status

Collect a payment (STK push)

Sends a payment prompt to the customer's phone. They approve it with their PIN. The response only means the prompt was sent: the result arrives later by webhook.

curl -X POST {{BASE}}/v1/collections/stkpush \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "msisdn": "0991234567",
    "amount": 1000,
    "tenant_reference": "ORDER-10045",
    "narration": "Order 10045"
  }'

{
  "gateway_reference": "MLIMIP261014K3F9Q2X7A1",
  "tenant_reference": "ORDER-10045",
  "provider": "airtel",
  "status": "pending",
  "amount": "1000.00",
  "fee_amount": "0.00",
  "provider_charge_amount": "0.00",
  "customer_amount": "1000.00",
  "wallet_amount": "1000.00",
  "message": "STK push sent to customer for approval"
}

• customer_amount is what the customer is asked to approve. It is higher than amount only when your account passes the network charge on to the payer (see charges).
• wallet_amount is what your wallet will be credited on success.
• If the network refuses the request outright, you get 502 PROVIDER_REJECTED_REQUEST with "status": "failed", and nothing was charged.

Quote a payout

Tells you what a payout would cost and whether your balance covers it. Nothing is created and nothing moves. msisdn is required because the network decides the charge.

curl -X POST {{BASE}}/v1/disbursements/quote \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "msisdn": "0881234567", "amount": 500 }'

{
  "provider": "tnm",
  "amount": "500.00",
  "fee_amount": "0.00",
  "provider_charge_amount": "10.28",
  "total_debit": "510.28",
  "available_balance": "84250.00",
  "sufficient_funds": true,
  "currency": "MWK"
}

Send a payout

Pays money from your wallet to a mobile money number. Both networks usually answer straight away, so in most cases the response is the final result.

curl -X POST {{BASE}}/v1/disbursements \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "msisdn": "0991234567",
    "amount": 100,
    "tenant_reference": "GROWER-PAYOUT-2219",
    "narration": "Tobacco sale 14 Oct"
  }'

Three possible answers

{
  "gateway_reference": "TEST261014BJCFQ9H1I8",
  "tenant_reference": "GROWER-PAYOUT-2219",
  "provider": "airtel",
  "status": "success",
  "amount": "100.00",
  "fee_amount": "0.00",
  "provider_charge_amount": "2.06",
  "wallet_amount": "102.06",
  "message": "Disbursement completed"
}

{
  "error": "PROVIDER_REJECTED_REQUEST",
  "gateway_reference": "TEST261014Q8VW2MZK4N",
  "tenant_reference": "GROWER-PAYOUT-2220",
  "status": "failed"
}

Refusals before anything is sent, where nothing is held:

Look up one transaction

Returns the current state, using your reference. If the transaction is still pending, the gateway first asks the network for the latest status, so a lookup can settle it.

curl {{BASE}}/v1/transactions/ORDER-10045 \
  -H "Authorization: Bearer $API_KEY"

{
  "tenant_reference": "ORDER-10045",
  "gateway_reference": "MLIMIP261014K3F9Q2X7A1",
  "type": "collection",
  "status": "failed",
  "amount": "1000.00",
  "wallet_amount": "1000.00",
  "msisdn": "265991234567",
  "failure_reason": "INSUFFICIENT_BALANCE",
  "failure_message": "You have insufficient funds. Please deposit money into your account and try again."
}

An unknown reference returns 404 TRANSACTION_NOT_FOUND.

List transactions

Newest first. All query parameters are optional.

curl "{{BASE}}/v1/transactions?status=success&type=collection&from=2026-10-01&limit=100" \
  -H "Authorization: Bearer $API_KEY"

{
  "total": 312,
  "limit": 100,
  "offset": 0,
  "transactions": [ { …same object as the single lookup… } ]
}

Wallet balance

curl {{BASE}}/v1/wallets/balance \
  -H "Authorization: Bearer $API_KEY"

{
  "currency": "MWK",
  "balance": "84250.00",
  "hold_balance": "0.00",
  "status": "active"
}

balance is what you can spend now. hold_balance is money reserved for payouts that are still pending. It goes back to balance if they fail, and leaves the wallet if they succeed.

Wallet statement

Every movement on your wallet, newest first. Takes from, to, limit (default 50, max 200) and offset.

{
  "currency": "MWK",
  "balance": "84250.00",
  "hold_balance": "0.00",
  "total": 58,
  "limit": 50,
  "offset": 0,
  "entries": [
    {
      "entry_type": "credit",
      "amount": "1000.00",
      "balance_after": "84250.00",
      "description": "Collection",
      "tenant_reference": "ORDER-10045",
      "gateway_reference": "MLIMIP261014K3F9Q2X7A1",
      "transaction_type": "collection",
      "reference": null,
      "created_at": "2026-10-14T08:21:09.000Z"
    }
  ]
}

entry_type is one of credit, debit, hold, release, reversal, manual_credit or manual_debit. Manual entries are made by the operator, for example a bank top-up, and carry their reference.

Webhooks

The gateway POSTs a JSON message to your callback URL when a transaction reaches a final state that you have not already been told about in a response.

{
  "event_id": "d04d3635-2b8a-ba25-d92c-05f5ba43db83",
  "tenant_reference": "ORDER-10045",
  "gateway_reference": "MLIMIP261014K3F9Q2X7A1",
  "type": "collection",
  "status": "success",
  "amount": "1000.00",
  "wallet_amount": "1000.00",
  "msisdn": "265991234567",
  "failure_reason": null,
  "failure_message": null,
  "timestamp": "2026-10-14T08:21:09.799Z"
}

The body is the same transaction object as the lookup, plus event_id and timestamp.

Your endpoint must

• Be public HTTPS, and must not be the gateway's own address. Pointing it at the gateway makes it call itself.
• Reply with any 2xx within 10 seconds. Do slow work after replying.
• Deduplicate on event_id. Delivery is at least once, so the same event can arrive more than once. It has the same event_id every time, so credit your customer only on the first.

Retries: if your endpoint does not answer 2xx, the gateway retries up to 6 times, waiting 5 s, 10 s, 20 s, 40 s and 80 s between attempts. After that, a background job keeps trying about once a minute. Missed one anyway? Look the transaction up; it always has the current state.

Receiving webhooks

Webhooks are plain JSON POSTs with no signature and nothing to set up. They start arriving as soon as your callback URL is saved in the portal.

app.post('/gateway/callback', express.json(), (req, res) => {
  const event = req.body;
  res.sendStatus(200);                  // answer first, then work
  handleOnce(event.event_id, event);    // skip if event_id already processed
});

$event = json_decode(file_get_contents('php://input'), true);
http_response_code(200);
// Process once per $event['event_id'], e.g. a UNIQUE column on event_id.
if ($event['status'] === 'success') {
  // mark $event['tenant_reference'] as paid
}

Fees and network charges

Airtel and TNM take a charge on each transaction. Depending on how your account is set up, either the gateway covers it or it is added for the payer. Your operator may also set a service fee on your account.

Example, K1,000 collection with the charge passed on to the payer: the customer approves about K1,020.56, and your wallet gets K1,000. For a payout, call quote first to see total_debit before sending.

Error codes

Every error has an error code. Most also have a message, and validation errors list each problem in details.

{
  "error": "VALIDATION_ERROR",
  "details": ["amount must have at most 2 decimal places"]
}

Failure reasons

A failed transaction carries one of these in failure_reason, whichever network it was on. Base your logic on failure_reason, and show failure_message to people.

Go-live checklist

• The API key is stored server-side, and no request is made from a browser or app.
• Every request has a unique tenant_reference, saved before you call the gateway.
• On a timeout or 5xx, you look the reference up instead of resending.
• Your callback URL is set in the portal, is public HTTPS, and is your own server.
• Your callback endpoint answers 2xx quickly and does slow work afterwards.
• Webhooks are processed once per event_id.
• Payouts treat 200 as paid, 202 as wait, 502 as failed and refunded.
• Money is handled as decimal strings, never floats.