Zetu Pay developer documentation

Zetu Pay lets a business or an individual collect M-Pesa payments and get paid, with one API. You can charge a customer's phone, share a hosted payment link, accept paybill payments, and receive signed webhook events when a payment changes state.

Collection channels

For supported STK Push and payment-link collections, choose an enabled channel in your account. C2B Paybill payments use the account code shown in your dashboard. Available methods depend on channel approval and configuration.

How a payment flows

1. Your server calls POST /payments (or a customer opens a payment link).
2. We send an M-Pesa prompt to the customer's phone. The response is 202: the payment is PENDING.
3. The customer enters their PIN. M-Pesa tells us the result.
4. We update the payment and send you a signed webhook. You can also fetch the payment at any time.

Never fulfil an order from the 202 response alone. Fulfil when you receive payment.success, or when GET /payments/:id says SUCCESS.

Quickstart

1. Create an account and verify your email.
2. In the dashboard, open Developers and create an API key. Copy it now: it is shown once.
3. Set your webhook URL (a public HTTPS address) and copy your signing secret.
4. Send your first payment request:

curl -X POST https://backend.zetopay.co.ke/api/v1/payments \
  -H "Authorization: Bearer zp_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"amount": 500, "phone": "0712345678", "external_reference": "ORDER-1001"}'

const res = await fetch('https://backend.zetopay.co.ke/api/v1/payments', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.ZETUPAY_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ amount: 500, phone: '0712345678', external_reference: 'ORDER-1001' }),
});
const { success, data, error } = await res.json();
if (!success) throw new Error(`${error.code}: ${error.message}`);
console.log(data.id, data.status); // clx9k2..., PENDING

$ch = curl_init('https://backend.zetopay.co.ke/api/v1/payments');
curl_setopt_array($ch, [
  CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ZETUPAY_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(['amount' => 500, 'phone' => '0712345678', 'external_reference' => 'ORDER-1001']),
]);
$out = json_decode(curl_exec($ch), true);
if (!$out['success']) { throw new Exception($out['error']['code'] . ': ' . $out['error']['message']); }
echo $out['data']['status']; // PENDING

import os, requests
r = requests.post(
    "https://backend.zetopay.co.ke/api/v1/payments",
    headers={"Authorization": f"Bearer {os.environ['ZETUPAY_KEY']}"},
    json={"amount": 500, "phone": "0712345678", "external_reference": "ORDER-1001"},
    timeout=15,
)
body = r.json()
if not body["success"]:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]["status"])  # PENDING

The customer's phone shows the M-Pesa prompt. When they approve it you receive a payment.success webhook.

Authentication

Send your API key as a Bearer token on every request:

Authorization: Bearer zp_live_xxxxxxxxxxxxxxxx

• Create keys in Dashboard, Developers. We store only a hash, so a lost key cannot be recovered: create a new one.
• Keep keys on your server. Never put one in a website, mobile app, repository or support chat.
• A key has the full access of your account. A suspended account's keys stop working.
• Dashboard logins use a short-lived session token instead of a key. Some actions (creating API keys, connecting channels) need a login session and refuse API keys on purpose.

Requests and responses

• Base URL: https://backend.zetopay.co.ke/api/v1
• Format: JSON in, JSON out, UTF-8, HTTPS only.
• Money: amounts are in Kenyan shillings as numbers, for example 1500. M-Pesa moves whole shillings only, so amounts with cents such as 1500.50 are rejected with a validation error.
• Phone numbers may be 0712345678, 254712345678 or +254712345678. We return the 254… form.
• Times are ISO 8601 in UTC.

Every response has the same envelope:

// success
{ "success": true, "data": { ... } }
// failure
{ "success": false, "error": { "code": "INVALID_PHONE", "message": "Enter a valid Kenyan phone number" } }

Branch on error.code (stable), not on message (for people).

Idempotency

• Payments: send a unique external_reference per order. Retrying the same reference with the same amount, phone, channel and callback details returns the original payment and does not start another prompt. Reusing a reference with different payment details returns 409 REFERENCE_REUSED.
• Withdrawals: an Idempotency-Key header is required. Retrying with the same key and same amount, external reference and callback URL returns the original withdrawal. Reusing the key with different details returns 409 IDEMPOTENCY_KEY_REUSED.

Errors

Registration

Sign-up is a short guided flow at /register: choose Personal or Business, enter your details, verify your email with a 6-digit code, then (when you are ready) verify your identity. You can pause at any step and return later: log in and the flow resumes where you stopped.

