A recurring question from clients, whether a church wanting a giving page or a business wanting to sell online, is some version of "can't we just use Stripe?" The short answer is usually no, or at least not in a way that helps most Ethiopian customers. International payment gateways are built around cards and bank rails that a large share of the local audience does not use day to day. TeleBirr and CBE Birr transfers are what people already use, so a payment flow that ignores them asks customers to jump through hoops that need not exist. This guide explains how we design around them.
Before you start
Provider rules, fees and APIs change, and merchant access differs between organisations. Treat this as a design guide and confirm current requirements with TeleBirr, the Commercial Bank of Ethiopia and any other provider directly.
Two integration levels
There is a big difference between "display our TeleBirr and CBE account details so people can send money and confirm manually" and "fully automated payment with instant confirmation".
- Manual confirmation: reliable, needs no special API access and matches what users already do when paying family and small businesses.
- Automated integration: a merchant integration that notifies your server when a payment arrives. It removes manual checking but requires access, setup and testing.
Most client projects of ours start at the first level. For the broader picture, read Digital Payments on Ethiopian Websites.
Designing a manual-confirmation page
The design work that matters most is not technical. It is clarity.
- Show account details so they cannot be mistyped: large type, a one-tap copy button and the account name beside the number, so customers can confirm they are paying the right party.
- Say which account is for what: general giving, a building fund or a product order should each be clearly labelled.
- Show the exact amount before the customer pays.
- Give simple numbered steps in the languages your audience uses.
- Collect a reference after payment: a transaction code from the confirmation SMS is best, with an optional screenshot, plus the customer's phone number.
- Say what happens next: how long verification takes and how the customer will be told.
Verifying the transfer
The customer's claim is not proof. An admin must check the submitted reference against the actual TeleBirr or bank record before marking the order paid.
- Store the transaction code in a column that must be unique, so the same code cannot be used twice.
- Check amount, date and recipient account, not just that the code exists.
- Keep statuses such as
pending,verifiedandrejected, with timestamps. - Give the admin a simple list of unverified payments, oldest first, so none are forgotten.
Building an admin-managed "multiple accounts" page
Organisations with several purposes for receiving money outgrow a hardcoded payment page quickly, because every new account or campaign means another code change. Build the list of accounts as admin-editable data instead: an admin adds an account, labels it, enters the name and number, and reorders how accounts appear, with no developer involved. Because the labels and instructions live in the same content system as everything else, supporting English, Amharic and, where needed, Oromiffa is much easier to maintain. We cover the pattern in Church Websites in Ethiopia.
Where automated integration makes sense
For higher-volume uses, such as an e-commerce checkout or a subscription, manual confirmation does not scale. A direct merchant integration is then worth the effort: automated callbacks confirm payment, customers get instant confirmation and nobody has to read bank statements. When you build it, follow the rules in the payments guide: confirm on the server, verify each notification is genuine, match amounts and make your handler safe to run twice. We reserve this for projects where transaction volume justifies the extra complexity.
Security and privacy
- Serve payment pages over HTTPS only.
- Store only what you need, such as phone number, reference and amount, and restrict who can see it.
- Protect the admin area with strong passwords and session timeouts. See PHP Security Basics.
- Never put provider secrets in front-end code.
- Tell customers in your privacy policy what you collect and why.
Common mistakes
| Mistake | Better approach |
|---|---|
| Account number shown as plain text only | Large, copyable, with account name beside it |
| One generic account for every purpose | Labelled accounts per purpose, managed by an admin |
| Marking orders paid when the customer submits a form | Mark paid only after verification |
| No unique check on transaction codes | Unique constraint on the code |
| No follow-up message | Tell customers when and how they will be confirmed |
The core principle
Design the payment experience around the rails people already trust and use, not around whatever is easiest to plug in from an international SDK. It takes more work up front, but it is the difference between a payment page people use and one that quietly gets abandoned at checkout.