Ciclo de una verificación

Una verificación nace pendiente y siempre termina sola en un estado final. No hay que cerrarla ni cancelarla.

De pendiente a un estado final

Toda verificación empieza en pending y termina exactamente una vez. Nadie tiene que cerrarla: si el usuario nunca escribe el código, vence sola al llegar a expires_at.

Estado	Qué significa	Final	Se factura
`pending`	Activa, esperando el código.	No	No
`approved`	El usuario escribió el código correcto.	Sí	Sí, solo con clave `live_`
`expired`	Venció sin una comprobación correcta.	Sí	No
`max_attempts_reached`	Se agotaron los intentos.	Sí	No
`failed`	Todos los canales de la cascada fallaron de forma definitiva.	Sí	No

Solo approved se factura. Un código que no llegó, un usuario que no terminó o un intento bloqueado no te cuestan nada.

📘
Nota
El contrato reserva además canceled y blocked, pero hoy ninguna verificación llega a ellos: no hay cancelación por API y los bloqueos antifraude rechazan la petición antes de crear la verificación.

Cómo avanza

Crear (POST /v1/verifications): nace en pending y empieza la cascada de canales.
Comprobar (POST /v1/verifications/{id}/check):
- código correcto → approved;
- incorrecto con intentos → sigue pending, con un intento menos;
- incorrecto en el último intento → max_attempts_reached.
Vencer: al llegar a expires_at sin aprobación, pasa a expired. Una comprobación en ese momento o después responde 409 con 30002, igual que cualquier comprobación sobre una verificación que ya terminó.
Fallar: si cada canal de la cascada falla de forma definitiva antes de vencer, pasa a failed. Si un canal aceptó el mensaje pero no sabemos si llegó, o un envío de correo fue incierto, la verificación sigue pending hasta vencer.

Parámetros que controlan el ciclo

Cada aplicación tiene su política. Puedes sobrescribirla por petición al crear la verificación:

Campo	Rango	Error si está fuera de rango
`expires_in`	60–1800 segundos	`20007`
`code_length`	4–10 caracteres	`20009`
`max_attempts`	1–10 intentos	`20011`
`channels`	hasta 4 pasos	`20006`

El tiempo de espera por canal y el plazo de reenvío son ajustes de la aplicación, no de la petición.

Cómo te enteras del resultado

En la respuesta de comprobación, si el usuario escribe el código en tu app.
Por webhook, para los finales que ocurren sin una llamada tuya: expired y failed.
Por cada paso de canal, si te suscribes a los eventos verification.channel.*: si cada envío fue aceptado, rechazado o entregado.

No hay un endpoint para consultar el estado de una verificación: el resultado llega solo.