Migrate to Unified Webhooks (intent.*) | Documentación API de Recurrente

Recurrente unified all payment events into a single format: intent.*. Instead of a separate event per payment method (payment_intent.*, bank_transfer_intent.*, etc.), you receive one intent.* event with a common structure, discriminated by the type field. You write one handler instead of one per type.

No breaking changes. Recurrente sends both formats: the classic per-type one and the unified one. Your current integration keeps working untouched; you choose which to subscribe your endpoint to, and migrate whenever you want.

New events to configure

Subscribe your endpoint to these events from your Webhooks dashboard:

Event	When it’s emitted
`intent.succeeded`	Successful charge (any payment method)
`intent.pending`	Charge started or pending (bank transfer, crypto)
`intent.failed`	Failed charge
`intent.canceled`	Canceled intent
`intent.paid`	Balance payments only: delivered to the payer account

How it works

Recurrente sends both formats for each payment: the legacy per-type one (payment_intent.*, etc.) and the unified one (intent.*), as separate deliveries.
In your Webhooks dashboard, subscribe your endpoint to the intent.* events you care about.
Your handler branches on the type field and processes.

If your endpoint doesn’t filter by event type, it will receive both payment_intent.* and intent.* for the same payment. To avoid processing the same charge twice, subscribe to only one of the two formats (or check the event_type field in your handler).

The unified payload

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",    // the concrete, non-normalized state
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 }

The envelope and common core are identical for all five types; only type and the details contents change. See the full structure in the Webhooks documentation.

Mapping: legacy → unified

Legacy event	Unified event	`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`

Intermediate card states (requires_capture, requires_verification) are normalized to pending. The concrete state is always available in raw_status.

Migration steps

Review the new payload. Look at the structure in the Webhooks documentation, or fetch a real payment with GET /api/intents/{id} (returns the same format as the webhook).

Update your handler to consume intent.* and branch on 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 // state is always in event.status: pending | succeeded | failed | canceled | paid

Subscribe your endpoint to the intent.* events from the Webhooks dashboard.
(Optional) Unsubscribe from the per-type events. Once your unified handler works, unsubscribe from payment_intent.*, bank_transfer_intent.*, etc., to stop receiving the duplicate format.

Events that don’t change

subscription.*, refund.*, dispute.*, and setup_intent.* stay exactly the same — they’re not part of the unified Intent resource.