Playground and testing

The API offers no test host, no test keys and no simulation mode in the request. Tests and real integration traffic reach the same endpoints, on the same domain (api.veriko.mx), with the same key. Every admitted call to POST /v1/validate or POST /v1/validate-ocr consumes quota the moment it is admitted, fires webhooks and shows up in GET /v1/usage/summary.

Simulation does exist, but it lives in the console and not in the request body: it is the playground, described below.

What consumes quota and what does not

Quota is consumed when the operation is admitted — after the body is validated and before the work against Banxico — and it is returned when the outcome is not attributable to the caller. An admitted attempt is charged except in these cases:

• A rejected body. A request whose body fails validation and answers 422 consumes no quota. In synchronous POST /v1/validate-ocr the file is checked after the request is admitted, so an invalid file is charged.
• A replayed idempotency key. Repeating an Idempotency-Key with the same body replays the stored response without re-entering the endpoint, so it is not charged twice. See idempotency.
• A platform failure. A validation that ends in error because Banxico does not answer, or because the provider that extracts the data from the image fails, returns the quota it consumed.
• An account that could not be resolved, in direct validation. The cuenta_unresolvable family — the data carries nothing that identifies the beneficiary account, or what it carries matches several — returns the quota, except with cuentas_candidatas: if none matches, the query already reached Banxico and is charged.
• A payment that admits no validation, in direct validation. A transfer inside the same bank issues no CEP (intra_bank_no_cep): it does not reach Banxico, and the quota is returned.
• Automatic retries. They belong to the validation that already consumed the quota. See retry policy.

A not_found is charged just like a valid: learning that a payment does not exist is a result, not a failure.

When the validation starts from a receipt, whatever happens after reading it is charged too: an unreadable image (image_not_readable_receipt) or one that is not a SPEI receipt (image_not_spei_receipt), a PDF with more than one receipt (pdf_multiple_receipts), an account that could not be resolved, or a transfer inside the same bank. The caller chose the receipt, and reading it already had a cost.

None of this is a test mode — the first call that reaches Banxico is charged — but all of it makes iterating on a failing test cheap. The cycle and the usage headers are detailed in quotas and plans.

Where a call runs without effects

In the console playground: the tab of that name inside the API section. The call is not made from the browser: the console sends it to the server, which runs it with the open session's credentials, so the key never appears in the browser or in the response.

By default those calls are real in every sense: they consume quota, produce effects and show up in the history. Operations that carry simulation scenarios also offer a playground mode: with it on, the operation runs its real pipeline with the Banxico step replaced by a prepared response, inside a transaction that is always rolled back — nothing is metered, no webhook is delivered, no notification is sent and no row survives. See playground.

The playground requires an open console session, and it is not an access layer: an integration calls the operation directly with its own key.

To exercise a webhook receiver without producing validations, POST /v1/webhooks/{id}/test sends a signed synthetic delivery to the subscribed endpoint, using that endpoint's secret.

Reproducible test data

Over the API there is no synthetic data returning a prepared response: Banxico answers what it sees. For deterministic scenarios:

• valid — a real SPEI transfer of the account. Any reference with an issued CEP works.
• not_found — one changed digit in the amount or in the clave_rastreo of a real transfer. Banxico answers not-found deterministically.
• cep_unavailable — depends on Banxico's availability, and cannot be forced from the client.
• 422 — a clave_rastreo with characters outside the allowed set, or a cuenta_beneficiaria with a bad checksum. The request is rejected before reaching Banxico, so it costs nothing.

A CLABE or a card with a valid format but no transfer behind it answers not_found: the institution is inferred from the prefix or the BIN, and the pipeline still reaches Banxico.

The terminal statuses are valid, not_found, cep_unavailable, invalid, returned, failed and error. An asynchronous request reaches one of them through polling or a webhook, as asynchronous validations describes.