tx-verify

TypeScript transaction receipt verification for Ethiopian payment providers. The package fetches official HTML, JSON, or PDF receipts and returns one consistent TransactionResult.

Image and OCR verification are intentionally not included.

Providers

| Provider | Function | | --- | --- | | Commercial Bank of Ethiopia | verifyCbe() | | Telebirr | verifyTelebirr() | | Dashen Bank | verifyDashen() | | Bank of Abyssinia | verifyAbyssinia() | | CBE Birr | verifyCbeBirr() | | M-Pesa Ethiopia | verifyMpesa() | | Awash Bank | verifyAwash() | | Siinqee Bank | verifySiinqee() | | Abay Bank | verifyAbay() | | Zemen Bank | verifyZemen() |

Installation

pnpm add tx-verify-ts

Node.js 20 or newer is required.

Usage

import { verifyCbe, verifyTelebirr } from "tx-verify-ts";

const telebirr = await verifyTelebirr("CGA6FL0MI0");
if (telebirr.success) {
  console.log(telebirr.payerName, telebirr.amount);
} else {
  console.error(telebirr.error);
}

const cbe = await verifyCbe("FT23062669JJ", "12345678");

Expected lookup, network, and parsing failures are returned as TransactionResult values with success: false. Callers normally do not need try/catch around a verifier.

Function Signatures

verifyCbe(reference, accountSuffix?, options?)
verifyAbyssinia(reference, accountSuffix?, options?)
verifyCbeBirr(receiptNumber, phoneNumber, options?)
verifyTelebirr(reference, options?)
verifyDashen(reference, options?)
verifyMpesa(transactionId, options?)
verifyAwash(referenceOrUrl, options?)
verifySiinqee(reference, options?)
verifyAbay(referenceOrUrl, options?)
verifyZemen(referenceOrUrl, options?)

Proxies

Proxy configuration is explicit. The package never reads HTTP_PROXY, HTTPS_PROXY, or related environment variables.

await verifyTelebirr("CGA6FL0MI0", {
  proxies: "socks5h://user:[email protected]:1080",
});

await verifyCbe("FT23062669JJ", "12345678", {
  proxies: {
    http: "http://127.0.0.1:8080",
    https: "socks5://127.0.0.1:1080",
  },
});

Supported proxy schemes are HTTP, HTTPS, SOCKS4, SOCKS5, and SOCKS5h.

Result

Every verifier returns Promise<TransactionResult>. Common fields include:

{
  success: boolean;
  error: string | null;
  provider: string | null;
  transactionReference: string | null;
  receiptNumber: string | null;
  payerName: string | null;
  payerAccount: string | null;
  receiverName: string | null;
  receiverAccount: string | null;
  amount: number | null;
  serviceCharge: number | null;
  vat: number | null;
  totalAmount: number | null;
  transactionDate: Date | null;
  currency: string | null;
  meta: Record<string, unknown>;
}

Provider-specific receipt fields are retained in meta.

Development

pnpm install --ignore-workspace
pnpm typecheck
pnpm test
pnpm build

Publishing

The package name tx-verify-ts is currently available on npm. Publishing runs the full verification and build pipeline automatically through prepack.

npm login
npm publish

Only dist, README.md, LICENSE, and package.json are included in the published package.

Contributing

Contributions are welcome. See CONTRIBUTING.md for the development workflow, testing requirements, and pull request guidance.

To report a bug, request an improvement, or suggest a provider, open a GitHub issue. For a new bank integration, include:

• The bank or payment provider name.
• A public transaction or receipt URL.
• A transaction ID or reference that can be used with the URL.
• The expected receipt format, such as HTML, JSON, or PDF.
• Any account suffix, phone number, or other required lookup value.

Do not include passwords, private customer information, unmasked account numbers, or confidential receipts. Use test or redacted transaction data whenever possible.