Skip to main content

Telebirr Mini App Development: Requirements, Timeline and Auto Sign-In

Telebirr Mini Apps help startups reach users fast, but INSA and telebirr integration requirements mean 4–6 months to go live. Plus a step-by-step Macle auto sign-in build.

A telebirr Mini App runs inside the telebirr SuperApp. For a startup, it is one of the fastest ways to reach users in Ethiopia: people open your service from an app they already use, without installing anything, creating an account or typing a password.

But a mini app is not a weekend project. Requirements such as the INSA security audit and telebirr integration approval mean that going live usually takes 4–6 months. This guide explains why mini apps are worth it, what the requirements are, and then walks through building one with auto sign-in, step by step.

Planning a telebirr Mini App? Talk to DreamTech. We build the mini app and its backend, integrate telebirr and prepare the paperwork for approval.

Why Telebirr Mini Apps Help Startups Get Users Fast

Getting users to download a new app and create an account is the hardest part of launching a startup. A telebirr Mini App removes most of that work:

  • No download. Users open your mini app inside telebirr, an app already on their phone.
  • No sign-up form. Auto sign-in identifies the telebirr user the moment your mini app opens.
  • No password. The SuperApp already knows who the user is.
  • Payments built in. Customers can pay from their telebirr wallet without leaving your service.
  • Found inside telebirr. Once approved, your mini app is published in the telebirr SuperApp, where users can find it.

That makes mini apps a strong fit for transport tickets, food and delivery orders, bookings, event tickets, subscriptions, school fees and loyalty programmes.

Plan for 4–6 Months, Not 4–6 Weeks

Building the mini app is the quick part. Going live usually takes 4–6 months, because of the requirements around it: telebirr merchant onboarding and integration approval, whitelisting, an INSA security audit and Ethio telecom's review before production.

RequirementWhat it involves
Business and merchant setupA registered business with a trade licence and TIN, and a telebirr merchant account with your merchant code
Developer accountTest-bed credentials from the Ethio telecom developer dashboard: X-APP-Key, appSecret, merchant app ID, merchant code and an RSA key pair
Telebirr integrationAuto sign-in and payment APIs built, signed with your RSA key and tested in the sandbox
WhitelistingYour backend's public HTTPS URL whitelisted for the mini app, and your merchant code whitelisted if you need the user's name and phone number
INSA security auditA security assessment of your mini app, backend and hosting by INSA, the Information Network Security Administration
Production reviewSandbox commissioning, Ethio telecom approval, production credentials and release

The best way to shorten the timeline is to start the paperwork on day one and build while the approvals move forward.

DreamTech designed a telebirr Mini App for the Electric Minibus Smart Fare system: passengers scan a QR code on the minibus, choose a seat and pay in telebirr, and the driver sees the confirmed payment live. See our payment gateway integration page for telebirr Mini App packages.


Building a Telebirr Mini App With Auto Sign-In

The most valuable feature a mini app gets is auto sign-in: the moment your mini app opens, you can identify the telebirr user. In this walkthrough we build exactly that, and nothing else:

  • an empty mini app built with Ethio telecom's Macle framework,
  • that signs the user in automatically on launch,
  • backed by a small Node.js merchant server,
  • tested end to end in the Macle simulator against the telebirr sandbox.

No payments and no products, just a clean starting point you can grow from.

Everything here is based on the official Mini App Development Guide and Mini App Integration docs, plus what we learned implementing it on an Apple Silicon Mac.

How Auto Sign-In Works

Three parties are involved: your mini app, which runs inside the SuperApp; your merchant backend, which holds your secrets; and the telebirr payment gateway, the API "fabric".

  1. The user opens your mini app, and the telebirr SuperApp launches it (App.onLaunch).
  2. The mini app asks the SuperApp for an access token with ma.getMiniAppToken({ appId }).
  3. The mini app sends that token to your backend: POST /apply/h5token.
  4. Your backend gets a short-lived fabric token from the gateway with your X-APP-Key and appSecret: POST /payment/v1/token.
  5. Your backend calls POST /payment/v1/auth/authToken with a request signed with your RSA private key.
  6. The gateway returns the user's open_id, identityId and, if you are whitelisted, nickName and identifier.
  7. The mini app greets the user: "Welcome, <name>".

