> ## Documentation Index
> Fetch the complete documentation index at: https://docs.masterid.co.ug/llms.txt
> Use this file to discover all available pages before exploring further.

# Go-live checklist

> A complete checklist to prepare your MasterID integration for production, covering security, consent, verifications, collections, webhooks, resilience, and data handling.

Before you process real data in production, walk through this checklist to confirm your integration is secure, compliant, and resilient.

## 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](https://docs.masterid.co.ug/products.md) 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](https://docs.masterid.co.ug/concepts/rate-limits.md) 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.

For implementation details, see [Webhooks](https://docs.masterid.co.ug/guides/webhooks.md).

## 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](https://docs.masterid.co.ug/concepts/idempotency.md).

**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](mailto:sales@masterid.co.ug)
* Phone: +256 771 922 513


## Related topics

- [POST /collections](https://docs.masterid.co.ug/api-reference/collections/create-collection.md)
- [MasterID Integration API](https://docs.masterid.co.ug/index.md)
- [Receive webhooks](https://docs.masterid.co.ug/guides/webhooks.md)
- [Products and fields](https://docs.masterid.co.ug/products.md)
- [Quickstart](https://docs.masterid.co.ug/quickstart.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.