Omari

Omari is a Zimbabwean mobile money wallet. Unlike the other wallets, Omari does not push an approval prompt to the phone. Paying takes two steps: the customer is sent a one-time password by SMS, and that code has to be submitted back to Pesepay to actually move the money. Omari works in both the redirect and seamless flows, in both currencies.

	US dollars	Zimbabwe dollars
Payment method code	PZW216	PZW217
Currency code to send	USD	ZWG
Amount range	$0.50 – $500.00	0.10 – 100,000.00
Required field	customerPhoneNumber	customerPhoneNumber
Redirect required	No	No

Caution

Charge PZW217 with the currency code ZWG, not ZiG. Zimbabwe dollars are addressed by two different currency codes depending on the method — see Payment method codes for which one goes with which.

Customer experience

Redirect flow

The customer selects Omari on the Pesepay-hosted payment page and enters the phone number registered to their Omari wallet. Omari sends them a six-digit code by SMS, and the hosted page then shows an O’mari OTP field for them to type it into. Nothing extra is required of you — the hosted page handles both steps.

Seamless flow

You build both screens: one to collect the phone number, and one to collect the six-digit code Omari texts the customer. A waiting state alone is not enough — if you never submit the code, the payment never completes. The two calls are below.

Seamless flow

Omari takes two calls. The first sends the customer a one-time code and moves no money; the second spends that code and debits the wallet.

Step 1: request the OTP

Send the customer’s Omari phone number as customerPhoneNumber to Make Payment:

{
  "paymentMethodCode": "PZW216",
  "paymentMethodRequiredFields": {
    "customerPhoneNumber": "263771234567"
  }
}

Field	Type	Required	Description
customerPhoneNumber	string	Yes	The customer’s Omari-registered number, in full international form without a + — twelve digits matching 2637XXXXXXXX

Send PZW217 instead of PZW216 when you’re charging in Zimbabwe dollars — the field is the same.

Caution

Omari is stricter about number format than the other wallets. A local form like 0771234567 is not accepted — send 263771234567. Pesepay’s own checkout rejects anything that doesn’t match 2637XXXXXXXX before it submits, and you should validate the same way so the customer sees your error rather than a failed transaction.

This call does not debit the customer — it asks Omari to text them a code. The decrypted response comes back with a transactionStatus of PENDING and an otpReference in transactionMetadata:

Key	Description
otpReference	Omari’s identifier for the OTP it just sent. Store it against the transaction for support and reconciliation

Store the referenceNumber as usual — you need it for step 2.

Step 2: submit the OTP

Omari sends the customer a six-digit numeric code by SMS. Collect it in your own UI, then post it with the transaction’s referenceNumber. This is the call that debits the wallet.

Environment	URL
Production	https://api.pesepay.com/api/omari/v1/payments/charge

{
  "otp": "123456",
  "referenceNumber": "20260901103214123-A1B2C3D4"
}

Field	Type	Required	Description
otp	string	Yes	The six-digit code the customer received by SMS
referenceNumber	string	Yes	The referenceNumber from step 1

Note

This endpoint is not part of the payments-engine API: it takes no integration key and the body is not encrypted. It is reachable from a browser — that is how Pesepay’s own hosted page submits the code — but prefer calling it from your server, so the OTP and reference number don’t pass through client-side code.

The response carries the resulting status directly:

Field	Description
referenceNumber	The transaction’s reference number
transactionStatus	The resulting status — SUCCESS when the wallet was debited
paymentProviderMessage	Human-readable description of that status
paymentProviderStatus	Omari’s own numeric response code
paymentProviderReference	Omari’s reference for the debit

Step 3: confirm the result

The charge response tells you what happened immediately, but reconcile against the result callback or Check Payment Status, exactly as with every other method.

Status while you’re waiting

Between steps 1 and 2 the transaction sits at PENDING. That is the normal state for “the OTP has been sent but not yet submitted”, not a sign that something has gone wrong, and polling during this window keeps returning PENDING.

If the customer abandons the flow and no OTP is ever submitted, the transaction stays non-terminal until Pesepay’s status reconciliation resolves it against Omari. It will not complete on its own.

Amount limits

Omari rejects amounts outside its configured range — $0.50 to $500.00 for US dollars, and a much wider range in Zimbabwe dollars. Amounts above the ceiling are rejected, not collected in parts. Validate in your own checkout so the customer sees your error message rather than a failed transaction.

Limits are configured per payment method and currency, and can change without a documentation update. Read them live from Get Payment Methods by Currency (minimumAmount / maximumAmount) if you want your checkout to stay in sync automatically.

Failure modes

What happened	What you see
Phone number isn’t in 2637XXXXXXXX form	Omari rejects it at step 1 and the transaction ends FAILED
Omari won’t send the OTP	Step 1 comes back non-PENDING and the transaction ends FAILED
Customer enters the wrong code	The transaction ends in a terminal non-success status, usually DECLINED or AUTHORIZATION_FAILED
Customer never enters the code	The transaction stays PENDING until reconciliation resolves it
Omari times out	The transaction ends TIME_OUT
Insufficient wallet balance	The transaction ends INSUFFICIENT_FUNDS; the message comes from Omari and is passed through as free text
Amount outside the range	The API rejects the request with 400 — see Errors

Caution

A rejected OTP is terminal. There is no second attempt on the same transaction — the customer has to start a new payment, which sends a new code. Build your UI around a single attempt rather than a retry loop.

Failure messages for mobile money come from the wallet provider, not from Pesepay, so match on transaction status rather than on message text.

Testing

Caution

The sandbox currently offers EcoCash, Visa and Mastercard only, so Omari can’t be exercised there — see Sandbox environment.