ለገንቢዎች
የዋቢ API
ክፍያን ከራስዎ የሽያጭ ሲስተም፣ የማድረሻ መተግበሪያ ወይም የቢሮ ሶፍትዌር ያረጋግጡ። የደረሰኙን ማጣቀሻ ከቁልፍዎ ጋር ይላኩ፤ ባንኩ የመዘገበውን መልሰው ያገኛሉ።
ቁልፍ ማግኘት
API የሚከፈተው በጥያቄ ነው። ምን እየሠሩ እንደሆነ ጽፈው ይላኩልን።
ቡድንዎ መዳረሻ ካገኘ በኋላ ይግቡ፣ ቅንብሮችን ከፍተው API የሚለውን ይምረጡ። ቁልፉን በሚጠቀምበት ሲስተም ስም ይሰይሙት። ሚስጥሩ የሚታየው አንድ ጊዜ ብቻ ስለሆነ ያኔውኑ ይቅዱት።
ጥያቄ መላክ
አንድ አድራሻ ብቻ ነው። JSON ይላኩ፤ ሚስጥርዎን በx-service-secret header ውስጥ ያስቀምጡ።
POST https://wabi.et/api/service/verifyreferenceየግድ- የደረሰኙ አገናኝ፣ ወይም በደረሰኙ ላይ ያለው ማጣቀሻ ወይም የደረሰኝ ቁጥር።
accountSuffixአማራጭ- የአካውንት ቁጥር የመጨረሻዎቹ 8 አሃዞች። ለብቻው ለሚላክ የንግድ ባንክ FT ቁጥር (የየትኛውም ወገን አካውንት) እና ለብቻው ለሚላክ የዘመን ባንክ ማጣቀሻ (የከፋዩ አካውንት) ያስፈልጋል። ለአቢሲኒያ ባንክ፣ የደረሰኙን አገናኝ ወይም የFT ቁጥሩን ከአካውንቱ የመጨረሻ 5 አሃዞች ጋር አያይዘው በ reference ይላኩ።
bankአማራጭ- ቁጥሩ ብቻውን ከአንድ በላይ ባንክ ወይም የሞባይል ገንዘብ ሊሆን ሲችል የትኛው እንደሆነ። ከታች ካሉት ኮዶች አንዱ።
claimedAmountአማራጭ- የደንበኛው ደረሰኝ የሚያሳየው መጠን። ባንኩ ከመዘገባቸው ሁለት መጠኖች ከአንዱም ጋር ካልተስማማ እንነግርዎታለን። ከ0 በላይ፣ ቢበዛ 10,000,000።
expectedAmountአማራጭ- ደንበኛው መክፈል የነበረበት። ክፍያው ምን ያህል እንደጎደለ እንነግርዎታለን። 0 ወይም ከዚያ በላይ፣ ቢበዛ 10,000,000።
የባንክ ኮዶች
CBEየኢትዮጵያ ንግድ ባንክTelebirrቴሌብርAwashአዋሽ ባንክZemenዘመን ባንክDashenዳሽን ባንክCBEBirrሲቢኢ ብርWegagenወጋገን ባንክAbyssiniaየአቢሲኒያ ባንክMPesaኤም-ፔሳ
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.
}መልሱ
ባንኩ ያገኘው ክፍያ በ200 ሁኔታ፣ በዚህ ቅርጽ ይመለሳል።
{
"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 ይሆናል። false ሲሆን ዕቃ አያስረክቡ።
data.amount- ለተቀባዩ የደረሰው መጠን። ደንበኛውን በዚህ መጠን ይመዝግቡ።
data.totalDebited- ከከፋዩ የወጣው ጠቅላላ፣ የባንኩን ክፍያ ጨምሮ።
data.status- ባንኩ ስለ ክፍያው የጻፈው ቃል፣ እንደጻፈው።
data- በ data ውስጥ ደግሞ፦ ማጣቀሻው፣ የሁለቱም ወገኖች ስምና አካውንት፣ የባንኩ ክፍያ፣ ምንዛሪው፣ ቀኑ እና ምክንያቱ። raw የባንኩን የራሱን መስኮች ይይዛል።
receipt.amountMismatch- claimedAmount ከ amount ወይም ከ totalDebited ከአንዱም ጋር ካልተስማማ true ይሆናል፦ የተቀየረ ደረሰኝ ማለት ነው።
receipt.claimedIsDebitTotal- claimedAmount የባንኩን ክፍያ ያካተተው ጠቅላላ ሲሆን true ይሆናል፤ የከፋይ ደረሰኝ የሚያሳየው ይህንን ነው።
shortfall- ከ expectedAmount ምን ያህል አንሶ እንደተከፈለ። expectedAmount ካልላኩ null ነው።
pdf- PDF ለሚያወጡ ባንኮች፣ የባንኩ የራሱ PDF በ base64።
cached- ዋቢ ለዚህ ክፍያ ቀድሞ የያዘውን መልስ ሲመልስ true ይሆናል።
stale- ባንኩን እንደገና መጠየቅ ባለመቻሉ የተቀመጠ መልስ ሲመለስ ይገኛል። ምክንያቱን refreshError ይናገራል።
usage- የቡድንዎ የወሩ አጠቃቀም፣ በሁሉም ቁልፎችና በመተግበሪያው የሚጋራ፦ ያገለገሉ ማረጋገጫዎች፣ ገደቡ፣ የቀረው፣ እቅዱ እና ማረጋገጫው እንዴት እንደተቆጠረ።
ስህተቶች
እያንዳንዱ ስህተት ተመሳሳይ ሁለት መስኮች አሉት። በ code ላይ ይወስኑ፤ በ error ውስጥ ያለው ዓረፍተ ነገር ሊቀየር ይችላል።
{
"error": "accountSuffix (exactly the last 8 digits of either account) is required for FT lookups",
"code": "ACCOUNT_REQUIRED"
}| ሁኔታ | ኮድ | ትርጉሙ |
|---|---|---|
| 400 | INVALID_INPUT | reference አልተላከም ወይም ዋቢ የሚያነበው ደረሰኝ አይደለም፤ ወይም አንዱ መጠን ከገደቡ ውጭ ነው። |
| 401 | UNAUTHORIZED | ሚስጥሩ አልተላከም፣ ተሳስቷል ወይም ተሰርዟል። |
| 402 | FEATURE_NOT_IN_PLAN | የቡድንዎ እቅድ API አያካትትም። እቅዱ ሲያካትተው እንዲሠሩ ቁልፎችዎ ይቀመጣሉ። |
| 402 | PLAN_LIMIT_REACHED, PLAN_REQUIRED | የዚህ ወር ማረጋገጫዎች አልቀዋል። መቼ እንደሚታደሱ resetsAt ይናገራል። |
| 402 | ACCOUNT_BLOCKED | ክፍት የክፍያ መጠየቂያ እስኪከፈል ድረስ ማረጋገጥ ታግዷል። |
| 404 | NOT_FOUND | ባንኩ እንዲህ ያለ ግብይት የለውም። |
| 422 | ACCOUNT_REQUIRED | ይህ ማጣቀሻ accountSuffix ያስፈልገዋል። |
| 429 | RATE_LIMITED | ጥያቄዎቹ በዝተዋል። በ Retry-After header ያሉትን ሰከንዶች ጠብቀው እንደገና ይሞክሩ። |
| 502 | TIMEOUT, NETWORK_ERROR, … | ባንኩ አልተገኘም፣ ወይም መልሱ ሊነበብ አልቻለም። የትኛው እንደሆነ code ይናገራል። ቆይተው እንደገና ይሞክሩ። |
| 503 | METERING_UNAVAILABLE | ማረጋገጥ ለአጭር ጊዜ አይገኝም። ትንሽ ቆይተው እንደገና ይሞክሩ። |
ክፍያዎችዎን ያንብቡ
ክፍያዎችን ማንበብ ይችላል የሚለው ተመርጦ ለተፈጠረ ቁልፍ። ሁሉም አድራሻዎች GET ናቸው፤ ቁልፉን በAuthorization: Bearer vfy_... ይላኩ።
/api/v1/payments- የቡድንዎ ክፍያዎች፣ አዲሱ መጀመሪያ፣ የተሰረዙት ሳይካተቱ። ለማሳያ ገጽ ነው እንጂ ቅጂ ለመያዝ አይደለም።
/api/v1/payments/changes- ከ cursor ወዲህ የተለወጠው ሁሉ፣ የተሰረዙ ክፍያዎችም ጭምር። ቅጂዎን ወቅታዊ ለማድረግ ይህንን ይጠቀሙ።
/api/v1/payments/{id}- አንድ ክፍያ፣ ቢሰረዝም ባይሰረዝም። የቡድንዎ ካልሆነ 404 ይመለሳል።
/api/v1/me- የቁልፉ ቡድን፣ ቅርንጫፎቹ፣ scopes፣ እቅዱና የደቂቃ ገደቡ። በየክፍያው ያለውን branch_id በስም ይነግርዎታል።
curl "https://wabi.et/api/v1/payments?date=2026-11-02&bank=CBE&limit=50" -H "Authorization: Bearer vfy_..."የማጣሪያ መለኪያዎች
from, to- ዋቢ ያረጋገጠበት ጊዜ። from ይካተታል፣ to አይካተትም። ISO 8601 ከ Z ወይም ከሰዓት ልዩነት ጋር።
paid_from, paid_to- የተከፈለበት ጊዜ፣ በዚያው መንገድ።
date- በአዲስ አበባ ሰዓት አንድ ቀን፣ በ YYYY-MM-DD።
bank, branch, channel- የባንክ ኮድ፣ branch_id፣ ወይም app ወይም api።
q- በማጣቀሻው፣ በስም ወይም በስልክ ቁጥር ውስጥ ያለ ጽሑፍ።
limit, cursor- በአንድ ገጽ እስከ 200፣ ካልተገለጸ 50። next_cursor ን እንደ cursor መልሰው ይላኩ።
እያንዳንዱ ክፍያ
id- ዋቢ ለክፍያው የሰጠው መለያ። በዚህ ያዘምኑ ወይም ያስገቡ።
bank, reference- የባንክ ኮዱና የባንኩ ማጣቀሻ። ሁለቱ አንድ ላይ በቡድንዎ ውስጥ አይደጋገሙም።
amount, service_charge, total_debited- ሁለት አስርዮሽ ያላቸው ጽሑፎች፦ ለእርስዎ የደረሰው፣ የባንኩ ክፍያ፣ እና ከከፋዩ የወጣው።
currency- ምንዛሪው፣ ለምሳሌ ETB።
payer_name, payer_account- ባንኩ እንደጻፋቸው፣ የተሸፈኑ አሃዞችም እንዳሉ።
receiver_name, receiver_account- ያው፣ ለተከፈለው ወገን።
reason- የዝውውሩ ምክንያት፣ ወይም null።
paid_at- ባንኩ ተከፍሏል የሚለው ጊዜ።
verified_at- ዋቢ ያረጋገጠበት ጊዜ።
updated_at- መጨረሻ የተለወጠበት ጊዜ። ለማንበብ ብቻ ነው፤ በዚህ አይደርድሩ፣ አያመሳስሉም።
channel- app ወይም api።
verified_by- ያረጋገጠው፦ የሠራተኛው ስም፣ ወይም በ api ሲሆን የቁልፉ ስም። ኢሜይል በጭራሽ አይሆንም።
branch_id- ቅርንጫፉ፣ ወይም null። ስሙን /api/v1/me ይነግርዎታል።
expected_amount, claimed_amount, shortfall- መከፈል የነበረበት፣ የደንበኛው ደረሰኝ ያሳየው፣ እና ክፍያው ምን ያህል እንደጎደለ። ጽሑፎች ወይም null።
customer_phone- ሠራተኞች ያስገቡት ስልክ ቁጥር፣ ወይም null።
deleted, deleted_at- በለውጦቹና በአንድ ክፍያ አድራሻ ብቻ። ክፍያው ሲሰረዝ true ይሆናል፣ ከጊዜው ጋር።
# 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..."
}ቅጂዎን ወቅታዊ ማድረግ
- ያለ cursor ይጀምሩ። እያንዳንዱ መልስ next_cursor ይይዛል፤ እንደተሰጠዎት ያስቀምጡት፣ በጭራሽ አይተንትኑት ወይም አያወዳድሩት።
- በእያንዳንዱ ጥሪ has_more false እስኪሆን ድረስ ገጾቹን ይቀጥሉ። በአንድ ጥሪ አንድ ገጽ ብቻ የሚያነብ ሥራ ወደኋላ ቀርቶ ሊቀር ይችላል፤ cursor ውም ጊዜው ያልፋል።
- አንድ ክፍያ ከአንድ ጊዜ በላይ ሊመጣ ይችላል። በ id ያዘምኑ ወይም ያስገቡ።
- የተሰረዘ ክፍያ ከ deleted: true ጋር ይመጣል፤ ከተመለሰ ደግሞ ከ deleted: false ጋር። ፈጽሞ የጠፋ ክፍያ { id, deleted: true, purged: true } ብቻ ሆኖ ይመጣል።
- ረጅም የዳታቤዝ ለውጥ ሲካሄድ ለውጦቹ ለጊዜው ሊቆሙ ይችላሉ። ግን አይዘሉም፤ ሲቀጥሉ ምንም አይጎድልም።
- 410 CURSOR_EXPIRED ማለት ያለ cursor እንደገና ይጀምሩ ማለት ነው። ገጾቹ full_resync: true እስካሉ ድረስ፣ ከለውጦቹ የመጡትን የእርስዎን መለያዎች ሁሉ ምልክት ያድርጉ፣ ዙሩን has_more false እስኪሆን ይጨርሱ፣ ከዚያ ዙሩ ያልመለሳቸውን ምልክት ያላቸውን ይሰርዙ።
እዚህ ያሉት ክፍያዎች ብቻ ናቸው። በማረጋገጫው አድራሻ የተደረገ ማረጋገጫ የሚመዘገበው ተሳክቶ ለቡድንዎ የተከፈለ ሲሆን ብቻ ነው፤ ስለዚህ ውድቅ የሆነ ማረጋገጫ እዚህ አይገኝም። የማረጋገጫ መልስን ከክፍያ ጋር ለማዛመድ bank እና reference ይጠቀሙ።
የራሳቸው እምቢታዎች
403 SCOPE_REQUIRED- ቁልፉ ክፍያዎችን ማንበብ ይችላል ሳይመረጥ ነው የተፈጠረው። ይህ ተመርጦ ሌላ ቁልፍ ይፍጠሩ።
403 KEY_HAS_NO_TEAM- ቁልፉ የየትኛውም ቡድን አይደለም፤ ስለዚህ የሚነበብ ነገር የለም።
400 BAD_PARAM, BAD_CURSOR- አንዱ መለኪያ ልክ አይደለም፤ የትኛው እንደሆነ error ይናገራል። ወይም የማሰሻው cursor እኛ የሰጠነው አይደለም።
503 FEED_PAUSED- ለውጦቹ ለጥገና ቆመዋል። በ Retry-After ያሉትን ሰከንዶች ይጠብቁ።
ማንበብ ምንም ማረጋገጫ አያስቆጥርም። ከማረጋገጥ የተለየ የራሱ የደቂቃ ገደብ በየቁልፉ አለው፤ ስለዚህ ማመሳሰል የሽያጭ ቦታውን አያዘገይም።
የሽያጭ ሪፖርቶችዎን ያንብቡ
ቁልፉ፣ ራስጌውና እምቢታዎቹ እንደ ክፍያዎቹ ናቸው። የሽያጭ ሪፖርት ከማስረከብ ጋር የተያያዘው የካሽ መመዝገቢያው ሪፖርት ነው፤ የተሸጠውን ከተከፈለው ጎን ለማስቀመጥ ይረዳዎታል።
/api/v1/sales-reports- የሽያጭ ሪፖርት ያላቸው ማስረከቦች፣ በ report_to አዲሱ መጀመሪያ።
/api/v1/sales-reports/{id}/photo- የሪፖርቱ ፎቶ፤ ለአምስት ደቂቃ ወደሚሠራ ሊንክ ይመራዎታል። ፎቶ ከሌለ 404 ይመለሳል።
curl "https://wabi.et/api/v1/sales-reports?from_day=2026-11-01&to_day=2026-11-15" -H "Authorization: Bearer vfy_..."ማጣሪያዎች
from_day, to_day- ቀኖች በ YYYY-MM-DD፣ ሁለቱም ይካተታሉ። የሪፖርቱ ቀኖች ከመስኮቱ ጋር ከተደራረቡ ይመለሳል፤ ከኅዳር 10 እስከ 12 ያለው ሪፖርት ለኅዳር 11 መስኮትም ይመጣል።
branch- ከ /api/v1/me የሚገኝ branch_id።
limit, cursor- ገጾቹ እንደ ክፍያዎቹ ናቸው።
{
"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"
}እያንዳንዱ ሪፖርት
id- የማስረከቡ መለያ። የፎቶው አድራሻ ይህንን ይቀበላል።
branch_id- ቅርንጫፉ፣ ወይም null።
report_from, report_to- መመዝገቢያው ሪፖርቱን ያተመላቸው ቀኖች።
net_sale- መመዝገቢያው የተሸጠ ነው የሚለው። ሁለት አስርዮሽ ያለው ጽሑፍ።
handover_total, handover_count- ማስረከቡ ራሱ የቆጠረው በጽሑፍ፣ እና የያዛቸው ክፍያዎች ብዛት።
recorded_at- ማስረከቡ የተደረገበት ጊዜ።
report_by- ሪፖርቱን ያያያዘው ሰው በስሙ። ኢሜይል በጭራሽ አይሆንም።
report_at- የተያያዘበት ጊዜ።
note- ልዩነትን ያስታረቀው ማስታወሻ፣ ወይም null።
reversed- በኋላ የመጣ ማስረከብ ይህንን ሲሽረው true ይሆናል። ሪፖርቱን ከድምሮችዎ ያውጡት።
photo- ፎቶ ሲያያዝ true ይሆናል።
updated_at- ሪፖርቱ ወይም ማስታወሻው መጨረሻ የተለወጠበት ጊዜ። ለንባብ ብቻ።
ገደቦችና ክፍያ
- መልስ ያገኘ እያንዳንዱ ማረጋገጫ ከእቅድዎ ወራዊ ማረጋገጫዎች ይቆጠራል፤ መተግበሪያው የሚጠቀማቸው እነዚያው ናቸው።
- ያልተሳካ ወይም ክፍያ ያላገኘ ማረጋገጫ አይቆጠርም። ያንኑ ክፍያ እንደገና ማረጋገጥም አይቆጠርም።
- እያንዳንዱ ቁልፍ በእቅድዎ የተወሰነ የደቂቃ ገደብ አለው። በቅንብሮች ውስጥ API ስር ይታያል።
- የአንድ ቡድን ቁልፎች በአንድ ላይ በደቂቃ ከ1,200 ጥያቄዎች አይበልጡም።
- በመተግበሪያውም በAPIም፣ አንድ ቡድን በ24 ሰዓት ውስጥ ባንኮችን ቢበዛ 20,000 ጊዜ ይጠይቃል። ዋቢ ቀድሞ መልስ ያለው ክፍያ አይቆጠርም።
- በቁልፍ የተደረጉ ማረጋገጫዎች በቡድንዎ ታሪክ ውስጥ በቁልፉ ስም ይታያሉ።