> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usebila.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Collections

> Initiate and track mobile money collections in the sandbox.

## Initiate a Collection

```bash theme={null}
POST /api/v1/bila/collections/mobile-money
```

| Parameter      | Type   | Required | Description                          |
| -------------- | ------ | -------- | ------------------------------------ |
| `amount`       | number | Yes      | Minimum `0.01`                       |
| `reference`    | string | Yes      | Unique — pattern `^[a-zA-Z0-9._-]+$` |
| `phone`        | string | Yes      | Customer's mobile money number       |
| `operator`     | string | Yes      | `mtn`, `airtel`, or `zamtel`         |
| `country`      | string | Yes      | `zm`                                 |
| `walletId`     | string | Yes      | Your sandbox wallet ID (UUID)        |
| `bearer`       | string | No       | `merchant` (default) or `customer`   |
| `narration`    | string | No       | Max 100 characters                   |
| `customerName` | string | No       | Max 100 characters                   |

**Example:**

```bash theme={null}
curl --request POST \
  --url https://sandbox.usebila.com/api/v1/bila/collections/mobile-money \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: sk_test_your_api_key_here' \
  --data '{
    "amount": 150.00,
    "reference": "INV-2026-001",
    "phone": "0966123456",
    "operator": "mtn",
    "country": "zm",
    "walletId": "68f11209-451f-4a15-bfcd-d916eb8b09f4",
    "narration": "Payment for April invoice",
    "customerName": "John Banda"
  }'
```

**Response:**

```json theme={null}
{
  "status": true,
  "message": "Operation completed successfully",
  "data": {
    "id": "col-uuid",
    "reference": "INV-2026-001",
    "status": "successful",
    "amount": 150.00,
    "currency": "ZMW",
    "customer": {
      "phone": "0966123456",
      "name": "John Banda",
      "operator": "mtn"
    },
    "createdAt": "2026-05-05T10:30:00Z"
  }
}
```

***

## Check Collection Status

```bash theme={null}
curl --request GET \
  --url https://sandbox.usebila.com/api/v1/bila/collections/status/INV-2026-001 \
  --header 'x-api-key: sk_test_your_api_key_here'
```

| Status       | Meaning                  |
| ------------ | ------------------------ |
| `pending`    | Awaiting final outcome   |
| `successful` | Funds credited to wallet |
| `failed`     | Transaction failed       |

***

## Pre-Launch Checklist

* Successful collection returns `"status": "successful"`
* Reference with `fail` returns `"status": "failed"`
* Duplicate reference returns `409`
* Status polling transitions correctly from `pending`