Recaudos

Los 22 eventos de recaudos a lo largo del ciclo de vida, y cuándo llega cada uno.

Cada entidad de recaudos reporta su ciclo de vida por webhooks: 7 eventos de la plantilla, 7 de la intención de pago, 5 del pago y 3 del lote de liquidación (22 en total). Cada payload lleva el recurso completo, con la misma forma en que lo devuelve la API. Esta página ubica cada evento en la línea de tiempo; los payloads exactos viven en la referencia de API de webhooks de recaudos. Para la verificación de firma, los reintentos y las convenciones de campos de dinero compartidas por todos los webhooks de Mono, ver Webhook conventions.

El camino feliz, en orden

Para un recaudo a través de una intención de pago, un solo pago produce esta secuencia:

Los recaudos sin intenciones de pago se saltan los cuatro eventos de la intención de pago; los eventos de la plantilla se disparan una vez por plantilla, no por pago.

Eventos de la plantilla

Evento	Llega cuando
`payin_template_created`	La plantilla es aceptada y persistida. Sus tokens de pago aún se están preparando (`payment_tokens` es null). Todavía no puede recibir pagos.
`payin_template_ready`	Terminó el setup del token: la plantilla puede recibir pagos, y `payment_tokens` lleva una entrada por método que emite token (para Bre-B, la llave y el QR).
`payin_template_updated`	Cada update exitoso. Lleva `previous_values` con los campos que cambiaron, incluida una transición de estado causada por mover los totales, que no dispara los eventos de estado separados.
`payin_template_minimum_paid`	El `paid_amount` acumulado alcanza por primera vez `total_minimum_amount`. La plantilla sigue aceptando pagos.
`payin_template_paid`	Se alcanza `total_maximum_amount`, o una plantilla `single_use` recibió su pago. No se aceptan más pagos.
`payin_template_discarded`	La plantilla fue eliminada, expiró o fue barrida por inactividad; sus tokens fueron dados de baja. `prune_reason` dice cuál fue el caso.
`payin_template_failed`	El setup del token agotó sus reintentos. `state_reason` lo explica (p. ej. `key_already_registered`).

Eventos de la intención de pago

Evento	Llega cuando
`payin_intent_created`	La intención de pago es aceptada y persistida. Su token aún se está preparando. El pagador todavía no puede pagar.
`payin_intent_ready_to_pay`	La intención de pago se vuelve pagable: `payment_tokens` y `expires_at` quedan definidos. También se reenvía cuando la intención de pago se rearma tras un intento fallido.
`payin_intent_awaiting_payment`	Un pago contra la intención de pago fue autorizado y está en vuelo.
`payin_intent_attempt_failed`	Un intento de pago falló después de la autorización pero la intención de pago sobrevive: está de vuelta en `ready_to_pay` para un reintento. El intento en sí llega como `payin_rejected` o `payin_failed`.
`payin_intent_successful`	La intención de pago fue consumida por su pago exitoso. Final: tokens dados de baja.
`payin_intent_failed`	La intención de pago falla definitivamente: falló el registro del token, o un pago falló sin rearme. `state_reason` lo explica.
`payin_intent_expired`	La ventana se cerró sin que nadie pagara. El `external_id` queda libre para una intención de pago nueva.

Eventos del pago

Evento	Llega cuando
`payin_created`	Un pago se persiste por primera vez, antes de la confirmación del proveedor. Lleva quién pagó (`instrument.payer`) y a qué llave (`recipient_data`).
`payin_approved_in_provider`	El proveedor confirmó el pago. El dinero existe del lado del proveedor; la subcuenta aún no se acredita.
`payin_subaccount_credited`	La subcuenta fue acreditada por `subaccount_amount`. Para la mayoría de las integraciones, la señal de "pago completo".
`payin_rejected`	Una condición de negocio, configuración o del pagador detuvo el pago. `state_reason` lo explica (p. ej. `amount_exceeds_maximum`, `payer_not_allowed`). Los fondos del pagador, si los hubo, se devuelven.
`payin_failed`	Una falla del sistema o del proveedor: `lock_timeout` o `unknown`.

Eventos del lote de liquidación

Evento	Llega cuando
`payin_settlement_batch_created`	Pagos pendientes fueron agrupados en un lote. `payins` lista lo que aporta cada uno; el dinero aún no se mueve.
`payin_settlement_batch_processing`	El proveedor de entrega aceptó la transferencia del lote.
`payin_settlement_batch_completed`	Los fondos llegaron a tu cuenta de fondeo.

Qué no se notifica

El breve estado awaiting_payment del pago no tiene evento propio; el payin_intent_awaiting_payment de la intención de pago cubre ese momento.
Las transiciones de estado de la plantilla causadas por un update viajan dentro de payin_template_updated, no como eventos de estado separados.
Los estados retryable y failed del lote de liquidación se pueden leer por la API pero nunca se notifican: Mono se está encargando de la entrega y no necesitas hacer nada.

Siguientes pasos

Webhook conventions: firmas, reintentos y reglas de entrega.
Referencia de API de webhooks de recaudos: el payload exacto de cada evento.
Flujos de recaudos: los eventos en el contexto de cada caso de uso.