> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withverifa.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withverifa.com/_mcp/server.

# Testing

> Test your integration with sandbox sessions, simulated outcomes, and test data.

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               | Production                 |
| ------------------- | --------------------- | -------------------------- |
| API key prefix      | `vk_sandbox_*`        | `vk_live_*`                |
| Document processing | Simulated             | Real OCR, face match, etc. |
| Billing             | Free                  | Per-session pricing        |
| Webhooks            | Delivered normally    | Delivered normally         |
| Data isolation      | Separate from live    | Separate from sandbox      |
| Feature access      | All features unlocked | Plan-gated                 |

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:

```bash
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:

```bash
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:

```json
{
  "session_id": "session_test123",
  "status": "approved",
  "is_sandbox": true,
  "face_match_passed": true,
  "face_match_score": 0.95,
  "age_check_passed": true,
  "extracted_age": 28,
  "extracted_data": {
    "first_name": "Jane",
    "last_name": "Doe",
    "date_of_birth": "1997-06-15",
    "document_type": "drivers_license"
  },
  "check_results": {
    "document_ocr": { "status": "passed" },
    "face_match": { "status": "passed", "score": 0.95 },
    "watchlist_screening": { "status": "passed", "hits": 0 },
    "risk_assessment": { "status": "passed", "risk_score": 5, "risk_level": "low" }
  }
}
```

## 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

```bash
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:

```bash
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](/getting-started/quickstart) — Create your first sandbox session
* [Webhooks Guide](/integration-guides/webhooks-guide) — Configure and test webhooks
* [Sessions](/core-concepts/sessions) — Full session lifecycle
* [Errors](/api-details/errors) — Handle error responses