Skip to main content

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​

GroupEventWhen it happens
Paymentspayment_intent.succeededA payment intent succeeded. With manual capture, it is sent when the capture completes.
Paymentspayment_intent.failedA 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.
Paymentspayment_intent.canceledA payment intent was canceled, for example with the API.
Paymentspayment_intent.processingA 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.
Renewalssubscription_renewal.succeededA subscription renewal payment succeeded.
Renewalssubscription_renewal.failedA subscription renewal payment attempt failed. It is sent for each failed attempt, including the last one; attemptCount tells which one it was.
Schedulessubscription_schedule.createdA subscription schedule was created. If it is created from an existing subscription, it starts active and sends no subscription_schedule.activated.
Schedulessubscription_schedule.updatedA schedule's settings or upcoming phases changed.
Schedulessubscription_schedule.activatedA schedule started its first phase. Its subscription arrives in subscriptionId.
Schedulessubscription_schedule.canceledA schedule was canceled before it finished.
Schedulessubscription_schedule.releasedA schedule released its subscription, which continues on its own.
Schedulessubscription_schedule.completedA schedule finished its last phase.
Schedulessubscription_schedule.phase_transitionedA schedule moved to its next phase.
Schedulessubscription_schedule.transition_failedA schedule could not start a phase after exhausting its automatic retries.
Checkoutcheckout_session.succeededA Checkout session completed successfully.
Transfersmobile_transfer.receivedAn incoming SINPE Movil transfer was received. Only applies to merchants with a custom SINPE Movil number.
Disputesdispute.createdA dispute was opened. If it is opened already resolved (won or lost), dispute.closed is sent too.
Disputesdispute.updatedAn open dispute's status changed, or the acquirer settled a dispute (acquirerPaidAt).
Disputesdispute.closedA dispute reached won or lost. If the outcome is reversed, another dispute.closed is sent with the new outcome.
Refundsrefund.createdONVO accepted a refund, before it is sent to the processor. A request rejected with a 4xx error creates no refund and sends no events.
Refundsrefund.succeededA refund completed successfully.
Refundsrefund.failedA refund failed definitively.
Payoutspayout.createdA payout was created.
Payoutspayout.paidONVO confirmed that a payout was paid.
Payoutspayout.failedA 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.

FieldDescription
id, amount, capturableAmount, receivedAmount, currencyIdentifier and amounts of the intent.
description, status, captureMethodDescription, status, and capture method.
customerId, paymentMethodIdRelated customer and payment method.
metadataThe metadata you defined.
lastPaymentErrorLast payment error: type, code, message, and paymentMethodType.
latestChargeLatest charge: id, amount, currency, status, failureCode, failureMessage, createdAt, and updatedAt.
createdAt, updatedAtCreation 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)​

FieldDescription
invoiceId, subscriptionId, paymentIntentIdInvoice, subscription, and payment intent for the period.
currency, total, attemptCountCurrency, total amount, and payment attempts.
invoiceStatus, subscriptionStatusInvoice and subscription status.
periodStart, periodEndBilled period.
lastPaymentAttempt, nextPaymentAttemptTime of the last attempt and of the next one, if any.
invoiceMetadata, subscriptionMetadataInvoice and subscription metadata.
errorOn 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.

FieldDescription
id, statusIdentifier and status: not_started, activating, active, completed, released, canceled, or error.
customerId, subscriptionIdRelated customer and subscription.
endBehaviorWhat happens to the subscription when the last phase ends: release or cancel.
defaultCollectionMethod, defaultPaymentMethodId, defaultDescriptionDefault values for the phases.
metadataThe metadata you defined.
startDate, releasedAt, canceledAt, completedAtStart, release, cancellation, and completion times.
lastTransitionedPhaseIndex, attemptedPhaseIndex, transitionAttempts, lastTransitionAtLast 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.
versionSchedule version. It increases with every update and every phase change.
phasesPhases: id, phaseIndex, startDate, endDate, iterations, trialEnd, description, collectionMethod, paymentMethodId, prorationBehavior, billingCycleAnchor, metadata, items (id, priceId, quantity, metadata, createdAt, and updatedAt), createdAt, and updatedAt.
createdAt, updatedAtCreation 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)​

FieldDescription
id, status, paymentStatus, paymentModeIdentifier and statuses of the session.
amountSubtotal, amountTotal, currencySession amounts.
paymentIntentId, customerId, subscriptionId, paymentLinkIdRelated objects.
clientReferenceId, metadataYour reference and your metadata.
expiresAt, createdAt, updatedAtSession times.

SINPE Movil transfer (mobile_transfer)​

FieldDescription
id, status, amount, currency, descriptionDetails of the received transfer.
sinpeReference, authorizationDateSINPE reference and authorization time.
processorProcessor that reported the transfer.
originWho sent the transfer: name, identificationLast4, and phoneLast4. The full identification and phone number are never sent.
createdAt, updatedAtRecord times.

Dispute (dispute)​

FieldDescription
id, amount, currency, descriptionDispute details.
statusneeds_response, under_review, won, or lost.
reasonReported reason.
responseDueAtResponse deadline.
acquirerPaidAtWhen the acquirer settled the dispute, if applicable.
paymentIntentId, chargeIdDisputed payment.
createdAt, updatedAtDispute 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)​

FieldDescription
id, amount, currency, description, reasonRefund details.
status, typeRefund status and type.
paymentIntentId, chargeIdRefunded payment.
authorizationNumber, referenceNumber, transactionReferenceProcessor references, when available.
failureReason, failureOn refund.failed: the code and a message. The possible codes are insufficient_funds, merchant_cannot_process, declined, and unknown.
createdAt, updatedAtRefund 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)​

FieldDescription
id, status, currency, descriptionPayout details.
railAlways local.
payoutGross, payoutNet, payoutFee, fees, vatTax, incomeTax, retentionsAmounts in the currency's smallest unit, sent as strings so no precision is lost.
transactionsCount, exchangeRateNumber of included transactions and exchange rate.
referencePayout reference.
destinationDestination account: ibanLast4. The full IBAN is never sent.
arrivedAtWhen it was paid, if applicable.
failureOn payout.failed: code (retries_exhausted: the payout exhausted its retries) and message. On other events it is null.
createdAt, updatedAtCreation 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"
}
}
}