Most integration failures in production are not surprises. They are edge cases that were never tested in sandbox: a webhook that times out under load, a liveness check that fails on a lower-end device, a partial match result your error handler was not written to deal with.

All of these are testable before a single real user hits your flow. Most teams just never get around to testing them.

This guide walks you through how to test your identity verification integration on Dojah before going live, covering the core scenarios to confirm first and a pre-go-live checklist to confirm everything is ready for production.

Setting Up KYC Sandbox Access

Every Dojah account includes a sandbox environment by default. Sandbox mode uses simulated responses from Dojah's verification backends, so you can run the full verification flow without querying live government databases, consuming wallet credits, or touching real user data.

To switch between sandbox and production, toggle the environment selector in your Dojah dashboard. Sandbox and production use separate API keys. Make sure your integration is pointing at sandbox keys during testing and that you update to production keys before going live. Never use production keys during development.

Sandbox base URL: https://sandbox.dojah.io

Dojah provides sandbox test credentials for all supported ID types, including Nigerian BVN, NIN, Driver's Licence, Passport, and more. Find the full list at docs.dojah.io/api-reference/get-started/sandbox-test-data.

Use these values in your test requests to simulate successful verification responses. To test failure scenarios, use values that do not match the provided test credentials.

The Core Test Cases Every Integration Must Pass

Before testing edge cases, confirm that the basic integration works end to end for the most common user journey. These are the scenarios your integration must handle correctly before anything else.

Test 1: Successful verification end to end

Run a complete verification using the sandbox test credentials. Confirm that:

• The API request is correctly authenticated with your sandbox App ID and Secret Key
• The response returns the expected fields for that ID type
• Your application correctly reads and stores the verification result
• The user is routed to the correct next step after a successful result

If this test fails, the integration has a fundamental issue that needs resolving before any edge case testing is worth doing.

Test 2: Webhook delivery

Submit a verification and confirm that the result is delivered to your webhook endpoint. Check that:

• The webhook fires after the verification completes
• Your endpoint receives the payload and returns a 200 response
• Your backend correctly processes the result and updates the user's status
• The webhook signature is correctly verified on your end

A webhook that fires but returns an error, or a backend that receives the payload but fails to parse it correctly, will create silent failures in production where verifications complete but user statuses never update.

Test 3: Correct result handling across all possible outcomes

Verification results are not binary. A verification can return pass, pending, or fail, and each outcome needs a defined handler in your integration. Test each explicitly:

• Pass: user is approved and moved to the next step
• Pending: user is placed in a review queue and notified appropriately
• Fail: user is rejected with a clear reason and a defined recovery path

If your integration only handles the pass case, it will silently break on pending and fail results in production.

Edge Cases Worth Deliberately Triggering

Once the core scenarios pass, test the edge cases most likely to cause failures in production. These are the scenarios that appear infrequently enough during development that teams often skip them, and consistently enough in production that skipping them is a mistake.

• Partial match on name fields: Submit a verification using the correct test ID number but with a name that does not exactly match the test record. This is one of the most common real-world scenarios and one of the least tested. Confirm that your error handler distinguishes between a partial match and a complete fail since the appropriate response to each is different. 
   
• Failed liveness or face match: Submit a liveness check that does not meet the confidence threshold and confirm the failure is handled without breaking the overall flow. The user should see a clear retry option or a defined fallback path, and the failure should be visible in your dashboard. A liveness failure with no recovery path is one of the most common sources of user abandonment in production. 
• Invalid ID format: Submit a verification request with an ID number in the wrong format, for example a BVN with too few digits. Confirm that your integration handles the format validation error correctly rather than throwing an unhandled exception. This scenario appears regularly in production when users enter their ID numbers manually and make a typo.
• Timeout and database unavailability: Simulate a timeout by configuring a very short timeout on your HTTP client and submitting a verification request. Confirm that your integration handles the timeout gracefully, surfaces an appropriate message to the user, and retries or routes to a fallback without dropping the session.
• Multiple verification attempts by the same user: If your platform allows users to retry a failed verification, test what happens when the same user submits multiple attempts in a short window. Confirm that your integration handles this correctly and that your fraud rules, if configured, fire as expected when the threshold is reached.
• Webhook failure recovery: Intentionally cause your webhook endpoint to return a non-200 response and confirm that Dojah retries the delivery. Confirm that your system can handle a delayed webhook delivery without creating duplicate records or inconsistent user states.

Testing EasyOnboard Flows Specifically

If your integration uses EasyOnboard rather than or in addition to the direct API, there are additional scenarios to test before going live.

• Complete the flow as a user would: Generate your EasyOnboard link or embed your widget, then complete the full flow yourself using the sandbox test credentials. Check every screen the user sees, including error states, retry prompts, and the completion screen. What looks correct in the flow builder configuration does not always look correct in the actual user-facing flow.
• Test each fraud rule individually: If you have configured fraud rules in your EasyOnboard flow, test each one by deliberately triggering it. Submit a verification that should fire the liveness score rule, then one that should fire the face match rule, and confirm that each produces the correct action: pass, pending, or fail.
• Test the redirect URL: Complete a verification and confirm that the redirect URL fires correctly and sends the user to the right destination after completion. A broken redirect URL is one of the simplest and most avoidable production failures.
• Test webhook delivery from EasyOnboard: Complete an EasyOnboard verification and confirm that the webhook fires to your configured endpoint with the correct payload. Check that the payload structure matches what your backend expects.

The Pre-Go-Live Checklist

Work through this checklist before switching your integration to production. Every item should return a confirmed yes before the switch is made.

When every item on this list is checked, the integration is ready for production.

From Sandbox to Production: Going Live With Your KYC Flow 

Once every item on the checklist is confirmed, switch your environment from sandbox to production in the Dojah dashboard, update your environment variables to production API keys, and confirm your webhook endpoint is pointing at your production backend.

Watch the first batch of real verifications closely. Check that results are returning as expected, webhooks are firing and being processed correctly, and your dashboard reflects the activity you would expect. If something looks off, check the API status page and your webhook logs before touching the integration.

The integration is live. If you run into anything unexpected, the answers are usually in the docs.

Ready to start testing? Explore the Dojah docs for the full API reference and sandbox test data, or reach out to support if you need help along the way.

FAQs

1. Does sandbox testing cost anything?
No. Sandbox verifications do not consume wallet credits and do not query live government databases. You can run as many test verifications as needed without any cost.

2. Do sandbox and production use the same API keys?
No. Sandbox and production use separate API keys. Make sure your integration is using sandbox keys during testing and that you update to production keys before going live.

3. What happens if my webhook endpoint fails to return a 200 response?
Dojah retries webhook delivery when your endpoint returns a non-200 response. Test this scenario explicitly in sandbox to confirm your backend can handle a delayed or retried webhook delivery without creating duplicate records.

4. How do I test a failed verification in sandbox?
Submit a verification request using values that do not match the sandbox test credentials. Using an incorrect ID number or a mismatched name will return a not-found or mismatch result depending on the endpoint. Use this to test your failure and error handling paths.

5. Can I test EasyOnboard flows in sandbox?
Yes. EasyOnboard flows run in sandbox mode when your account is set to sandbox. Complete the full flow manually using the sandbox test credentials to test the user experience and confirm webhook delivery before switching to production.