Key points:

  • The access token can only come from inside the SuperApp. Your mini app asks the SuperApp for it; there is no way to get one from a browser or your server.
  • Your backend exchanges it for the user's identity. It first gets a fabric token with your X-APP-Key and appSecret, then calls authToken with a request signed with your RSA private key.
  • Name and phone number need whitelisting. nickName and identifier (the phone number) are returned only if Ethio telecom has whitelisted your merchant code. Everyone gets open_id.
EnvironmentGateway base URL
Sandbox (test bed)https://developerportal.ethiotelebirr.et:38443/apiaccess/payment/gateway
Productionhttps://superapp.ethiomobilemoney.et:38443/apiaccess/payment/gateway

Prerequisites

ToolNotes
Visual Studio CodeThe Macle IDE is a VS Code extension.
Node.js 18+For the merchant backend. We used Node 22.
Macle DevToolkit 25.9.0DevToolkit_25.9.0.zip, about 274 MB.
Rosetta 2 (Apple Silicon only)The macOS simulator is an x86_64 build. Install it with softwareupdate --install-rosetta.
Test-bed credentialsX-APP-Key, appSecret, merchant app ID, merchant code and an RSA key pair, from your developer dashboard.

You will also want the official demos referenced in the docs:

Install the Macle DevToolkit

The toolkit zip contains five items:

Macle_25.9.0_DevSuite_IDE.zip        → VS Code extension (.vsix)
Macle_25.9.0_DevSuite_Simulator.zip  → offline simulator (Mac + Windows)
Macle_25.9.0_DevSuite_UI.zip         → UI component library
Macle_25.9.0_Engine_JSSDK.zip        → JS SDK + TypeScript typings (jssdk.d.ts)
vconsole.min.js                      → on-device debug console

Install the IDE extension

Extract Macle_25.9.0_DevSuite_IDE.zip, then in VS Code choose Extensions → ⋯ → Install from VSIX… and pick macle-miniprogram-tools-25.9.0.vsix. Or install it from the terminal:

Shell
code --install-extension macle-miniprogram-tools-25.9.0.vsix

Reload VS Code. You should see the M logo in the activity bar.

Import the offline simulator

Gotcha: Macle_25.9.0_DevSuite_Simulator.zip is not a zip. It is a RAR v5 archive with a .zip name, so unzip fails with "End-of-central-directory signature not found". On macOS, the built-in tar (libarchive) reads RAR5 without problems.

Shell
mkdir simulator && tar -xf Macle_25.9.0_DevSuite_Simulator.zip -C simulator
# → simulator/Macle_25.9.0_DevSuite_Simulator_Mac.zip
# → simulator/Macle_25.9.0_DevSuite_Simulator_Win.zip

Then in VS Code choose M → Help → Import Offline Simulator and select Macle_25.9.0_DevSuite_Simulator_Mac.zip. The importer insists that the file name contains _Mac on macOS or _Win on Windows.

Under the hood, the importer simply unzips the app to:

~/.vscode/extensions/macleteam.macle-miniprogram-tools-25.9.0/src/utils/simulator/mac/macle-simulator.app

If the import ever fails, the extension tells you to place it manually. Extracting it there with ditto -x -k <zip> <that folder> does the same job.

Create the Mini App Project

Choose M → New Project, pick the Hello World template, and give it a name and App ID. The App ID comes from the AppCube Macle Management Console when you register the mini app; any placeholder works for local development.

Macle's DSL will feel familiar if you have used other mini program frameworks:

FilePurpose
app.jsonPages list and window and navigation bar settings
app.jsApp({...}): the app lifecycle (onLaunch, onShow)
app.massGlobal styles. .mass works like CSS and supports rpx.
project.config.jsonappid and projectname
pages/x/x.mamlMarkup: <view>, <text>, <button>, ma:if, ma:for, bindtap
pages/x/x.jsPage({...}): data, lifecycle and event handlers
pages/x/x.jsonPage settings (usingComponents)

