PrevailPay Gateway
API Reference
One API for every Prevail SBU to take payments through ZB Smile&Pay. Start here for the concepts that apply everywhere, then pick a section for the routes themselves.
https://13-247-53-102.sslip.ioDev http://localhost:8080JSON onlySections
Payment methods — start here
How to integrate every rail: EcoCash, InnBucks, O'mari, SmileCash, Visa/Mastercard, ZimSwitch, WalletPlus and OneMoney.
Integration guide →
Payments
Charge customers and track transactions
6 endpoints →
Admin — Transactions
Search every SBU's payments from head office
2 endpoints →
Admin — SBUs
Register sub-business units and issue keys
5 endpoints →
Admin — Users
Dashboard accounts, roles and sessions
7 endpoints →
Reports
Who received how much, and by which method
3 endpoints →
Webhooks
How final payment results reach you
1 endpoint →
Getting started
- 1. Get your key. Head office registers your SBU and hands you an
X-SBU-Key. Send it on every payment request. - 2. Initiate a payment. Hosted checkout for a redirect flow, or express checkout to keep customers in your own UI.
- 3. Wait for the result. We receive the gateway webhook and update the transaction; poll
?refresh=trueif you need it sooner. - 4. Fulfill on PAID. Never on PENDING — the customer may still abandon or fail.
curl -X POST https://13-247-53-102.sslip.io/api/v1/payments/checkout/initiate \
-H 'X-SBU-Key: sbu_your_key_here' \
-H 'Content-Type: application/json' \
-d '{
"amount": 10.00,
"currencyCode": "840",
"itemName": "Invoice INV-1042",
"returnUrl": "https://yourapp.example/payment/return"
}'Authentication
Two header-based keys, issued by head office. Send the right one for the route you are calling — there are no tokens or OAuth flows.
| X-SBU-Key | Identifies one SBU. Grants /api/v1/payments/** and that SBU's own /api/v1/reports/**. Rotatable at any time. |
| X-Admin-Key | Head office only. Grants /api/v1/admin/** (SBUs, keys, dashboard users) and group-wide reports. |
| (none) | /api/v1/webhooks/** is unauthenticated — it is called by ZB Smile&Pay servers, not by you. |
The Payment object
Every endpoint under Payments returns this shape. Fields that do not apply to a method are omitted rather than null.
| Field | Type | Description |
|---|---|---|
| orderReference | string | Gateway-generated reference, format {SBUCODE}-{16 hex}. Use it for status checks, confirm and cancel. |
| sbuCode | string | Code of the SBU that owns the transaction. |
| sbuReference | string | Your own invoice/order number, echoed back if you sent one. |
| paymentMethod | enum | INNBUCKS, ECOCASH, OMARI, SMILECASH, CARD, WALLETPLUS, ONEMONEY or HOSTED. |
| status | enum | PENDING, AWAITING_CONFIRMATION, PAID, FAILED, CANCELED or UNKNOWN. |
| amount | number | Transaction amount. |
| currencyCode | string | "840" = USD, "924" = ZWG. |
| itemName | string | Item name supplied at initiation. |
| gatewayReference | string | Smile&Pay's own transaction reference. |
| innbucksPaymentCode | string | InnBucks only — code the customer enters in the InnBucks app. |
| innbucksDeepLink | string | InnBucks only — deep link that opens the app pre-filled with the code. |
| paymentUrl | string | Hosted checkout only — URL to redirect the customer to. |
| clientFee | number | Fee charged to the customer, when reported by the gateway. |
| merchantFee | number | Fee charged to the merchant, when reported by the gateway. |
| createdAt | string | ISO-8601 timestamp of creation. |
| completedAt | string | ISO-8601 timestamp of the final state, once reached. |
| gatewayResponse | object | Raw Smile&Pay response for anything not modelled above (e.g. 3DS HTML). Only on calls that hit the gateway. |
Statuses & payment methods
Transaction statuses
| PENDING | Initiated; awaiting customer action or gateway processing. |
| AWAITING_CONFIRMATION | OTP sent (Omari/SmileCash); waiting for the confirm call. |
| PAID | Completed successfully — fulfill the order. |
| FAILED | Payment failed or was declined. |
| CANCELED | Transaction was canceled. |
| UNKNOWN | Gateway returned a status we could not map. |
Payment methods
| ECOCASH | Express — USSD push to the customer's phone. Needs walletNumber. |
| INNBUCKS | Express — returns a payment code and deep link for the InnBucks app. |
| OMARI | Express, two legs — OTP, then confirm. Needs walletNumber. |
| SMILECASH | Express, two legs — OTP, then confirm. Needs walletNumber. |
| CARD | Express — 3DS redirect HTML in gatewayResponse. Needs the card object. |
| WALLETPLUS | Hosted checkout only (preselectable). |
| ONEMONEY | Hosted checkout only (preselectable). |
| HOSTED | Customer picks the method on the Smile&Pay page. |
Currencies are ISO numeric codes sent as strings: "840" = USD, "924" = ZWG.
Errors
Errors use standard HTTP status codes with a JSON body. Anything from the upstream gateway is surfaced as 502 with the original response attached.
| 400 | Validation failure or bad input. Body: { error, message, details? }. |
| 401 | Missing or invalid X-SBU-Key / X-Admin-Key. |
| 404 | Unknown resource — including another SBU's orderReference, which is never leaked. |
| 502 | Smile&Pay gateway error. Body includes gatewayStatus and the raw gatewayBody. |