Initiate MOMO Collection

Use this endpoint to initiate a USSD push collection from a customer’s mobile wallet. The customer receives a USSD PIN prompt in their mobile device for authorization.

Endpoint

POST /collection

Request

Headers

• Content-Type* — Must be application/json

• x-account-id* — Your unique TemboPlus account identifier

• x-secret-key* — Your TemboPlus API secret key

• x-request-id* — Unique UUID per request for tracing

Body Parameters

• channel* (string) — The MNO channel to be used for the transaction. Supported values include: TZ-AIRTEL-C2B, TZ-TIGO-C2B, TZ-HALOTEL-C2B.

• msisdn* (string) — The customer’s mobile number in international format. Must start with 255 (for Tanzania) followed by the subscriber number, e.g. 255712345678.

• amount* (number) — The amount to be collected, in Tanzanian Shillings (TZS). The value must be an integer representing the total amount in shillings (decimals are not allowed).

• transactionRef* (string) — Your unique transaction reference for reconciliation.

• narration* (string) — A short description of the payment. This will appear in your statement.

• transactionDate* (string) — The timestamp of the request in ISO 8601 format, e.g. 2025-09-11T10:30:00Z.

• callbackUrl* (string) — Your HTTPS endpoint where TemboPlus will send a POST notification once the payment status changes.

Matching msisdn to channel

The msisdn must belong to the same Mobile Network Operator (MNO) specified in the channel field.

Examples:

• Use TZ-AIRTEL-C2B for numbers starting with Airtel prefixes (e.g. 068x, 078x).

• Use TZ-TIGO-C2B for Tigo prefixes (e.g. 065x, 071x).

• Use TZ-HALOTEL-C2B for Halotel prefixes (e.g. 062x).

Tanzania does not implement Mobile Number Portability (MNP), so mobile numbers remain tied to their original operator prefixes.

For precise validation, request the MNO Prefix Reference Document from TemboPlus Support for the current mapping of prefixes to channels.

Collection Limits

TemboPlus enforces transaction amount limits for all Mobile Money Collection requests.

• Minimum: TZS 1,000 • Maximum: TZS 5,000,000

Example Request Payload

{
    "channel": "TZ-TIGO-C2B",
    "msisdn": "255712345678",
    "amount": 1000,
    "transactionRef": "order-2025-001",
    "narration": "Payment for Order #001",
    "transactionDate": "2025-09-11T10:30:00Z",
    "callbackUrl": "https://merchant.example.com/webhook"
}

Responses

200 OK

If the request is valid and the USSD prompt is successfully initiated, TemboPlus responds with:

{
  "statusCode": "PENDING_ACK",
  "transactionId": "gm56e6CmzwyD", // sample value; will differ per request
  "transactionRef": "order-2025-001" // sample reference from your system
}

Response Fields:

• statusCode — Indicates the current state of the collection request. Possible values include PENDING_ACK, PAYMENT_REJECTED, GENERIC_FAILURE, INSUFFICIENT_FUNDS and PROVIDER_FAILED.

• transactionId — A unique identifier for this transaction, generated by TemboPlus.

• transactionRef — Echo of your original transaction reference.

400 BAD REQUEST

Returned when the request payload is missing one or more required fields, or when any field contains invalid data.

Response Format

{
  "statusCode": 400,
  "reason": "VALIDATION_ERROR",
  "details": {
    "msisdn": "\"msisdn\" is required"
  },
  "message": "{\"msisdn\":\"\\\"msisdn\\\" is required\"}"
}

Fields inside details and message are optional and vary depending on the specific validation failure.

---

Common Validation Errors to Avoid

• Ensure all required fields are included in the request body.

• amount must be an integer (whole number) — decimals are not allowed.

• msisdn must be in the correct international format, beginning with 255.

• Use only supported channel codes that correspond to valid MNO integrations.

• x-request-id must be included in the request headers.

401 UNAUTHORIZED

Returned when authentication headers are missing or invalid.

Response Format:

{
    "statusCode": 401,
    "reason": "INVALID_CREDENTIALS",
    "details": {}
}

500 INTERNAL SERVER ERROR

Indicates a temporary issue within TemboPlus. Retry later or contact TemboPlus Support with your x-request-id.

Response Format:

{
    "statusCode": 500,
    "reason": "SERVER_ERROR"
}

Webhook Notification

After the customer responds to the USSD prompt, TemboPlus sends a POST request to your configured callbackUrl with the final transaction outcome. The webhook body contains the same identifiers returned in the initial response, along with an updated statusCode value. Possible values for statusCode include PAYMENT_ACCEPTED, PAYMENT_REJECTED, PROVIDER_FAILED, INSUFFICIENT_FUNDS, and GENERIC_FAILURE.

Example:

{
  "statusCode": "PAYMENT_ACCEPTED",
  "transactionId": "gm56e6CmzwyD",
  "transactionRef": "order-2025-001"
}

Values above are examples only; actual transactionId and transactionRef will vary per request.

---

Webhook Delivery Notes

• TemboPlus will make a POST request to your callbackUrl immediately after receiving the final response from the MNO.

• Each webhook contains a JSON payload with statusCode, transactionId and transactionRef.

• Webhook delivery is asynchronous; the callback may arrive a few seconds after the initial API response.

• Always validate both transactionId and transactionRef before updating your internal records.

• Your endpoint should return an HTTP 200 OK response upon successful receipt to acknowledge the notification.