API Reference

Payments

Initiate, confirm, track and cancel payments. Every route here needs your SBU's X-SBU-Key and returns a Payment object.

POSTInitiate hosted checkoutReturns a paymentUrl to redirect the customer to Smile&Pay's payment page.
POSTInitiate express checkoutCharge directly — no redirect — via ecocash, innbucks, omari, smilecash or card.
POSTConfirm with OTPSecond leg for Omari and SmileCash — submits the customer's one-time PIN.
GETGet payment statusReads the transaction; add ?refresh=true to poll Smile&Pay for the live status.
POSTCancel paymentAsks Smile&Pay to cancel; the record moves to CANCELED once confirmed.
GETList paymentsYour SBU's transaction history, newest first, paginated.

Initiate hosted checkout

Returns a paymentUrl to redirect the customer to Smile&Pay's payment page.

POST/api/v1/payments/checkout/initiate

Auth: X-SBU-Key

The simplest way to take a payment: Smile&Pay hosts the payment page and handles method selection. Redirect the customer to the returned paymentUrl. You may preselect a method with paymentMethod, otherwise the customer chooses on the page.

Body — required

Field	Type	Description
amount	number	Amount to charge. Minimum 0.01.
currencyCode	string	"840" = USD, "924" = ZWG.
itemName	string	Name of the item or service being paid for.
returnUrl	string	Where the customer's browser lands after payment.

Body — optional (10)

Field	Type	Description
paymentMethod	enum	Preselect on the hosted page: WALLETPLUS, ECOCASH, INNBUCKS, CARD, OMARI or ONEMONEY. Omit to let the customer choose.
itemDescription	string	Description of the item. Defaults to itemName.
sbuReference	string	Your invoice/order number, echoed back in every response.
firstName	string	Customer first name.
lastName	string	Customer last name.
email	string	Customer email address.
mobilePhoneNumber	string	Customer mobile number.
cancelUrl	string	Redirect target if the customer cancels.
failureUrl	string	Redirect target if the payment fails.
extraFields	object	Extra Smile&Pay fields not modelled here; passed through verbatim.

Request

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": 25.50,
    "currencyCode": "840",
    "itemName": "Invoice INV-1042",
    "sbuReference": "INV-1042",
    "returnUrl": "https://yourapp.example/payment/return"
  }'

Response · 200

{
  "orderReference": "PMICRO-32BB1F259960401B",
  "sbuCode": "PMICRO",
  "paymentMethod": "HOSTED",
  "status": "PENDING",
  "amount": 25.50,
  "currencyCode": "840",
  "gatewayReference": "WAJL5621BJYQ",
  "paymentUrl": "https://zbnet.zb.co.zw/wallet_sandbox_checkout?reference=WAJL5621BJYQ",
  "createdAt": "2026-07-19T02:17:20.805236Z"
}

Returns a Payment object.

Redirect the customer to paymentUrl to complete payment.
The method they actually used arrives later via webhook or status check and replaces HOSTED on the transaction.

Initiate express checkout

Charge directly — no redirect — via ecocash, innbucks, omari, smilecash or card.

POST/api/v1/payments/{method}/initiate

Auth: X-SBU-Key

Express checkout keeps the customer in your own UI. Each method needs one or two extra fields and finishes differently — see the method notes below.

Path parameters

Field	Type	Description
method	string	innbucks \| ecocash \| omari \| smilecash \| card

Body — required

Field	Type	Description
amount	number	Amount to charge. Minimum 0.01.
currencyCode	string	"840" = USD, "924" = ZWG.
itemName	string	Name of the item or service being paid for.
walletNumber	string	Required for ecocash, omari and smilecash — the wallet mobile number to charge.
card	object	Required for card: { cardholderName, cardNumber, expiryMonth, expiryYear, cvv }.

Body — optional (10)

