Developers
The Wabi API
Verify a payment from your own point of sale, delivery app or back office. Send a receipt reference with your key, and get back what the bank recorded.
Getting a key
API access is by request. Write to us with what you are building.
Once your team has access, sign in, open Settings and choose API. Name the key after the system that will use it. The secret is shown once, so copy it then.
Make a request
One endpoint. Send JSON, with your secret in the x-service-secret header.
POST https://wabi.et/api/service/verifyreferencerequired- The receipt link, or the reference or receipt number from the receipt.
accountSuffixoptional- The last 8 digits of an account. Needed for a bare CBE FT number (either party's account) and a bare Zemen Bank reference (the payer's account). For Bank of Abyssinia, send the receipt link, or the FT number with the account's last 5 digits joined to it, as reference.
bankoptional- Which bank or wallet, when a bare number could belong to more than one. One of the codes below.
claimedAmountoptional- The amount the customer's receipt shows. We tell you if it matches neither figure the bank recorded. Above 0, at most 10,000,000.
expectedAmountoptional- What the customer owed. We tell you how much short the payment is. 0 or more, at most 10,000,000.
Bank codes
CBECommercial Bank of EthiopiaTelebirrTelebirrAwashAwash BankZemenZemen BankDashenDashen BankCBEBirrCBE BirrWegagenWegagen BankAbyssiniaBank of AbyssiniaMPesaM-Pesa
curl -X POST https://wabi.et/api/service/verify \
-H "x-service-secret: vfy_..." \
-H "Content-Type: application/json" \
-d '{ "reference": "FT26251ABCDE", "accountSuffix": "12345678" }'const res = await fetch("https://wabi.et/api/service/verify", {
method: "POST",
headers: {
"x-service-secret": process.env.WABI_SECRET,
"Content-Type": "application/json",
},
body: JSON.stringify({
reference: "FT26251ABCDE",
accountSuffix: "12345678",
expectedAmount: 1500,
}),
})
const body = await res.json()
if (!res.ok) throw new Error(body.code)
if (body.settled && body.shortfall === 0) {
// The bank recorded the full amount: hand the goods over.
}The answer
A payment the bank found comes back with status 200, in this shape.
{
"data": {
"referenceNumber": "FT26251ABCDE",
"payerName": "PAYER NAME",
"payerAccount": "****5678",
"receiverName": "RECEIVER NAME",
"receiverAccount": "****4321",
"amount": 1500,
"amountInWords": null,
"serviceCharge": 0.5,
"totalDebited": 1500.5,
"currency": "ETB",
"paymentDate": "2026-10-13T06:24:00.000Z",
"reason": null,
"status": "Completed",
"bank": "CBE",
"token": null,
"raw": { }
},
"settled": true,
"receipt": {
"claimedAmount": null,
"amountMismatch": false,
"claimedIsDebitTotal": false
},
"shortfall": 0,
"cached": false,
"parserVersion": 3,
"usage": {
"mode": "plan",
"used": 41,
"limit": 10000,
"remaining": 9959,
"plan": "pro",
"fee": 0
}
}settled- True when the bank reports the money as moved. Never hand goods over on false.
data.amount- What reached the receiver. Credit the customer with this.
data.totalDebited- What left the payer, the bank's fee included.
data.status- The bank's own word for the payment, as it wrote it.
data- Also in data: the reference, both parties' names and accounts, the fee, the currency, the date and the reason. raw holds the bank's own fields.
receipt.amountMismatch- True when claimedAmount matches neither amount nor totalDebited: an edited receipt.
receipt.claimedIsDebitTotal- True when claimedAmount is the total with the fee, as a payer's receipt prints it.
shortfall- How much less than expectedAmount was paid. Null when you sent no expectedAmount.
pdf- The bank's own PDF in base64, for banks that issue one.
cached- True when the answer is one Wabi already had for this payment.
stale- Present when a stored answer is served because the bank could not be asked again. refreshError says why.
usage- Your team's month, shared by every key and the app: checks used, the limit, what remains, the plan and how the check was counted.
Errors
Every error has the same two fields. Branch on code; the sentence in error can change.
{
"error": "accountSuffix (exactly the last 8 digits of either account) is required for FT lookups",
"code": "ACCOUNT_REQUIRED"
}| Status | Code | What it means |
|---|---|---|
| 400 | INVALID_INPUT | reference is missing or is not a receipt Wabi can read, or an amount is out of range. |
| 401 | UNAUTHORIZED | The secret is missing, wrong or revoked. |
| 402 | FEATURE_NOT_IN_PLAN | Your team's plan does not include the API. Your keys are kept for when it does. |
| 402 | PLAN_LIMIT_REACHED, PLAN_REQUIRED | This month's checks are used. resetsAt says when they come back. |
| 402 | ACCOUNT_BLOCKED | Verification is on hold until an open invoice is settled. |
| 404 | NOT_FOUND | The bank has no such transaction. |
| 422 | ACCOUNT_REQUIRED | This reference needs accountSuffix. |
| 429 | RATE_LIMITED | Too many requests. Wait the seconds in the Retry-After header, then retry. |
| 502 | TIMEOUT, NETWORK_ERROR, … | The bank could not be reached, or its answer could not be read. The code says which. Retry later. |
| 503 | METERING_UNAVAILABLE | Verification is briefly unavailable. Retry in a moment. |
Read your payments
For a key made with Can read payments ticked. Every route is GET, with the key in Authorization: Bearer vfy_....
/api/v1/payments- Your payments, newest first, removed ones left out. For a screen, not for keeping a copy.
/api/v1/payments/changes- Every change since your cursor, removed payments included. Use this to keep a copy in step.
/api/v1/payments/{id}- One payment, removed or not. 404 when it is not your team's.
/api/v1/me- The key's team, its branches, scopes, plan and rate. Names the branch_id on each payment.
curl "https://wabi.et/api/v1/payments?date=2026-11-02&bank=CBE&limit=50" -H "Authorization: Bearer vfy_..."Browse filters
from, to- When Wabi verified it. from is included, to is not. ISO 8601 with Z or an offset.
paid_from, paid_to- When it was paid, the same way.
date- One day in Addis Ababa, as YYYY-MM-DD.
bank, branch, channel- A bank code, a branch_id, or app or api.
q- Text in the reference, a name or a phone number.
limit, cursor- Up to 200 a page, 50 if left out. Send next_cursor back as cursor.
Each payment
id- Wabi's id for the payment. Upsert by it.
bank, reference- The bank code and the bank's reference. Together they are unique in your team.
amount, service_charge, total_debited- Strings with two decimals: what reached you, the bank's fee, and what left the payer.
currency- The currency, such as ETB.
payer_name, payer_account- As the bank printed them, masks included.
receiver_name, receiver_account- The same, for the side that was paid.
reason- The transfer's reason, or null.
paid_at- When the bank says it was paid.
verified_at- When Wabi verified it.
updated_at- When it last changed. For reading only: never order or sync by it.
channel- app or api.
verified_by- Who checked it: a staff member's name, or the key's name for api. Never an email.
branch_id- The branch, or null. /api/v1/me names it.
expected_amount, claimed_amount, shortfall- What was owed, what the customer's receipt showed, and how much short the payment is. Strings, or null.
customer_phone- The phone number staff entered, or null.
deleted, deleted_at- On the feed and by id only. true, with the time, when the payment was removed.
# First call: no cursor. Then send back the next_cursor you were given.
curl "https://wabi.et/api/v1/payments/changes?cursor=$NEXT_CURSOR" -H "Authorization: Bearer vfy_..."{
"data": [
{
"id": "6f1c2a9e-0b7d-4c55-9a51-2f8e1d3c4b70",
"bank": "CBE",
"reference": "FT26251ABCDE",
"amount": "1500.00",
"paid_at": "2026-11-02T06:24:00.000Z",
"deleted": false,
"deleted_at": null
},
{ "id": "0c9b7e44-5d21-4f3a-8e6b-7a1d2c3e4f50", "deleted": true, "purged": true }
],
"has_more": false,
"full_resync": false,
"next_cursor": "AQ..."
}Keeping a copy in step
- Start with no cursor. Every answer carries next_cursor: store it as given, and never parse or compare it.
- On every poll, page until has_more is false. A job that reads one page a poll can fall behind for good, and its cursor expires.
- A payment can arrive more than once. Upsert by id.
- A removed payment comes with deleted: true, and with deleted: false if it is put back. One erased for good comes as only { id, deleted: true, purged: true }.
- The feed can pause while a long database change runs. It never skips: when it resumes, nothing is missing.
- 410 CURSOR_EXPIRED means start again with no cursor. While pages say full_resync: true, mark every local id that came from the feed, take the pass to has_more false, then delete each marked id the pass did not return.
Only payments are here. A check through the verify endpoint is filed only when it succeeded and was paid to your team, so a refused check never appears. To match a verify answer to a payment, use bank and reference.
Refusals of their own
403 SCOPE_REQUIRED- The key was made without Can read payments. Create one with it.
403 KEY_HAS_NO_TEAM- The key belongs to no team, so there is nothing to read.
400 BAD_PARAM, BAD_CURSOR- A parameter is malformed, and error names it. Or the browse cursor is not one we gave you.
503 FEED_PAUSED- The feed is paused for maintenance. Wait the Retry-After seconds.
Reading costs no checks. It has its own rate per key, apart from verifying, so a sync never slows a checkout.
Read your sales reports
The same key, header and refusals as payments. A sales report is the register's report attached to a handover, so you can set what was sold beside what was paid.
/api/v1/sales-reports- Handovers that carry a sales report, newest first by report_to.
/api/v1/sales-reports/{id}/photo- The report's photo: a redirect to a link that works for five minutes. 404 when there is none.
curl "https://wabi.et/api/v1/sales-reports?from_day=2026-11-01&to_day=2026-11-15" -H "Authorization: Bearer vfy_..."Filters
from_day, to_day- Days as YYYY-MM-DD, both included. A report is returned when its days overlap them, so one for 10 to 12 Nov is in a window of 11 Nov.
branch- A branch_id from /api/v1/me.
limit, cursor- Paged like payments.
{
"id": "6f1c2a9e-0b7d-4c55-9a51-2f8e1d3c4b70",
"branch_id": "a20e4b1c-7d3f-4e2a-9b8c-1d2e3f4a5b6c",
"report_from": "2026-11-15",
"report_to": "2026-11-15",
"net_sale": "1225.00",
"handover_total": "1200.00",
"handover_count": 47,
"recorded_at": "2026-11-15T17:42:10.512Z",
"report_by": "Booth 1",
"report_at": "2026-11-15T17:44:03.118Z",
"note": null,
"reversed": false,
"photo": true,
"updated_at": "2026-11-15T17:44:03.118Z"
}Each report
id- The handover's id. The photo route takes it.
branch_id- The branch, or null.
report_from, report_to- The days the register printed the report for.
net_sale- What the register says was sold. A string with two decimals.
handover_total, handover_count- What the handover itself counted, as a string, and how many payments it held.
recorded_at- When the handover was made.
report_by- Who attached the report, by name. Never an email.
report_at- When it was attached.
note- The note that settled a difference, or null.
reversed- true when a later handover undid this one. Leave its report out of your totals.
photo- true when a photo is attached.
updated_at- When the report or its note last changed. For reading only.
Limits and billing
- Each answered check counts toward your plan's monthly checks, the same checks the app uses.
- A check that fails, or finds no payment, costs nothing. Checking the same payment again costs nothing either.
- Each key has a per-minute rate set by your plan. Settings, under API, shows it.
- All of a team's keys together stay under 1,200 requests a minute.
- Across the app and the API, a team asks the banks at most 20,000 times in 24 hours. Payments Wabi already has an answer for do not count.
- Checks made with a key show in your team's History, under the key's name.