Test mode

Test mode lets you create sessions, force terminal outcomes, and exercise webhook handling without using prepaid credit.

Test keys

Keys beginning with agvf_test_ create test sessions. Use them with the same endpoint and X-API-Key header as live keys:

curl https://api.agerail.com/api/v1/sessions/create \
  --request POST \
  --header "Content-Type: application/json" \
  --header "X-API-Key: agvf_test_your_key" \
  --data '{
    "target_age": 18
  }'

Test keys use the same callback enforcement as live keys. Before creating test sessions, register your sandbox Success URL, Cancel URL, and Webhook URL in the tenant dashboard's Settings screen. For optional per-request success_url and cancel_url values, the path and query may vary; their lowercased host and port must match a registered callback URL. There is no test-mode exemption for unregistered hosts or the removed webhook_url request field.

The key mode is copied to the session when it is created.

Force an outcome

For a test session, append ?force=<outcome> to the returned verification_url:

{verification_url}?force=verified

Supported values are:

force value	Result status
verified	VERIFIED
fallback	ROUTED_TO_FALLBACK
spoof	SPOOF_DETECTED

Treat force as test-only. In production, using it with a live session is rejected with HTTP 400; the gateway fails closed instead of forcing the result.

Distinguish test and live events

Webhook payloads include a boolean livemode field:

• false for traffic created with a test key
• true for traffic created with a live key

Always trust the webhook's livemode field when separating test processing from live processing. Do not infer the mode from a browser URL or redirect parameter.

Test optional estimated age visibility

By default, the verification response, webhook, and redirect contain only the signed result and its status, and no estimated age. If your tenant enables estimated age visibility, a test-key integration can use the same separate GET /api/v1/sessions/{session_id}/detected-age operation as live mode, only for sessions whose shoppers accepted the visibility disclosure. The estimate is stored only for those consented sessions and is deleted when its session record is deleted; session records currently have no fixed automatic deletion period.

Force the outcome through the hosted flow, verify its completion webhook, then call the estimate operation with the test X-API-Key. The operation returns not_consented, pending, not_estimated, or available; the webhook itself never contains detected_age.

Test verifications use 0 billing units and do not debit prepaid credit. See the verification flow and the webhook guide.