Collect Tanzania mobile money with a small, boring API.

01 · Start here

Getting started

Karibu is the public site. Register on me.thetrotal.com, complete KYC, then collect from your server against https://pesa.thetrotal.com. Checkout pages live only on pay-by-link.thetrotal.com.

02 · Security

Authentication

Server integrations use a merchant API key as a bearer token. Console login uses httpOnly cookies on me.thetrotal.com only. Never put a secret key in a browser or on pay-by-link.

Authorization: Bearer pk_live_…

Create a collection

Amount is TZS major units (same as minor for TZS). Send an Idempotency-Key. Network must be canonical: MPESA_TZ, AIRTEL_MONEY_TZ, MIXX_BY_YAS_TZ, HALOPESA_TZ.

curl https://pesa.thetrotal.com/v1/collections \
  -H "Authorization: Bearer pk_live_..." \
  -H "Idempotency-Key: inv_48291" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 137000,
    "currency": "TZS",
    "msisdn": "255712345678",
    "network": "MPESA_TZ",
    "merchant_reference": "inv_48291"
  }'

{
  "id": "pay_01J57R9",
  "status": "ACCEPTED",
  "amount": 137000,
  "currency": "TZS",
  "msisdn": "255712345678",
  "network": "MPESA_TZ"
}

03 · Hosted checkout

Pay by Link

Merchants mint links from the console. Customers open https://pay-by-link.thetrotal.com/p/{slug}. That host never sets merchant cookies. Default expiry is 24 hours (30m, 2h, 6h, 24h, 7d, 30d). One payment per link is on by default. A double tap returns the same collection; a FAILED attempt releases the lock so the same phone can try again.

POST https://pesa.thetrotal.com/v1/public/payment-links/{slug}/pay
{
  "msisdn": "255712345678",
  "network": "MPESA_TZ"
}

04 · Events

Webhooks

AzamPay posts collection and disbursement callbacks to https://pesa.thetrotal.com/azampay/callback (alias payments.thetrotal.com). Register that URL in the AzamPay portal. Merchant application webhooks are a separate HTTPS URL you set on the console.

https://pesa.thetrotal.com/azampay/callback?token=YOUR_CALLBACK_TOKEN

05 · SMS

RafikiSMS

Optional. Vendor API from developers.rafikisms.com. We POST to https://api.rafikisms.com/v1/vendor/send-sms with header X-API-Key. Phone format 255XXXXXXXXX, 160 characters. Set RAFIKISMS_ENABLED=true and the key from Profile → Integration. Collection still succeeds if SMS fails.