Testing

Verifa’s sandbox environment lets you build and test your integration without processing real documents or incurring charges. Sandbox sessions return simulated results that you control.

Sandbox vs. production

Sandbox and production are fully isolated — separate API keys, separate webhooks, separate data. A sandbox key cannot access production resources and vice versa.

Creating sandbox sessions

Use a sandbox API key to create test sessions:

$
curl -X POST https://api.withverifa.com/api/v1/sessions \
>
  -H "X-API-Key: vk_sandbox_your_key_here" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "external_ref": "test_user_1",
>
    "country": "US"
>
  }'

The response includes "is_sandbox": true.

Controlling outcomes

Via the capture UI

When you open the capture_url for a sandbox session, the capture flow includes a final screen where you can select the outcome:

• Approve — Session completes with status approved
• Reject — Session completes with status rejected
• Needs Review — Session routes to the review queue

Via the API

Set the outcome programmatically:

$
curl -X POST https://api.withverifa.com/verify/{token}/sandbox-outcome \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "outcome": "approve"
>
  }'

Options: approve, reject, needs_review.

Simulated results

Sandbox sessions return realistic but simulated data:

1
{
2
  "session_id": "session_test123",
3
  "status": "approved",
4
  "is_sandbox": true,
5
  "face_match_passed": true,
6
  "face_match_score": 0.95,
7
  "age_check_passed": true,
8
  "extracted_age": 28,
9
  "extracted_data": {
10
    "first_name": "Jane",
11
    "last_name": "Doe",
12
    "date_of_birth": "1997-06-15",
13
    "document_type": "drivers_license"
14
  },
15
  "check_results": {
16
    "document_ocr": { "status": "passed" },
17
    "face_match": { "status": "passed", "score": 0.95 },
18
    "watchlist_screening": { "status": "passed", "hits": 0 },
19
    "risk_assessment": { "status": "passed", "risk_score": 5, "risk_level": "low" }
20
  }
21
}

Testing webhooks

Sandbox sessions fire webhooks to your sandbox webhook endpoints just like production. This lets you test your webhook handler end-to-end.

Send a test event

$
curl -X POST https://api.withverifa.com/api/v1/webhooks/endpoints/webhook_abc123/test \
>
  -H "X-API-Key: vk_sandbox_your_key_here"

Sandbox secret visibility

Sandbox webhook secrets are visible in API responses (similar to Stripe’s test mode). This makes it easier to set up and debug during development. Production secrets are only shown on creation and rotation.

Testing the review queue

Create demo review cases in sandbox:

$
curl -X POST https://api.withverifa.com/api/v1/cases/demo \
>
  -H "X-API-Key: vk_sandbox_your_key_here"

This creates a case with simulated session data, documents, and check results so you can test the review workflow. Maximum 3 demo cases per organization.

Testing specific check types

AML screening

Sandbox AML checks return simulated hits. Use specific names to trigger different outcomes:

• Any name — Returns clear (no matches)
• Use real session flow — Simulated hits based on sandbox outcome selection

List matching

Lists work identically in sandbox and production. Create test lists and items, then create sessions to verify matching behavior.

Fraud signals

Sandbox sessions include simulated fraud signal data. The risk score and triggered signals in the result are realistic examples, not derived from actual client-side collection.

Testing checklist

Before going live, verify:

• Session creation returns a valid capture_url
• Webhook endpoint receives events and verifies signatures correctly
• Your app handles session.approved, session.declined, and session.requires-review events
• Session result retrieval returns expected data structure
• Error handling works for expired sessions, rate limits, and auth errors
• Review queue integration works (if using manual review)
• Data redaction works (DELETE /api/v1/sessions/\{id\}/data)
• Idempotency keys prevent duplicate session creation

Switching to production

1. Create a production API key in the dashboard (prefix: vk_live_*)
2. Create a production webhook endpoint
3. Update your server configuration to use the production key
4. Create a test session in production to verify the full flow with real document processing

Related

• Quickstart — Create your first sandbox session
• Webhooks Guide — Configure and test webhooks
• Sessions — Full session lifecycle
• Errors — Handle error responses