An MTN MoMo collection needs 3 separate observations: the request was accepted for processing, the customer reached a decision and the transaction has a final status. HTTP 202 Accepted is not proof of payment. Keep the merchant order linked to the payment reference until the documented status mechanism establishes what happened.
MTN’s official API use-case documentation describes this asynchronous flow. It supports a technical design and test plan, not a claim that a Zambian merchant has been approved for production or that every API product is available under the same conditions. No account was provisioned and no payment was initiated for this article.
How should the collection move from request to final status?
Start with an order the merchant system can identify. The customer selects a mobile-money payment route, and the provider system prepares the relevant request. Retain a stable order reference before initiating payment. A support operator should be able to identify the attempted collection without asking the customer to repeat a financial action.
MTN describes Request to Pay as requesting a payment from a payer who must approve it through their own client. The provider sends the request to the wallet platform, which responds with HTTP 202 Accepted. The documentation then describes the request as pending until the customer approves or rejects it. These states should remain distinct in your website and internal record.
Tell the customer what is actually happening. The documented flow says the merchant should explain that approval is needed through the customer’s own client. Do not display “paid” just because the first API call returned successfully. Equally, do not declare failure merely because the customer has not yet returned to the website.
The provider’s record should connect the attempted collection to its eventual result. MTN documents final states such as SUCCESSFUL and FAILED. Your application should retain the returned status and its relationship to the order, with any unresolved state visible. Avoid replacing the original attempt with another reference whenever a browser refreshes.
Callbacks are one notification route. The use-case guide says a callback can be sent when the request reaches a final state if a callback URL was provided. It also says the callback is sent once, without retry. A design that depends on every notification arriving therefore needs a recovery path for an event that is missed.
The same documentation describes a GET request for checking transaction status when a callback was not requested or received. Build that distinction into the integration brief. The callback and the status check are related evidence routes; neither should be confused with a customer screenshot or a browser redirect.
Use this original state map to discuss what the merchant system must retain. The state names in the first column are explanatory groupings, with the documented provider statuses noted where applicable.
| Merchant observation | Evidence | Safe operational meaning |
|---|---|---|
| Request prepared | Order reference and intended transaction | No payment initiated yet |
| Request accepted | HTTP 202 and related request reference | Processing accepted, not payment confirmed |
| Customer decision pending | Provider status still pending | Outcome remains unresolved |
| Final result received | Relevant callback or checked status | Apply the documented SUCCESSFUL or FAILED result |
| Callback absent | Missing event and retained reference | Obtain the status through the supported route |
| Record disagreement | Order and provider evidence do not align | Investigate before another financial action |
Which tests expose collection and callback failures?
Use the authorised sandbox and its current instructions, keeping test and production environments separate. The opened MTN documentation distinguishes sandbox examples from production values shared through onboarding. Do not copy a sample environment, payment value or account identifier into a live integration and assume it represents the approved Zambia arrangement.
Document the proposed production product and merchant conditions separately. Ask the onboarding contact which operation, environment, account and enabled capabilities apply to your business. A successful generic API sample establishes something about that sample, not universal production eligibility. Keep unresolved country or product questions visible in the scope.
Test a customer approval and a customer rejection. Record the initial request result, the intermediate state and the final observed status. The order’s paid state should depend on the relevant confirmed result, not on whether the customer visited a particular page. Keep test records distinguishable from real customer orders.
Test a delayed or missing callback in a controlled environment. Demonstrate how the transaction reference is retained and how the supported status request resolves the uncertainty. Do not invent a universal polling interval or a guaranteed completion time. The useful acceptance criterion is that staff can identify and investigate the unresolved attempt without guessing.
Test a repeated browser action and an event replay. Define what should happen when the same order is revisited or a notification is processed again. The proposed implementation should avoid creating another obligation or applying the same result twice. This is a design requirement to prove, not a claim that the documented API supplies your application’s duplicate-handling logic automatically.
Include a mismatch scenario in the test plan. If the application cannot connect an event to a known payment attempt, preserve it as an exception rather than attaching it to a convenient open order. Any validation and authentication method must follow the actual provider documentation and approved configuration; this guide does not invent a webhook-signature scheme.
Keep credentials and tokens restricted to the intended server-side implementation. A public website brief can name the custodian and environment without containing secrets. The operator receiving a support ticket should use the order and payment references, not ask a customer to supply a wallet PIN or reproduce an approval screen containing private information.
Reconcile the final payment record with the business obligation. A successful collection is one state; later refund, settlement and accounting treatment are separate workflows that require their own evidence. Do not turn the collection status into a bank-settlement guarantee or imply that a technical callback resolves every financial record automatically.
See Spout’s online payments page for related website requirements. Get started with the state map and the exception you need to handle. Keep merchant keys, payer details and live transaction records outside the initial enquiry, and retain unverified production conditions as open questions.
By Spout Team. AI-assisted drafting by Codex, grounded in the linked primary documentation.