Testing and Sandbox

Test your iDenfy integration with dummy verification results in the sandbox environment before going live with real users and documents.

How to Test

iDenfy uses the same API URL for sandbox and production. Your API key determines which mode you’re in.

1. Get sandbox API keys

   Your sandbox keys are in Dashboard → Settings → API Keys.

2. Set up a webhook receiver

   Use one of these to inspect incoming webhooks:

   # Option 1: webhook.site (no setup)
   # Go to https://webhook.site — you get a unique URL immediately
   
   # Option 2: ngrok (tunnels to localhost)
   ngrok http 3000
   # Use the https URL it gives you
   

   Paste the URL in Dashboard → Settings → Webhooks.

3. Create a test session

   curl -X POST https://ivs.idenfy.com/api/v2/token \
     -u "SANDBOX_API_KEY:SANDBOX_API_SECRET" \
     -H "Content-Type: application/json" \
     -d '{"clientId": "test-001"}'
   
4. Run a dummy verification

   Use the Sample Verification feature in your Dashboard to generate mock results with predefined outcomes — no real documents needed.

---

Simulating Different Outcomes

Use Dummy Results to trigger specific verification statuses:

Outcome	What to test in your app
APPROVED	Happy path — user gets access
DENIED	Show rejection message, offer retry
SUSPECTED	Check fraudTags / mismatchTags, make a decision
EXPIRED	Token timed out — prompt re-verification

For AML screening, use AML Dummy Results to trigger sanctions/PEP matches.

---

Go-Live Checklist

Before switching to production keys:

• Webhooks — all statuses handled (APPROVED, DENIED, SUSPECTED, EXPIRED)
• Error handling — graceful responses for 400, 401, 403, 429, 500
• Token expiry — tested what happens when user returns after session expires
• Callback signing — HMAC verification implemented
• IP whitelisting — iDenfy IPs whitelisted on your webhook endpoint
• Data storage — scanRef stored in your database for each verification
• Production webhook URL — configured in Dashboard
• Production API keys — generated and stored securely (env vars, not code)

The most common go-live issue: webhook endpoint returns non-2xx. iDenfy retries, and in the meantime the user sees a “failed” redirect even though verification may have succeeded. Test your webhook endpoint thoroughly.