This API provides verification services for payment transactions made through Commercial Bank of Ethiopia (CBE), Telebirr, Dashen Bank, Bank of Abyssinia, CBE Birr, and M-Pesa mobile payment platforms in Ethiopia.
It allows applications to verify the authenticity and details of payment receipts by reference numbers or uploaded images.

⚠️ Disclaimer: This is not an official API. I am not affiliated with Ethio Telecom, Telebirr, or Commercial Bank of Ethiopia (CBE). This tool is built for personal and developer utility purposes only and scrapes publicly available data.

• One endpoint to rule them all: Verifies transactions from multiple providers (CBE, Telebirr, Dashen, Bank of Abyssinia, CBE Birr) using a single, intelligent endpoint (POST /verify). Note: M-Pesa is currently supported via its dedicated endpoint only.
• Automatically detects the provider based on the format of the provided reference number and accompanying JSON payload.
• Strictly validates payloads and intelligently delegates to the correct backend service.

• Verifies CBE bank transfers using reference number and account suffix
• Extracts key payment details:
  • Payer name and account
  • Receiver name and account
  • Transaction amount
  • Payment date and time
  • Reference number
  • Payment description/reason

• Verifies Telebirr mobile money transfers using a reference number
• Extracts key transaction details:
  • Payer name and Telebirr number
  • Credited party name and account
  • Bank name (if the transaction was made to another bank)
  • Transaction status
  • Receipt number
  • Payment date
  • Settled amount
  • Service fees and VAT
  • Total paid amount

• Verifies Dashen bank transfers using reference number
• Extracts comprehensive transaction details:
  • Sender name and account number
  • Transaction channel and service type
  • Narrative/description
  • Receiver name and phone number
  • Institution name
  • Transaction and transfer references
  • Transaction date and amount
  • Service charges, taxes, and fees breakdown
  • Total amount

• Verifies Bank of Abyssinia transfers using reference number and 5-digit suffix
• Extracts key transaction details:
  • Transaction reference and details
  • Account information
  • Payment amounts and dates
  • Verification status

• Verifies M-Pesa mobile money transfers using receipt reference
• Extracts transaction details from the generated receipt PDFs

• Verifies CBE Birr mobile money transfers using receipt number and phone number
• Extracts transaction details:
  • Receipt and transaction information
  • Payer and receiver details
  • Transaction amounts and fees
  • Payment status and timestamps
  • Ethiopian phone number validation (251 format)

• Verifies payments by analyzing uploaded receipt images
• Uses Mistral AI to detect receipt type and extract transaction details
• Supports both CBE and Telebirr receipt screenshots

Due to regional restrictions by the Telebirr system and Safaricom M-Pesa, hosting these endpoints outside of Ethiopia/Kenya (e.g., on a foreign VPS like Hetzner or AWS) may result in failed receipt verification. Specifically:

