Webhook events
Each endpoint only receives the event types you selected when you created or edited it. Every event uses the envelope with id, type, and data.object; the event type says what changed and data.object.object names the resource type.
Event types
| Group | Event | When it happens |
|---|---|---|
| Payments | payment_intent.succeeded | A payment intent succeeded. With manual capture, it is sent when the capture completes. |
| Payments | payment_intent.failed | A payment attempt failed: for example a decline, a failed 3DS authentication, a declined manual capture, or a canceled crypto payment. It is sent for each failed attempt, and the intent can still succeed with another attempt, so treat payment_intent.succeeded as the final result. |
| Payments | payment_intent.canceled | A payment intent was canceled, for example with the API. |
| Payments | payment_intent.processing | A payment intent is waiting for an asynchronous confirmation, for example a SINPE transfer, a bank deposit, or a crypto payment. It is sent once for each attempt that goes into processing, so it can repeat for the same intent. |
| Renewals | subscription_renewal.succeeded | A subscription renewal payment succeeded. |
| Renewals | subscription_renewal.failed | A subscription renewal payment attempt failed. It is sent for each failed attempt, including the last one; attemptCount tells which one it was. |
| Schedules | subscription_schedule.created | A subscription schedule was created. If it is created from an existing subscription, it starts active and sends no subscription_schedule.activated. |
| Schedules | subscription_schedule.updated | A schedule's settings or upcoming phases changed. |
| Schedules | subscription_schedule.activated | A schedule started its first phase. Its subscription arrives in subscriptionId. |
| Schedules | subscription_schedule.canceled | A schedule was canceled before it finished. |
| Schedules | subscription_schedule.released | A schedule released its subscription, which continues on its own. |
| Schedules | subscription_schedule.completed | A schedule finished its last phase. |
| Schedules | subscription_schedule.phase_transitioned | A schedule moved to its next phase. |
| Schedules | subscription_schedule.transition_failed | A schedule could not start a phase after exhausting its automatic retries. |
| Checkout | checkout_session.succeeded | A Checkout session completed successfully. |
| Transfers | mobile_transfer.received | An incoming SINPE Movil transfer was received. Only applies to merchants with a custom SINPE Movil number. |
| Disputes | dispute.created | A dispute was opened. If it is opened already resolved (won or lost), dispute.closed is sent too. |
| Disputes | dispute.updated | An open dispute's status changed, or the acquirer settled a dispute (acquirerPaidAt). |
| Disputes | dispute.closed | A dispute reached won or lost. If the outcome is reversed, another dispute.closed is sent with the new outcome. |
| Refunds | refund.created | ONVO accepted a refund, before it is sent to the processor. A request rejected with a 4xx error creates no refund and sends no events. |
| Refunds | refund.succeeded | A refund completed successfully. |
| Refunds | refund.failed | A refund failed definitively. |
| Payouts | payout.created | A payout was created. |
| Payouts | payout.paid | ONVO confirmed that a payout was paid. |
| Payouts | payout.failed | A payout failed after exhausting its automatic retries. |
For a payment completed across several transfers, payment_intent.succeeded is sent only once the full amount is received. Each partial transfer can produce its own mobile_transfer.received.
Fields by object
ONVO sends only the fields on this list. It never includes card numbers, tokens, full IBANs, identification numbers, or secrets.
Payment intent (payment_intent)
Sent by every payment_intent.* event.
| Field | Description |
|---|---|
id, amount, capturableAmount, receivedAmount, currency | Identifier and amounts of the intent. |
description, status, captureMethod | Description, status, and capture method. |
customerId, paymentMethodId | Related customer and payment method. |
metadata | The metadata you defined. |
lastPaymentError | Last payment error: type, code, message, and paymentMethodType. |
latestCharge | Latest charge: id, amount, currency, status, failureCode, failureMessage, createdAt, and updatedAt. |
createdAt, updatedAt | Creation and last update times. |
{
"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"
}
}
}
Subscription renewal (subscription_renewal)
| Field | Description |
|---|---|
invoiceId, subscriptionId, paymentIntentId | Invoice, subscription, and payment intent for the period. |
currency, total, attemptCount | Currency, total amount, and payment attempts. |
invoiceStatus, subscriptionStatus | Invoice and subscription status. |
periodStart, periodEnd | Billed period. |
lastPaymentAttempt, nextPaymentAttempt | Time of the last attempt and of the next one, if any. |
invoiceMetadata, subscriptionMetadata | Invoice and subscription metadata. |
error | On subscription_renewal.failed: type, code, message, and paymentMethodType. If the payment failed because of an internal error, it is { "type": "processing_error", "code": "renewal_failed", "message": "The renewal payment could not be processed." }, without paymentMethodType. It is omitted when there is no error. |
Subscription schedule (subscription_schedule)
Sent by every subscription_schedule.* event. It carries customerId, not the full customer.
| Field | Description |
|---|---|
id, status | Identifier and status: not_started, activating, active, completed, released, canceled, or error. |
customerId, subscriptionId | Related customer and subscription. |
endBehavior | What happens to the subscription when the last phase ends: release or cancel. |
defaultCollectionMethod, defaultPaymentMethodId, defaultDescription | Default values for the phases. |
metadata | The metadata you defined. |
startDate, releasedAt, canceledAt, completedAt | Start, release, cancellation, and completion times. |
lastTransitionedPhaseIndex, attemptedPhaseIndex, transitionAttempts, lastTransitionAt | Last phase started, phase it tried to start, phase change attempts, and time of the last change. Phases are numbered from 0; lastTransitionedPhaseIndex is -1 until one has started. |
version | Schedule version. It increases with every update and every phase change. |
phases | Phases: id, phaseIndex, startDate, endDate, iterations, trialEnd, description, collectionMethod, paymentMethodId, prorationBehavior, billingCycleAnchor, metadata, items (id, priceId, quantity, metadata, createdAt, and updatedAt), createdAt, and updatedAt. |
createdAt, updatedAt | Creation and last update times. |
subscription_schedule.transition_failed sends a partial object: id, status (error), attemptedPhaseIndex, transitionAttempts and, if a phase has already started, lastTransitionedPhaseIndex. It includes no dates and no error details.
For example, a schedule that could not move from its first phase to the second:
{
"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
}
}
}
Checkout session (checkout_session)
| Field | Description |
|---|---|
id, status, paymentStatus, paymentMode | Identifier and statuses of the session. |
amountSubtotal, amountTotal, currency | Session amounts. |
paymentIntentId, customerId, subscriptionId, paymentLinkId | Related objects. |
clientReferenceId, metadata | Your reference and your metadata. |
expiresAt, createdAt, updatedAt | Session times. |
SINPE Movil transfer (mobile_transfer)
| Field | Description |
|---|---|
id, status, amount, currency, description | Details of the received transfer. |
sinpeReference, authorizationDate | SINPE reference and authorization time. |
processor | Processor that reported the transfer. |
origin | Who sent the transfer: name, identificationLast4, and phoneLast4. The full identification and phone number are never sent. |
createdAt, updatedAt | Record times. |
Dispute (dispute)
| Field | Description |
|---|---|
id, amount, currency, description | Dispute details. |
status | needs_response, under_review, won, or lost. |
reason | Reported reason. |
responseDueAt | Response deadline. |
acquirerPaidAt | When the acquirer settled the dispute, if applicable. |
paymentIntentId, chargeId | Disputed payment. |
createdAt, updatedAt | Dispute times. |
In a marketplace, the events of a dispute on a payment made on behalf of a connected account (onBehalfOf) go to the platform account, even though the dispute belongs to the connected account.
A dispute opened already resolved sends dispute.created and then dispute.closed without previousAttributes. Otherwise, dispute.updated and dispute.closed include data.previousAttributes with the previous value of whichever of status, responseDueAt, and acquirerPaidAt changed.
A dispute's outcome can be reversed, for example from lost to won. ONVO then sends another dispute.closed, with the new outcome in status and the previous one in previousAttributes.status, at most one per outcome. Do not treat the first dispute.closed as final: compare its updatedAt or fetch the dispute from the API.
For example, a dispute that moves from under_review to 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"
}
}
}
Refund (refund)
| Field | Description |
|---|---|
id, amount, currency, description, reason | Refund details. |
status, type | Refund status and type. |
paymentIntentId, chargeId | Refunded payment. |
authorizationNumber, referenceNumber, transactionReference | Processor references, when available. |
failureReason, failure | On refund.failed: the code and a message. The possible codes are insufficient_funds, merchant_cannot_process, declined, and unknown. |
createdAt, updatedAt | Refund times. |
In a marketplace, the events of a refund on a payment made on behalf of a connected account (onBehalfOf) go to the platform account, even though the refund belongs to the connected account.
{
"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."
}
}
}
}
Payout (payout)
| Field | Description |
|---|---|
id, status, currency, description | Payout details. |
rail | Always local. |
payoutGross, payoutNet, payoutFee, fees, vatTax, incomeTax, retentions | Amounts in the currency's smallest unit, sent as strings so no precision is lost. |
transactionsCount, exchangeRate | Number of included transactions and exchange rate. |
reference | Payout reference. |
destination | Destination account: ibanLast4. The full IBAN is never sent. |
arrivedAt | When it was paid, if applicable. |
failure | On payout.failed: code (retries_exhausted: the payout exhausted its retries) and message. On other events it is null. |
createdAt, updatedAt | Creation time and time of the last status change. |
{
"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"
}
}
}
Test event
Test connection sends a webhook_endpoint.test event signed like every other event. You cannot subscribe to it, and it is not retried.
{
"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"
}
}
}