API DOCUMENTATION

Integrate Ethiopian payment verification across CBE, Telebirr, Bank of Abyssinia, Dashen, Zemen, Awash, M-Pesa, CBE Birr and Bunna into your applications.

BASE URLhttps://verify.haqpass.et/api

AUTHENTICATION

Include your API key in the request header:

X-API-Key: bv_your_api_key

RATE LIMITS

ANONYMOUS5 requests/day
REGISTERED (FREE)10 requests/day
API WITH BALANCEUnlimited (5 ETB/req)
POST/api/verify-cbe

Verify a CBE transaction using the reference number and account number.

REQUEST

POST /api/verify-cbe
Content-Type: application/json
X-API-Key: your_api_key_here

{
  "transactionRef": "FT26095HT668",
  "accountNumber": "1000680017250"
}

RESPONSE

{
  "status": "success",
  "data": {
    "bank": "Commercial Bank of Ethiopia",
    "document_type": "VAT Invoice/Customer Receipt",
    "status": "Verified",
    "transaction_reference": "FT26095HT668",
    "payment_date": "4/5/2026, 7:58:00 PM",
    "payer_name": "ABEBE KEBEDE BEKELE",
    "payer_account": "1****1427",
    "receiver_name": "Mr Dawit Tesfaye Mekonnen",
    "receiver_account": "1****7259",
    "transferred_amount": "60.00 ETB",
    "commission": "0.50 ETB",
    "total_debited": "60.61 ETB",
    "pdf_available": true
  }
}
POST/api/upload-cbe

Upload an image containing a QR code with CBE transaction reference.

REQUEST

POST /api/upload-cbe
X-API-Key: your_api_key_here
Content-Type: multipart/form-data

image: <file>
POST/api/scan-cbe

Verify a transaction reference extracted from a scanned QR code.

REQUEST

POST /api/scan-cbe
Content-Type: application/json
X-API-Key: your_api_key_here

{
  "transactionRef": "FT26095HT668",
  "accountNumber": "1000680017250"
}
POST/api/verify-telebirr

Verify a Telebirr receipt using the 10-character receipt reference.

REQUEST

POST /api/verify-telebirr
Content-Type: application/json
X-API-Key: your_api_key_here

{
  "reference": "CJ81K4M9PQ"
}

RESPONSE

{
  "status": "success",
  "data": {
    "bank": "Telebirr",
    "document_type": "Telebirr Transaction Receipt",
    "status": "Verified",
    "transaction_reference": "CJ81K4M9PQ",
    "payment_date": "11-06-2026 08:34:12",
    "payer_name": "Sara Tesfaye Lemma",
    "payer_account": "0911223344",
    "receiver_name": "Dawit Bekele Asfaw",
    "receiver_account": "0922334455",
    "transferred_amount": "250.00 ETB",
    "commission": "0.00 ETB",
    "total_debited": "250.00 ETB",
    "pdf_available": true
  }
}
POST/api/verify-abyssinia

Verify a Bank of Abyssinia transfer receipt using the FT-prefixed reference (17 chars total).

REQUEST

POST /api/verify-abyssinia
Content-Type: application/json
X-API-Key: your_api_key_here

{
  "reference": "FT26AB12CD34"
}

RESPONSE

{
  "status": "success",
  "data": {
    "bank": "Bank of Abyssinia",
    "document_type": "Transfer Receipt",
    "status": "Verified",
    "transaction_reference": "FT26AB12CD34",
    "payment_date": "29/05/26 14:21",
    "payer_name": "Hanna Girma Wolde",
    "payer_account": "1200000012345",
    "receiver_name": "Yonas Alemu Tadesse",
    "receiver_account": "1200000067890",
    "transferred_amount": "1,500.00 ETB",
    "total_debited": "1,500.00 ETB",
    "pdf_available": true
  }
}
POST/api/verify-dashen

Verify a Dashen Bank receipt. Reference is 16 chars starting with 3 digits.

REQUEST

POST /api/verify-dashen
Content-Type: application/json
X-API-Key: your_api_key_here

{
  "reference": "108ABCD1234567XY"
}
POST/api/verify-cbebirr

Verify a CBE Birr (mobile wallet) receipt using the receipt id and the customer's phone.

REQUEST

POST /api/verify-cbebirr
Content-Type: application/json
X-API-Key: your_api_key_here

{
  "receipt": "ABC123XYZ789",
  "phone": "0911223344"
}
POST/api/verify-bunna

Verify a Bunna Bank receipt by URL. Use the receipt link, not the feedback link.

REQUEST

POST /api/verify-bunna
Content-Type: application/json
X-API-Key: your_api_key_here

