Agent services

These operations are for businesses set up as InnBucks agents. A cash withdrawal uses a code, exactly like a payment. Deposits, deposit inquiries, reversals and bank change don’t: each call returns its result directly, usually within 2 to 10 seconds.

6.1 Cash withdrawal (cash-out)

A withdrawal works like a payment, in reverse: you generate a withdrawal code, the customer claims it in their app or by USSD, and once the code is claimed you hand over the cash.

Generate a code with "type": "WITHDRAWAL" and the cash amount in cents (5.1).
Show the code and QR code to the customer (5.2).
The customer confirms the withdrawal in the InnBucks app or on *569#.
Check the code every 30 seconds (5.4).
Hand over the cash only when the status is Claimed (or Paid).

{
  "reference": "WD-20931",
  "narration": "Cash out WD-20931",
  "currency": "USD",
  "amount": 2000,
  "type": "WITHDRAWAL"
}

6.2 Cash deposit (cash-in)

A deposit credits a customer’s wallet with cash they hand over at your store. It takes three steps, and step 2 is a compliance requirement:

Find the account for the customer’s phone number with the linked account inquiry.
Verify the customer: check the returned first and last name against the customer’s national ID, by hand.
Deposit to the account number from step 1.

Step 1: linked account inquiry. GET {baseUrl}/api/v1/account/msisdn/{msisdn}/details?currency={currency}

curl -sS "$INNBUCKS_BASE_URL/api/v1/account/msisdn/263772123123/details?currency=USD" \
  -H "X-Api-Key: $INNBUCKS_API_KEY" \
  -H "Authorization: Bearer $TOKEN"

{
  "responseCode": "000",
  "responseDescription": "Approved or completed successfully",
  "firstname": "James",
  "lastname": "Mufambanaayo",
  "accounts": [
    {
      "accountNumber": "3003373465942",
      "currency": "USD",
      "alias": null,
      "type": null,
      "productId": null
    }
  ]
}

Success here is "000" (three zeros). If you leave out currency, you get the USD account. Pick the account whose currency matches the deposit.

Step 3: deposit. POST {baseUrl}/api/transaction/deposit

{
  "reference": "DEP-88213",
  "currency": "USD",
  "amount": 1000,
  "narration": "Cash deposit DEP-88213",
  "destinationAccount": "3003373465942"
}

{
  "stan": "DEP-88213",
  "authNumber": "1735042",
  "processedDateTime": "2021-03-12T12:39:19.641+0200",
  "responseCode": "00",
  "responseMsg": "Success",
  "accountNumber": "3003373465942"
}

Always send your own reference. It is the key you need later to check or reverse the deposit. If you leave it out, InnBucks generates one.
If duplicate checking is enabled for your account, a second deposit with the same reference is rejected as a duplicate. Ask InnBucks whether it is enabled for you.
type is optional. Send it only if InnBucks configured special deposit types for you.

6.3 When a deposit result is lost: deposit inquiry

If a deposit times out, or you don’t know whether it went through, don’t send it again. Ask for its status with the same reference.

POST {baseUrl}/bank/api/transaction/inquiry (note the /bank prefix)

{
  "accountNumber": "3003373465942",
  "participantReference": "INQ-DEP-88213",
  "originalParticipantReference": "DEP-88213"
}

Field	Value
`accountNumber`	The `destinationAccount` of the original deposit
`originalParticipantReference`	The `reference` of the original deposit
`participantReference`	A new, unique reference for this inquiry

{
  "responseCode": "00",
  "responseDescription": "Approved or completed successfully",
  "reference": "678054",
  "participantReference": "INQ-DEP-88213",
  "details": {
    "responseCode": "00",
    "responseDescription": "Approved or completed successfully",
    "reference": "9001746",
    "participantReference": "DEP-88213",
    "additionalData": {},
    "currency": "USD",
    "amount": 1000,
    "dateTime": "2022-12-16 11:39:01.387000",
    "narration": "Cash deposit DEP-88213",
    "accountNumber": "3003373465942"
  }
}

If the original deposit is found, details holds it, and details.responseCode is the deposit’s own result ("00" = it succeeded). The outer responseCode only says the inquiry itself worked. InnBucks says a deposit has either succeeded or been rejected within 30 minutes, so an answer you get after that is final.

6.4 Reversing a deposit

Reversal is available only for deposits. Real-time reversals are not available for any code-based transaction (payments and withdrawals). InnBucks has a separate reversal process, with its own document and training at go-live: ask InnBucks how to reverse a code payment.

POST {baseUrl}/api/transaction/reversal/v2

{
  "amount": 1000,
  "currency": "USD",
  "type": "CREDIT",
  "destinationAccount": "3003373465942",
  "participantReference": "REV-DEP-88213",
  "originalParticipantReference": "DEP-88213"
}

Field	Value
`amount`	Exactly the amount of the original deposit
`currency`	The currency of the original deposit
`type`	Always `"CREDIT"`
`destinationAccount`	The `destinationAccount` of the original deposit
`originalParticipantReference`	The `reference` of the original deposit
`participantReference`	A new, unique reference for this reversal

{
  "reference": "588586383",
  "participantReference": "REV-DEP-88213",
  "responseCode": "00",
  "responseDescription": "Approved or completed successfully"
}

`responseCode`	Meaning
`00`	Reversed
`025`	Unable to locate the original request, or it was already processed (reversed)
`096`	Request failed. Try again later

On 096, try again later. InnBucks doesn’t say whether the retry should reuse the same participantReference or use a new one, so ask them; either way, run a deposit inquiry first if you are unsure whether the first attempt went through. On 025, check the original with a deposit inquiry before doing anything else.

6.5 Bank change

When a customer pays cash and you can’t give exact change, you can credit the change to their InnBucks wallet instead. The limit is US$5.00 (500 cents) or less, and InnBucks may change it. No ZWG limit is documented: ask InnBucks.

POST {baseUrl}/api/transaction/bankChange

{
  "reference": "CHG-55102",
  "currency": "USD",
  "amount": 150,
  "narration": "Change for receipt 55102",
  "destinationMsisdn": "263770123123"
}

{
  "stan": "CHG-55102",
  "authNumber": "1735095",
  "processedDateTime": "2021-03-12 15:23:45.387",
  "responseCode": "00",
  "responseMsg": "Approved or completed successfully",
  "accountNumber": "123456789"
}

Validate the amount before sending (more than 0, and at most 500 cents in USD), and only do this when the customer asks for it.

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