POST /collections

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

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);

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"])

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

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

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);

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"])

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

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

string

required

Your workspace API key.

string

required

Your workspace API secret.

string

required

Must be application/json.

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

string

required

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

string

required

Payer’s name. 2-120 characters.

string

required

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

string

required

Payer’s address. 2-160 characters.

integer

required

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

string

required

Reason for the payment. 2-30 characters.

Response fields

string

required

API request ID.

object

Show properties

string

required

Payment code for the collection.

string

required

Collection reference. Store this value to query status later.

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

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);

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"])

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

Overview

Catalog and wallet

Verifications

Collections

Webhooks

Prerequisites

Authentication

Request body

Response fields

Status codes

​Prerequisites

​Authentication

​Request body

​Response fields

​Status codes

Prerequisites

Authentication

Request body

Response fields

Status codes