📘 README.md (Developer Documentation)

Telebirr Payment Module

A reusable TypeScript module for integrating Telebirr InApp payments with safe Fabric token reuse.

Installation

npm install telebirr-payment

Environment Setup

Copy .env.example → .env and fill in:

BASE_URL=https://developerportal.ethiotelebirr.et:38443/apiaccess/payment/gateway
FABRIC_APP_ID=your-x-app-key
APP_SECRET=your-app-secret
MERCHANT_APP_ID=your-merchant-app-id
MERCHANT_CODE=your-short-code
PRIVATE_KEY_PATH=./keys/private_key.pem
NOTIFY_URL=https://your-domain.com/payment/notify
REDIRECT_URL=https://your-domain.com/redirect

Fabric Token Format

{
  token: "Bearer xxx",
  effectiveDate: "20260124201821",
  expirationDate: "20260124211821"
}

Basic Usage

import { createInAppOrder, FabricToken } from "telebirr-payment";

let storedToken: FabricToken | null = null;

const result = await createInAppOrder(
  { title: "Test Payment", amount: "10.00" },
  storedToken,
);

// IMPORTANT: always store the returned token
storedToken = result.fabricToken;

console.log(result.receiveCode);

Token Handling Rules

• You must always pass back the last returned fabricToken

• The module will:

  • Reuse it if valid
  • Refresh it if expired

• This prevents exceeding Telebirr’s 100 tokens/day limit

Storage Recommendations

You may store the token in:

• Memory (single-instance apps)
• Redis
• Database
• KV store
• Secrets manager

The module does not care how you store it.

Errors

• Network errors → thrown
• Telebirr business errors → thrown as JSON string
• Invalid configuration → thrown at startup

What this module does NOT do

• ❌ Does not store tokens
• ❌ Does not generate QR images
• ❌ Does not verify callback signatures
• ❌ Does not manage databases

Supported Payment Types

• ✅ InApp (current)
• ⏳ QuickPay / QR (future extension)
• ⏳ WebCheckout (future extension)