Migrar a Webhooks Unificados (intent.*) | Documentación API de Recurrente

Recurrente unificó todos los eventos de pago en un solo formato: intent.*. En lugar de un evento distinto por método de pago (payment_intent.*, bank_transfer_intent.*, etc.), recibís un único evento intent.* con una estructura común, discriminada por el campo type. Escribís un handler en vez de uno por tipo.

No hay breaking changes. Recurrente envía ambos formatos: el clásico por tipo y el unificado. Tu integración actual sigue funcionando sin tocar nada; vos elegís a cuáles suscribir tu endpoint y migrás cuando quieras.

Eventos nuevos a configurar

Suscribí tu endpoint a estos eventos desde tu dashboard de Webhooks:

Evento	Cuándo se emite
`intent.succeeded`	Cobro exitoso (cualquier método de pago)
`intent.pending`	Cobro iniciado o pendiente (transferencia, cripto)
`intent.failed`	Cobro fallido
`intent.canceled`	Intent cancelado
`intent.paid`	Solo para pagos con balance: le llega a la cuenta pagadora

Cómo funciona

Recurrente envía los dos formatos por cada pago: el legacy por tipo (payment_intent.*, etc.) y el unificado (intent.*), como entregas separadas.
En tu dashboard de Webhooks suscribís tu endpoint a los intent.* que te interesen.
Tu handler ramifica según el campo type y procesa.

Si tu endpoint no filtra por tipo de evento, recibirá tanto los payment_intent.* como los intent.* para el mismo pago. Para no procesar el mismo cobro dos veces, suscribite a uno solo de los dos formatos (o chequeá el campo event_type en tu handler).

El payload unificado

1 {
2   "type": "payment",            // payment | bank_transfer | crypto | balance | cash
3   "event_type": "intent.succeeded",
4   "id": "in_8c3a1f20",
5   "status": "succeeded",        // pending | succeeded | failed | canceled | paid
6   "raw_status": "succeeded",    // el estado concreto, sin normalizar
7   "amount_in_cents": 25000,
8   "currency": "GTQ",
9   "customer": { "id": "cus_...", "email": "...", "nit": "CF" },
10   "product": { "id": "prod_..." },
11   "checkout": { "...": "..." },
12   "payment":  { "...": "..." },
13   "details": { "fee": 875, "installments": 1, "channel": "Tarjeta", "...": "..." }
14 }

El envelope y el núcleo común son idénticos para los cinco tipos; solo cambia type y el contenido de details. Ver la estructura completa en la documentación de Webhooks.

Mapeo: legacy → unificado

Evento legacy	Evento unificado	`type`
`payment_intent.succeeded`	`intent.succeeded`	`payment`
`payment_intent.failed`	`intent.failed`	`payment`
`payment_intent.requires_capture` / `requires_verification`	`intent.pending`	`payment`
`bank_transfer_intent.{pending,succeeded,failed}`	`intent.{pending,succeeded,failed}`	`bank_transfer`
`crypto_intent.{pending,succeeded,failed}`	`intent.{pending,succeeded,failed}`	`crypto`
`balance_intent.succeeded`	`intent.succeeded`	`balance`
`balance_intent.paid`	`intent.paid`	`balance`
`cash_intent.{succeeded,failed,canceled}`	`intent.{succeeded,failed,canceled}`	`cash`

Los estados intermedios de tarjeta (requires_capture, requires_verification) se normalizan a pending. El estado concreto siempre está disponible en raw_status.

Pasos para migrar

Revisá el payload nuevo. Mirá la estructura en la documentación de Webhooks, o consultá un pago real con GET /api/intents/{id} (devuelve el mismo formato que el webhook).

Actualizá tu handler para consumir intent.* y ramificar por type:

1 switch (event.type) {
2   case "payment":       /* event.details.fee, .installments, ... */ break
3   case "bank_transfer":
4   case "crypto":
5   case "balance":
6   case "cash":          break
7 }
8 // el estado siempre en event.status: pending | succeeded | failed | canceled | paid

Suscribí tu endpoint a los intent.* desde el dashboard de Webhooks.
(Opcional) Dá de baja los eventos por tipo. Cuando tu handler unificado funcione, desuscribite de los payment_intent.*, bank_transfer_intent.*, etc., para dejar de recibir el formato duplicado.

Eventos que no cambian

subscription.*, refund.*, dispute.* y setup_intent.* siguen exactamente igual — no son parte del recurso Intent unificado.