Field	Type	Description
returnUrl	string	Where the customer lands after payment. Defaults to the gateway's public base URL.
itemDescription	string	Description of the item. Defaults to itemName.
sbuReference	string	Your invoice/order number, echoed back in every response.
firstName	string	Customer first name.
lastName	string	Customer last name.
email	string	Customer email address.
mobilePhoneNumber	string	Customer mobile number.
cancelUrl	string	Redirect target if the customer cancels.
failureUrl	string	Redirect target if the payment fails.
extraFields	object	Extra Smile&Pay fields not modelled here; passed through verbatim.

Request

curl -X POST https://13-247-53-102.sslip.io/api/v1/payments/ecocash/initiate \
  -H 'X-SBU-Key: sbu_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 10.00,
    "currencyCode": "840",
    "itemName": "Order #883",
    "walletNumber": "0771234567"
  }'

Response · 200

{
  "orderReference": "PMICRO-3FD0A655EB7A4AE7",
  "paymentMethod": "ECOCASH",
  "status": "PENDING",
  "amount": 10.00,
  "gatewayReference": "SPUJ8657IOHJ",
  "gatewayResponse": {
    "responseMessage": "Awaiting Payment",
    "status": "AWAITING_PAYMENT"
  }
}

Returns a Payment object.

Ecocash — the customer gets a USSD push to approve. Poll the status endpoint until PAID or FAILED.
InnBucks — the response carries innbucksPaymentCode and innbucksDeepLink; show them to the customer.
Omari & SmileCash — the customer gets an OTP; status becomes AWAITING_CONFIRMATION until you call confirm.
Card — gatewayResponse contains the 3DS redirect HTML for the issuer's page.

Confirm with OTP

Second leg for Omari and SmileCash — submits the customer's one-time PIN.

POST/api/v1/payments/{orderReference}/confirm

Auth: X-SBU-Key

Path parameters

Field	Type	Description
orderReference	string	The orderReference returned at initiation.

Body — required

Field	Type	Description
otp	string	One-time PIN the customer received.

Request

curl -X POST https://13-247-53-102.sslip.io/api/v1/payments/PMICRO-3FD0A655EB7A4AE7/confirm \
  -H 'X-SBU-Key: sbu_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '{ "otp": "123456" }'

Returns a Payment object.

Only OMARI and SMILECASH have a confirmation leg; other methods return 400.

Get payment status

Reads the transaction; add ?refresh=true to poll Smile&Pay for the live status.

GET/api/v1/payments/{orderReference}

Auth: X-SBU-Key

Path parameters

Field	Type	Description
orderReference	string	The orderReference returned at initiation.

Query parameters

Field	Type	Description
refresh	boolean	true = also query Smile&Pay and update the local record. Default false.

Request

curl 'https://13-247-53-102.sslip.io/api/v1/payments/PMICRO-3FD0A655EB7A4AE7?refresh=true' \
  -H 'X-SBU-Key: sbu_your_key_here'

Returns a Payment object.

SBUs only see their own transactions — other references return 404.
Prefer webhooks for the final status; use refresh=true as a fallback poll.

Cancel payment

Asks Smile&Pay to cancel; the record moves to CANCELED once confirmed.

POST/api/v1/payments/{orderReference}/cancel

Auth: X-SBU-Key

Path parameters

Field	Type	Description
orderReference	string	The orderReference returned at initiation.

Request

curl -X POST https://13-247-53-102.sslip.io/api/v1/payments/PMICRO-3FD0A655EB7A4AE7/cancel \
  -H 'X-SBU-Key: sbu_your_key_here'

Returns a Payment object.

List payments

Your SBU's transaction history, newest first, paginated.

GET/api/v1/payments

Auth: X-SBU-Key

Query parameters

Field	Type	Description
page	integer	Zero-based page index. Default 0.
size	integer	Page size, capped at 100. Default 20.

Request

curl 'https://13-247-53-102.sslip.io/api/v1/payments?page=0&size=20' \
  -H 'X-SBU-Key: sbu_your_key_here'

Response

Field	Type	Description
content	Payment[]	The page of Payment objects.
totalElements	integer	Total transactions matching the query.
totalPages	integer	Total number of pages.
number	integer	Current zero-based page index.