One API to verify every payment.
Check a telebirr receipt in seconds and confirm the amount and receiver before you release the order.
Build once, verify everywhere.
Every provider returns the same clean JSON. Send a transaction number and what you expect, get back a verified flag and the parsed transaction.
Set your API key
Add API_KEYS to your environment variables and send
it in the x-api-key header.
Call the API
Send POST /api/verify from your server with the
transaction number and expected values.
Check verified
If verified is true, save the reference so it can’t
be reused, then mark the order paid.
Copy, paste, ship.
Server-side examples for the most common stacks.
- Call the API from your server, never from the browser, so your key stays private.
- Reject references you have already used.
- Send amount, receiverPhone and maxAgeMinutes so a valid receipt for someone else can’t pass.
Endpoints
Base URL
| Endpoint | Description |
|---|---|
POST /api/verify |
Fetch a transaction and run checks against your expected values. |
GET /api/transactions/:provider/:reference |
Parsed transaction details only. |
GET /api/providers |
List supported providers. |
GET /health |
Health check. |
Expected fields (all optional)
| Field | Checks that |
|---|---|
amount |
Paid amount equals the value. |
minAmount |
Paid amount is at least the value. |
receiverName |
Every word appears in the receiver’s name. |
receiverPhone |
Last 4 digits match the receiver. |
payerPhone |
Last 4 digits match the payer. |
maxAgeMinutes |
Paid within this many minutes. |
Errors
| HTTP | Code | Meaning |
|---|---|---|
| 400 |
INVALID_REFERENCE UNKNOWN_PROVIDER
BAD_REQUEST
|
Bad input. |
| 401 | UNAUTHORIZED |
Missing or wrong API key. |
| 404 | NOT_FOUND |
Receipt does not exist. |
| 501 | NOT_IMPLEMENTED |
Provider not available yet. |
| 502 |
UPSTREAM_UNREACHABLE UPSTREAM_ERROR
|
Provider unavailable. Retry. |