Security
1
Protect credentials
Store your API key and API secret in a server-side secret store (for example, AWS Secrets Manager, GCP Secret Manager, or HashiCorp Vault). Never include them in browser JavaScript, public repositories, URLs, analytics, or application logs.
2
Rotate safely
If you regenerate credentials in the Developer Console, update every integration immediately. Old credentials stop working the moment regeneration completes.
3
Separate webhook secret
Store the webhook signing secret separately from API credentials. It cannot be used to authenticate API requests.
Consent
1
Obtain lawful authorisation
Confirm you have the data subject’s consent or other lawful basis before submitting any verification. The workspace account holder is responsible for this confirmation.
2
Use exact consent wording
Request the exact confirmation text with
POST /verifications/consent using the same fields you intend to submit. Present that wording for genuine confirmation and submit it verbatim. If the identity details change, request fresh wording.Verifications
1
Confirm catalog and fields
Call
GET /catalog to review the current product list, required fields, allowed selections, and prices. See Products for a full reference.2
Check wallet balance
Both matching and no-match verification results are charged. Call
GET /wallet before submitting checks to confirm sufficient funds.3
Store every session ID
Persist the
sessionId returned from POST /verifications. It is different from the API request ID and is required to retrieve results later.4
Handle pending states
A 202 response means processing is ongoing. Poll the saved session ID no more frequently than every 15 seconds, or wait for a webhook.
5
Handle failed checks
A status of
failed means no completed result was obtained and no charge is applied. Do not auto-retry a failed check without reviewing the cause.Collections
1
Activate merchant account
Complete merchant setup in the MasterID app before collecting payments. Generating API credentials does not grant collection rights.
2
Use your own Merchant ID
The
merchantId in a collection request must belong to the same workspace that issued the API credentials. A different Merchant ID is rejected with HTTP 403.3
Do not report success from initiation
A
POST /collections response only confirms a pending request. Wait for the final status via GET /collections/{reference} or the webhook before recording a completed payment.4
Respect phone-level limits
Collections have additional per-phone and per-workspace limits. See Rate limits for details.
Webhooks
1
Configure a public HTTPS URL
Add one webhook endpoint in the Developer Console. Redirects and private network destinations are not supported.
2
Verify signatures
Compute the HMAC SHA-256 of
timestamp + "." + rawBody using your signing secret. Compare the result in constant time with the X-MasterID-Signature header. Reject timestamps older than 5 minutes.3
Parse after verification
Parse the JSON payload only after the signature and timestamp have passed validation.
4
Deduplicate events
Delivery is at-least-once. Use
payload.id to ignore duplicates. Return any HTTP 2xx after accepting the event durably.Resilience
1
Use idempotency keys
Generate a unique
Idempotency-Key for every POST /verifications and POST /collections. Retry with the same key and identical body. See Idempotency.2
Back off after throttling
On HTTP 429, wait for the
Retry-After header. On 500/503, retry with exponential backoff and reuse the same idempotency key.3
Poll as a recovery path
If webhooks are unavailable, poll saved references on a schedule. Do not poll more frequently than every 15 seconds for verifications.
Data handling
1
Scope all reads to your workspace
Only records created in the issuing workspace are returned. Never attempt to access session IDs or references from another workspace.
2
Keep logs free of secrets
Redact API keys, API secrets, webhook signing secrets, and sensitive request fields from application logs and error reporters.
Support
If you need help during go-live, contact MasterID support:- Email: sales@masterid.co.ug
- Phone: +256 771 922 513