By Bonaventure Ogeto · Published · Last verified: 2026-11-04

EcoCash API: what exists and how merchants connect

The short answer

Yes, there is an EcoCash API. EcoCash runs an official developer portal for its Open API, with a sandbox and certification before you go live[EcoCash developer portal, checked 2026-11-05]. Merchants connect directly through that portal or through Paynow, which bundles EcoCash with other wallets, ZimSwitch and Visa/Mastercard[Paynow developer docs, checked 2026-11-04]. Go direct for EcoCash-only control; use Paynow for breadth.

Source: Mctaba Labs, “EcoCash API: what exists and how merchants connect”, last verified 2026-11-04, mctaba.com/learn/payments/zimbabwe/ecocash-api

Mctaba Labs builds payment integrations for businesses across Africa. This guide is written to be useful whether or not you ever hire us.

Is there an official EcoCash API?

Yes. EcoCash runs an official developer portal for its Open API at developers.ecocash.co.zw[EcoCash developer portal, checked 2026-11-05]. The same portal gives you a sandbox with simulated transactions, and you go live once your integration is certified[EcoCash developer portal, checked 2026-11-05].

That settles the first question for a builder. You can read the documentation, design your payment flow against test transactions, and treat go-live as a planned milestone rather than a favour you wait for.

This page covers what the portal gives you, the routes merchants use to accept EcoCash, and how to choose between them. For where EcoCash sits beside ZimSwitch, the card networks and the ZiG, start with payments in Zimbabwe for builders. The working code lives in the Paynow integration tutorial; this page is about the decision that comes before it.

What does the EcoCash developer portal give you?

Three things, and each one changes how you plan the work.

Documentation for the Open API. Before you write code, read it for three answers: how your server authenticates, how the outcome of a payment reaches you (a callback to your server, a status request from your server, or both), and which final statuses a payment can end in. Those three answers decide your data model, so get them first.

A sandbox. Simulated transactions in the sandbox[EcoCash developer portal, checked 2026-11-05] let you test without moving money. Spend that time on the unhappy paths: the customer who never confirms, the payment that fails, the callback that arrives twice, the callback that arrives after your checkout page has given up. A successful test payment proves very little on its own.

Certification before go-live. You go live once your integration is certified[EcoCash developer portal, checked 2026-11-05], so certification belongs in your project plan as a dated milestone with slack around it. Teams that leave it to the last week end up launching on someone else's calendar.

The portal is the primary source for everything technical. Where this page and the portal's documentation differ, follow the portal.

Which routes do merchants use to accept EcoCash?

There are two documented routes and one that depends on who you already work with. You can integrate EcoCash's own Open API, or you can integrate Paynow, an aggregator that lists EcoCash beside OneMoney, InnBucks, Omari, ZimSwitch and Visa/Mastercard in its express checkout[Paynow developer docs, checked 2026-11-04]. The third option is a payment partner that already has a Zimbabwean connection.

Routes for accepting EcoCash, compared
RouteWhat you build againstMethods from one integrationSuits
EcoCash Open API, directEcoCash's own Open API, tested in its sandbox and certified before go-liveEcoCash onlyProducts whose customers pay by EcoCash and teams that want the merchant relationship in their own name
PaynowPaynow's API, one integration for every method it carriesEcoCash, OneMoney, InnBucks, Omari, ZimSwitch and Visa/MastercardShops and platforms that want several wallets and cards without several certifications
A payment partner you already useThat partner's API, if it has a Zimbabwean connectionWhatever the partner has connected: ask for the list in writingRegional products that would rather add a country than add a provider

Last verified: 2026-11-04. Sources, checked 2026-11-04 to 2026-11-05: EcoCash developer portal, Paynow developer docs. Fees are left out: neither EcoCash nor Paynow pricing was confirmed against a primary source for this page.

The table hides one asymmetry. Going direct means you carry the certification, the monitoring and every future API change yourself, for one payment method. Going through Paynow means one integration covers several methods, but your coverage and your terms are Paynow's, and an outage on their side is an outage on yours.

If you would like a second opinion on which route fits your volumes and your team, Mctaba Labs payment integration does that scoping as the first step of a build.

How does an EcoCash payment move through your system?

Wallet payments are asynchronous. Your server asks for the money, the customer confirms on their side, and the result arrives later. Whichever route you pick, build for that shape from the first commit:

  1. Create the record first. Save a payment row with your own reference, the amount, the currency and an idempotency key, in a pending state, before you call any API.
  2. Show a waiting state. The checkout page says the payment is waiting for the customer. It never says paid until your server knows.
  3. Verify, store, then act. When the result arrives, check that it really came from your provider in the way its documentation specifies, store the raw message, and update the payment once. A duplicate message changes nothing.
  4. Ask about anything stuck. A job looks for payments still pending after your timeout and asks the provider for their status. It never charges again because a message did not come.
  5. Reconcile daily. A second job compares your records with the merchant statement and flags every difference for a person.

Step four is the one teams skip, and it is the one customers notice: the customer has paid, your system still says pending, and support has nothing to look at. Our guide to why a payment webhook needs checking, not trusting covers step three in depth, and moving a payment API from sandbox to production covers what changes on go-live day.

