If you've only integrated Stripe or PayPal, you might assume payment integrations are straightforward: send an API call, get a response, redirect the user, receive a webhook. In Africa, every one of those assumptions can break.
USSD is not HTTP
The most popular payment method in Ethiopia isn't a web checkout. It's USSD — Unstructured Supplementary Service Data. When a customer pays via Telebirr, your server initiates a "push" request. Telebirr's infrastructure sends a USSD prompt directly to the customer's phone. The customer enters their PIN on a text-based menu. There's no redirect URL, no browser involved.
This means:
- No synchronous confirmation. The customer might take 30 seconds or 3 minutes to enter their PIN. Your server needs to poll or wait for a callback.
- Timeout handling is critical. If the USSD session expires (typically 60-90 seconds), you need to handle that gracefully. The payment didn't fail — it just wasn't completed.
- Phone number normalization matters. Ethiopian phone numbers can be formatted as
0911234567,+251911234567, or251911234567. Telebirr expects a specific format, and getting it wrong means the USSD push never arrives.
Sandboxes that aren't sandboxes
In the Stripe world, you get a sandbox that perfectly mirrors production. You can create test cards, simulate failures, and build your entire integration before touching real money.
African payment sandboxes are... different:
- Telebirr's sandbox requires RSA encryption of the entire request payload. The sandbox credentials use different key formats than production. The sandbox sometimes goes down for days without notice.
- Chapa's sandbox is actually quite good — one of the best on the continent. But even here, certain edge cases (like refund callbacks) behave differently in sandbox vs production.
- Some providers don't have sandboxes at all. You test with real money, in small amounts, and hope for the best.
Settlement timelines
Stripe settles in 2 business days, reliably. African payment settlement is more varied:
- Mobile money settlements can take 24-72 hours depending on the provider and the amount.
- Bank transfers might settle same-day or next business day, but "business day" varies by country and sometimes by bank.
- Cross-border settlements add another layer of complexity with forex considerations.
Your reconciliation system needs to handle all of these timelines gracefully.
The regulatory maze
Each African country has its own central bank regulations, KYC requirements, and licensing frameworks for payment service providers. What's legal in Kenya might not be in Ethiopia. Cross-border payments add another dimension entirely.
How Zirzir helps
Zirzir doesn't eliminate these challenges — they're fundamental to the African payment landscape. But it normalizes them:
- USSD flows and HTTP checkouts produce the same
Transactionobject with the same status lifecycle. - Provider-specific quirks are handled inside the adapter layer. Your application code doesn't need to know about RSA encryption or phone number formats.
- The webhook engine handles the variable timing of callbacks with configurable retry schedules.
- The transaction ledger gives you a single source of truth regardless of settlement timelines.
The goal isn't to pretend African payments are simple. It's to make the complexity manageable.