Our final project:

telebirr-miniapp-demo/
├── app.js
├── app.json
├── app.mass
├── project.config.json
├── utils/
│   ├── config.js      ← backend URL + merchant app ID
│   └── auth.js        ← auto sign-in logic
└── pages/index/
    ├── index.js
    ├── index.json
    ├── index.maml
    └── index.mass

Build the Merchant Backend

We start from the official Auto Login demo (autoLoginDemo/autoLogin/node_demo-master) and keep only what sign-in needs.

Configuration

config/config.js. Never commit real values:

JavaScript
// test bed env (never commit real values)
module.exports = {
  baseUrl: "https://developerportal.ethiotelebirr.et:38443/apiaccess/payment/gateway",
  fabricAppId: "your X-APP-Key",
  appSecret: "your appSecret",
  merchantAppId: "your merchant app id",
  merchantCode: "your merchant code",
  privateKey: "-----BEGIN PRIVATE KEY-----\n...your RSA private key...\n-----END PRIVATE KEY-----",
};

Step 1: Apply for a fabric token

service/applyFabricTokenService.js:

JavaScript
const axios = require("axios");
const config = require("../config/config");

async function applyFabricToken() {
  const response = await axios.post(
    config.baseUrl + "/payment/v1/token",
    { appSecret: config.appSecret },
    {
      headers: {
        "Content-Type": "application/json",
        "X-APP-Key": config.fabricAppId,
      },
    }
  );
  return response.data; // { token: "Bearer …", effectiveDate, expirationDate }
}

module.exports = applyFabricToken;

Step 2: Sign the request

Every gateway request carries a sign. The recipe from the docs:

  1. Take all top-level fields plus all fields inside biz_content, flattened.
  2. Drop the excluded fields: sign, sign_type, header, refund_info, openType, raw_request and biz_content (the container itself).
  3. Sort the keys alphabetically and join them as key=value with &.
  4. Sign the string with your private key and base64-encode it.

utils/tools.js, from the demo:

JavaScript
const pmlib = require("./sign-util-lib");
const config = require("../config/config");

const excludeFields = ["sign", "sign_type", "header", "refund_info", "openType", "raw_request", "biz_content"];

function signRequestObject(requestObject) {
  const fieldMap = {};
  for (const key in requestObject) {
    if (!excludeFields.includes(key)) fieldMap[key] = requestObject[key];
  }
  // the fields in "biz_content" must participate in the signature
  for (const key in requestObject.biz_content || {}) {
    if (!excludeFields.includes(key)) fieldMap[key] = requestObject.biz_content[key];
  }
  const signOriginStr = Object.keys(fieldMap).sort()
    .map((key) => key + "=" + fieldMap[key])
    .join("&");
  return signString(signOriginStr, config.privateKey);
}

function signString(text, privateKey) {
  const signer = new pmlib.rs.KJUR.crypto.Signature({ alg: "SHA256withRSAandMGF1" });
  signer.init(privateKey);
  signer.updateString(text);
  return pmlib.rs.hextob64(signer.sign());
}
The Node demo uses RSA-PSS (SHA256withRSAandMGF1), and the Java demo matches it with SHA256withRSA/PSS. If the gateway answers "verify sign failed", check how you built the string and which algorithm you used.

Step 3: Exchange the access token for the user

service/authTokenService.js:

JavaScript
const applyFabricToken = require("./applyFabricTokenService");
const tools = require("../utils/tools");
const config = require("../config/config");
const request = require("request");

exports.authToken = async (req, res) => {
  const appToken = req.body.authToken;               // from ma.getMiniAppToken()
  const { token: fabricToken } = await applyFabricToken();
  const result = await exports.requestAuthToken(fabricToken, appToken);
  res.send(result);
};

