Known documentation issues

InnBucks’ documents are the contract, but in places they contradict themselves or leave details out. This section records each one and what this guide does about it.

14.1 Contradictions in the examples

Issue	Where	What this guide does
All amounts are cents, but the generate-code example sends "amount": 1 and its response returns "amount": 10	Generate code	Follows the rule, cents. Examples use realistic cent values (450)
Claimed and Paid are both described as “Code has been finalised by the customer”; the guidelines say a paid code shows Claimed	Code inquiry	Treats both as paid
The failure reason is in responseMsg for some endpoints and responseDescription for others	General notes	Reads responseMsg, falling back to responseDescription
Success is "00", but linked account inquiry returns "000"	Linked account inquiry	Accepts both
The statement example is not valid JSON (a missing comma after accountDetails); the deposit inquiry example uses curly quotes	Statement, deposit inquiry	Examples here are valid JSON
Code validity is “10 minutes”, but the inquiry example shows timeToLive: "576sec"	Guidelines, inquiry	Consistent: 576 s is the time left, under 10 minutes
Bank change is “up to US$5” in one place and “$5 and under” in another	API document, guidelines	Same meaning: 500 cents or less
Deposit inquiry’s path starts with /bank/api/, every other with /api/ or /auth/	Deposit inquiry	Uses the documented /bank/api/transaction/inquiry
“Currency” appears under Sample Request instead of Parameters for utility payment and reversal	Utility payment, reversal	Documented as a normal required field

14.2 Inconsistent response formats

• Dates: processedDateTime appears as 2026-02-25 15:48:42.208, 2021-03-12T12:39:19.641+0200 and 2022-12-16 11:39:01.387000; statements use 2024-01-01T00:00:00. Parse leniently; no time zone is stated except in one example (+02:00, Harare time).
• Amounts come back as numbers (10) or strings ("100"). Accept both.
• timeToLive is a string with a unit ("576sec"), not a number.
• qrCode is described only as a “base64 string”. The image type and whether a data: prefix is included are not stated; the clients here handle both.

14.3 Gaps

These are not documented. Confirm them with InnBucks rather than guessing:

• Code mini statement. The UAT form has a Code mini statement test case, but the API document has no endpoint for it. Ask InnBucks which endpoint to use, or mark it not applicable.
• Refunds of code payments. There is no refund endpoint, and real-time reversals are not available for code-based transactions. How a code payment is reversed is covered by InnBucks’ separate reversal process, which is not part of the API document.
• Callbacks. No callbacks or webhooks are documented; the guidelines describe status only through code inquiry.
• Reversal retries. Whether a retry after 096 reuses the participantReference or needs a new one is not stated.
• Withdrawal code validity. The 10-minute validity is stated for payment codes; withdrawal codes are assumed to behave the same.
• The “Required” column in section 7. InnBucks marks only a few fields optional (reference, deposit type, utility narration and additionalData, the linked account currency); the rest are marked required here because every example sends them.
• Bank change in ZWG. Only the US$5 limit is documented.
• Base URLs for each environment are issued privately.
• Limits: maximum reference and narration lengths, allowed characters, minimum and maximum amounts, and the rate limit beyond “one inquiry every 30 seconds”.
• Duplicate checking on deposits is per account; whether it applies to other endpoints is not stated.
• Utility providers and products: only ECONET / AIRTIME is shown.
• accountNumber in the statement request: whose account can be queried (your own only, presumably) is not stated.
• The response to an unknown deposit in deposit inquiry (no details) is not shown.
• Error HTTP statuses beyond 401 for an expired token are not listed per endpoint.

---

This page is generated from section 14 of the README in README.md. Spotted something wrong? Open an issue.