Should you go direct, use Paynow, or both?

Choose by what your customers pay with and how many integrations your team can look after.

  • Your customers pay by EcoCash and nothing else matters yet. Go direct. You get the merchant relationship in your own name, one less company between you and your money, and no aggregator margin to explain later. Budget for certification and for owning the integration over time.
  • You sell to a mix of wallet and card users. Use Paynow. One integration reaches EcoCash, OneMoney, InnBucks, Omari, ZimSwitch and Visa/Mastercard[Paynow developer docs, checked 2026-11-04], and you certify and maintain one connection instead of several.
  • You are a South African or regional product entering Zimbabwe. Start with Paynow to learn how your customers actually pay, then add a direct EcoCash integration if the numbers justify a second connection. Keep your payment layer provider-neutral so that move is a configuration change, not a rewrite.

The trade-offs are set out side by side in Paynow vs direct EcoCash vs aggregators, and the other wallets on Paynow's list are compared in Zimbabwe's challenger wallets.

What licensing and onboarding questions come up?

A merchant integration and a payments business are different things in law. The Reserve Bank of Zimbabwe regulates payment systems under the National Payment Systems Act[RBZ, checked 2026-11-05], and institutions that want to offer payment services apply to the RBZ for recognition, with a non-bank applying through a deposit-taking partner[RBZ, checked 2026-11-04]. If your product collects money on behalf of other businesses, settle the licensing question with a lawyer before you build the checkout.

Whichever route you take, ask the onboarding questions early, in writing:

  • Can a company registered outside Zimbabwe sign up, or do you need a local entity?
  • Which documents does onboarding need, and who reviews them?
  • Which currency will you be settled in, and into which kind of account?
  • How long do approval and certification usually take, and what makes them slower?

Foreign businesses have extra questions about where the money lands. Those are covered in accepting payments from Zimbabwe as a foreign business.

Which currency does each payment carry?

Never assume. The RBZ describes its move to a single currency as gradual and market-led, and several currencies stay in use meanwhile[RBZ Strategy Plan, checked 2026-11-05], so one merchant account can see payments in more than one currency over its life.

Three rules keep the books straight:

  • Store the currency on every payment record, next to the amount, and never infer it from the size of the number.
  • Reconcile each currency on its own; a total across currencies hides errors.
  • Show the customer the currency they will be charged in before they confirm on their side.

Zimbabwe also taxes electronic money transfers through IMTT, the Intermediated Money Transfer Tax, and the rate depends on the currency: the 2026 budget cut IMTT on ZiG-denominated transactions from 2% to 1.5% and kept it at 2% on foreign currency transactions[Citizens’ Budget 2026, checked 2026-11-04]. Model it in your fees using the rate in force when you launch, and confirm which of your flows it applies to; IMTT and transaction taxes in Zimbabwe covers how. Pricing in two currencies is its own design problem, set out in ZiG, USD and multi-currency pricing for apps.

What should you have ready before you integrate?

A short list that saves most of the rework:

  • A decision on the route, written down with the reason, so nobody reopens it in week three.
  • The onboarding answers above, in writing.
  • A payment state model: pending, paid, failed, expired, with the transitions your code allows.
  • An HTTPS endpoint for results, with verification and raw-message storage built before any business logic.
  • A test script for the sandbox covering success, failure, no response, duplicate results and late results.
  • A daily reconciliation report and a named person who reads it.
  • A support answer for the customer who says the money left their wallet but the order did not confirm.

If you are building for several countries, the same checklist applies to each new rail; payments in Southern Africa maps them country by country. And when you would rather have the EcoCash or Paynow side built, certified and reconciled for you, Mctaba Labs payment integration builds this kind of integration.

Frequently asked questions

Is there an official EcoCash developer portal?
Yes. EcoCash publishes its Open API on an official developer portal at developers.ecocash.co.zw, with a sandbox, and you go live once your integration is certified[EcoCash developer portal, checked 2026-11-05].
Should I integrate EcoCash directly or go through Paynow?
Go direct when EcoCash is the only method you need and you want the merchant relationship yourself. Use Paynow when you also want OneMoney, InnBucks, Omari, ZimSwitch or Visa/Mastercard[Paynow developer docs, checked 2026-11-04] from the same integration.
Can I test EcoCash payments without moving real money?
Yes. The portal offers a sandbox with simulated transactions[EcoCash developer portal, checked 2026-11-05]. Rehearse failures and late callbacks there as well as successful payments, because those are the cases that hurt in production.
When does an EcoCash integration need RBZ recognition?
When you offer payment services: such institutions apply to the RBZ for recognition, and a non-bank applies through a deposit-taking partner[RBZ, checked 2026-11-04]. Collecting money for other businesses can put you in that group, so take legal advice before you launch a marketplace.
Where do I find working code for a Paynow integration?
Paynow's developer documentation is at developers.paynow.co.zw[Paynow Developer Hub, checked 2026-11-04], and our Paynow integration tutorial works through it in Node.js and Python.

Need this integration built?

Mctaba Labs builds payment integrations across South Africa and the region: PayShap, pay by bank, card gateways, mobile money and cross-border payouts, with the webhooks and reconciliation that keep the money matching the books.

Talk to the payments team

Related guides