exports.requestAuthToken = (fabricToken, appToken) =>
  new Promise((resolve) => {
    request(
      {
        method: "POST",
        url: config.baseUrl + "/payment/v1/auth/authToken",
        headers: {
          "Content-Type": "application/json",
          "X-APP-Key": config.fabricAppId,
          Authorization: fabricToken,
        },
        body: JSON.stringify(createRequestObject(appToken)),
      },
      (error, response) => {
        if (error) return resolve({ result: "FAIL", msg: error.message });
        resolve(JSON.parse(response.body));
      }
    );
  });

function createRequestObject(appToken) {
  const req = {
    timestamp: tools.createTimeStamp(),   // UTC seconds
    nonce_str: tools.createNonceStr(),    // 32 random chars
    method: "payment.authtoken",
    version: "1.0",
    biz_content: {
      access_token: appToken,
      trade_type: "InApp",
      appid: config.merchantAppId,
      resource_type: "OpenId",
    },
  };
  req.sign = tools.signRequestObject(req);
  req.sign_type = "SHA256WithRSA";
  return req;
}

A successful response looks like this:

JSON
{
  "result": "SUCCESS",
  "code": "0",
  "biz_content": {
    "open_id": "…",
    "identityId": "…",
    "identityType": "CUSTOMER",
    "walletIdentityId": "…",
    "identifier": "2519XXXXXXXX",
    "nickName": "Abebe",
    "status": "…"
  }
}

The server: auth only

The demo's app.js also had payment routes, some referencing modules that were never imported, and a WebSocket broadcaster. For a sign-in-only app we trimmed it down to:

JavaScript
const express = require("express");
const bodyParser = require("body-parser");
const http = require("http");
const authToken = require("./service/authTokenService");

const app = express();
app.use(bodyParser.json());

