For an M-Pesa payment gateway, choose the operator and market before implementing the API. Vodacom Mozambique documents a customer-to-business route for websites and applications, with synchronous and asynchronous operation. Its developer guide describes account setup, authentication, sandbox requests and a separate go-live submission. These sources do not establish eligibility for a Zambian-registered merchant.
This guide follows that documented Mozambique route for an international reader. M-Pesa is not one interchangeable global integration contract: do not copy a Kenyan Daraja payload, another operator’s credentials or a remittance description into this implementation. The business must obtain its applicable merchant arrangement before accepting real payments.
Which M-Pesa API matches the payment you want to accept?
Vodacom Mozambique’s Open API explanation distinguishes customer-to-business collections from business-to-customer disbursements and business-to-business transfers. For an online sale, its C2B description is the relevant starting point. It names remote website, mobile-application and USSD purchases separately from payments at a physical establishment.
That distinction changes the question to ask the operator. Describe the real seller, operating market, customer journey and collection purpose. A system that pays beneficiaries is not automatically configured to collect an order payment. Likewise, an organisation’s ability to receive a transfer does not establish permission to operate an online merchant gateway.
The same official page identifies reversal requests and transaction-status queries as separate functions. A reversal is not a convenient replacement for checking an uncertain attempt, and a status query is not a new collection. Keep the purpose of each operation visible in the application’s design.
| Business task | Documented API category | Boundary to preserve |
|---|---|---|
| Customer pays for an online order | C2B | Actual merchant and operator conditions still apply |
| Organisation pays a beneficiary | B2C | Disbursement is different from accepting a sale |
| Businesses transfer between enterprise accounts | B2B | Not an ordinary consumer checkout |
| Investigate a payment’s reported state | Query Transaction Status | A query does not initiate another payment |
| Request a payment reversal | Reversal | Requesting a reversal is not proof it completed |
This is an original operation-selection map, not a claim that every operation is enabled on a particular account. The marketing page’s broader list and the developer guide’s list of exposed APIs differ in breadth. Confirm the actual available package instead of promising every advertised function.
How do you prepare the documented developer account?
The public developer documentation starts with registration. It describes an emailed activation link and a phone-number step when signing in. After activation, the account can access API documentation and testing. That is a developer-account process; the page does not establish every commercial or jurisdictional condition for a merchant.
The guide says the account profile contains an API key and public key. It also describes renewing the API key. Keep those materials in the authorised server configuration, outside a public repository, browser-delivered code and ordinary enquiry messages. A public key’s role is different from the secret API key’s role; publishing a sample is not a reason to reuse its values.
The guide offers Java and Python examples and an optional library to support communication and authentication. Its alternative without the library describes encrypting the API key with the public key and providing the resulting encoded value in the Authorization Bearer field. This is the documented route, not evidence that a different operator accepts the same header.
Do not reconstruct missing cryptographic details from this article. Obtain the actual account’s current API package, library guidance and supported implementation requirements. Test authentication through the authorised environment before connecting it to order fulfilment.
What must the request and response implementation preserve?
The developer guide separates context, request parameters and response output. Context includes the method and resource URL; the request parameters have descriptions, data types and required or optional indicators. Use the selected API’s actual schema. This public guide does not supply a complete unauthenticated C2B endpoint contract, so this article invents no endpoint, parameter name or customer-number format.
Keep the merchant order and payment attempt distinguishable in your own records. Before initiating a collection, retain which obligation the attempt concerns and what the application expects to reconcile. That is an original implementation requirement, not a claim about an undocumented provider field.
The guide says responses include a code and accompanying description whose meaning belongs to the relevant API’s table. An HTTP request completing is therefore insufficient to label the order paid. Inspect the documented business result and preserve an uncertain state when its meaning cannot yet be established.
Use a clearly marked sandbox request and retain a redacted record of its environment, operation, input reference and reported outcome. The guide’s sample-request control sends to a sandbox testing system. Nothing here reports a request executed by Spout, a customer wallet prompt or a real payment.
How does the asynchronous setting change the design?
The public guide says the APIs work synchronously by default. Registering an asynchronous response URL on the account page switches the APIs to asynchronous operation; clearing it restores synchronous operation. Treat this as an account-wide configuration decision described by this guide, not a harmless setting for one isolated page.
Its asynchronous endpoint requirements specify HTTPS and a permitted listening-port range of 11000–19000. These are documented technical conditions, not recommended public-server defaults. Have the authorised infrastructure operator establish the appropriate route. Do not disable TLS verification or expose unrelated services to make a callback appear to work.
A receiver needs a defined responsibility and an investigation path. Establish the applicable authenticity and retry rules from the actual API package; this public overview does not document them fully. The original checklist below keeps that gap separate from a successful local web response.
| Acceptance record | Evidence to obtain | Reason to stop |
|---|---|---|
| Market and merchant | Operator confirmation for the actual seller and collection purpose | A different country’s route is assumed |
| Account and package | Current enabled API, environment and schema | Only a marketing feature has been identified |
| Authentication | Redacted result using the documented account route | Sample credentials or an invented header are used |
| Response interpretation | Relevant API code/description table | Transport success is treated as payment success |
| Asynchronous configuration | Intended account mode and supported secure receiver | Changing one setting unexpectedly changes other calls |
| Reconciliation | Attempt linked to its order and checked outcome | A return page alone causes fulfilment |
| Exception handling | Named owner and investigation record | An unknown attempt triggers a blind repeat collection |
| Operational acceptance | Provider decision and separately tested application workflow | Sandbox activity is presented as production approval |
This checklist is an original acceptance artefact. It records requirements to demonstrate, not tests already passed.
What separates sandbox work from going live?
The developer guide describes reports filtered by date and API key, including earlier inactive keys. Preserve that context when investigating a test or a key rotation: changing credentials should not erase the meaning of the earlier transaction record.
Its go-live section says the account control submits the latest report and account details to Vodafone M-Pesa, allowing the operator to review the integration and advise whether it may go live. The article does not claim that this review occurred, guarantee approval or infer a timetable. Obtain the current commercial conditions separately.
For a Zambian business, keep the unresolved merchant-country question explicit. This Mozambique documentation is useful international implementation evidence, but it is not evidence of cross-border merchant eligibility. See Spout’s online payments service context and get started with the intended operator, market and unresolved workflow. Keep credentials and real customer transaction records private.
By Spout Team. AI-assisted drafting by Codex using the linked primary sources.