MOMO Collection Flow

The TemboPlus Mobile Money (MOMO) Collection APIs integrate with multiple Mobile Network Operators (MNOs) in Tanzania to initiate and track customer payments via USSD. While each MNO operates independently, TemboPlus provides a unified experience by normalizing all responses and status codes into a consistent set of outcomes.

This page explains the general flow, transaction states, and practical notes that partners should consider when integrating with TemboPlus MOMO collection APIs in Tanzania.

Overview

When you initiate a collection request, TemboPlus connects with the appropriate MNO to deliver a USSD prompt to the customer. The customer then authorizes or rejects the payment, and TemboPlus updates the transaction status asynchronously (via the webhook callback).

Because different MNOs process requests differently, the same status may appear either in the immediate response or later in the webhook. Partners should always handle both.

---

Common Transaction States

TemboPlus standardizes the following statusCode values across all MNO integrations:

• PENDING_ACK — The request was accepted by TemboPlus and forwarded to the MNO. The customer has been prompted via USSD to authorize the payment.

• PAYMENT_ACCEPTED — The customer authorized the transaction successfully; funds were transferred to your collection wallet.

• PAYMENT_REJECTED — The customer entered an invalid PIN, or the MNO could not complete the transaction due to a temporary service issue.

• INSUFFICIENT_FUNDS — The customer’s wallet does not have enough balance to complete the transfer.

• PROVIDER_FAILED — The MNO rejected the request due to provider-side validation rules. This typically occurs when the MSISDN does not match the selected channel, the amount is not a valid integer, or other input validations failures at the provider level.

• GENERIC_FAILURE — The transaction failed due to temporary network or account conditions, such as an active USSD session, a barred mobile number, or other transient MNO issues.

---

Behaviour Notes

• Session Duration: The USSD authorization window typically lasts about 15 seconds, but this can vary by MNO. If no response is received, the transaction may remain in PENDING_ACK. TemboPlus plans to automatically flag such transactions as SESSION_EXPIRED in a future release.

• Timing of Updates: Depending on the MNO’s internal design, a status such as INSUFFICIENT_FUNDS, PROVIDER_FAILED, GENERIC_FAILURE or PAYMENT_REJECTED may appear either:

  • Immediately in the API response, or

  • Later via the webhook callback.

  Implementations should process both sources.

• Environment Differences: The sandbox environment simulates transactions only and does not trigger real USSD prompts. The live environment performs actual mobile money collections with the connected MNO.

---

Best Practices for Implementors

• Always record and reconcile both the API response and callback notification for each transactionRef.

• Treat transactions that remain in PENDING_ACK beyond 30 seconds as likely expired.

• Use the Transaction Status endpoint to poll for updates if your webhook is unavailable.

• Never rely on exact timing or order of status changes; behaviour may vary across MNOs.

---

Future Enhancements

TemboPlus continues to harmonize behaviour across MNOs. Planned improvements include automatic session expiry handling (SESSION_EXPIRED) and additional consistency guarantees for synchronous versus asynchronous status reporting.