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 with Hosted checkout, Embedded checkout and the Direct API, in both currencies.
| US dollars | ZiG | |
|---|---|---|
| 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
Section titled “Customer experience”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.
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.”
Direct API: required fields
Section titled “Direct API: required fields”{ "paymentMethodCode": "PZW211", "paymentMethodRequiredFields": { "customerPhoneNumber": "0771234567" }}| Field | Type | Required | Description |
|---|---|---|---|
customerPhoneNumber | string | Yes | The customer’s EcoCash-registered phone number, in local form: 0771234567. Pesepay checks that it is an Econet number (077 or 078, or the same with 263 in front) of at most 14 digits, then passes it to EcoCash as you sent it. The sandbox recognises only its test numbers, written exactly as listed |
Send PZW201 instead of PZW211 when you’re charging in ZiG
— the field is the same.
See Make Payment for the full request and response shape with code samples.
Payments above the limit
Section titled “Payments above the limit”A single EcoCash transaction can’t exceed $500 (or 8,000 in ZiG). Pesepay doesn’t reject larger payments — it collects them in several parts automatically, and your integration doesn’t have to do anything different.
-
Pesepay divides the amount into legs, each within the ceiling. A $1,200 payment becomes three legs: $500, $500, and $200.
-
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.
-
You still see one transaction. The legs are internal — you get the same single
referenceNumberyou’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. -
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.
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.
Amount limits
Section titled “Amount limits”These ranges can change: read the current minimumAmount and
maximumAmount from
Get Payment Methods by Currency.
Failure modes
Section titled “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
Section titled “Testing”Sandbox numbers that force a successful or failed EcoCash payment are on test credentials.