These endpoints back that flow. They use a login session, not an API key.

Account verification

Some account features, including withdrawals or connecting a merchant-owned channel, may require account verification. Complete verification through the authenticated Zetu Pay dashboard and follow the instructions shown there. This public API reference does not expose identity-document submission endpoints.

Where to manage verification

Open the dashboard and follow the verification checklist displayed for your account. Submit personal or business information only through the authenticated dashboard. The dashboard shows your verification status and any next steps. For help, contact support through the Support Centre; never send passwords, API keys, M-Pesa PINs or provider secrets to support.

Notifications and email

Zetu Pay tells you what matters in two places: the bell in your dashboard and email. We send email from [email protected].

GET /notifications returns your latest 50 with an unread count. POST /notifications/read-all marks them read. Codes and reset links are never re-sent; request a new one instead. Add [email protected] to your contacts if our email lands in spam.

Payments (M-Pesa prompt)

// 202 Accepted
{ "success": true, "data": {
  "id": "clx9k2...", "kind": "PAYMENT", "settlement": "POOLED", "status": "PENDING",
  "amount": 500, "fee": 7.5, "phone": "254712345678", "external_reference": "ORDER-1001",
  "link_id": null, "receipt": null, "created_at": "2026-10-29T08:15:00.000Z" } }

:id is the payment id or your external_reference.

Newest first, up to 100 per page. Includes payments, payment-link payments, paybill payments and fee top-ups (kind: "TOPUP").

Statuses

A pending payment that gets no answer is checked with M-Pesa automatically and closed as FAILED after 30 minutes.

Channels

Your account ID identifies you; each channel ID identifies a place money can go. Find both in Dashboard, Developers and Channels.

[ { "id": "zetupay", "name": "Zetu Pay collection", "type": "POOLED", "status": "ACTIVE" },
  { "id": "clx2...", "name": "Main shop till", "type": "DIRECT", "mode": "OWN_DARAJA", "kind": "TILL",
    "shortcode": "5551234", "account_number": null, "status": "PENDING", "verified": false } ]

Connecting your own account

Needs approved verification and a login session. Connect or manage a channel in Dashboard, Channels. Only use channel options shown in your dashboard for your account. Never paste provider credentials into a public website, code sample, support message or unapproved API request.

Available channel types and the information needed to connect them are displayed in the authenticated dashboard. For safety, this public guide does not publish provider-credential submission payloads or internal verification steps. Zetu Pay staff will never ask you to send a consumer secret, passkey, password or API key through support.

The number of channels available to an account may be limited. Use the dashboard to enable or disable a channel. Before using a live channel for a real customer, confirm the setup with a controlled test plan; live requests can initiate real M-Pesa transactions.

Fee balance for direct channels

Where your account uses a prepaid fee balance for direct-channel collections, the dashboard shows the current balance and available top-up action. Use the top-up instructions provided in your authenticated dashboard.

Payment links

A payment link is a hosted page at https://zetopay.co.ke/pay/<slug>. Share it on WhatsApp, SMS or social media. The payer enters their phone number, approves the M-Pesa prompt, and sees a confirmation. You need no website.

GET /links lists your links with paid_count and paid_total. POST /links/:id/active { "active": false } switches a link off.

Link payments appear in your transactions with link_id set, and trigger the same webhooks as API payments. Abuse-prevention limits may apply to repeated attempts. The payer only ever sees "waiting", "paid" or "failed". If a link's channel is disabled, or your fee balance is empty, the page shows "currently unavailable".

Paybill payments

Customers can also pay without a prompt: M-Pesa, Lipa na M-Pesa, Pay Bill, then your business number and your personal account number. Both are on your dashboard and in GET /me as paybill.shortcode and paybill.account.

• Where M-Pesa validation is switched on for our paybill, a wrong account number is declined while the customer pays. Otherwise the payment arrives and our team matches it.
• A good payment is credited to your wallet and appears in your transactions with external_reference C2B-<receipt>. You receive payment.success like any other payment.
• If money arrives for an account number we cannot match, we keep it safe and our team resolves it.

Wallet and fees

Returns the effective pooled-collection, direct-collection and withdrawal fee rules configured for your account. On the wallet channel the fee is taken from each payment before it reaches your wallet. On a direct channel you receive the full amount and the fee comes from your fee balance. The fee field on every payment shows exactly what was charged. Current rates are shown in your dashboard and may change; changes never affect a payment already made.

Withdrawals

Move your wallet balance to your M-Pesa phone. Needs: verified email, approved verification, a payout phone that we have verified, and an account older than 24 hours.

