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

# POST /collections

> POST /collections: request a mobile money payment using your activated merchant account.

Request a mobile money payment from a payer using your activated merchant account. The request returns a pending status; the payer must authorise the request on their phone. Never report a successful payment from the initiation response.

```text theme={null}
POST https://masterid.me/api/public/v1/collections
```

## Prerequisites

Complete merchant setup and activation in the MasterID app before collecting payments. The Merchant ID alone does not activate collection. See the [Go-live checklist](https://docs.masterid.co.ug/guides/go-live-checklist.md).

## Authentication

**X-API-Key** `string` *required*

Your workspace API key.

**X-API-Secret** `string` *required*

Your workspace API secret.

**Content-Type** `string` *required*

Must be `application/json`.

**Idempotency-Key** `string` *required*

Unique request identifier, 8-100 characters: letters, digits, or `._:-`. Retry with the same key and identical body to avoid duplicates. See [Idempotency](https://docs.masterid.co.ug/concepts/idempotency.md).

## Request body

**merchantId** `string` *required*

Your Merchant ID. Must match the authenticated workspace's merchant account.

**payerName** `string` *required*

Payer's name. 2-120 characters.

**payerPhone** `string` *required*

Payer's phone number. Must be a supported Uganda mobile money number (MTN or Airtel).

**payerAddress** `string` *required*

Payer's address. 2-160 characters.

**amount** `integer` *required*

Amount in UGX. Minimum 10,000, maximum 20,000,000.

**reason** `string` *required*

Reason for the payment. 2-30 characters.

## Response fields

**id** `string` *required*

API request ID.

**data** `object`

**properties**

**paymentCode** `string` *required*

Payment code for the collection.

**reference** `string` *required*

Collection reference. Store this value to query status later.

**status** `string`

`pending` while awaiting payer authorisation.

## Status codes

| Status | Meaning |
| - | - |
| 200 | Request accepted. Collection is pending. |
| 400 | Invalid input or idempotency header. |
| 401 | Missing, invalid or revoked credentials. |
| 403 | Suspended account or Merchant ID mismatch. |
| 409 | Idempotency conflict. |
| 413 | Body too large. |
| 422 | Merchant activation or validation failed. |
| 429 | API request limit or payment rate limit reached. Check `Retry-After`. |
| 500/503 | Temporary processing error or unavailability. |

> [!WARNING]
>
> Never report a successful payment from the initiation response. It only confirms a pending collection request. Query [GET /collections/:reference](https://docs.masterid.co.ug/api-reference/collections/get-collection.md) or wait for `collection.completed` webhooks for final status.

> [!NOTE]
>
> Payment requests have additional rate limits: 40 per workspace per hour and 200 per day; 3 per phone per 15 minutes, 8 per phone per workspace per day, and 10 per phone across MasterID per day. These are internal limits, not a guarantee of throughput.

```bash cURL theme={null}
curl -X POST "https://masterid.me/api/public/v1/collections" \
  -H "X-API-Key: $MASTERID_API_KEY" \
  -H "X-API-Secret: $MASTERID_API_SECRET" \
  -H "Idempotency-Key: your-unique-request-id" \
  -H "Content-Type: application/json" \
  --data '{
    "merchantId": "<YOUR_MERCHANT_ID>",
    "payerName": "Amina K",
    "payerPhone": "2567XXXXXXXX",
    "payerAddress": "Kampala",
    "amount": 10000,
    "reason": "Invoice payment"
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  "https://masterid.me/api/public/v1/collections",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.MASTERID_API_KEY,
      "X-API-Secret": process.env.MASTERID_API_SECRET,
      "Idempotency-Key": "your-unique-request-id",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      merchantId: "<YOUR_MERCHANT_ID>",
      payerName: "Amina K",
      payerPhone: "2567XXXXXXXX",
      payerAddress: "Kampala",
      amount: 10000,
      reason: "Invoice payment",
    }),
  }
);
const body = await response.json();
console.log(body.data.reference);
```

```python Python theme={null}
import os, requests

r = requests.post(
    "https://masterid.me/api/public/v1/collections",
    headers={
        "X-API-Key": os.environ["MASTERID_API_KEY"],
        "X-API-Secret": os.environ["MASTERID_API_SECRET"],
        "Idempotency-Key": "your-unique-request-id",
        "Content-Type": "application/json",
    },
    json={
        "merchantId": "<YOUR_MERCHANT_ID>",
        "payerName": "Amina K",
        "payerPhone": "2567XXXXXXXX",
        "payerAddress": "Kampala",
        "amount": 10000,
        "reason": "Invoice payment",
    },
)
print(r.json()["data"]["reference"])
```

```json 200 theme={null}
{
  "id": "req_5f6g7h8i9j0k",
  "data": {
    "paymentCode": "PAY123456789",
    "reference": "COL987654321",
    "status": "pending"
  }
}
```


## Related topics

- [GET /collections/{reference}](https://docs.masterid.co.ug/api-reference/collections/get-collection.md)
- [API Overview](https://docs.masterid.co.ug/api-reference/overview.md)
- [Responses and status codes](https://docs.masterid.co.ug/concepts/responses.md)
- [Idempotency](https://docs.masterid.co.ug/concepts/idempotency.md)
- [Go-live checklist](https://docs.masterid.co.ug/guides/go-live-checklist.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.