API Overview

Base URL, authentication, endpoint index, and fundamentals for the MasterID Public API v1.

The MasterID Public API v1 lets you submit identity verifications, check wallet balances, request mobile money collections, and receive event webhooks. Every request is authenticated, scoped to your workspace, and returns a consistent JSON envelope.

Base URL

https://masterid.me/api/public/v1

All requests require HTTPS. Unauthenticated browser visits return service information only. They never expose workspace data.

Authentication

Send your API credentials on every request using these headers.

X-API-Key · string · required

Your workspace API key, generated in the Developer Console.

X-API-Secret · string · required

Your workspace API secret, shown once when credentials are generated.

Content-Type · string · required

Must be application/json for requests with a body.

Keep credentials in your server’s secret store. Never include them in browser JavaScript, public repositories, URLs, analytics, or application logs. Secrets cannot be recovered after their first display is closed.

Your Merchant ID does not authenticate requests. It is used only for payment collections after merchant activation.

Endpoint index

Method	Endpoint	Description
GET	GET /catalog	List supported products, required fields, selections, and prices.
GET	GET /wallet	Read your workspace wallet balance.
POST	POST /verifications/consent	Request exact consent wording before submitting a verification.
POST	POST /verifications	Submit a verification with confirmed consent.
GET	GET /verifications/	Retrieve the status and result of a verification.
POST	POST /collections	Request a mobile money payment collection.
GET	GET /collections/	Read the status of a collection.

Response envelope

All authenticated responses are JSON and follow one of two envelopes.

Success

{
  "id": "<REQUEST_ID>",
  "data": { }
}

The id field is the API request ID. The data object contains endpoint-specific fields.

Error

{
  "id": "<REQUEST_ID>",
  "error": "Error description"
}

Errors may omit the id when the request cannot be processed. For details on handling errors, see Errors. For common HTTP status meanings, see Responses.

Status codes

Code	Meaning
200	Completed request.
202	Accepted or pending. The operation is in progress.
400	Invalid input, consent, or idempotency header.
401	Missing, invalid, or revoked credentials.
403	Suspended account or Merchant ID mismatch.
404	Unknown operation or resource outside your workspace.
409	Idempotency conflict.
413	Request body too large.
422	Insufficient funds, merchant activation required, or other validation failure.
429	API rate limit reached.
500 / 503	Temporary processing error or unavailability.

Rate limits

Your workspace is limited to 60 authenticated API requests per minute. When you receive a 429 response, wait for the Retry-After header before retrying.

Payment collections have additional limits:

• 40 per workspace per hour
• 200 per workspace per day
• 3 per phone number per 15 minutes
• 8 per phone number per workspace per day
• 10 per phone number across MasterID per day

These are MasterID limits, not a guarantee of throughput.

For idempotency behaviour and how to safely retry requests, see Idempotency. For webhook handling, see Webhooks.