Eventos de webhook
Cada endpoint recibe solo los tipos de evento que seleccionaste al crearlo o editarlo. Todos los eventos usan el sobre con id, type y data.object; el tipo de evento indica qué cambió y data.object.object indica el tipo de recurso.
Tipos de evento
| Grupo | Evento | Cuándo ocurre |
|---|---|---|
| Pagos | payment_intent.succeeded | Una intención de pago se completó correctamente. Con captura manual, se envía cuando la captura se completa. |
| Pagos | payment_intent.failed | Falló un intento de pago: por ejemplo, un rechazo, una autenticación 3DS fallida, una captura manual rechazada o un pago con cripto cancelado. Se envía por cada intento fallido y la intención puede completarse después con otro intento, así que tratá payment_intent.succeeded como el resultado final. |
| Pagos | payment_intent.canceled | Una intención de pago fue cancelada, por ejemplo con la API. |
| Pagos | payment_intent.processing | Una intención de pago espera una confirmación asíncrona, por ejemplo una transferencia SINPE, un depósito bancario o un pago con cripto. Se envía una vez por cada intento que queda en procesamiento, así que puede repetirse para la misma intención. |
| Renovaciones | subscription_renewal.succeeded | El cobro de renovación de un cargo recurrente fue exitoso. |
| Renovaciones | subscription_renewal.failed | Falló un intento de cobro de renovación de un cargo recurrente. Se envía por cada intento fallido, incluido el último; attemptCount indica cuál fue. |
| Programaciones | subscription_schedule.created | Se creó una programación de cargo recurrente. Si se crea a partir de un cargo recurrente existente, nace activa y no envía subscription_schedule.activated. |
| Programaciones | subscription_schedule.updated | Cambió la configuración o las próximas etapas de una programación. |
| Programaciones | subscription_schedule.activated | Una programación inició su primera etapa. Su cargo recurrente llega en subscriptionId. |
| Programaciones | subscription_schedule.canceled | Una programación se canceló antes de terminar. |
| Programaciones | subscription_schedule.released | Una programación liberó su cargo recurrente, que sigue por su cuenta. |
| Programaciones | subscription_schedule.completed | Una programación terminó su última etapa. |
| Programaciones | subscription_schedule.phase_transitioned | Una programación pasó a su siguiente etapa. |
| Programaciones | subscription_schedule.transition_failed | Una programación no pudo iniciar una etapa después de agotar sus reintentos automáticos. |
| Checkout | checkout_session.succeeded | Una sesión de Checkout se completó correctamente. |
| Transferencias | mobile_transfer.received | Se recibió una transferencia SINPE Móvil entrante. Solo aplica a comercios con un número SINPE Móvil personalizado. |
| Disputas | dispute.created | Se abrió una disputa. Si se abre ya resuelta (won o lost), también se envía dispute.closed. |
| Disputas | dispute.updated | Cambió el estado de una disputa abierta, o el adquirente liquidó una disputa (acquirerPaidAt). |
| Disputas | dispute.closed | Una disputa llegó a won o lost. Si el resultado se revierte, se envía otro dispute.closed con el resultado nuevo. |
| Reembolsos | refund.created | ONVO aceptó un reembolso, antes de enviarlo al procesador. Una solicitud rechazada con un error 4xx no crea un reembolso ni envía eventos. |
| Reembolsos | refund.succeeded | Un reembolso se completó correctamente. |
| Reembolsos | refund.failed | Un reembolso falló de forma definitiva. |
| Liquidaciones | payout.created | Se creó una liquidación. |
| Liquidaciones | payout.paid | ONVO confirmó el pago de una liquidación. |
| Liquidaciones | payout.failed | Una liquidación falló después de agotar sus reintentos automáticos. |
payment_intent.succeeded no se envía para un pago que se completa en varias transferencias hasta que se recibe el monto total. Cada transferencia parcial puede generar su propio mobile_transfer.received.
Campos por objeto
ONVO envía solo los campos de esta lista. Nunca incluye números de tarjeta, tokens, IBAN completos, números de identificación ni secretos.
Intención de pago (payment_intent)
Lo envían todos los eventos payment_intent.*.
| Campo | Descripción |
|---|---|
id, amount, capturableAmount, receivedAmount, currency | Identificador y montos de la intención. |
description, status, captureMethod | Descripción, estado y método de captura. |
customerId, paymentMethodId | Cliente y método de pago asociados. |
metadata | Los metadatos que definiste. |
lastPaymentError | Último error de pago: type, code, message y paymentMethodType. |
latestCharge | Último cargo: id, amount, currency, status, failureCode, failureMessage, createdAt y updatedAt. |
createdAt, updatedAt | Fechas de creación y última actualización. |
{
"id": "evt_k5ufdj5r8btq7t8esdhbpwe7",
"object": "event",
"createdAt": "2026-10-21T16:12:00.000Z",
"mode": "test",
"accountId": "clacct0001",
"type": "payment_intent.failed",
"data": {
"object": {
"object": "payment_intent",
"id": "clpiment0002",
"amount": 250000,
"capturableAmount": 0,
"receivedAmount": 0,
"currency": "CRC",
"status": "requires_payment_method",
"customerId": "clcus0002",
"metadata": { "orderId": "order_1002" },
"lastPaymentError": {
"type": "processing_error",
"code": "declined",
"message": "Transaction declined",
"paymentMethodType": "card"
},
"latestCharge": {
"id": "clch0002",
"amount": 250000,
"currency": "CRC",
"status": "failed",
"failureCode": "declined",
"failureMessage": "Transaction declined",
"createdAt": "2026-10-21T16:11:58.000Z",
"updatedAt": "2026-10-21T16:12:00.000Z"
},
"createdAt": "2026-10-21T16:11:50.000Z",
"updatedAt": "2026-10-21T16:12:00.000Z"
}
}
}
Renovación de cargo recurrente (subscription_renewal)
| Campo | Descripción |
|---|---|
invoiceId, subscriptionId, paymentIntentId | Factura, cargo recurrente e intención de pago del período. |
currency, total, attemptCount | Moneda, monto total e intentos de cobro. |
invoiceStatus, subscriptionStatus | Estado de la factura y del cargo recurrente. |
periodStart, periodEnd | Período cobrado. |
lastPaymentAttempt, nextPaymentAttempt | Fecha del último intento y del próximo, si hay. |
invoiceMetadata, subscriptionMetadata | Metadatos de la factura y del cargo recurrente. |
error | En subscription_renewal.failed: type, code, message y paymentMethodType. Si el cobro falló por un error interno, es { "type": "processing_error", "code": "renewal_failed", "message": "The renewal payment could not be processed." }, sin paymentMethodType. Se omite cuando no hay error. |
Programación de cargo recurrente (subscription_schedule)
Lo envían todos los eventos subscription_schedule.*. Incluye customerId, no el cliente completo.
| Campo | Descripción |
|---|---|
id, status | Identificador y estado: not_started, activating, active, completed, released, canceled o error. |
customerId, subscriptionId | Cliente y cargo recurrente asociados. |
endBehavior | Qué pasa con el cargo recurrente al terminar la última etapa: release o cancel. |
defaultCollectionMethod, defaultPaymentMethodId, defaultDescription | Valores por defecto de las etapas. |
metadata | Los metadatos que definiste. |
startDate, releasedAt, canceledAt, completedAt | Fechas de inicio, liberación, cancelación y finalización. |
lastTransitionedPhaseIndex, attemptedPhaseIndex, transitionAttempts, lastTransitionAt | Última etapa iniciada, etapa que se intentó iniciar, intentos de cambio de etapa y fecha del último cambio. Las etapas se numeran desde 0; lastTransitionedPhaseIndex es -1 mientras no haya iniciado ninguna. |
version | Versión de la programación. Aumenta con cada actualización y cada cambio de etapa. |
phases | Etapas: id, phaseIndex, startDate, endDate, iterations, trialEnd, description, collectionMethod, paymentMethodId, prorationBehavior, billingCycleAnchor, metadata, items (id, priceId, quantity, metadata, createdAt y updatedAt), createdAt y updatedAt. |
createdAt, updatedAt | Fechas de creación y última actualización. |
subscription_schedule.transition_failed envía un objeto parcial: id, status (error), attemptedPhaseIndex, transitionAttempts y, si ya se inició alguna etapa, lastTransitionedPhaseIndex. No incluye fechas ni el detalle del error.
Por ejemplo, una programación que no pudo pasar de su primera etapa a la segunda:
{
"id": "evt_t4w9n2xk7dq1mzb6hcs8vryp",
"object": "event",
"createdAt": "2026-12-01T10:00:02.000Z",
"mode": "live",
"accountId": "clacct0001",
"type": "subscription_schedule.transition_failed",
"data": {
"object": {
"object": "subscription_schedule",
"id": "clsched0001",
"status": "error",
"lastTransitionedPhaseIndex": 0,
"attemptedPhaseIndex": 1,
"transitionAttempts": 5
}
}
}
Sesión de Checkout (checkout_session)
| Campo | Descripción |
|---|---|
id, status, paymentStatus, paymentMode | Identificador y estados de la sesión. |
amountSubtotal, amountTotal, currency | Montos de la sesión. |
paymentIntentId, customerId, subscriptionId, paymentLinkId | Objetos relacionados. |
clientReferenceId, metadata | Tu referencia y tus metadatos. |
expiresAt, createdAt, updatedAt | Fechas de la sesión. |
Transferencia SINPE Móvil (mobile_transfer)
| Campo | Descripción |
|---|---|
id, status, amount, currency, description | Datos de la transferencia recibida. |
sinpeReference, authorizationDate | Referencia SINPE y fecha de autorización. |
processor | Procesador que reportó la transferencia. |
origin | Quien envió la transferencia: name, identificationLast4 y phoneLast4. La identificación y el teléfono completos nunca se envían. |
createdAt, updatedAt | Fechas de registro. |
Disputa (dispute)
| Campo | Descripción |
|---|---|
id, amount, currency, description | Datos de la disputa. |
status | needs_response, under_review, won o lost. |
reason | Motivo reportado. |
responseDueAt | Fecha límite para responder. |
acquirerPaidAt | Fecha en que el adquirente liquidó la disputa, si aplica. |
paymentIntentId, chargeId | Pago disputado. |
createdAt, updatedAt | Fechas de la disputa. |
En un marketplace, los eventos de la disputa de un pago hecho en nombre de una cuenta conectada (onBehalfOf) van a la cuenta de la plataforma, aunque la disputa pertenezca a la cuenta conectada.
Una disputa que se abre ya resuelta envía dispute.created y después dispute.closed sin previousAttributes. En los demás casos, dispute.updated y dispute.closed incluyen data.previousAttributes con el valor anterior de los campos que cambiaron entre status, responseDueAt y acquirerPaidAt.
El resultado de una disputa puede revertirse, por ejemplo de lost a won. ONVO envía entonces otro dispute.closed, con el resultado nuevo en status y el anterior en previousAttributes.status, como máximo uno por resultado. No trates el primer dispute.closed como definitivo: compará su updatedAt o consultá la disputa en la API.
Por ejemplo, una disputa que pasa de under_review a won:
{
"id": "evt_yfktqrqm5p47uwg7kcb6po4s",
"object": "event",
"createdAt": "2026-10-22T14:00:00.000Z",
"mode": "live",
"accountId": "clacct0001",
"type": "dispute.closed",
"data": {
"object": {
"object": "dispute",
"id": "cldsp0001",
"amount": 500000,
"currency": "CRC",
"status": "won",
"reason": "fraudulent",
"responseDueAt": "2026-10-28T23:59:59.000Z",
"paymentIntentId": "clpiment0001",
"chargeId": "clch0001",
"createdAt": "2026-10-15T10:00:00.000Z",
"updatedAt": "2026-10-22T14:00:00.000Z"
},
"previousAttributes": {
"status": "under_review"
}
}
}
Reembolso (refund)
| Campo | Descripción |
|---|---|
id, amount, currency, description, reason | Datos del reembolso. |
status, type | Estado y tipo de reembolso. |
paymentIntentId, chargeId | Pago reembolsado. |
authorizationNumber, referenceNumber, transactionReference | Referencias del procesador, cuando existen. |
failureReason, failure | En refund.failed: el código y un mensaje. Los códigos posibles son insufficient_funds, merchant_cannot_process, declined y unknown. |
createdAt, updatedAt | Fechas del reembolso. |
En un marketplace, los eventos del reembolso de un pago hecho en nombre de una cuenta conectada (onBehalfOf) van a la cuenta de la plataforma, aunque el reembolso pertenezca a la cuenta conectada.
{
"id": "evt_eqf1z262w9lqzccagn8dzvjh",
"object": "event",
"createdAt": "2026-10-21T17:00:05.000Z",
"mode": "test",
"accountId": "clacct0001",
"type": "refund.failed",
"data": {
"object": {
"object": "refund",
"id": "clref0001",
"amount": 500000,
"currency": "CRC",
"status": "failed",
"failureReason": "declined",
"paymentIntentId": "clpiment0001",
"chargeId": "clch0001",
"createdAt": "2026-10-21T17:00:00.000Z",
"updatedAt": "2026-10-21T17:00:05.000Z",
"failure": {
"code": "declined",
"message": "The refund was declined."
}
}
}
}
Liquidación (payout)
| Campo | Descripción |
|---|---|
id, status, currency, description | Datos de la liquidación. |
rail | Siempre local. |
payoutGross, payoutNet, payoutFee, fees, vatTax, incomeTax, retentions | Montos en la unidad mínima de la moneda, enviados como texto para no perder precisión. |
transactionsCount, exchangeRate | Cantidad de transacciones incluidas y tipo de cambio. |
reference | Referencia de la liquidación. |
destination | Cuenta de destino: ibanLast4. El IBAN completo nunca se envía. |
arrivedAt | Fecha en que se pagó, si aplica. |
failure | En payout.failed: code (retries_exhausted: la liquidación agotó sus reintentos) y message. En los demás eventos llega null. |
createdAt, updatedAt | Fecha de creación y del último cambio de estado. |
{
"id": "evt_c9qc6r21en3coaomguwl2lpx",
"object": "event",
"createdAt": "2026-10-21T20:00:00.000Z",
"mode": "live",
"accountId": "clacct0001",
"type": "payout.paid",
"data": {
"object": {
"object": "payout",
"id": "clpo0001",
"status": "paid",
"rail": "local",
"currency": "CRC",
"payoutGross": "12500000",
"payoutNet": "12187500",
"payoutFee": "0",
"fees": "312500",
"transactionsCount": 42,
"reference": "202610210",
"destination": { "ibanLast4": "4066" },
"arrivedAt": "2026-10-21T19:59:30.000Z",
"failure": null,
"createdAt": "2026-10-21T06:00:00.000Z",
"updatedAt": "2026-10-21T20:00:00.000Z"
}
}
}
Evento de prueba
Probar conexión envía un evento webhook_endpoint.test firmado igual que los demás. No se puede seleccionar como suscripción ni se reintenta.
{
"id": "evt_d1jcvxbv79lhgptshb2jh35a",
"object": "event",
"createdAt": "2026-10-21T15:00:00.000Z",
"mode": "test",
"accountId": "clacct0001",
"type": "webhook_endpoint.test",
"data": {
"object": {
"object": "webhook_endpoint",
"id": "wh_gsx8lkls3a63evk9yj4qba4m"
}
}
}