# API Reference

The **Mobile Money Collection API Reference** provides all the technical details you need to integrate with TemboPlus — including authentication, environments, supported channels, and standard response formats.

Use this reference as the foundation for all MOMO Collection endpoints.

***

### 🔐 Authentication

All MOMO Collection API requests require two headers for authentication:

* `x-account-id` — Your unique partner account identifier provided by TemboPlus.
* `x-secret-key` — Your API secret key used to authorize and sign each request.

Each request is authenticated by verifying these headers.\
Requests without valid credentials will return a `401 INVALID_CREDENTIALS` error.

{% hint style="danger" %}
For security, never share your secret key publicly or embed it in client-side code.
{% endhint %}

***

### 🧾 Required Request Headers

Each API request must include the following headers:

* `Content-Type`: `application/json`\
  Defines the request body format.
* `x-account-id`: Partner account identifier.\
  Used to identify the organization making the call.
* `x-secret-key`: Secret key assigned by TemboPlus.\
  Used for authentication.
* `x-request-id`: A unique UUID generated by you for every request.\
  Helps TemboPlus trace and support your transactions when needed.

Example:

```http
POST /collection HTTP/1.1
Content-Type: application/json
x-account-id: 6da81b2c
x-secret-key: a72f0e03c42e8b52
x-request-id: 734cc91d-4291-46cf-b96b-9f223d3c1be9
```

***

### 🌍 Environments

TemboPlus provides separate environments for **testing** and **production**.

#### Sandbox Environment

Used for testing and development.\
All transactions here are simulated and do not move real funds.

```
https://sandbox.temboplus.com/tembo/v1
```

#### Production Environment

Used for live transactions once integration is complete.

```
https://api.temboplus.com/tembo/v1
```

> You will receive unique credentials (`x-account-id`, `x-secret-key`) for each environment.

***

### 📡 Supported Channels

Each environment supports specific mobile money channels.

**Sandbox**

* `TZ-AIRTEL-C2B`
* `TZ-TIGO-C2B`

**Production**

* `TZ-AIRTEL-C2B`
* `TZ-TIGO-C2B`
* `TZ-HALOTEL-C2B`

***

### ⚠️ Common Error Responses

These standard error responses may apply to all MOMO Collection endpoints.

<details>

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

Returned when the request payload is missing required fields or has invalid data.

#### Response Format

```json
{
  "statusCode": 400,
  "reason": "VALIDATION_ERROR",
  "details": {
    "fieldName": "\"fieldName\" is required"
  },
  "message": "{\"fieldName\":\"\\\"fieldName\\\" is required\"}"
}
```

</details>

<details>

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

Returned when `x-account-id` or `x-secret-key` is incorrect or missing.

#### Response Format

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

</details>

<details>

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

Indicates a temporary issue with TemboPlus service.

#### Response Format

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

</details>
