Prerequisites & onboarding
3.1 What you need
| You need | Where it comes from |
|---|---|
| A merchant (or agent) account with InnBucks | InnBucks merchant onboarding, with your account-opening documents |
| Test credentials: API key, username, password | Sent by InnBucks for your business |
| The test base URL | Sent by InnBucks with the credentials |
| The InnBucks test customer app (Android) and its registration OTP | Download link and OTP from InnBucks |
| A Zimbabwean mobile number to register in the test app | Your own |
| Test funds in that test wallet | Credited by InnBucks when you send them the number |
| The InnBucks test merchant app (optional) and its activation code | InnBucks, on request |
| An HTTPS server that can keep secrets | Your side. Never call the API from a browser or a mobile app |
InnBucks also sends the Merchant API document, the Reversal Process and the Integration UAT sign-off form. This guide covers what those documents cover, rewritten and checked for consistency, but InnBucks’ documents are the contract.
3.2 Collect your credentials
You receive three secrets, and each has one job:
| Secret | Header or field | Used on |
|---|---|---|
| API key | X-Api-Key header |
Every request, including login |
| Username and password | Login request body | POST /auth/third-party only |
| Access token (you get it by logging in) | Authorization: Bearer ... header |
Every request except login |
đź”’ These are secrets. Keep them in environment variables or a secret manager. Never commit them, never log them, and never send them to a browser or a mobile app. The mobile app talks to your server; your server talks to InnBucks.
3.3 Install the test apps
- Customer app. InnBucks sends a download link for the test build of the InnBucks customer app. It is Android only in test (production has Android and iOS).
- Register in the app with a Zimbabwean mobile number. Registration asks for an OTP; in the test environment InnBucks gives you a fixed test OTP instead of sending an SMS.
- Tell InnBucks the numbers you registered, so they can credit them with test funds. You can’t pay a code from an empty wallet.
- Merchant app (optional). If you want to use InnBucks’ own test merchant app, ask for it and for an activation code once it is installed.
3.4 Nominate your business administrator
Send InnBucks the first name, last name, email address and phone number of the person who will be your business administrator on the InnBucks business portal. That person can view transactions, set up locations and generate statements.
3.5 Know your merchant type
What you may do depends on how InnBucks set up your account. InnBucks’ documents say only that the code types you can generate depend on your merchant type; the split below follows how the integration guidelines describe each service, so confirm yours with InnBucks.
| Account type | Typical capabilities |
|---|---|
| Merchant | Payment codes, code inquiry, bank change, utility payments, statement |
| Agent | All of the above, plus withdrawal codes, deposits, deposit inquiry and reversals |
If a request is not allowed for your account, it fails with a non-00 responseCode. Ask
InnBucks which code types and transactions are enabled for you.
Checkpoint: you have an API key, a username, a password, a test base URL, and a funded test wallet in the test customer app. Continue to Authentication.
This page is generated from section 3 of the README in README.md. Spotted something wrong? Open an issue.