Skip to main content
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

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.
​
string
required
Your workspace API key, generated in the Developer Console.
​
string
required
Your workspace API secret, shown once when credentials are generated.
​
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

​
Response envelope

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

​
Success

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

​
Error

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

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