> For the complete documentation index, see [llms.txt](https://tembo.gitbook.io/tembo/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tembo.gitbook.io/tembo/momo-collection-and-payout-api/api-reference/momo-collection/initiate-momo-collection.md).

# 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`**<mark style="color:red;">**\***</mark> — Must be `application/json`&#x20;
* **`x-account-id`**<mark style="color:red;">**\***</mark> — Your unique TemboPlus account identifier
* **`x-secret-key`**<mark style="color:red;">**\***</mark> — Your TemboPlus API secret key
* **`x-request-id`**<mark style="color:red;">**\***</mark> — Unique UUID per request for tracing

#### **Body Parameters**

* **`channel`**<mark style="color:red;">**\***</mark> *(string)* — The MNO channel to be used for the transaction. Supported values include:\
  `TZ-AIRTEL-C2B`, `TZ-TIGO-C2B`, `TZ-HALOTEL-C2B`, `KE-SAFARICOM-C2B`.
* **`msisdn`**<mark style="color:red;">**\***</mark> *(string)* — The customer’s mobile number in international format. Must start with `255` (for Tanzania) or `254` (for Kenya) followed by the subscriber number, e.g. `255712345678`.
* **`amount`**<mark style="color:red;">**\***</mark> *(number)* — The amount to be collected. The value must be an integer representing the total amount in shillings (decimals are not allowed).
* **`transactionRef`**<mark style="color:red;">**\***</mark> *(string)* — Your unique transaction reference for reconciliation.
* **`narration`**<mark style="color:red;">**\***</mark> *(string)* — A short description of the payment. This will appear in your statement.
* **`transactionDate`**<mark style="color:red;">**\***</mark> *(string)* — The timestamp of the request in ISO 8601 format, e.g. `2025-09-11T10:30:00Z`.
* **`callbackUrl`**<mark style="color:red;">**\***</mark> *(string)* — Your HTTPS endpoint where TemboPlus will send a POST notification once the payment status changes.

#### Example Request Payload

```json
{
    "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

<details>

<summary><code>200</code> OK</summary>

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

```json
{
  "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.

</details>

<details>

<summary><code>400</code> BAD REQUEST</summary>

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

#### **Response Format**

```json
{
  "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.

</details>

<details>

<summary><code>401</code> UNAUTHORIZED</summary>

Returned when authentication headers are missing or invalid.

#### Response Format:

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

</details>

<details>

<summary><code>500</code> INTERNAL SERVER ERROR</summary>

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

#### Response Format:

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

</details>

### 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:

```json
{
  "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.