The API does not expose a separate sandbox host. Tests and real integration traffic both go to the same endpoints, on the same domain (api.example.com). To make a test validation skip quota, billing, and webhooks, you use the playground flag in the request body.

How playground works

Both POST /v1/validate and POST /v1/validate-ocr accept an optional playground field in the body:

curl -X POST 'https://api.veriko.mx/v1/validate' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "fecha": "2025-03-15",
    "monto": 15000.50,
    "clave_rastreo": "MXBA20250315001234",
    "cuenta_beneficiaria": "012180004412345678",
    "playground": true
  }'

When playground=true:

• The request goes through the same input validation and the same Banxico pipeline as a normal validation — the results (valid, not_found, cep_unavailable, error) are real.
• The row is marked is_playground=1 in the database. It shows up in your listing with the corresponding badge and stays out of usage counts (/v1/usage) and invoices.
• Webhook events (validation.completed, validation.failed, validation.error) do not fire.
• Channel notifications (email/SMS/push) do not send.
• The response carries meta.playground: true so your client can detect it.

This lets you run smoke tests, CI integrations, and demos without polluting your production metrics or hammering your webhook receivers.

Reproducible test data

There are no hardcoded fixtures that return synthetic responses — Banxico answers what it sees. For deterministic scenarios:

• valid: use a real SPEI transfer of your own (you can find one in your banking app or statement). Any reference with an issued CEP works.
• not_found: change one digit of the amount or the clave_rastreo of a real transfer. Banxico returns "not found" deterministically.
• cep_unavailable: this state depends on Banxico's availability — it cannot be forced from the client.
• error: send a clave_rastreo with non-alphanumeric characters or a cuenta_beneficiaria with an invalid checksum to trigger 422 validation errors on our side.

For CLABEs or cards with a valid format but no real transfer attached, expect not_found — the bank is inferred from the prefix and the pipeline reaches Banxico.

Idempotency and retries

Requests with playground=true participate in the same idempotency and automatic retry flow as regular ones. But because they do not consume quota, they are cheap to reproduce — useful when you are writing tests for your async-response handler.

When NOT to use playground

Any validation you want to count as real (for auditing, reporting, or because the webhook receiver needs to know about it) must be sent without the flag — or with an explicit playground: false. The default is false.

If you are integrating webhooks, note that your subscribed endpoints will not receive events for playground validations. To test your webhook pipeline use the Test delivery button in the webhooks panel (which sends a signed test event using your secret) instead of the playground flag.