67even

InnBucks Merchant API Developer Guide

Integrate InnBucks step by step: generate a payment code, show it with its QR code and deep link, confirm payment and go live.

GitHub stars Tests MIT licence Last commit

View on GitHub Install the skill

Where to start

   
Installing the skill Install the Claude skill and let Claude write and review your InnBucks integration.
Quick start Log in, generate a US$1 code, pay it with the test app, check it. Ten minutes.
Prerequisites & onboarding Credentials, the test customer app, test funds and your merchant type.
Authentication The X-Api-Key header, the 15-minute bearer token, and 401s.
Accepting payments Generate a payment code; show the code, QR and deep link; check the status.
Agent services Withdrawals, deposits, deposit inquiry, reversals and bank change.
API reference Every endpoint, field, request and response.
Response codes & errors Response codes 00, 000, 025, 096, HTTP statuses, and what to retry.
Code examples Tested clients for PHP/Laravel, Node.js and Python.
Testing & UAT UAT test cases, the journey video and sign-off.
Going live Production credentials, pre-funding and the go-live checklist.
Best practices Cents, references, status checks, idempotency, security, reconciliation.
Troubleshooting Something is broken right now. Symptom-to-cause table.
Known documentation issues Where InnBucks’ documents contradict themselves, and the gaps.
API method index Every API method in alphabetical order, with client functions.
About this guide Repository layout, sources and licence.

Overview

InnBucks is a Zimbabwean mobile wallet run by InnBucks MicroBank Limited. The InnBucks Merchant API lets your server take payments from InnBucks customers and, if you are an InnBucks agent, pay customers cash out, take cash deposits and credit their change.

The payment model is different from a card or a USSD push. You don’t charge the customer. You generate a code, show it to them, and they pay against it from the InnBucks app or USSD (*569#). Your server then asks InnBucks whether the code has been paid.

1.1 What you can do

Capability Endpoint Who uses it
Log in and get an access token POST /auth/third-party Everyone
Generate a payment code for a customer to pay POST /api/code/generate (type: PAYMENT) Merchants
Generate a withdrawal code for a cash-out POST /api/code/generate (type: WITHDRAWAL) Agents
Check a code’s status (paid, expired…) POST /api/code/inquiry Merchants, agents
Find a customer’s account from their phone number GET /api/v1/account/msisdn/{msisdn}/details Agents
Deposit cash into a customer’s wallet POST /api/transaction/deposit Agents
Check a deposit whose result you missed POST /bank/api/transaction/inquiry Agents
Reverse a deposit POST /api/transaction/reversal/v2 Agents
Bank change (credit a customer’s change, up to US$5) POST /api/transaction/bankChange Merchants, agents
Pay a utility (airtime, bills) POST /api/utility/provider/payment Merchants, agents
Download your account statement POST /api/account/fullStatement Everyone
Download the response-code list GET /api/file/response-codes Everyone

Every endpoint is described in API reference and listed alphabetically in the API method index.

1.2 How a code payment works 

 Your server                      InnBucks API                     Customer
     │ 1. POST /auth/third-party       │                                │
     │ ──────────────────────────────▶ │                                │
     │ ◀──── accessToken (15 min) ──── │                                │
     │ 2. POST /api/code/generate      │                                │
     │ ──────────────────────────────▶ │                                │
     │ ◀── code + qrCode, "00" ─────── │                                │
     │ 3. Show the code, QR and deep link ─────────────────────────────▶│
     │                                 │ 4. Pays in the app or *569#    │
     │                                 │ ◀───────────────────────────── │
     │ 5. POST /api/code/inquiry       │                                │
     │    (once every 30 seconds)      │                                │
     │ ──────────────────────────────▶ │                                │
     │ ◀── status: New → Claimed ───── │                                │
     │ 6. Fulfil the order             │                                │

A code payment is asynchronous. Generating the code only means a code exists. The money moves later, when the customer pays against it. InnBucks documents no callbacks, so your server learns the result by asking (step 5). A code expires after 10 minutes.

1.3 Quick facts

   
Base URL Not public. InnBucks gives you one per environment (test, production) as {baseUrl}
Authentication X-Api-Key header on every request, plus Authorization: Bearer <accessToken> on every request except login
Token lifetime 15 minutes by default. Log in again after 14 minutes, or when you get 401
Format HTTPS, JSON request and response bodies
Amounts Integer cents (minor units): 100 means USD 1.00 or ZWG 1.00
Currencies USD, ZWG
Success responseCode "00" in the JSON body. "000" on linked account inquiry
Code validity 10 minutes
Status checks At most one code inquiry every 30 seconds
Customer channels InnBucks app (Android and iOS) and USSD *569#
Tracing Every response carries an X-Trace-Id header. Log it; InnBucks support asks for it
API version Merchant API document v1.2.1

1.4 The integration path

  1. Get your credentials and the test app from InnBucks.
  2. Log in and manage the token.
  3. Run the quick start: generate a code, pay it with the test app, check it.
  4. Build the payment screen: code, QR code, deep link, countdown, status checks.
  5. Add agent services if you are an InnBucks agent.
  6. Test every case and sign off UAT, with a short video.
  7. Go live with production credentials.

1.5 Words used in this guide

Term Meaning
InnBucks code A number, usually 9 digits (e.g. 535403380), that a customer pays or claims against. Also called the payment code or payment token.
MSISDN A mobile phone number in international format without +: 263772123123.
Minor units / cents The smallest unit of a currency. All InnBucks amounts are whole numbers of cents: 450 = 4.50.
Reference Your ID for a request (an order or transaction number). InnBucks echoes it back, often as stan.
stan System trace audit number: the request’s reference as InnBucks records it.
authNumber InnBucks’ authorisation number for the request. Keep it for reconciliation.
Agent A business registered with InnBucks to pay out cash and take cash deposits.
Deep link A link that opens the InnBucks app directly on the payment screen.
UAT User acceptance testing: the sign-off InnBucks needs before issuing production credentials.

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

Back to top

MIT licensed. Written and maintained by John Mugabe under 67even. Independent and community-maintained - not affiliated with or endorsed by InnBucks MicroBank Limited. "InnBucks" and the InnBucks logo belong to their owner.

InnBucks