// Allow the mini app to call us (tighten this in production)
app.use((req, res, next) => {
  res.header("Access-Control-Allow-Origin", "*");
  res.header("Access-Control-Allow-Headers", "Origin, X-Requested-With, Content-Type, Accept");
  res.header("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
  next();
});

// Auto login: exchange the SuperApp access_token for the user's telebirr identity
app.post("/apply/h5token", async (req, res) => {
  try {
    await authToken.authToken(req, res);
  } catch (error) {
    console.error("Error applying auth token:", error.message);
    if (!res.headersSent) res.status(500).json({ error: error.message });
  }
});

const port = process.env.PORT || 8081;
http.createServer(app).listen(port, () => console.log("Server started, port:" + port));
Wrapping the async handler in try/catch matters. Express 4 does not catch rejected promises, and on Node 15+ an unhandled rejection kills the process.

The TLS surprise

Our first run failed with:

Error while applying fabric token: unable to verify the first certificate

The sandbox server sends only its leaf certificate and leaves out the GlobalSign GCC R3 EV TLS CA 2025 intermediate. curl on macOS works anyway because the operating system fetches missing intermediates; Node does not.

The demo code "solves" this with rejectUnauthorized: false. Do not do that: it turns off certificate checking entirely. Supply the missing intermediate instead:

Shell
# Fetch the intermediate from the URL in the leaf certificate's AIA extension
curl -o inter.der http://secure.globalsign.com/cacert/gsgccr3evtlsca2025.crt
openssl x509 -inform DER -in inter.der -out certs/globalsign-gcc-r3-ev-tls-ca-2025.pem

Then start Node with it added to the trust store, so full verification stays on:

JSON
"scripts": {
  "start": "NODE_EXTRA_CA_CERTS=./certs/globalsign-gcc-r3-ev-tls-ca-2025.pem node app.js"
}

Smoke test:

Shell
PORT=8081 npm start
curl -X POST http://localhost:8081/apply/h5token \
  -H 'Content-Type: application/json' -d '{"authToken":"test"}'
# → {"result":"FAIL","code":"60320005","msg":"The token is empty or expired, …"}

That FAIL is good news: the fabric token worked, the signature was accepted, and the gateway is correctly rejecting a fake access token.

Write the Mini App

utils/config.js

JavaScript
// Merchant backend for auto login. On a real device this must be a public
// HTTPS URL whitelisted for the mini app.
module.exports = {
  baseUrl: 'http://localhost:8081',
  merchantAppId: 'your merchant app id'
};

utils/auth.js: the sign-in flow

JavaScript
// telebirr auto sign-in: SuperApp access_token -> merchant backend authToken -> user identity
const config = require('./config.js');

let loginPromise = null;

function requestAuthToken(accessToken) {
  return new Promise((resolve, reject) => {
    ma.request({
      url: config.baseUrl + '/apply/h5token',
      method: 'POST',
      header: { 'Content-Type': 'application/json' },
      data: { authToken: accessToken },
      success: (res) => resolve(res.data),
      fail: reject
    });
  });
}

function signIn() {
  return ma.getMiniAppToken({ appId: config.merchantAppId })
    .then((tokenResp) => {
      if (!tokenResp || !tokenResp.token) throw new Error('SuperApp returned no access token');
      return requestAuthToken(tokenResp.token);
    })
    .then((body) => {
      const res = typeof body === 'string' ? JSON.parse(body) : body;
      if (res.result !== 'SUCCESS') throw new Error(res.msg || res.errorMsg || 'authToken failed');
      return res.biz_content;
    });
}

// Shared by app launch and pages; pass retry=true to start a fresh attempt
function autoLogin(retry) {
  if (!loginPromise || retry) loginPromise = signIn();
  return loginPromise;
}

module.exports = { autoLogin };

Two details are worth calling out:

  • Use the DSL call. Call ma.getMiniAppToken(...), not window.ma.native(...). The docs show window.ma.native("getMiniAppToken", …), which is the H5 flavour where you load js-sdk.min.js in index.html. In a DSL mini app, ma is a Proxy: calling any unknown method, such as ma.getMiniAppToken(params), forwards a native call with that name and returns a Promise when you do not pass success or fail callbacks.
  • The promise lives in a module, not on the App instance. The gotchas section below explains why.

app.js: start sign-in at launch

JavaScript
// app.js
const auth = require('./utils/auth.js');

App({
  globalData: {
    user: null
  },

  onLaunch() {
    auth.autoLogin()
      .then((user) => {
        getApp().globalData.user = user;
      })
      .catch(() => {});
  },

  onShow() {}
});

pages/index/index.js

JavaScript
// index.js
const auth = require('../../utils/auth.js');

Page({
  data: {
    status: 'loading',
    user: null,
    error: ''
  },

  onLoad(options) {
    this.waitForLogin(auth.autoLogin());
  },

  waitForLogin(loginPromise) {
    this.setData({ status: 'loading', error: '' });
    loginPromise
      .then((user) => this.setData({ status: 'signedIn', user }))
      .catch((err) => {
        const error = (err && (err.errMsg || err.message)) || JSON.stringify(err);
        this.setData({ status: 'failed', error });
      });
  },

  retry() {
    this.waitForLogin(auth.autoLogin(true));
  }
});

pages/index/index.maml

MAML
<!--index.maml-->
<view class="container">
  <text ma:if="{{status === 'loading'}}" class="muted">Signing in with telebirr…</text>

  <view ma:if="{{status === 'signedIn'}}" class="user">
    <text class="title">Welcome, {{user.nickName || 'telebirr user'}}</text>
    <text class="muted">{{user.identifier || user.open_id}}</text>
  </view>

  <view ma:if="{{status === 'failed'}}" class="user">
    <text class="title">Sign-in failed</text>
    <text class="muted">{{error}}</text>
    <button class="retry" bindtap="retry">Try again</button>
  </view>
</view>

pages/index/index.mass

MASS
/**index.mass**/
.container { justify-content: center; }

.user {
  display: flex;
  flex-direction: column;
  align-items: center;
  padding: 0 48rpx;
  text-align: center;
}

.title { font-size: 40rpx; font-weight: 600; margin-bottom: 16rpx; }
.muted { font-size: 28rpx; color: #888; }
.retry { margin-top: 40rpx; }

Finally, set a title in app.json:

JSON
"window": {
  "navigationBarTitleText": "Telebirr Demo",
  "navigationBarBackgroundColor": "#fff",
  "navigationBarTextStyle": "black"
}

That is the whole app.

Run and Test in the Simulator

  1. Start the backend: PORT=8081 npm start.
  2. Open the project folder in VS Code and click M → Simulator. The extension compiles the DSL into ~/.macle/target/compile/<name><appid>/app and launches the simulator. Saving a file recompiles and refreshes automatically.

The simulator can run as a standalone window (the default), inside VS Code, or in Chrome. Set it per project in .vscode/settings.json:

JSON
{ "macle.openSimulator": "Open in Chrome" }

Chrome mode is handy for automation and DevTools. The simulator is then served at http://localhost:30001/<name><appid>/root/debug/simulator/.

Mocking the SuperApp

The simulator is not a SuperApp, so getMiniAppToken has no real implementation. The extension's Custom API panel (MOCK commissioning in the docs) lets you define a return value. A mock entry looks like this:

JSON
[
  {
    "mockName": "telebirr getMiniAppToken",
    "apiName": "getMiniAppToken",
    "enable": true,
    "mockType": "Local",
    "returnType": "Success",
    "delayTime": "300",
    "returnValue": "{ \"token\": \"mock-access-token\" }"
  }
]

macOS gotcha: "macle-simulator is damaged and can't be opened". Custom API's Apply button writes mockApi.json into the simulator's .app bundle. On macOS that breaks the notarized app's code signature, and Gatekeeper then refuses to launch it. Newer macOS versions block the write outright with "operation not permitted". If you see the dialog, click Cancel, not "Move to Trash", and extract a fresh copy from Macle_25.9.0_DevSuite_Simulator_Mac.zip.

A safer alternative: at launch, the simulator copies its web assets to ~/.macle/target/compose/<name><appid>/root/debug/simulator/ and serves them from there. Drop your mockApi.json into that folder after the simulator starts and refresh, and the signed app stays untouched. The extension also keeps a backup at ~/.macle/mock/mockApi.json.

What you should see

With the mock in place, the app opens on "Signing in with telebirr…" and then shows Sign-in failed with the message "The token is empty or expired, or the token associated information is incorrect", and a Try again button.

This is the expected result in the simulator, and it proves the whole chain works:

StepResult
ma.getMiniAppTokenPassed: returned the mocked token
ma.request → backend /apply/h5tokenPassed: reached the backend through the simulator's request proxy
Backend → /payment/v1/tokenPassed: fabric token issued
Backend → /payment/v1/auth/authTokenPassed: signature accepted
Gateway verdictFailed as expected: 60320005, because a mock token is not a real SuperApp token

To see the real "Welcome, <name>" screen you need a genuine access token, which only exists inside the telebirr SuperApp. The production section below shows how to get there.

Gotchas We Hit and How We Fixed Them

SymptomCauseFix
unzip: "End-of-central-directory signature not found"The simulator "zip" is actually RAR5Use tar -xf on macOS
Simulator will not start on M1, M2 or M3 MacsThe simulator is x86_64 onlyInstall Rosetta 2
"macle-simulator is damaged"Custom API → Apply writes into the signed .appExtract the app again and put mocks in ~/.macle/target/compose/…
unable to verify the first certificateThe sandbox server leaves out its intermediate CAUse NODE_EXTRA_CA_CERTS with the GlobalSign intermediate, never rejectUnauthorized: false
Page stuck on "Signing in…" although the backend got the requestIn the Macle runtime, this inside App.onLaunch is not the object getApp() returns, so this.loginPromise was invisible to the pageKeep shared state in a module (utils/auth.js), because require returns the same instance everywhere
ma.native is not a function style errorswindow.ma.native(...) is the H5 SDK APIIn DSL mini apps, call ma.getMiniAppToken({...}) directly
Backend crashes on the first upstream errorUnhandled promise rejection in an Express 4 async routeAdd try/catch and check res.headersSent
Organization … does not existSample merchant credentials in some demos are out of dateUse the test-bed credentials from your own dashboard

From Simulator to Production

The development guide's end-to-end process is Develop → Debug → Package → Commission (sandbox) → Go live (production).

Package

In the Macle sidebar, click Package. When it finishes, open the output folder from the notification in the bottom-right corner.

Commission in the sandbox

  1. Log in to AppCube as a merchant administrator or developer.
  2. Open Admin → Application Management → Macle Management Console and open your app's card.
  3. Click Upload Mini APP to add a development version.
  4. Under Operation, choose Set as Trial Version.
  5. Click QR Code of The Trial Version and scan it with the sandbox SuperApp. This is where you see real auto sign-in for the first time.
  6. Click Submit for Approve. Once reviewed, the app can be found in the sandbox SuperApp.

Before this works on a device, your backend must be reachable over public HTTPS and whitelisted for the mini app. Update baseUrl in utils/config.js to match.

Go live

  1. Create the mini app in the production environment and upload the package.
  2. Remove vconsole.js from the package so users do not see the debug console.
  3. Click Submit for Approve, add images and a description, and tick Automatically Release after Approval if you want it published as soon as it is approved.
  4. A reviewer approves it under Audit Management → Application Approval, and can scan a QR code with the production SuperApp to try it first.
  5. Switch the backend baseUrl to the production gateway and use your production X-APP-Key and appSecret, which you request from the Ethio telecom administrator.

Security Checklist

  • Secrets stay on the server. appSecret and the RSA private key belong in the backend only, never in the mini app bundle. Keep config.js out of Git and use environment variables or a secret manager in production.
  • Share only your public key with telebirr. Keep the private key private.
  • Never disable TLS verification. Fix the trust chain instead, as shown in the TLS section above.
  • Lock down CORS to the origins you actually serve.
  • Use the open_id as the stable user key. nickName and identifier require whitelisting and may be missing.
  • Remove debug tooling such as vconsole.js and verbose token logging before going live.

Wrapping Up

With about 60 lines of mini app code and a backend of about 100 lines, you get a telebirr Mini App that knows who the user is the instant it opens: no sign-up forms and no passwords. From here you can add pages, call your own APIs with the user's open_id and, when you are ready, add the payment APIs from the same integration guide.

The code is the quick part. Merchant onboarding, telebirr integration approval, the INSA security audit and the production review take most of the 4–6 months, so start them early. Talk to DreamTech if you want a team that has already been through the process.

Frequently Asked Questions

What is a telebirr Mini App?

A lightweight app that runs inside the telebirr SuperApp. Users open it from telebirr without installing anything, and the SuperApp can sign them in automatically and let them pay from their telebirr wallet.

Why should a startup build a telebirr Mini App?

It removes the biggest barriers to getting users: no download, no sign-up form and no password. People open your service from an app they already use, and telebirr already knows who they are.

How long does it take to launch a telebirr Mini App?

Plan for 4 to 6 months from start to go-live. Building the mini app is the quick part. Merchant onboarding, telebirr integration approval, whitelisting, the INSA security audit and Ethio telecom's production review take most of the time.

Does a telebirr Mini App need an INSA security audit?

Plan for one. Your mini app, backend and hosting go through a security assessment by INSA, the Information Network Security Administration, before going live. Starting the audit paperwork early is the best way to shorten the timeline.

What framework are telebirr Mini Apps built with?

Ethio telecom's Macle framework. You write pages in .maml markup, .mass styles and JavaScript, using the Macle IDE extension for VS Code and its simulator. Existing H5 web apps can also be converted and use the telebirr JS SDK.

Can a telebirr Mini App get the user's phone number?

Every mini app receives the user's open_id. The user's name (nickName) and phone number (identifier) are returned only if your merchant code is whitelisted by Ethio telecom.

Can DreamTech build my telebirr Mini App?

Yes. DreamTech builds the mini app and the merchant backend, integrates auto sign-in and telebirr payments, runs sandbox commissioning and prepares the documentation for the INSA audit and telebirr approval.


References and related resources

  • 5+Years of Experience
  • 500+Projects Delivered
  • 100%Built & Supported in Ethiopia
TechBehemoths Verification
GoodFirms Top Software Development Company 2025TechReviewer Top 100 Software Developers for Startups 2025

Ready to Start Your Project?

Book a free consultation to discuss requirements, constraints, delivery options, and the information needed for a scoped proposal.