ethio-receipt-parser

A modular TypeScript parser for Ethiopian banking and payment receipts.

ethio-receipt-parser helps developers extract structured transaction data from Ethiopian payment providers such as:

• Bank of Abyssinia (BOA)
• Commercial Bank of Ethiopia (CBE)
• Telebirr
• Awash Bank

Built for automation, fintech integrations, dashboards, bots, transaction verification systems, and internal tooling.

Features

• Unified receipt parsing API
• Parse BOA receipt links
• Parse CBE receipt pages/PDFs
• Parse Telebirr receipts
• Parse Awash Bank receipts
• Clean TypeScript architecture
• Promise-based API
• Modular provider system
• Easily extendable
• Built for real-world integrations

Installation

Using pnpm:

pnpm add ethio-receipt-parser

Using npm:

npm install ethio-receipt-parser

Using yarn:

yarn add ethio-receipt-parser

Quick Start

import {
  handleBoaReceipt,
  handleCbeReceipt,
  handleTelebirrReceipt,
  handleAwashReceipt,
} from "ethio-receipt-parser";

const run = async () => {
  const boa = await handleBoaReceipt(
    "https://cs.bankofabyssinia.com/slip/?trx=XXXX",
  );

  const cbe = await handleCbeReceipt("https://apps.cbe.com.et:100/?id=XXXX");

  const telebirr = await handleTelebirrReceipt(
    "https://transactioninfo.ethiotelecom.et/receipt/XXXX",
  );

  const awash = await handleAwashReceipt(
    "https://awashbank.com/receipt?id=XXXX",
  );

  console.log(boa);
  console.log(cbe);
  console.log(telebirr);
  console.log(awash);
};

run();

Example Output

{
  "provider": "BOA",
  "payer": "ABEL TESFAYE DEMEKE",
  "account": "2******91",
  "creditedPartyName": "SELAMAWIT KASSA BERHANE",
  "bankAccountNumber": "7*****38",
  "amount": 54320,
  "date": "18/03/25 10:42",
  "reference": "FT259871KLMQ43210",
  "status": "SUCCESS"
}

Supported Providers

| Provider | Status | | -------- | --------------------------- | | BOA | Stable | | Telebirr | Stable | | CBE | Working (Under Maintenance) | | Awash | Stable |

Important Note About CBE

The CBE parser is currently working, but it is still under maintenance for a more permanent and reliable solution.

At the moment, CBE parsing depends on request-specific values such as:

• x-app-id
• client keys
• internal request headers
• validation tokens

These values are currently hardcoded internally.

As the developer, I do not consider this a reliable long-term approach because CBE may change these values at any time.

If the CBE parser suddenly stops working, the first thing to inspect is:

• changed x-app-id
• expired client keys
• modified request headers
• updated request validation rules

Most CBE-related issues will likely originate from those changes.

A better dynamic extraction system is currently being researched.

API

BOA

handleBoaReceipt(url: string)

Example

const result = await handleBoaReceipt(receiptUrl);

CBE

handleCbeReceipt(url: string)

Example

const result = await handleCbeReceipt(receiptUrl);

Telebirr

handleTelebirrReceipt(url: string)

Example

const result = await handleTelebirrReceipt(receiptUrl);

Awash

handleAwashReceipt(url: string)

Example

const result = await handleAwashReceipt(receiptUrl);

Project Structure

src
├── core
│   └── http
│       └── axios.client.ts
├── services
│   ├── boa
│   ├── cbe
│   ├── telebirr
│   └── awash
├── shared
│   ├── payment.parser.ts
│   ├── types.ts
│   └── utils.ts
└── index.ts

Architecture

Each provider follows the same structure:

provider/
├── provider.client.ts
├── provider.parser.ts
├── provider.service.ts
└── index.ts

Responsibilities

| File | Purpose | | --------- | --------------------- | | client | Handles HTTP requests | | parser | Extracts receipt data | | service | Main business logic | | index | Exports module APIs |

Development

Clone Repository

git clone <repo-url>

Install Dependencies

pnpm install

Run Development Mode

pnpm dev

Build

pnpm build

Test

pnpm test

Use Cases

• Telegram bots
• Payment verification systems
• Fintech apps
• Internal dashboards
• Accounting automation
• Transaction extraction pipelines
• Mobile app backends

Roadmap

• Better CBE dynamic request handling
• Awash Bank support
• Dashen Bank support
• OCR support for screenshots/images
• PDF receipt parsing improvements
• Automatic provider detection
• Webhook-ready integrations

Contributing

Contributions are welcome.

Especially useful contributions include:

• additional bank support
• parser stability improvements
• token extraction research
• test receipt samples
• TypeScript improvements
• better error handling

Disclaimer

This package is not affiliated with any Ethiopian bank or payment provider.

Banks may update their APIs, security systems, HTML structure, or validation methods at any time, which may temporarily affect parser stability.

Use responsibly.

License

MIT