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.

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.

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.

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

Show 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.

Never report a successful payment from the initiation response. It only confirms a pending collection request. Query GET /collections/:reference or wait for collection.completed webhooks for final status.

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.

cURL

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"
  }'

200

{
  "id": "req_5f6g7h8i9j0k",
  "data": {
    "paymentCode": "PAY123456789",
    "reference": "COL987654321",
    "status": "pending"
  }
}