Integrating Telebirr: USSD Payments in Ethiopia

Telebirr is Ethiopia's largest mobile money platform, operated by Ethio Telecom with over 40 million subscribers. Unlike web-based checkout flows, Telebirr uses USSD push — a payment prompt sent directly to the customer's phone. This guide walks through the integration, the gotchas, and how Zirzir simplifies the process.

How Telebirr works

The payment flow is fundamentally different from card-based systems:

1. Your server sends a charge request to Telebirr's API with the customer's phone number and amount.
2. Telebirr sends a USSD prompt to the customer's phone.
3. The customer sees a text menu on their phone and enters their PIN to confirm.
4. Telebirr sends a callback to your server confirming the payment.

There's no browser redirect. No checkout page. The entire payment happens on the customer's phone via text-based menus.

The RSA encryption requirement

Telebirr's API requires that the entire request payload be encrypted with RSA using their public key. This isn't just TLS — the payload itself must be encrypted before transmission.

from cryptography.hazmat.primitives import serialization

# Load Telebirr's public key public_key = serialization.load_pem_public_key(telebirr_public_key_bytes)

# Encrypt the payload encrypted = public_key.encrypt( payload_json.encode(), padding.PKCS1v15() ) ```

With Zirzir, you don't need to handle this. The Telebirr adapter manages RSA encryption internally. You just call charge():

client = Zirzir( mode="standalone", providers={ "telebirr": { "app_id": "YOUR_APP_ID", "app_key": "YOUR_APP_KEY", "public_key": "YOUR_PUBLIC_KEY", } } )

tx = await client.charge({ "provider": "telebirr", "amount": 100.0, "currency": "ETB", "phone": "0911234567", "reference": "order-123", }) ```

Phone number normalization

Ethiopian phone numbers come in multiple formats:

Telebirr expects the 251XXXXXXXXX format without the + prefix. The Zirzir Telebirr adapter automatically normalizes phone numbers, so you can pass any common format.

Sandbox testing

Telebirr's sandbox is functional but has some quirks:

• Different base URL — sandbox and production use completely different API endpoints.
• Sandbox credentials have different key formats than production.
• The sandbox is occasionally unstable — if you're getting connection errors, it might not be your code.
• Callback URLs must be publicly accessible — even in sandbox mode. Use ngrok or a similar tunnel for local development.

Zirzir's test mode (zz_test_ API keys) automatically routes requests to sandbox endpoints.

Handling the asynchronous flow

After initiating a charge, the transaction enters a pending state. You need to handle two scenarios:

1. Customer completes payment — Telebirr sends a callback, Zirzir updates the transaction to completed, and fires a webhook to your application.
2. Customer doesn't respond — The USSD session times out (typically 60-90 seconds). You can poll the transaction status or wait for a timeout callback.

// Option 1: Poll for status

// Option 2: Listen for webhook // POST /webhooks/zirzir // { event: "transaction.completed", data: { reference: "order-123", ... } } ```

Common pitfalls

1. Don't assume instant confirmation. USSD payments take time. Show the customer a "waiting for confirmation" screen.
2. Handle duplicate callbacks. Network issues can cause Telebirr to send the same callback twice. Use the transaction reference for deduplication.
3. Test with real phones. The USSD experience varies by phone model. Older feature phones handle the menu differently than smartphones.
4. ETB only. Telebirr only supports Ethiopian Birr. Multi-currency transactions need a different provider.

Telebirr is a powerful payment method that reaches millions of Ethiopians who don't have bank accounts or smartphones. Understanding its USSD-based flow is essential for anyone building payment infrastructure in Ethiopia.