Products · Agent Operations

Agent Operations

For merchants who also act as InnBucks cash points — tuck shops, agents, retail counters. Two tools: withdrawal codes (customer takes cash out at your till) and bank change (send small change straight to a customer's wallet).

Withdrawal codes — customer cash-out

The customer wants cash from their InnBucks wallet; you have cash in the drawer. The flow:

You create a code

POST /v1/agent/withdrawal_codes for the amount the customer wants.

→

Customer claims it

They enter the code (or scan the QR) in their InnBucks app — their wallet is debited.

→

You hand over cash

Status flips to redeemed; your platform balance is credited the same amount.

curl https://omniway.online/v1/agent/withdrawal_codes \
  -H "Authorization: Bearer sk_live_..." -H "Content-Type: application/json" \
  -H "Idempotency-Key: till3-cashout-0611-001" \
  -d '{"amount_cents": 2000, "currency": "USD"}'

# → { "id":"…", "status":"pending", "code":"794104062",
#     "qr_png_data_url":"data:image/png;base64,…", "expires_at":"…" }

Track it with GET /v1/agent/withdrawal_codes/:id (statuses: pending → redeemed, or expired after the 10-minute window) — or just wait for the withdrawal.redeemed webhook and release the cash when it arrives.

⛔

Hand over cash only on redeemed

The claim in the customer's app is what debits their wallet. Until your system sees status: "redeemed" (poll or webhook), no money has moved — don't open the drawer.

Bank change — change to wallet, instantly

Cash purchase, no coins for change? Push the change straight to the customer's InnBucks wallet by phone number. Instant (2–10 s), no code, no inquiry; capped at USD 5.00 per InnBucks rules.

curl https://omniway.online/v1/agent/bank_changes \
  -H "Authorization: Bearer sk_live_..." -H "Content-Type: application/json" \
  -H "Idempotency-Key: till3-change-0611-014" \
  -d '{
    "amount_cents": 150,
    "currency": "USD",
    "destination_msisdn": "263772000111",
    "narration": "Change — till 3"
  }'
# → { "status": "sent", … }   debited from your platform balance

destination_msisdn must be the full international format: 263XXXXXXXXX.
Amounts above 500 cents USD are rejected before anything moves (bank_change_limit).
The debit comes off your balance under the same no-overdraft guarantees as payouts; if the gateway refuses, the debit is automatically compensated.

Look up a customer first

Confirm you're sending to the right person before bank change or any wallet operation:

curl "https://omniway.online/v1/account/lookup?msisdn=263772000111" \
  -H "Authorization: Bearer sk_live_..."
# → { "first_name":"Farai", "last_name":"Gumbo",
#     "accounts":[{"account_number":"3007720001110","currency":"USD"}] }

Show the name to the cashier (“send $1.50 to Farai G.?”) — the same check the platform performs before your own payouts.

Previous← Payouts & Balance NextUtility Payments →