POST /api/v1/withdrawals
Authorization: Bearer zp_live_...
Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7

{ "amount": 2500, "external_reference": "PAYOUT-2026-10" }

// 202 Accepted
{ "success": true, "data": { "reference": "clx5...", "status": "QUEUED", "external_reference": "PAYOUT-2026-10" } }

Your wallet is debited at once, then the payout runs in the background. GET /withdrawals/:reference returns the status, amount, fee and M-Pesa receipt, and GET /withdrawals lists recent ones. Withdrawals do not send webhooks yet: poll the status.

Your applicable payout limits and fees are shown in the dashboard before you submit a withdrawal. High-value or unusual payouts may require additional review. The dashboard is the source of truth for the limits currently applied to your account.

Webhooks

We send an HTTPS POST to your webhook URL (set in Dashboard, Developers, or per payment with callback_url) when a payment changes state.

{ "event": "payment.success",
  "data": { "id": "clx9k2...", "kind": "PAYMENT", "settlement": "POOLED", "status": "SUCCESS", "amount": 500, "fee": 7.5,
            "phone": "254712345678", "external_reference": "ORDER-1001", "link_id": null, "receipt": "SBX1A2B3C", "created_at": "2026-10-29T08:15:00.000Z" },
  "created": "2026-10-29T08:15:21.000Z" }

Verify the signature

Every request carries X-ZetuPay-Timestamp (Unix seconds) and X-ZetuPay-Signature = sha256= followed by the hex HMAC-SHA256 of timestamp + "." + rawBody, keyed with your signing secret. Use the raw request body, not re-serialised JSON, and compare in constant time. Reject requests older than 5 minutes.

import crypto from 'crypto';
export function verify(rawBody, headers, secret) {
  const ts = headers['x-zetupay-timestamp'], sig = headers['x-zetupay-signature'] || '';
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(sig);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}
// Express: app.post('/zetupay-webhook', express.raw({ type: 'application/json' }), (req, res) => { if (!verify(req.body.toString(), req.headers, SECRET)) return res.sendStatus(400); ... res.sendStatus(200); });

$raw = file_get_contents('php://input');
$ts  = $_SERVER['HTTP_X_ZETUPAY_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_ZETUPAY_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $raw, $secret);
if (abs(time() - (int)$ts) > 300 || !hash_equals($expected, $sig)) { http_response_code(400); exit; }
$event = json_decode($raw, true); // handle $event['event'], then:
http_response_code(200);

import hmac, hashlib, time
def verify(raw: bytes, ts: str, sig: str, secret: str) -> bool:
    if not ts or abs(time.time() - int(ts)) > 300:
        return False
    expected = "sha256=" + hmac.new(secret.encode(), ts.encode() + b"." + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

Delivery rules

• Reply with any 2xx within 10 seconds. Anything else counts as a failure.
• We retry up to 6 times with growing delays (about 10 seconds, then longer). After that, fetch the payment with GET /payments/:id.
• Events can arrive twice or out of order. Make your handler idempotent: look the payment up by id and ignore it if you have already handled that status.
• The URL must be a public https address. We do not follow redirects.
• Do the slow work after replying 200.

Limits and rate limits

On 429, wait before retrying and use exponential backoff. Repeated failed prompts may trigger protective controls; do not repeatedly prompt the same customer. Account-specific limits and eligibility are shown in the dashboard.

If a request times out or returns a server error, check the existing transaction using its ID or external reference before making another payment request. Reuse the same external reference for a retry of the same order.

Testing

Only use a sandbox or test endpoint if it has been explicitly enabled for your account and is documented for your environment. Do not assume a live API request is a simulation: live collection requests may send a real M-Pesa prompt and move real money. Confirm the environment and transaction status before testing.

Go-live checklist

• ☐ Email verified and identity verification approved.
• ☐ API key stored securely and never exposed in browser-side code or public repositories.
• ☐ Webhook endpoint is public HTTPS, verifies the signature using the raw body, and is idempotent.
• ☐ Orders are fulfilled on payment.success, never on the 202.
• ☐ Every payment carries a unique external_reference.
• ☐ You handle failed, pending and timed-out payments in your UI; verify the final status before fulfilling an order.
• ☐ Payout phone added and verified; test withdrawal done.
• ☐ One real test payment on each channel you use.

Support

Include your account ID and the payment id or external_reference when you contact us. Never send an API key, signing secret, password, M-Pesa PIN or one-time code. Visit Support for contact details.