Reference
API Reference
Endpoint contracts, permissions, request shapes, response envelopes, webhooks, and platform surfaces verified against the current server and worker code.
Overview
API responses use a predictable envelope with success, message, and data. Verification submissions also include requestId, verification, and links when a status URL is available.
Base URL: https://verify.et
Supported Banks & Required Fields
| Field | Required | Description |
|---|---|---|
| cbe | Required | referenceNumber/reference plus accountSuffix/suffix exactly 8 digits. |
| boa | Required | referenceNumber/reference plus accountSuffix/suffix exactly 5 digits. |
| telebirr | Required | transactionNumber or reference. |
| mpesa | Required | transactionNumber or reference. Supported receipt URLs/SMS text can be parsed. |
| cbebirr | Required | receiptNumber/reference plus phone/phoneNumber. |
| dashen | Required | referenceNumber or reference. |
| awash | Required | referenceNumber or reference. Universal detection supports configured receipt host or token. |
| siinqee | Required | referenceNumber or reference. Universal detection supports configured receipt host or token. |
| kaafiebirr | Required | referenceNumber or reference. Full receipt URLs auto-route; bare tokens require explicit bank. phone is optional. |
| zemen | Optional | Enum/status surface only. POST /api/verify returns unsupported for direct Zemen submissions. |
Universal smart-router fields
You may omit
bank and send reference, optional suffix, and optional phoneNumber. Explicit bank payloads always win when bank is present. Full SMS or supported receipt URLs in identifier fields are best-effort sanitized to clean bank fields when the server can extract them confidently.Settlement Account Matching
New FeatureSettlement account matching verifies that a valid receipt was paid into the intended wallet or bank account. This protects checkout, fulfillment, and support workflows from accepting a real receipt that belongs to a different receiver.
How matching works
Send
settlementAccount for a one-off receiver check. If it is omitted, Verify.ET checks the authenticated user's saved /api/bank-accounts records and registered business settlement accounts for the request bank. Wallet-like banks such as Telebirr and M-Pesa use Ethiopian phone canonicalization, while regular banks prefer normalized account-number matching.| Field | Required | Description |
|---|---|---|
| settlementAccount | Optional | Expected receiver account or phone number for this request. Manual values are checked before saved accounts. |
| settlementAccountMatch | Optional | Stable response object returned on completed result items, including matched, confidence, source, candidate count, ambiguity, reason, and safe debug data. |
| receiverAccount | Optional | Provider receiver field used for matching. Masked values such as 2519****0897 or 1****7441 are matched by visible digits. |
Manual settlementAccount
{
"bank": "telebirr",
"transactionNumber": "DET8FJGUJ4",
"settlementAccount": "0939080897"
}Saved-account fallback
{
"bank": "telebirr",
"transactionNumber": "DET8FJGUJ4"
}Matched Response Object
{
"matched": true,
"matchType": "masked_pattern",
"matchConfidence": "high",
"source": "account_registry",
"bank": "telebirr",
"receiverAccount": "2519****0897",
"matchedSettlementAccount": "0939080897",
"matchedUserBankAccountId": "58807b8e-ff38-49c9-a836-304c6b88bc29",
"matchedBusinessBankAccountId": null,
"candidateCount": 1,
"ambiguous": false,
"reason": "receiver_mask_matches_visible_digits",
"debug": {
"receiverAccount": "2519****0897",
"candidateCount": 1,
"matchType": "masked_pattern",
"visiblePrefix": "2519",
"visibleSuffix": "0897",
"visibleCharacterCount": 8,
"matchedUserBankAccountId": "58807b8e-ff38-49c9-a836-304c6b88bc29",
"matchedBusinessBankAccountId": null
}
}No Saved Account Response Object
{
"matched": false,
"matchType": "unmatched",
"matchConfidence": "none",
"source": "account_registry",
"bank": "telebirr",
"matchedUserBankAccountId": null,
"matchedBusinessBankAccountId": null,
"candidateCount": 0,
"ambiguous": false,
"reason": "no_registered_accounts"
}Stable Reason Codes
receiver_account_exact_matchreceiver_mask_matches_visible_digitsreceiver_suffix_matchesno_registered_accountsmissing_receiver_accountcandidate_account_mismatchambiguous_registered_accountsverification_not_successfulAmbiguous masked matches return matched: false, ambiguous: true, and a safe candidate count instead of silently picking one saved account.
