API reference

7.1 Conventions

   
Base URL {baseUrl}, given to you by InnBucks per environment. Every path below is appended to it.
Headers X-Api-Key on every request. Authorization: Bearer <accessToken> on every request except login. Content-Type: application/json on every request with a body.
Amounts Whole numbers of cents. Send JSON integers (450), not decimals (4.50) or strings. Responses may return amounts as numbers or strings ("450"): accept both.
Currencies USD or ZWG.
reference Your own reference for the request. Optional where supported (InnBucks generates one if you leave it out), but always send one: you need it to reconcile, and for deposits to check or reverse them. Echoed back as stan.
Result responseCode "00" is success, except linked account inquiry, which uses "000". The reason for anything else is in responseMsg or responseDescription (the field name differs by endpoint).
HTTP status 2xx success, 4xx a problem with your request, 5xx a problem at InnBucks. The JSON responseCode is the primary result; the HTTP status is secondary.
Tracing Every response has an X-Trace-Id header. Log it with the request.
Dates Requests use yyyy-MM-dd HH:mm:ss. Responses use several formats (14.2).

7.2 Login

POST /auth/third-party · no bearer token · returns the access token.

Field Type Required Description
username string Yes Your API username
password string Yes Your API password
Response field Description
accessToken The bearer token. Valid for 15 minutes by default
responseCode "00" on success
responseDescription Human-readable result

Examples: 4.1.

7.3 Generate code

POST /api/code/generate · creates a payment or withdrawal code, valid for 10 minutes.

Field Type Required Description
reference string Recommended Your reference for this code. Returned as stan
narration string Recommended Description. Shown on your merchant statement: include your reference
currency string Yes USD or ZWG
amount integer Yes Amount in cents
type string Yes PAYMENT (customer pays you) or WITHDRAWAL (customer cashes out). What you may use depends on your merchant type
Response field Description
code The InnBucks code to show the customer, and the deep link’s paymentToken
qrCode The code as a QR image, base64-encoded
stan Your reference, as InnBucks recorded it
authNumber InnBucks’ authorisation number
processedDateTime When InnBucks processed the request
amount, currency, currencySymbol The amount (in cents) and currency. currencySymbol notes that values are in the subunit
description The narration
responseCode, responseMsg Result
available, ledger, debitAccountNumber, creditAccountNumber, reference Returned as null in the documented example

Examples: 5.1 and 6.1.

7.4 Code inquiry

POST /api/code/inquiry · returns a code’s current status. At most once every 30 seconds per code.

Field Type Required Description
code string Yes The code from generate
reference string No Your reference for this inquiry request
Response field Description
status New, Claimed, Paid, Expired or Timed Out (5.4)
timeToLive Time the code has left, as a string such as "576sec"
code, amount, description The code, its amount (cents) and narration
stan, authNumber, processedDateTime Request tracing
responseCode, responseMsg Result of the inquiry (not of the payment)

Examples: 5.4.

7.5 Linked account inquiry

GET /api/v1/account/msisdn/{msisdn}/details?currency={currency} · finds the wallet linked to a phone number.

Parameter In Required Description
msisdn path Yes Customer’s number, 263 format: 263772123123
currency query No USD or ZWG. Defaults to USD
Response field Description
firstname, lastname Account holder’s name. Check it against the customer’s national ID before a deposit
accounts[] accountNumber, currency, alias, type, productId
responseCode, responseDescription "000" on success

Examples: 6.2.

7.6 Deposit

POST /api/transaction/deposit · credits cash to a customer’s wallet.

Field Type Required Description
reference string Recommended Your reference. Needed for deposit inquiry and reversal; used for duplicate checks when that feature is enabled
currency string Yes USD or ZWG
amount integer Yes Amount in cents
narration string Recommended Description
destinationAccount string Yes accountNumber from the linked account inquiry
type string No Only if InnBucks configured custom deposit types for you

Response: stan, authNumber, processedDateTime, responseCode, responseMsg, accountNumber. Examples: 6.2.

7.7 Deposit inquiry

POST /bank/api/transaction/inquiry · the status of an earlier deposit.

Field Type Required Description
accountNumber string Yes The original deposit’s destinationAccount
originalParticipantReference string Yes The original deposit’s reference
participantReference string Yes A new, unique reference for this inquiry

Response: responseCode, responseDescription, reference, participantReference and, if the deposit was found, details (the original request and its result: responseCode, responseDescription, reference, participantReference, additionalData, currency, amount, dateTime, narration, accountNumber). Examples: 6.3.

7.8 Reversal

POST /api/transaction/reversal/v2 · reverses a deposit. Deposits only.

Field Type Required Description
amount integer Yes Exactly the original deposit amount, in cents
currency string Yes USD or ZWG
type string Yes "CREDIT"
destinationAccount string Yes The original deposit’s destinationAccount
originalParticipantReference string Yes The original deposit’s reference
participantReference string Yes A new, unique reference for this reversal

