EcoCash

EcoCash is Zimbabwe’s largest mobile money network. Customers pay by entering their PIN on the phone registered to the number they’re paying with. It works in both the redirect and seamless flows, in both currencies.

	US dollars	Zimbabwe dollars
Payment method code	PZW211	PZW201
Currency code to send	USD	ZiG
Amount range	$1.00 – $500.00	2.00 – 8,000.00
Required field	customerPhoneNumber	customerPhoneNumber

Amounts above the range aren’t rejected — they’re collected in several parts. No redirect is required in either currency; the payment completes on the customer’s phone.

Customer experience

Redirect flow

The customer selects EcoCash on the Pesepay-hosted payment page, enters their EcoCash-registered phone number, and enters their PIN on that phone to approve the payment.

Seamless flow

You collect the customer’s phone number in your own UI and submit it as customerPhoneNumber. Pesepay pushes a prompt to that phone; the customer enters their EcoCash PIN to approve. Your UI should show a waiting state — Pesepay’s own wording for this step is “Please enter PIN on the phone that is making the payment.”

Seamless flow: required fields

{
  "paymentMethodCode": "PZW211",
  "paymentMethodRequiredFields": {
    "customerPhoneNumber": "0771234567"
  }
}

Field	Type	Required	Description
customerPhoneNumber	string	Yes	The customer’s EcoCash-registered phone number. Digits only — a leading + and any spaces are stripped. Must start with a recognised Econet prefix and be no more than 14 digits

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

See Make Payment for the full request and response shape with code samples.

Payments above the limit

A single EcoCash transaction can’t exceed $500 (or 8,000 in Zimbabwe dollars). Pesepay doesn’t reject larger payments — it collects them in several parts automatically, and your integration doesn’t have to do anything different.

1. Pesepay divides the amount into legs, each within the ceiling. A $1,200 payment becomes three legs: $500, $500, and $200.

2. The customer approves each leg on their phone. They get one prompt per leg and enter their PIN each time, so a large payment takes longer and asks more of the customer than a small one.

3. You still see one transaction. The legs are internal — you get the same single referenceNumber you’d get for any other payment, one result callback when it’s done, and one status when you check the payment. The individual legs are never exposed to you.

4. If any leg fails, the whole payment is reversed. Every leg that already succeeded is refunded automatically, and the transaction ends REVERSED. The customer doesn’t have to ask for the money back, and you never have to handle a partly-paid order.

Caution

In the rare case where a reversal itself fails, the transaction ends FAILED rather than REVERSED and the customer may be temporarily out of pocket for one or more legs. Treat a FAILED status on a large EcoCash payment as something to reconcile, not just an unpaid order — contact Pesepay support with the referenceNumber.

This applies to EcoCash only — every other method rejects amounts over its ceiling. Because a multi-part payment asks the customer for several PIN entries, tell them what to expect at checkout when the amount is over the limit: an unexplained second prompt is the most common reason customers abandon these payments.

Note

This has nothing to do with split payments, which divide a payment between two merchants. The legs here are one customer paying one merchant in several charges, and they’re what the splits array on the result callback describes.

Amount limits

The ranges above are configured per payment method and currency, and can change without a documentation update. Read minimumAmount and maximumAmount live from Get Payment Methods by Currency if you want your checkout’s validation to stay in sync automatically.

Failure modes

What happened	What you see
Phone number isn’t a valid Econet number	400 with Invalid Ecocash phone number supplied
customerPhoneNumber missing	400 with Ecocash paying phone number should be provided
Customer enters the wrong PIN, cancels, or ignores the prompt	The transaction ends in a non-success status
Insufficient wallet balance	The transaction fails; the message comes from EcoCash and is passed through as free text
One leg of a multi-part payment fails	The whole payment is reversed — see above

Decline messages for mobile money come from EcoCash, not from Pesepay, so match on transaction status rather than on message text.

Testing

Sandbox numbers that force a successful or failed EcoCash payment are on Test credentials.