Top-Ups & Pricing

#Credit fundamentals

• 1 credit = 1 SMS part (GSM-7: 160 chars single / 153 multipart; UCS-2: 70 / 67).
• Tanzania domestic rate: TZS 35 per credit (Tier 1).
• International sends charge ceil(rate_tzs / 35) credits per part using the country rate card.
• Credits are deducted atomically before sending and refunded automatically on gateway rejection.

#Voucher tier math

Bigger top-ups buy cheaper credits — Tier 3 is ~14% more credits per shilling than Tier 1. Fetch live numbers from GET /v1/vouchers/rate rather than hardcoding.

#Mobile money

1. Verify your phone first (send-phone-otp + verify-phone) — unverified phones get 409 phone_not_verified.
2. Create the order: POST /v1/vouchers/ with {"amount": 75000, "provider": "snippe", "phone": "0712345678"}.
3. Approve the USSD prompt pushed to your phone.
4. A signed webhook confirms the payment; credits land atomically and a notification fires.

#Automate low-balance top-ups

THRESHOLD = 500
TOPUP_TZS = 100_000  # Tier 2 rate

def maybe_top_up(client):
    balance = client.credits.balance().balance
    if balance >= THRESHOLD:
        return None

    rate = client.payments.rate()
    tier_rate = next(
        t.rate_tzs_per_credit for t in rate.tiers
        if t.max_amount_tzs is None
        or TOPUP_TZS <= t.max_amount_tzs
    )
    est_credits = TOPUP_TZS // tier_rate

    payment = client.payments.create(
        amount=TOPUP_TZS,
        provider="snippe",
        phone="0712345678",
    )
    print(f"Order {payment.id}: ~{est_credits} credits pending USSD approval")
    return payment