Response: reference, participantReference, responseCode (00, 025, 096), responseDescription. Examples: 6.4.

7.9 Bank change

POST /api/transaction/bankChange · credits a cash customer’s change to their wallet (US$5 or less).

Field Type Required Description
reference string Recommended Your reference
currency string Yes USD or ZWG
amount integer Yes Amount in cents; at most 500 for USD
narration string Recommended Description
destinationMsisdn string Yes Customer’s number, 263 format

Response: stan, authNumber, processedDateTime, responseCode, responseMsg, accountNumber. Examples: 6.5.

7.10 Utility payment

POST /api/utility/provider/payment · pays a utility provider (for example airtime) from your account.

Field Type Required Description
provider string Yes Provider code, e.g. ECONET
providerProduct string Yes Product code, e.g. AIRTIME
amount integer Yes Amount in cents
currency string Yes USD or ZWG
reference string Recommended Your reference
narration string No Description
destinationAccount string Yes The account or number to credit at the provider
additionalData object No Extra key/value data a provider or product needs 
{
  "provider": "ECONET",
  "providerProduct": "AIRTIME",
  "amount": 100,
  "currency": "USD",
  "reference": "UTL-3301",
  "narration": "Airtime UTL-3301",
  "destinationAccount": "263771234567",
  "additionalData": {}
}

{
  "stan": "UTL-3301",
  "authNumber": "249878909",
  "processedDateTime": "2021-09-05 10:48:08.040",
  "responseCode": "00",
  "responseMsg": "Approved or completed successfully",
  "fees": [],
  "amount": "100",
  "ledger": "2500",
  "available": "2500",
  "currency": "USD",
  "dynamicData": {
    "reference": "56677493",
    "instructions": "Transaction Amount USD1.00",
    "notifications": {}
  },
  "commissions": [
    { "name": "Commission", "description": "DebitCommission", "amount": "5" }
  ],
  "accountNumber": "123456789",
  "currencySymbol": "$ (values are in subunit)"
}

ledger and available appear to be your account balances after the payment, in cents (InnBucks doesn’t define them). dynamicData.instructions appears to hold text to show the customer (possibly a token or voucher, for some products). The list of providers and products is not published: ask InnBucks for the codes you need.

7.11 Account statement

POST /api/account/fullStatement · every transaction on an account for a period of at most one calendar month.

Field Type Required Description
accountNumber string Yes The account to report on
currency string Yes USD or ZWG
startDateTime string Yes yyyy-MM-dd HH:mm:ss, e.g. 2026-09-01 00:00:00
endDateTime string Yes yyyy-MM-dd HH:mm:ss, e.g. 2026-09-30 23:59:59 
{
  "startDate": "2024-01-01T00:00:00",
  "endDate": "2024-01-31T23:59:59",
  "responseCode": "00",
  "responseMsg": "Approved or completed successfully",
  "reference": "1290786790",
  "accountDetails": {
    "accountNumber": "1234",
    "currency": "USD",
    "firstName": "Client Name",
    "lastName": "Client Surname",
    "mobileNumber": "263773123123"
  },
  "transactions": [
    {
      "type": "Opening Balance", "narration": "Opening Balance",
      "creditAmount": 100000, "debitAmount": null, "balance": 100000,
      "reference": "222556",
      "postingDate": "2024-01-01T00:00:00", "transactionDate": "2024-01-01T00:00:00",
      "additionalData": {}
    },
    {
      "type": "Credit", "narration": "Transfer",
      "creditAmount": 27000, "debitAmount": null, "balance": 127000,
      "reference": "6789123",
      "postingDate": "2024-01-12T15:21:00", "transactionDate": "2024-01-12T15:21:00",
      "additionalData": {}
    },
    {
      "type": "Debit", "narration": "Payment",
      "creditAmount": null, "debitAmount": 2000, "balance": 125000,
      "reference": "6789123",
      "postingDate": "2024-01-13T17:45:00", "transactionDate": "2024-01-13T17:45:00",
      "additionalData": {}
    },
    {
      "type": "Closing Balance", "narration": "Closing Balance",
      "creditAmount": 125000, "debitAmount": null, "balance": 125000,
      "reference": "785634",
      "postingDate": "2024-01-31T23:59:59", "transactionDate": "2024-01-31T23:59:59",
      "additionalData": {}
    }
  ]
}

Transaction type is Opening Balance, Credit, Debit or Closing Balance. For a longer period, request one calendar month at a time.

7.12 Response code list

GET /api/file/response-codes · the complete list of response codes for your environment.

curl -sS "$INNBUCKS_BASE_URL/api/file/response-codes" \
  -H "X-Api-Key: $INNBUCKS_API_KEY" \
  -H "Authorization: Bearer $TOKEN" -o innbucks-response-codes

Download it when you integrate and keep it with your code; see 8.2.

This page is generated from section 7 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