Telebirr and Chapa Payment Integration in Ethiopia

Direct answer

Integrating Telebirr or Chapa is more than adding a payment button. A production integration is complete only when the business can create an order securely, send the customer through the provider's approved payment flow, verify the result on the backend, fulfill exactly once, reconcile settlement, handle exceptions and refunds, support customers, and investigate incidents.

In our integration work, the reliable approach is to treat merchant onboarding, backend engineering, finance reconciliation, customer support, and production operations as one delivery stream. Code can pass a test transaction while the overall payment service is still not ready to operate.

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.

Merchant setup comes before coding

Start with the business account that will actually receive and settle the money. The legal name, trade-license activity, tax details, bank or wallet details, authorized contacts, domain, application details, and settlement owner should agree across the merchant application and the product. Ask the provider for its current document list rather than copying an old checklist.

Before development, confirm:

• whether the merchant is approved for Telebirr, Chapa, or both;
• which payment product and customer journey the account is approved to use;
• whether test credentials, production credentials, callback configuration, and IP or domain approval are separate steps;
• supported currency, amount limits, settlement timing, fees, refunds, and transaction lookup options;
• who in the business owns provider communication, finance reconciliation, refunds, and support escalation.

For Chapa, the merchant dashboard is used for API credentials and webhook settings. Telebirr offers several documented integration paths, so the team should implement the exact product approved for the merchant instead of mixing examples from a different Telebirr flow.

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.

API and backend integration 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. For example, Chapa documents signed webhook headers and recommends re-querying its verification API before providing value. The endpoint should validate content type and size, handle duplicate and out-of-order events, and return only the response the provider requires.

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.

Failed, pending, and interrupted payments

In real payment work, the difficult cases are usually not clean successes. A customer may close the browser, lose connectivity, retry, see a timeout while the provider later records success, or return to the app before the callback reaches the backend. Model these as explicit order and payment states instead of one paid/unpaid flag.

• Keep the order reference stable while creating a unique reference for each permitted payment attempt.
• Show pending when the backend does not yet have an authoritative result; do not label it failed just because the customer did not return.
• Let a scheduled worker recheck old pending transactions through the documented verification method.
• Permit a retry only when the order and previous attempt state make it safe.
• Give support staff a transaction search that shows the internal reference, provider reference, state history, amount, and timestamps without exposing credentials.
• Define how a paid-but-unfulfilled order, duplicate customer payment, failed refund, or missing settlement is escalated.

Reconciliation is an operating process

The application's payment table, the provider's transaction record, the settlement account, and the accounting entry must be compared. A daily reconciliation job can identify successful provider payments that remain pending internally, amount mismatches, duplicate attempts, refunds, fees, and settlements that finance has not matched. Automation should produce an exception queue; a named finance or operations owner still needs to investigate and close each exception with an audit note.

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.

Production deployment checklist

Keep test and live environments separate. Before switching to production, confirm that the live merchant account is approved, live keys are stored in the production secret manager, callback URLs use HTTPS, production domains or IPs are registered where required, database migrations and background reconciliation jobs are deployed, logs and alerts are active, and support and finance teams know the operating procedure.

Run a small, provider-approved live transaction and follow it end to end: order creation, payment, callback, backend verification, fulfillment, receipt, provider record, settlement record, and reconciliation. Record who can rotate credentials, pause payment acceptance, issue refunds, and contact the provider during an incident. A technically successful API request is not the same as an operationally ready payment service.

Common integration problems in Ethiopia

• Starting development before merchant approval:: the selected flow, credentials, settlement terms, or required documents may differ from the team's assumption.
• Using client-side success as proof:: redirect parameters, screenshots, and customer messages are not substitutes for backend verification.
• Reusing transaction references:: retries then become hard to distinguish and reconcile.
• Treating callbacks as exactly-once events:: network retries can deliver the same event more than once or in a different order.
• Exposing a secret key in a mobile app or frontend:: provider credentials belong on the server, never in a distributed client.
• Ignoring pending transactions:: local network interruptions can separate the customer journey from the final provider state.
• Testing only the happy path:: launch problems often appear in timeouts, duplicate taps, delayed callbacks, refunds, and provider outages.
• No finance ownership:: even correct code leaves unresolved settlement and customer issues when nobody owns daily reconciliation.

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