- Start with a sandbox key and fixture verification payloads.
- Build consent status handling before result handling.
- Verify webhook signatures and retry behavior before production.
- Log correlation IDs and statuses, not raw identity secrets.
Overview
Sandbox first
Use fixture data to test request shape, errors, and callback handling before any live verification.
Purpose required
Every request needs a clear purpose string that matches the consent copy shown to the subject.
Consent-first flow
Do not trigger live checks until the subject has completed the guided consent step.
Signed webhooks
Validate signatures, timestamps, replay windows, and idempotency before trusting an event.
Production after review
Move to production only after PRAMAAN reviews purpose, consent, callback, and support paths.
No live PII in sandbox
Use test fixtures and masked values. Never paste Aadhaar, PAN, OTPs, or raw documents into examples.
Sandbox to production flow
- 1Create or request a sandbox key.
- 2Send a fixture verification request with a stated purpose.
- 3Capture consent-flow status and handle declined consent.
- 4Receive verification status updates.
- 5Validate signed webhook delivery.
- 6Request production access after consent and purpose are reviewed.
Create a sandbox verification
Use environment variables and fixture values. This example is intentionally not live personal data.
bash
Create a sandbox verification
curl -X POST "https://api.pramaan.online/v1/verify" \
-H "Authorization: Bearer $PRAMAAN_SANDBOX_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: demo-fixture-001" \
-d '{
"mode": "sandbox",
"purpose": "domestic-worker-onboarding-demo",
"subject": {
"fixture_id": "worker_fixture_green_001"
},
"callback_url": "https://example.com/webhooks/pramaan"
}'Webhook security checklist
- Validate the HMAC signature against the raw request body.
- Check the timestamp and reject stale events to reduce replay risk.
- Use the event ID and idempotency key to process each event once.
- Store the correlation ID for support without logging personal data.
- Retry safely and route exhausted callbacks to a dead-letter review queue if your stack supports one.
API readiness checklist
- Sandbox key issued and stored outside client-side code.
- Purpose string and consent copy approved by your product owner.
- Callback URL is HTTPS and monitored.
- Signature verification, idempotency, retry, and error handling are tested.
- Logs avoid raw PII and include a human review path for unclear results.
Frequently asked questions
Can I test without live personal data?›
Yes. Start with sandbox fixture data. Do not use real Aadhaar, PAN, OTPs, documents, or live personal data in sandbox payloads.
What is the minimum request shape?›
A sandbox request should include mode, purpose, fixture subject, callback URL, authorization, and an idempotency key.
What should I build first?›
Build consent status handling, then webhook verification, then result display. Treat a declined or incomplete consent as a normal product state.
How do signed webhooks work?›
PRAMAAN sends server-to-server events with a signature. Your system should verify the signature and timestamp before processing the event.
What should I log?›
Log event IDs, correlation IDs, status, timestamps, and error categories. Do not log raw identity documents or secret identifiers.
When can I request production access?›
Request production after sandbox flows, purpose copy, consent capture, callbacks, and support routing are working end to end.
Glossary terms
When to talk to a human
Use human handoff for production access, enterprise review, unclear callback behavior, or account-specific API questions.
Keep raw identity data out of chat
Do not paste Aadhaar, PAN, OTPs, raw documents, full passport numbers, or sensitive screenshots into chat or free-text support fields. Use guided verification, DSR, dashboard, or API flows instead.
Was this helpful?
Feedback helps PRAMAAN improve support answers without collecting raw identity data.
Move safely from answer to action
Use the route that matches the sensitivity of your case. Keep raw documents out of support messages unless a controlled workflow asks for them.