• Telebirr’s receipt pages (https://transactioninfo.ethiotelecom.et/receipt/[REFERENCE]) often block or timeout requests made from foreign IP addresses.
• Safaricom's M-Pesa API (https://m-pesabusiness.safaricom.et/api/receipt/getReceipt) strictly blocks connections from foreign data centers, resulting in 504 Gateway Timeout or 500 Internal Server Errors.

• VPS or cloud servers located outside Ethiopia/Kenya

• Ethiopian-hosted servers (e.g., Ethio Telecom web hosting, TeleCloud VPS)
• Developers self-hosting the code on infrastructure based in Ethiopia

This project supports secondary fallback verification relays hosted inside Ethiopia. When the primary verify-telebirr or verify-mpesa fetch fails on your foreign VPS, the server can fallback to our proxy to complete the verification. A standalone mpesa.php file is included in the .github / repository root which can be easily hosted on any cheap generic cPanel host inside Ethiopia to act as your own private proxy.

For best results and full control, clone the repository and self-host the main Node.js application from inside Ethiopia.

If you know your environment cannot access the primary endpoint, set the following in your .env:

SKIP_PRIMARY_VERIFICATION=true

This will skip the primary Telebirr receipt fetch entirely and go straight to the fallback proxy — only for your local use case. Other users can still benefit from both layers.

# Clone the repository
git clone https://github.com/Vixen878/verifier-api

# Navigate to the project directory
cd verifier-api

# Install dependencies
pnpm install

pnpm dev

pnpm build
pnpm start

Verify a payment from multiple providers using a single endpoint. The API automatically detects the provider based on the reference format and accompanying payload.

Requires API Key

Request Body:

{
  "reference": "REQUIRED_REFERENCE_STRING",
  "suffix": "OPTIONAL_SUFFIX_FOR_CBE_OR_ABYSSINIA",
  "phoneNumber": "OPTIONAL_PHONE_FOR_CBEBIRR"
}

Sorting Rules:

• Dashen Bank: reference must be 16 chars starting with 3 digits. No extra params.
• CBE: reference must be 12 chars starting with FT. Requires 8-digit suffix.
• Bank of Abyssinia: reference must be 12 chars starting with FT. Requires 5-digit suffix.
• CBE Birr: reference must be 10 alphanumeric chars. Requires 10-12 digit phoneNumber.
• Telebirr: reference must be 10 alphanumeric chars. No extra params.

Verify a CBE payment using a reference number and account suffix.

Requires API Key

Request Body:

{
  "reference": "REFERENCE_NUMBER",
  "accountSuffix": "ACCOUNT_SUFFIX"
}

Verify a Telebirr payment using a reference number.

Requires API Key

Request Body:

{
  "reference": "REFERENCE_NUMBER"
}

Verify a Dashen bank payment using a reference number.

Requires API Key

Request Body:

{
  "reference": "DASHEN_REFERENCE_NUMBER"
}

Response:

{
  "success": true,
  "senderName": "John Doe",
  "senderAccountNumber": "1234567890",
  "transactionChannel": "Mobile Banking",
  "serviceType": "Fund Transfer",
  "narrative": "Payment for services",
  "receiverName": "Jane Smith",
  "phoneNo": "251912345678",
  "transactionReference": "TXN123456",
  "transactionDate": "2023-06-15T10:30:00Z",
  "transactionAmount": 1000.0,
  "serviceCharge": 5.0,
  "total": 1005.0
}

Verify a Bank of Abyssinia payment using a reference number and 5-digit suffix.

Requires API Key

Request Body:

{
  "reference": "ABYSSINIA_REFERENCE",
  "suffix": "12345"
}

Note: The suffix must be exactly 5 digits.

Verify an M-Pesa payment using a receipt number (reference).

Requires API Key

Request Body:

{
  "receiptNumber": "RECEIPT_REFERENCE"
}

Verify a CBE Birr payment using receipt number and phone number.

Requires API Key

Request Body:

{
  "receiptNumber": "RECEIPT_NUMBER",
  "phoneNumber": "251912345678"
}

Note: Phone number must be in Ethiopian format (251 + 9 digits).

Requires API Key

Verify a payment by uploading an image of the receipt. This endpoint supports both CBE and Telebirr screenshots.

Request Body: Multipart form-data with an image file.

• Optional Query Param: ?autoVerify=true
  When enabled, the system detects the receipt type and routes it to the correct verification flow automatically.
• Note: If the auto-detected receipt is from CBE, the request must include your Suffix (last 8 digits of your account).

curl -X POST https://verifyapi.leulzenebe.pro/verify \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reference": "FT253089F68Z", "suffix": "16825193" }'

curl -X POST https://verifyapi.leulzenebe.pro/verify-cbe \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reference": "FT2513001V2G", "accountSuffix": "39003377" }'

curl -X POST https://verifyapi.leulzenebe.pro/verify-telebirr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reference": "CE2513001XYT" }'

curl -X POST https://verifyapi.leulzenebe.pro/verify-dashen \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reference": "DASHEN_REFERENCE_NUMBER" }'

curl -X POST https://verifyapi.leulzenebe.pro/verify-abyssinia \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reference": "ABYSSINIA_REFERENCE", "suffix": "12345" }'

curl -X POST https://verifyapi.leulzenebe.pro/verify-cbebirr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "receiptNumber": "RECEIPT_NUMBER", "phoneNumber": "251912345678" }'

curl -X POST https://verifyapi.leulzenebe.pro/verify-mpesa \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "receiptNumber": "RECEIPT_REFERENCE" }'

curl -X POST https://verifyapi.leulzenebe.pro/verify-image?autoVerify=true \
  -H "x-api-key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "suffix=39003377"

Check if the API is running properly.

No API Key Required

Response:

{
  "status": "ok",
  "timestamp": "2023-06-15T12:34:56.789Z"
}

Get information about the API and available endpoints.

Response:

{
  "message": "Verifier API is running",
  "version": "2.1.0",
  "endpoints": [
    "/verify-cbe",
    "/verify-telebirr",
    "/verify-dashen",
    "/verify-abyssinia",
    "/verify-cbebirr",
    "/verify-image"
  ],
  "health": "/health",
  "documentation": "https://github.com/Vixen878/verifier-api"
}

All verification endpoints require a valid API key.
Pass the key using either:

• Header: x-api-key: YOUR_API_KEY
• Query: ?apiKey=YOUR_API_KEY

To generate an API key, visit: https://verify.leul.et

Use your API key to call endpoints from:

https://verifyapi.leulzenebe.pro/[endpoint]

API Documentation: https://verify.leul.et/docs

Requires x-admin-key in header (from your environment config).

Generate a new API key.

{
  "owner": "your-identifier"
}

List existing API keys (masked view).

Retrieve usage statistics:

• Request count by endpoint
• Success/failure ratio
• Average response time
• Requests by IP

Create a .env file in the root directory with the following variables:

PORT=3001
NODE_ENV=development # or production
LOG_LEVEL=info       # or debug, error
MISTRAL_API_KEY=your_mistral_api_key # Required for image verification
SKIP_PRIMARY_VERIFICATION=false      # Set to true to bypass primary fetch

You can get an API key for Mistral AI from https://mistral.ai/

• Uses winston for structured logging.
• Log files are stored under the logs/ directory:
  • logs/error.log – error-level logs
  • logs/combined.log – all logs including debug/info
• debug logs are only visible in development mode (NODE_ENV !== 'production').

To override log level manually:

LOG_LEVEL=debug

• Node.js with Express
• TypeScript
• Axios – HTTP requests
• Cheerio – HTML parsing
• Puppeteer – headless browser automation (used for CBE scraping)
• Winston – structured logging
• Prisma + MySQL (persistent storage)
• Mistral AI – OCR for image-based verification

• apiKey model stores API key, usage count, owner, timestamps.
• usageLog model stores every request metadata:
  • endpoint, method, status code, duration, IP, API key ID

Stats are used for /admin/stats endpoint and dashboard monitoring.

MIT License — see the LICENSE file for details.

Leul Zenebe
Creofam LLC
🌐 creofam.com
🌐 Personal Site