Payments & Vouchers

Top up credits via fixed packages or pay-as-you-go vouchers — mobile money with USSD prompts and signed webhooks.

Two ways to size a top-up, both feeding the same credit-granting logic:

Packages — fixed bundles priced via GET /v1/packages (POST /v1/payments/).
Vouchers (pay-as-you-go) — any amount above the minimum, converted at a tiered TZS-per-credit rate (POST /v1/vouchers/).

Both are paid via mobile money: a USSD prompt is pushed to the payer's phone to approve the payment.

#Fixed packages

POST/v1/payments/JWT or API Key

bash

# Browse packages first (public)
curl -s https://api.sendafrica.online/v1/packages

# Initiate an order
curl -s -X POST https://api.sendafrica.online/v1/payments/ \
  -H "X-API-Key: $SENDAFRICA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "package_id": 2, "provider": "snippe", "phone": "0712345678" }'

201 Created

json

{
  "success": true,
  "data": {
    "id": "b2c3d4e5-f6a7-...",
    "status": "pending",
    "source": "package",
    "provider": "snippe",
    "amount": 50000,
    "currency": "TZS",
    "credit_amount": 5000,
    "checkout_message": "Confirm the USSD prompt on your phone"
  }
}

#Pay-as-you-go vouchers

GET/v1/vouchers/ratePublic rate card · orders need JWT/API Key

rate card

json

{
  "success": true,
  "data": {
    "min_amount_tzs": 1000,
    "tiers": [
      { "max_amount_tzs": 49999,   "rate_tzs_per_credit": 35 },
      { "max_amount_tzs": 149999,  "rate_tzs_per_credit": 32 },
      { "max_amount_tzs": null,    "rate_tzs_per_credit": 30 }
    ]
  }
}

POST/v1/vouchers/JWT or API Key

voucher.sh

bash

curl -s -X POST https://api.sendafrica.online/v1/vouchers/ \
  -H "X-API-Key: $SENDAFRICA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 75000, "provider": "snippe", "phone": "0712345678" }'

# 75,000 TZS lands in Tier 2 → 32 TZS/credit → 2,343 credits

Verified phones only

Mobile-money payments require a verified phone number on the account — otherwise you get 409 phone_not_verified. Verify via POST /v1/auth/send-phone-otp + /verify-phone first.

#How confirmation works

Order created with status pending.
A USSD prompt is pushed to the payer's phone; approving it confirms the payment.
On confirmation, credits are granted atomically and a notification fires to the account.

#Tier math reference

Tier	Amount range (TZS)	Rate (TZS/credit)	Example
1	1,000 – 49,999	35	10,000 TZS → 285 credits
2	50,000 – 149,999	32	75,000 TZS → 2,343 credits
3	150,000+	30	200,000 TZS → 6,666 credits

Credits & Billing

Notifications