API Reference
Base URL https://omniway.online. Authenticate every call with
Authorization: Bearer sk_test_… | sk_live_…. Amounts are integer cents; currencies
USD | ZWG. Money-moving POSTs require Idempotency-Key.
Payments
Create a payment. Body: amount_cents*, currency, narration, merchant_ref, metadata, success_url, cancel_url. Returns the payment with code, qr_png_data_url, deep_link, ussd, checkout_url, expires_at. Guide
Retrieve one payment; refreshes live status while pending (upstream inquiry throttling handled by the platform).
List. Query: status, merchant_ref, from, to, limit≤100, cursor. Returns { data, has_more }.
Hosted checkout (public, unauthenticated)
The hosted payment page. Safe to share — the unguessable id is the capability. Guide
Lightweight poll the page itself uses: { status, expires_at, success_url, cancel_url }.
Instantly settle (or expire with {"outcome":"expired"}) a sandbox payment. 403 on live payments. Guide
The popup snippet: POS.pay({ checkoutUrl, onSuccess, onCancel }).
Balance & reporting
Available balance per currency for the key's mode.
Ledger entries. Query: entry_type, from, to, limit, cursor. Entry types
CSV with running balance. Query: from, to.
Your merchant profile: name, type, status, fee_bps, fee_fixed_cents, payout destination + verification state.
Resolve a phone number to InnBucks account holder name + account numbers.
Catalog (products)
Create a product. Body: name*, price_cents (null = price-at-sale), currency, barcode (unique per merchant), sku, category, track_stock, stock_qty, low_stock_at. Guide
List/search. Query: q (name/sku/barcode), barcode (exact — the scanner lookup), category, active=true|false|all, limit≤500.
Retrieve / update (name, price, barcode, tracking, active for soft-delete).
Stock
Goods in. Body: product_id*, qty* (positive), note.
Correction by delta (±). Body: product_id*, qty* (signed), note.
Stocktake: set the absolute counted quantity; the delta is computed and journaled.
The append-only movement journal. Query: product_id, limit.
On-hand units + valuation per product, totals, and the low_stock list.
Sales
Body: items* (array of {product_id, qty} or ad-hoc {name, qty, unit_cents}), tender*: cash | innbucks, currency, cashier, note. Cash completes instantly; innbucks returns an embedded payment (code/QR) and completes on settlement. Guide
Retrieve; pending innbucks sales refresh their payment live and finalize when paid.
List. Query: status (pending|completed|cancelled), from, to, limit.
Takings by tender + currency, top products, totals. Query: from, to.
Payouts
Body: amount_cents*, currency. Destination is always your verified wallet. 402 if it exceeds your balance. Guide
Track requested → submitted → confirmed | failed | reversed; failure_reason on failures.
Agent operations
Body: amount_cents*, currency. Returns a claimable code + QR; balance credited on redemption. Guide
Status: pending → redeemed | expired.
Body: amount_cents* (≤500 USD cents), currency, destination_msisdn* (263…), narration. Instant; debits your balance. Guide
Utilities
Body: provider*, provider_product*, amount_cents*, currency, destination_account*, narration, additional_data. Returns fees + commissions; commission auto-credited. Guide
Webhooks & events
Body: url* (https; http allowed in test mode), event_types (default ["*"]). Returns the whsec_ secret — shown once. Guide
List / deactivate.
Polling fallback; oldest-first after since. Guide
Conventions
| Convention | Rule |
|---|---|
| Auth | Authorization: Bearer sk_… on every /v1/* call. The key's prefix selects test vs live world. |
| Idempotency | Rows marked ⚿ require Idempotency-Key. Same key + same body replays the stored response; same key + different body → 409. Details |
| Money | Integer cents everywhere. USD | ZWG. |
| Pagination | limit (≤100) + cursor keyset; responses are { data, has_more }. |
| Errors | One envelope: { "error": { type, code, message } }. Reference |
| Rate limits | 60 requests / 10 s per merchant on /v1; 429 with rate_limited beyond. |