Get the appCreate an account
Register and choose a subscription plan that fits your verification volume.
Sign up freeDeveloper API
Integrate payment verification in minutes
A single REST endpoint to verify Telebirr, CBE, CBE Birr, BOA and more, with ready-to-paste code samples in 7 languages.
- 1
- Endpoint
- 7
- Languages
- 6+
- Providers
- <5s
- Response time
Quick start
Up and running in 3 steps
Generate an API key
Create an API key in your dashboard, then enable providers under My providers. CBE Birr needs your wallet phone in 251XXXXXXXXX format; CBE and Bank of Abyssinia need account numbers.
DashboardCall POST /api/verify
Send a provider key (for example cbebirr) and transaction ID. Wallet phone and account numbers stay in your dashboard — not in the request body.
See endpointVerify request
Send a POST with your API key in the header and a JSON body. Keys start with vk_live_. Use the short provider key from the table below, not a UUID.
- Method
POST- URL
https://veriq.company/api/verify- Header
X-API-Key: YOUR_API_KEY- Content-Type
application/json
Request body
application/json
Loading…- provider
- Required. Lowercase API key from the supported providers table.
- transactionId
- Required. Bank reference / receipt ID (max 128 characters).
Supported providers
Supported provider keys for the API. Enable each provider and add any required config in your dashboard under My providers; wallet phone in 251XXXXXXXXX format (CBE Birr) and account numbers (CBE, BOA) are not sent in the request body.
| API key | Provider | Config on file |
|---|---|---|
amhara |  Amhara Bank | Not required |
boa |  Bank of Abyssinia | Enable this provider under Providers and save your account number (at least 5 digits). Verification uses reference + last 5 digits. |
cbebirr |  CBE Birr | Save your CBE Birr wallet phone under Providers in 251XXXXXXXXX format (e.g. 251947431170). Verification uses the transaction ID and that phone number. |
cbe |  Commercial Bank of Ethiopia | Save your account number under Providers. Verification matches the reference with the last 8 digits of that account. |
mpesa |  M-PESA | Not required |
telebirr |  Telebirr | Not required |
wegagen |  Wegagen Bank | Not required |
Success response (200)
On HTTP 200, check success === true and read payment details from receipt.
200 OK
Loading…Error responses
Common failures. Use message for display and code for programmatic handling when present.
HTTP 401Unauthorized
Missing, invalid, or revoked API key.
401 example
Loading…HTTP 400
MISSING_ACCOUNTMissing account configurationSome providers require an account number or CBE Birr wallet phone on your enabled provider before verification.
400 example
Loading…HTTP 400Validation failed
Invalid JSON or invalid provider key format.
400 example
Loading…HTTP 403
PLAN_REQUIREDNo subscription planUser has not selected an active payment plan.
403 example
Loading…HTTP 429
QUOTA_EXCEEDEDMonthly limit reachedAPI and dashboard verification attempts exceeded the plan limit for this month.
429 example
Loading…HTTP 403Provider not enabled
The provider key exists but is not enabled for your account.
403 example
Loading…HTTP 404Unknown provider key
No provider with this API key is configured.
404 example
Loading…HTTP 404
INVALID_TRANSACTION_IDTransaction not foundBank could not find a receipt for this reference (wrong ID or account).
404 example
Loading…HTTP 502
NETWORK_FAILEDBank temporarily unavailableUpstream bank or receipt service timed out or returned a server error.
502 example
Loading…HTTP 502
PROVIDER_FETCH_BLOCKEDProvider blocked server requestThe receipt host rejected the request from your server IP (common on overseas hosting). Use an Ethiopian HTTP proxy via TELEBIRR_HTTP_PROXY.
502 example
Loading…Code examples
Replace YOUR_TRANSACTION_ID and your API key. Pick a provider key for the sample payload.
bash
Loading…Receipt fields
All providers return the same receipt object shape when verification succeeds.
- transactionId
- Bank reference or receipt ID
- payer
- Who paid
- receiver
- Who received
- amount
- Transferred amount
- totalAmount
- Total debited
- commissionAmount
- Fee or service charge (e.g. CBE Birr), if shown on receipt
- vatAmount
- VAT (e.g. CBE Birr), if shown on receipt
- date
- Payment date and time
- reason
- Payment reason or remark, when available
- creditedAccount
- Credited account, when available
- status
- VERIFIED on success
Get started
Start verifying payments today
Free account. No card required. API access after choosing a plan.