Telebirr and Chapa Payment Integration in Ethiopia

Direct answer

A payment integration is complete only when the business can create an order securely, send the customer through an approved payment flow, verify the result server-side, fulfill exactly once, reconcile settlement, handle exceptions and refunds, support customers, and investigate incidents.

Provider access and features change. Verify current eligibility, documentation, credentials, methods, currencies, fees, settlement, limits, support, and commercial terms through the official Telebirr developer portal or Chapa documentation before committing scope.

Define the business flow first

Document:

• what is being paid for and when an order becomes binding;
• who calculates price, tax, discount, delivery, and currency;
• whether partial, repeated, subscription, split, or bulk payments are needed;
• when inventory, a seat, service, or account credit is reserved;
• what the customer sees for success, pending, cancellation, failure, and timeout;
• who can refund or adjust a transaction and what approval is required;
• how finance reconciles provider transactions, fees, settlement, bank records, and internal orders;
• how support searches a transaction without exposing secrets or unnecessary personal data.

A safe reference flow

1. Create the order on the server

The merchant backend should load products or services from trusted data, recalculate totals, apply approved discounts, create a unique internal order, and record the expected amount and currency. Do not trust a price sent by the browser or mobile app.

2. Initialize through the provider API

The backend sends only the required fields over TLS using credentials stored outside source code and client applications. Record the provider transaction identifier, request state, and correlation ID without logging secrets.

3. Send the customer to the approved payment interface

Use the provider's documented hosted checkout, SDK, or direct-charge method that matches the merchant's approved account. Explain what will happen, preserve the internal order reference, and make the return journey accessible and usable on mobile networks.

4. Receive return and server notification events

A browser return is useful for customer experience but is not authoritative proof. Webhooks or callbacks must be authenticated using the provider's current documented method. The endpoint should validate content type and size, handle duplicate and out-of-order events, and return only the required response.

5. Verify before fulfillment

Call the official verification endpoint from the backend when required. Match provider, transaction ID, internal order, merchant account, status, expected amount, and currency. Never fulfill solely because a URL says success.

6. Process exactly once

Use a database transaction or equivalent control so retries cannot create duplicate delivery, tickets, credits, receipts, or notifications. Record the final state transition and retain the provider reference needed for reconciliation.

7. Reconcile and investigate

Run scheduled reconciliation between provider records, internal orders, refunds, fees, settlement, and the bank or wallet account. Pending or mismatched items need an owner, age, alert, evidence, and resolution workflow.

Security checklist

• keep secret keys in a managed secret store and rotate them under a documented process;
• never place server credentials in JavaScript, mobile binaries, screenshots, tickets, or analytics;
• restrict production credentials and refund access by role and environment;
• validate callback authenticity and verify status with the provider;
• use unique transaction references and idempotent processing;
• log state changes and administrative actions without sensitive payment data;
• monitor unusual failures, amount mismatches, repeated callbacks, and refund activity;
• protect support tools against insecure direct-object reference and excessive data exposure;
• review dependencies, headers, TLS, input handling, and incident procedures;
• document the data shared with each provider and update privacy information accordingly.

Test matrix

Run provider-approved test cases and controlled production verification for:

• successful payment;
• customer cancellation;
• insufficient funds or provider decline;
• slow network, closed browser, and lost return navigation;
• delayed, duplicated, malformed, or out-of-order callback;
• invalid signature or credential;
• changed amount, currency, order, or account;
• repeated customer click and concurrent verification;
• provider API timeout and retry;
• pending status that later succeeds or fails;
• refund, partial refund where supported, and failed refund;
• reconciliation mismatch and missing settlement;
• provider outage, internal outage, and recovery;
• accessible keyboard, screen-reader, error, and mobile journeys.

Questions for a provider or implementation partner

• Which merchant categories, onboarding documents, methods, currencies, and transaction types are currently approved?
• Which sandbox and production credentials exist, and who owns the accounts?
• How are callbacks authenticated and retried?
• Which verification, refund, dispute, settlement, and reconciliation APIs are available?
• What rate, amount, timing, retention, and support limits apply?
• What changes require re-certification or provider approval?
• Which responsibilities remain with the merchant during fraud, outage, refund, and customer dispute?

Primary references

• Ethio telecom developer portal
• Telebirr official service site
• Chapa developer documentation
• OWASP payment gateway integration guidance