Errores de plantilla

Por qué una plantilla termina fallida o descartada, y qué significa cada razón de estado.

Una plantilla lleva state_reason en sus dos estados terminales, y significan cosas muy distintas:

failed: la plantilla nunca llegó a ser pagable. La preparación de su token de pago agotó sus reintentos, así que ningún pagador pudo alcanzarla.
discarded: la plantilla sí fue pagable y su vida terminó: fue podada o borrada, y sus tokens de pago fueron desmontados.

Lees el código en los webhooks payin_template_failed y payin_template_discarded, y en la plantilla misma con get o list.

Ejemplo de payload del webhook

{
  "timestamp": "2026-02-11T14:22:07.913204Z",
  "event": {
    "type": "payin_template_failed",
    "data": {
      "id": "cpit_034EASMHlq36oZISbc9W4b",
      "state": "failed",
      "state_reason": "key_already_registered",
      "external_id": "campaign-2026-02",
      "subaccount_id": "csub_034EASMIAFVq06j2NxhnIJ"
    }
  }
}

Fallida: la plantilla nunca llegó a ser pagable

Una plantilla se crea en created y sólo llega a ready cuando su token de pago existe. Estas son las formas en que esa preparación termina en vez de lograrlo.

Código	Descripción	Causa	Solución sugerida
`key_already_registered`	La llave ya está tomada	El valor de llave personalizado que pediste ya está registrado en la red de pagos inmediatos: las llaves son únicas en toda la red.	Crea la plantilla otra vez con otro `custom_key_value`, o deja que Mono genere la llave.
`key_registration_failed`	Falló el registro de la llave	Registrar la llave de pago en la red agotó sus reintentos.	Crea la plantilla otra vez. Si se repite, contacta a soporte con el `id` de la plantilla.
`collection_registration_failed`	Falló el registro del cobro	Mono no pudo registrar el cobro con el proveedor del método de pago.	Crea la plantilla otra vez. Si se repite, contacta a soporte con el `id` de la plantilla.
`unknown`	Desconocido	Una falla sin clasificar durante la preparación.	Contacta a soporte con el `id` de la plantilla.

Una plantilla fallida es definitiva, su `external_id` no

No hay forma de reintentar la preparación de una plantilla que ya falló. El estado es terminal. Crea una nueva: una plantilla que termina failed o discarded libera su external_id, así que puedes reusar el mismo identificador para el reemplazo.

Descartada: la vida de la plantilla terminó

Tres salidas, y sólo una la pediste tú. Las tres desmontan los tokens de pago, así que cualquier llave o QR ya distribuido deja de funcionar.

Código	Descripción	Causa	Solución sugerida
`deleted`	Borrada	Borraste la plantilla por la API.	Esperado. Crea una plantilla nueva cuando necesites volver a cobrar.
`expired`	Expirada	La plantilla pasó su `expires_at` y fue podada.	Define una ventana más larga en la siguiente, o crea una plantilla nueva.
`inactivity`	Inactividad	La plantilla pasó demasiado tiempo sin actividad y fue podada. Cubre los dos casos: nunca pagada, y pagada alguna vez pero inactiva desde entonces.	Crea una plantilla nueva. Si el cobro es de larga vida, mantenlo en uso o reemítelo.

`prune_reason` dice más que `state_reason`

Para una plantilla podada, prune_reason conserva la distinción fina que state_reason colapsa: inactivity_without_attempts e inactivity_with_attempts se vuelven ambos inactivity. Lee prune_reason cuando necesites distinguir "nunca nadie pagó" de "los pagos se detuvieron" (ver Poda).

Cómo manejarlos

Una plantilla que falla o se descarta no es un error en un pago; es un cobro que ya no existe. Lo que importa es que dejes de distribuir su token de pago, porque a los pagadores que tengan una llave o un QR suyo se les rechazará el pago con template_deleted, template_expired o template_invalid_state.

app.post('/webhook', (req, res) => {
  const { event } = req.body;

  if (event.type === 'payin_template_failed') {
    const { id, state_reason } = event.data;

    if (state_reason === 'key_already_registered') {
      // Elige otro valor de llave y crea la plantilla de nuevo
    } else {
      // Falló la preparación: reintenta la creación, y alerta si se repite
    }
  }

  if (event.type === 'payin_template_discarded') {
    const { id, state_reason } = event.data;
    // Deja de mostrarle a los pagadores la llave o el QR de esta plantilla
    // `deleted` es tuyo; `expired` e `inactivity` son la poda
  }

  res.status(200).send();
});

Soporte

Cuando contactes a soporte por una plantilla, entrega el id de la plantilla y el external_id con el que la creaste.

Siguientes pasos

Errores de pago: por qué se rehusó un pago individual.
Poda: cuándo y por qué se barren las plantillas.
Webhooks: cada evento de plantilla y su payload.