{
  "url": "https://online.bunnabanksc.com/receipt/#/abc123token"
}
POST/api/verify-zemen

Verify a Zemen Bank receipt. Accepts a full share.zemenbank.com URL, the combined account+reference string, or a reference plus account number (we use the last 8 digits).

REQUEST

POST /api/verify-zemen
Content-Type: application/json
X-API-Key: your_api_key_here

# either give reference + account
{
  "reference": "108ATWR2520600HM",
  "accountNumber": "1009449497018"
}

# or pass the full URL (or combined account+reference string)
{
  "url": "https://share.zemenbank.com/rt/94497018108ATWR2520600HM/pdf"
}

RESPONSE

{
  "status": "success",
  "data": {
    "bank": "Zemen Bank",
    "document_type": "Zemen Bank VAT Invoice",
    "status": "Verified",
    "transaction_reference": "108ATWR2520600HM",
    "payment_date": "25-Jul-2025",
    "payer_name": "Nahom Alemu Nebebe",
    "payer_account": "103****7018",
    "receiver_name": "Zemen Bank S.C.",
    "receiver_account": "20****20",
    "transferred_amount": "4000.00 ETB",
    "commission": "20.00 ETB",
    "vat_on_commission": "3.00 ETB",
    "total_debited": "4023.00 ETB",
    "pdf_available": true
  }
}
POST/api/verify-awash

Verify an Awash Bank receipt. Accepts the full awashpay.awashbank.com URL or the bare token (12 hex + "-" + 4-8 alphanumeric).

REQUEST

POST /api/verify-awash
Content-Type: application/json
X-API-Key: your_api_key_here

# either the full URL
{
  "url": "https://awashpay.awashbank.com:8225/-E41AE0D86FFA-21XYYW"
}

# or the bare token
{
  "reference": "E41AE0D86FFA-21XYYW"
}

RESPONSE

{
  "status": "success",
  "data": {
    "bank": "Awash Bank",
    "document_type": "Awash Bank Transfer Receipt",
    "status": "Verified",
    "transaction_reference": "E41AE0D86FFA",
    "payment_date": "2025-08-04 09:25:12 AM",
    "payer_name": "Binyam Feyissa Gudina",
    "payer_account": "01320******100",
    "receiver_name": "Binyam Feyissa Gudina",
    "receiver_account": "1000361990898",
    "transferred_amount": "20 ETB",
    "commission": "0.12 ETB",
    "vat_on_commission": "0.02 ETB",
    "total_debited": "20.14 ETB",
    "pdf_available": false
  }
}
POST/api/verify-mpesa

Verify an M-Pesa (Safaricom Ethiopia) receipt. Accepts the transaction id (trxNo) or the full m-pesabusiness.safaricom.et receipt URL.

REQUEST

POST /api/verify-mpesa
Content-Type: application/json
X-API-Key: your_api_key_here

# either the transaction id
{
  "transactionId": "TFK1ABCD23"
}

# or the full receipt URL
{
  "url": "https://m-pesabusiness.safaricom.et/api/receipt/getReceipt?trxNo=TFK1ABCD23"
}

RESPONSE

{
  "status": "success",
  "data": {
    "bank": "M-Pesa",
    "document_type": "M-Pesa Transaction Receipt",
    "status": "Verified",
    "transaction_reference": "TFK1ABCD23",
    "payment_date": "2025-09-15 14:22:08",
    "payer_name": "Abebe Kebede",
    "payer_account": "0712345678",
    "receiver_name": "Sheger Mart",
    "receiver_account": "0798765432",
    "transferred_amount": "250.00 ETB",
    "commission": "1.50 ETB",
    "vat_on_commission": "0.23 ETB",
    "total_debited": "250.00 ETB",
    "pdf_available": true
  }
}

REFERENCE AUTO-DETECTION

The verification form auto-switches banks based on the reference shape you paste. If you type an FT reference while Dashen is selected, the form will jump to CBE or Abyssinia automatically.

# Reference auto-detection rules
CBE         FT + 10 alphanumeric            (12 chars total)
Abyssinia   FT + 15 alphanumeric            (17 chars total)
Dashen      3 digits + 13 alphanumeric      (16 chars total)
Telebirr    10 alphanumeric (no FT prefix)
Zemen       reference (typically 16 chars) + last 8 digits of account
Awash       12 hex chars + "-" + 4-8 alphanumeric  e.g. E41AE0D86FFA-21XYYW
M-Pesa      8-16 alphanumeric trxNo (Safaricom Ethiopia receipt)
CBE Birr    receipt id (6-30 alphanumeric) + Ethiopian phone number
Bunna       full https://online.bunnabanksc.com/receipt/#/<token> URL