Saltar al contenido principal

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​

GrupoEventoCuándo ocurre
Pagospayment_intent.succeededUna intención de pago se completó correctamente. Con captura manual, se envía cuando la captura se completa.
Pagospayment_intent.failedFalló 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.
Pagospayment_intent.canceledUna intención de pago fue cancelada, por ejemplo con la API.
Pagospayment_intent.processingUna 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.
Renovacionessubscription_renewal.succeededEl cobro de renovación de un cargo recurrente fue exitoso.
Renovacionessubscription_renewal.failedFalló 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.
Programacionessubscription_schedule.createdSe 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.
Programacionessubscription_schedule.updatedCambió la configuración o las próximas etapas de una programación.
Programacionessubscription_schedule.activatedUna programación inició su primera etapa. Su cargo recurrente llega en subscriptionId.
Programacionessubscription_schedule.canceledUna programación se canceló antes de terminar.
Programacionessubscription_schedule.releasedUna programación liberó su cargo recurrente, que sigue por su cuenta.
Programacionessubscription_schedule.completedUna programación terminó su última etapa.
Programacionessubscription_schedule.phase_transitionedUna programación pasó a su siguiente etapa.
Programacionessubscription_schedule.transition_failedUna programación no pudo iniciar una etapa después de agotar sus reintentos automáticos.
Checkoutcheckout_session.succeededUna sesión de Checkout se completó correctamente.
Transferenciasmobile_transfer.receivedSe recibió una transferencia SINPE Móvil entrante. Solo aplica a comercios con un número SINPE Móvil personalizado.
Disputasdispute.createdSe abrió una disputa. Si se abre ya resuelta (won o lost), también se envía dispute.closed.
Disputasdispute.updatedCambió el estado de una disputa abierta, o el adquirente liquidó una disputa (acquirerPaidAt).
Disputasdispute.closedUna disputa llegó a won o lost. Si el resultado se revierte, se envía otro dispute.closed con el resultado nuevo.
Reembolsosrefund.createdONVO aceptó un reembolso, antes de enviarlo al procesador. Una solicitud rechazada con un error 4xx no crea un reembolso ni envía eventos.
Reembolsosrefund.succeededUn reembolso se completó correctamente.
Reembolsosrefund.failedUn reembolso falló de forma definitiva.
Liquidacionespayout.createdSe creó una liquidación.
Liquidacionespayout.paidONVO confirmó el pago de una liquidación.
Liquidacionespayout.failedUna 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.*.

CampoDescripción
id, amount, capturableAmount, receivedAmount, currencyIdentificador y montos de la intención.
description, status, captureMethodDescripción, estado y método de captura.
customerId, paymentMethodIdCliente y método de pago asociados.
metadataLos 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, updatedAtFechas 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)​

CampoDescripción
invoiceId, subscriptionId, paymentIntentIdFactura, cargo recurrente e intención de pago del período.
currency, total, attemptCountMoneda, monto total e intentos de cobro.
invoiceStatus, subscriptionStatusEstado de la factura y del cargo recurrente.
periodStart, periodEndPeríodo cobrado.
lastPaymentAttempt, nextPaymentAttemptFecha del último intento y del próximo, si hay.
invoiceMetadata, subscriptionMetadataMetadatos de la factura y del cargo recurrente.
errorEn 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.

CampoDescripción
id, statusIdentificador y estado: not_started, activating, active, completed, released, canceled o error.
customerId, subscriptionIdCliente y cargo recurrente asociados.
endBehaviorQué pasa con el cargo recurrente al terminar la última etapa: release o cancel.
defaultCollectionMethod, defaultPaymentMethodId, defaultDescriptionValores por defecto de las etapas.
metadataLos metadatos que definiste.
startDate, releasedAt, canceledAt, completedAtFechas 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.
versionVersión de la programación. Aumenta con cada actualización y cada cambio de etapa.
phasesEtapas: id, phaseIndex, startDate, endDate, iterations, trialEnd, description, collectionMethod, paymentMethodId, prorationBehavior, billingCycleAnchor, metadata, items (id, priceId, quantity, metadata, createdAt y updatedAt), createdAt y updatedAt.
createdAt, updatedAtFechas 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)​

CampoDescripción
id, status, paymentStatus, paymentModeIdentificador y estados de la sesión.
amountSubtotal, amountTotal, currencyMontos de la sesión.
paymentIntentId, customerId, subscriptionId, paymentLinkIdObjetos relacionados.
clientReferenceId, metadataTu referencia y tus metadatos.
expiresAt, createdAt, updatedAtFechas de la sesión.

Transferencia SINPE Móvil (mobile_transfer)​

CampoDescripción
id, status, amount, currency, descriptionDatos de la transferencia recibida.
sinpeReference, authorizationDateReferencia SINPE y fecha de autorización.
processorProcesador que reportó la transferencia.
originQuien envió la transferencia: name, identificationLast4 y phoneLast4. La identificación y el teléfono completos nunca se envían.
createdAt, updatedAtFechas de registro.

Disputa (dispute)​

CampoDescripción
id, amount, currency, descriptionDatos de la disputa.
statusneeds_response, under_review, won o lost.
reasonMotivo reportado.
responseDueAtFecha límite para responder.
acquirerPaidAtFecha en que el adquirente liquidó la disputa, si aplica.
paymentIntentId, chargeIdPago disputado.
createdAt, updatedAtFechas 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)​

CampoDescripción
id, amount, currency, description, reasonDatos del reembolso.
status, typeEstado y tipo de reembolso.
paymentIntentId, chargeIdPago reembolsado.
authorizationNumber, referenceNumber, transactionReferenceReferencias del procesador, cuando existen.
failureReason, failureEn refund.failed: el código y un mensaje. Los códigos posibles son insufficient_funds, merchant_cannot_process, declined y unknown.
createdAt, updatedAtFechas 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)​

CampoDescripción
id, status, currency, descriptionDatos de la liquidación.
railSiempre local.
payoutGross, payoutNet, payoutFee, fees, vatTax, incomeTax, retentionsMontos en la unidad mínima de la moneda, enviados como texto para no perder precisión.
transactionsCount, exchangeRateCantidad de transacciones incluidas y tipo de cambio.
referenceReferencia de la liquidación.
destinationCuenta de destino: ibanLast4. El IBAN completo nunca se envía.
arrivedAtFecha en que se pagó, si aplica.
failureEn payout.failed: code (retries_exhausted: la liquidación agotó sus reintentos) y message. En los demás eventos llega null.
createdAt, updatedAtFecha 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"
}
}
}