Telebirr

Installation

pnpm add @birrjs/telebirr

Configuration

import { createBirr } from "@birrjs/core";
import { telebirr } from "@birrjs/telebirr";

const birr = createBirr({
  provider: telebirr({
    gatewayUrl: process.env.TELEBIRR_GATEWAY_URL!,
    checkoutUrl: process.env.TELEBIRR_CHECKOUT_URL!,
    fabricAppId: process.env.TELEBIRR_FABRIC_APP_ID!,
    appSecret: process.env.TELEBIRR_APP_SECRET!,
    merchantAppId: process.env.TELEBIRR_MERCHANT_APP_ID!,
    merchantCode: process.env.TELEBIRR_MERCHANT_CODE!,
    privateKeyPem: process.env.TELEBIRR_PRIVATE_KEY!,
    notifyUrl: process.env.TELEBIRR_NOTIFY_URL!,
    redirectUrl: process.env.TELEBIRR_REDIRECT_URL!,
    telebirrPublicKeyPem: process.env.TELEBIRR_PUBLIC_KEY || undefined,
  }),
  // ...
});

Options

Sandbox & production values (same for every merchant):

• gatewayUrl
  • Sandbox: https://developerportal.ethiotelebirr.et:38443/apiaccess/payment/gateway
  • Production: https://superapp.ethiomobilemoney.et:38443/apiaccess/payment/gateway
• checkoutUrl
  • Sandbox: https://developerportal.ethiotelebirr.et:38443/payment/web/paygate
  • Production: https://superapp.ethiomobilemoney.et:38443/payment/web/paygate

Environment variables

birrjs init writes these for you:

Prefer a PEM file on disk instead of a single-line env value? Keep TELEBIRR_PRIVATE_KEY_PATH in your .env and load it yourself — privateKeyPem: readFileSync(process.env.TELEBIRR_PRIVATE_KEY_PATH!, "utf8"). normalizePrivateKey() accepts either form.

Where these values come from

Sign in to the Telebirr developer portal — your credentials are listed on the home screen:

gatewayUrl and checkoutUrl are the same for every merchant — see the sandbox and production values under Options.

Private key

The factory runs every key through normalizePrivateKey(), so all of these work:

• A base64-DER one-liner in TELEBIRR_PRIVATE_KEY (what Telebirr's Postman environment ships) — recommended for .env files, since most .env loaders parse line-by-line and multi-line PEMs don't survive
• A multi-line PEM string in your environment (if your loader supports it)
• A PEM file on disk, loaded with readFileSync(TELEBIRR_PRIVATE_KEY_PATH)

An unusable key fails fast at startup with TELEBIRR_INVALID_PRIVATE_KEY.

TLS certificate (sandbox)

Symptom — every call to the sandbox gateway fails before it reaches Telebirr:

TelebirrError: fetch failed
caused by: unable to verify the first certificate

Cause — the sandbox gateway only sends its own (leaf) certificate, not the intermediate CA that links it to GlobalSign. Browsers fetch the missing piece automatically. Node.js does not, so it can't verify who it's talking to. Production serves the full chain — this hits the sandbox only.

Fix — download the missing intermediate once, then point Node at it:

curl -o globalsign-ev-intermediate.pem https://secure.globalsign.com/cacert/gsgccr3evtlsca2025.crt
NODE_EXTRA_CA_CERTS=$PWD/globalsign-ev-intermediate.pem pnpm dev

curl.exe -o globalsign-ev-intermediate.pem https://secure.globalsign.com/cacert/gsgccr3evtlsca2025.crt
setx NODE_EXTRA_CA_CERTS "C:\full\path\to\globalsign-ev-intermediate.pem"

Only server-side gateway calls need this — the checkout page opens in the payer's browser, which handles certificate chains on its own. Production certificates chain correctly.

How it works

Delivery paths

Both mechanisms are safe to lose: each one independently verifies against the API and activates idempotently.

The params are visible to the payer but carry no secrets (identifiers and a signature, not credentials) — and they're tamper-proof: BirrJS reads them but never trusts them, re-querying queryOrder instead, so editing trade_status by hand cannot fake a payment. If the long query string bothers you in the address bar, strip it after landing with history.replaceState.

Supported events

There is no charge.reversed / charge.refunded path — Telebirr refunds are handled out-of-band.

Testing in the sandbox

Everything below comes from getting a real payment to complete end-to-end. it saves the steps that otherwise cost hours.

Credentials

Sandbox credentials come from the Telebirr developer portal (a Postman collection + environment are provided there too). You need the merchant half (gateway, checkout, fabric, merchant ids, private key) — see Where these values come from.

Install the testbed app

Paying on the web checkout requires the Telebirr test app — a real wallet app pointed at the sandbox. Your personal Telebirr app/account will not work.

Log in with the sandbox test phone and PIN exactly like the real Telebirr app.

Test consumer

Paying: use the QR code

1. Open your app's checkoutUrl in a browser
2. Scan the displayed QR code with the testbed app
3. Approve in the app

The QR path completes in seconds and avoids the web page's SMS-OTP step, which is unreliable for test numbers (the OTP either never arrives anywhere visible or is rejected as expired).

Callbacks without a public server

Point notifyUrl at a tunnel (ngrok, Cloudflare Tunnel):

ngrok http 3001
# notifyUrl = https://<id>.ngrok-free.app/api/birrjs/handle-webhook

The sandbox accepts notify from tunnel URLs with no IP whitelist — the whitelist and SSL certificate submission process described in Telebirr's guides applies to production. Verify what arrived in the tunnel inspector: it shows every request, forwarded or failed.

Troubleshooting

Production checklist

• Switch gatewayUrl / checkoutUrl to production endpoints (confirm current values with Telebirr)
• Complete Telebirr's official IP whitelist + SSL certificate submission process — unlike sandbox, production callbacks are enforced
• Confirm the required RSA padding with Telebirr (sandbox accepts SHA256WithRSA some Telebirr SDK documentation requires PSS for production)
• Set TELEBIRR_PUBLIC_KEY so notify signatures are verified fail-closed
• API response payloads' own sign field is currently not verified — traffic is trusted after TLS and, more importantly, never trusted for payment decisions (queryOrder is always re-queried)

Known gaps

• Pending-notify race — a notify can arrive while queryOrder still reports a transient status (PAYING/WAIT_PAY) BirrJS then classifies it as charge.failed/cancelled and marks a pending subscription failed. A later success delivery (or redirect replay) recovers it, since activation has no status guard.
• No charge.reversed / charge.refunded — refunds aren't surfaced as webhook events.