> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.stakaba.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.stakaba.com/_mcp/server.

# Mobile Money Collections

Send a USSD payment prompt to a customer's phone. They approve with their PIN and the funds transfer instantly. Supports M-Pesa (Vodacom), Airtel Money, Mixx by Yas, and HaloPesa.

## How it works

1. Your server calls `POST /api/v1/payments/collection`
2. Stakaba sends a USSD prompt to the customer's phone
3. The customer enters their mobile money PIN to approve
4. Stakaba sends a webhook when payment is confirmed

## Collect a payment

```http
POST /api/v1/payments/collection
x-api-key: sk_live_...
Content-Type: application/json
```

```json
{
  "grossAmount": 5000,
  "currency": "TZS",
  "mobileNumber": "255742000331",
  "network": "Mpesa",
  "metadata": {
    "orderId": "ORD-2026-001"
  }
}
```

**Response:**

```json
{
  "internalReference": "M_X7Y8Z9W0"
}
```

The customer will receive a USSD prompt on their phone within seconds.

## Parameters

| Field          | Type    | Required | Description                                |
| -------------- | ------- | -------- | ------------------------------------------ |
| `grossAmount`  | integer | Yes      | Amount in TZS — **must be a whole number** |
| `currency`     | string  | No       | Always `TZS`                               |
| `mobileNumber` | string  | Yes      | Recipient number in `255XXXXXXXXX` format  |
| `network`      | string  | Yes      | See supported networks below               |
| `metadata`     | object  | No       | Your custom data, returned in webhooks     |

## Supported networks

| `network` value | Operator           |
| --------------- | ------------------ |
| `Mpesa`         | Vodacom M-Pesa     |
| `AirtelMoney`   | Airtel Money       |
| `TigoPesa`      | Mixx by Yas (Tigo) |
| `HaloPesa`      | HaloPesa           |

> **Warning**
>
> The `network` value is case-sensitive. Use exactly the values shown above.

## Amount requirements

`grossAmount` must be a **whole integer** — mobile money operators do not accept decimal amounts.

```json
{ "grossAmount": 5000 }   // ✓ correct
{ "grossAmount": 4999.50 }  // ✗ rejected
```

## Check payment status

```http
GET /api/v1/transactions/M_X7Y8Z9W0
x-api-key: sk_live_...
```

Or receive real-time updates via [webhook](/webhooks).