Skip to main content

Webhook Event Reference

Every webhook Von Payments delivers shares the same envelope. The type field tells you which event it is; the data field holds the per-event payload. Subscribe only to the event types on this page: the dashboard picker at /dashboard/developers/webhooks can list more than it. New event types and new data fields may appear without an SDK version bump — treat an unknown type as a no-op (return 200, log, do not raise) and ignore unknown keys.

Envelope​

Every event Von Payments delivers is wrapped in the same envelope:

{
"id": "vp_evt_live_8x4n2pq7m1",
"type": "charge.succeeded",
"created": 1728936000,
"livemode": true,
"merchant_id": "b6b8d25f-80d5-4b31-8ac6-fd3c5727c4ce",
"data": { "...": "per-event payload — see the sections below" }
}
FieldTypeNotes
idstringUnique per outbound event. Use this for idempotent processing — the same event ID is never delivered twice with different payloads.
typestringEvent type from the catalog below.
createdintegerUnix seconds when Von Payments emitted the event. For replay-window enforcement, compare against the t= field inside the x-vonpay-signature header (there is no separate timestamp header).
livemodebooleantrue for events on a live key; false for every event on a test key, real test payments included. It does not tell you an event came from Send test event: check test_event for that.
test_eventtrue, or absentPresent only on an event from Send test event (the dashboard button, or POST /v1/webhook_subscriptions/{id}/send_test_event), and then always true. Absent, never false, on every real event. Check it first, before any lookup or write, and return 2xx without doing anything else: a test event sent for a session carries that session's real ids, a live session's included, so the rest of the payload can look like a real payment.
merchant_idstringThe merchant the event belongs to (a UUID). On a multi-tenant platform integrator, route on this value.
dataobjectPer-event payload. Shape is fixed per type; see sections below.

All amounts in minor units (cents for USD, pence for GBP, etc.). All currency codes uppercase ISO-4217. All timestamps as unix seconds.

Charge events​

The charge.* family fires for the card-charge lifecycle when a session reaches settlement (or a direct /v1/payment_intents charge succeeds without a session wrapper).

charge.succeeded​

A charge completed successfully. Fires after the buyer finishes checkout and the processor confirms the charge, and when you capture a held (manual-capture) payment, with amount the amount captured.

{
"id": "vp_evt_live_8x4n2pq7m1",
"type": "charge.succeeded",
"created": 1728936000,
"livemode": true,
"merchant_id": "b6b8d25f-80d5-4b31-8ac6-fd3c5727c4ce",
"data": {
"session_id": "vp_cs_live_kJq7Lp...",
"payment_intent_id": "vpi_live_9f2ndx7k...",
"transaction_id": "7c1f4e2a-9b3d-4f60-8e5a-2d1c0b9a8f7e",
"vp_tx_id": "vp_tx_live_9f2nd...",
"amount": 1499,
"currency": "USD",
"card": { "brand": "visa", "last4": "4242" },
"payment_method_id": null,
"network_transaction_id": "381234567890123"
}
}
data fieldTypeDescription
session_idstring | nullThe session this charge belongs to. Null for direct-charge flows that do not go through /v1/sessions.
payment_intent_idstring | nullPayment intent (vpi_*) this charge settled. Null on hosted-direct flows that never minted an intent. POST /v1/refunds takes it as payment_intent.
vp_tx_idstring | nullThe Von transaction id. Reconcile and refund on this. It is the value the SDK's submit result returns as transactionId, the id your dashboard's transaction list shows, and what POST /v1/refunds takes as transaction. null on a vault-forward charge (its settlement row cannot be named) and whenever the settlement row could not be read at delivery time; the event is still sent. When it is null, key on payment_intent_id instead.
vp_tx_id_sourcestring | nullHow vp_tx_id was matched to this payment. payment_intent: it is this charge's own transaction. session: it was found only through the checkout session, so it is the session's first recorded payment. On a checkout paid more than once, that can be a different charge. Do not repair or re-link an order from a session value: match on payment_intent_id, and read the payment with GET /v1/payment_intents/{id}. null exactly when vp_tx_id is null.
transaction_idstring | nullThe card processor's reference for the charge, not a Von id. On Embedded Fields, hosted checkout and every asynchronously settled payment it is the processor's transaction id (a UUID on one connection, a pi_… reference on another); in the sandbox it is sbx_pi_*. Every event about one charge carries the same value, so it correlates events with each other. It is not the vp_tx_* your dashboard shows: never match it against your transaction list or pass it to a refund. Use vp_tx_id.
amountintegerAmount charged, in minor units.
currencystringISO-4217 uppercase.
cardobject | nullPCI-safe card presentation — { "brand": ..., "last4": ... }. brand is one of visa, mastercard, amex, discover, diners, jcb, unionpay, unknown; last4 is 4 digits. null when not available for this payment. Always present: an empty card is sent as null. Older deliveries left the key out, so treat a missing card the same as null. No PAN, BIN, or fingerprint is ever included.
avs_result_codestring | nullNormalized Address Verification (AVS) result — match, partial_postal, partial_address, no_match, unavailable, or not_supported. null when no billing address was sent or no result was returned.
cvv_result_codestring | nullNormalized card security-code result — match, no_match, not_provided, or unavailable.
payment_method_idstring | nullThe saved card (vp_pmt_*) this payment stored, to charge again with POST /v1/payment_intents payment_method: { id }. null when nothing was saved, for example a guest payment.
network_transaction_idstring | nullThe card network's own identifier for the charge (Visa's Transaction Identifier, Mastercard's trace id). Store it exactly as received if you keep your own records of stored cards. It can be null here even for a card charge, because some connections report it only after this event: read it later from GET /v1/payment_intents/{id}. Only this event and payment_intent.succeeded carry it.
processor_connectionobject | nullWhich of your payment connections processed this payment, as { id, name }. The same value as on the payment intent. null when no connection was reached.

charge.failed​

A charge attempt failed. Includes a failure_reason describing the decline.

{
"id": "vp_evt_live_3x8m1q4r5s",
"type": "charge.failed",
"created": 1728936010,
"livemode": true,
"merchant_id": "b6b8d25f-80d5-4b31-8ac6-fd3c5727c4ce",
"data": {
"session_id": "vp_cs_live_pK7nLm...",
"payment_intent_id": "vpi_live_8d4nex2p...",
"transaction_id": "d2e5b7c1-3a9f-4e08-b6c4-1f0a2d3e4b5c",
"vp_tx_id": null,
"amount": 1499,
"currency": "USD",
"failure_reason": "Your card was declined.",
"failure_code": "card_declined",
"decline_code": "card_declined",
"action": "generic",
"decline_message": "The card was declined. Please use a different payment method.",
"network_decline_code": "05",
"rule_code": null,
"retry": { "allowed": true, "attempts_remaining": 2 },
"card": { "brand": "visa", "last4": "4242" }
}
}

failure_code is the normalized decline code (card_declined, insufficient_funds, expired_card, fraudulent, processing_error, …) you should branch on; decline_code carries the same value under the API response's name, so one handler can read both surfaces by one key. action is the retry classification — soft / hard / fix_and_retry / generic — from the same published mapping the API response uses. network_decline_code is the raw issuer code (05, 51, …); rule_code names which of your own provider rules refused the charge, and is null unless failure_code is blocked_by_rule. All seven are string | null. The five derived from the normalized decline code — failure_code, decline_code, action, decline_message and rule_code — are populated or null together, so handle the whole block being absent rather than testing one field. card carries the PCI-safe { brand, last4 }, or null when not available — same shape and the same missing-key rule as on charge.succeeded. vp_tx_id (and vp_tx_id_source with it) is always null here: a declined charge writes no settlement row, and the key is present so the charge.* payloads share one shape. transaction_id is the processor's reference for the attempt, when it reported one.

network_advice is the card network's own advice about this card: stop_recurring (the cardholder cancelled recurring payments to you: stop the arrangement), do_not_try_again, try_again_later (the shortest wait, when the network named one, is in network_advice_retry_after_ms) or confirm_card_data. It means the same as on the payment intent. It is null when the network gave no advice we can read, including every payment on the hosted checkout page, and null is never permission to retry. A decline we learn about only from the provider's later notice carries at most stop_recurring, so read the payment intent for the full reading. Both fields are also on payment_intent.failed and session.failed. processor_connection names the payment connection, as on charge.succeeded. On this event it can be null even when the attempt reached a connection, because the event can be sent before every detail of the decline is known. The connection is filled in afterwards (usually within seconds, not guaranteed), and the decline code can be corrected at the same time. The event is a snapshot of the moment it was sent: read GET /v1/payment_intents/{id} when you need the current values.

Show decline_message to the buyer; keep failure_reason for your logs. failure_reason is written for you, and for fraudulent, stolen_card and lost_card it states the signal outright; decline_message gives those the ordinary decline copy. See Showing a decline to the buyer and rule declines.

A failed charge is not always the end of the checkout​

Before you cancel an order, release stock or email the buyer on a failure event, read retry. On accounts with retry on the same session switched on, a declined buyer can try another card on the same checkout session, including after the bank refuses the payment on its 3-D Secure page. A failure event is sent for each declined attempt, so a buyer who tries a second card and succeeds produces a charge.failed followed by a charge.succeeded.

retry is on charge.failed, payment_intent.failed and session.failed, with the same meaning on all three. It describes the session after this decline was handled, and agrees with retry on GET /v1/sessions/{id}:

retryWhat it meansWhat to do with the order
{ "allowed": true, "attempts_remaining": n }The session is open again and the buyer can pay with another card.Keep it open. If the buyer pays, charge.succeeded follows. If they leave, nothing more is sent: close the session (below) before you cancel.
{ "allowed": false, "attempts_remaining": n }, n above 0Open again; the form for the next card is still being prepared (about a second).Keep it open, as above.
{ "allowed": false, "attempts_remaining": 0 }No more cards can be tried on this session.Close the session (below) before you cancel.
nullThis field does not decide it: retry on the same session is not switched on for your account, the session's card form is not on your own page (an elements or embed session; the hosted checkout page has its own retry), the decline handed the session back without using up an attempt (it can still be paid), the event is about an earlier attempt, or the session has since expired (a bank check that timed out: the session reads expiredFrom: "failed", which is final).Not final by itself. Read GET /v1/sessions/{id} before you cancel; a session can still take a payment until it succeeds or expires (session rules).

Close the session before you cancel the order. Call POST /v1/sessions/{id}/expire. A 200 means no payment is in progress on it and none can start, so cancelling is safe. A 409 means not yet: with reason: "recent_activity", call again after retryAfterSeconds; with payment_may_be_in_flight, do not cancel, and wait for the payment webhook.

The same event can arrive more than once with the same id, so deduplicate on id as usual.

charge.refunded​

A charge was refunded — full or partial. Fires once per refund record. A fully-refunded charge that was issued in two partial refunds fires this event twice.

charge.refunded does not always mean the refund completed. On one card connection it can arrive while the refund is still pending, and a pending refund can still fail. Before you treat the money as back with the buyer, read the refund with GET /v1/refunds: succeeded means done, requested means still in progress.

{
"id": "vp_evt_live_7t6r5w4v3u",
"type": "charge.refunded",
"created": 1729022400,
"livemode": true,
"merchant_id": "b6b8d25f-80d5-4b31-8ac6-fd3c5727c4ce",
"data": {
"session_id": "vp_cs_live_kJq7Lp...",
"payment_intent_id": "vpi_live_9f2ndx7k...",
"transaction_id": "7c1f4e2a-9b3d-4f60-8e5a-2d1c0b9a8f7e",
"vp_tx_id": "vp_tx_live_9f2nd...",
"refund_id": "vpr_live_3kQpL2nM...",
"amount": 500,
"currency": "USD",
"reason": "customer_request",
"is_partial": true,
"original_charge_amount": 1499,
"card": { "brand": "visa", "last4": "4242" }
}
}
data fieldTypeDescription
payment_intent_idstring | nullPayment intent (vpi_*) of the original charge.
vp_tx_idstring | nullThe Von transaction id of the refunded charge, the same value its charge.succeeded carried. Match this refund to the charge on it. transaction_id is the processor's reference, as on every event.
vp_tx_id_sourcestring | nullHow vp_tx_id was matched to the refunded payment. Same values and meaning as on charge.succeeded: match on it only when it says payment_intent.
refund_idstring | nullRefund record id (vpr_*) — identifies WHICH refund in a multi-partial sequence this event references.
amountinteger⚠️ Meaning varies by processor connection — do not sum it. On some connections it is this refund; on others it is the running total refunded so far. They agree only on the first refund. Kept for backward compatibility; use refund_amount / amount_refunded_total below.
refund_amountinteger | nullThis refund only, unambiguously, on every connection. null means the connection could not derive it — which is different from 0.
amount_refunded_totalinteger | nullCumulative refunded so far for the charge, including this refund, on every connection. Failed refunds are never counted; a refund still processing on the same charge is. Compare this against original_charge_amount to decide "fully refunded". null only in the rare case our records could not be read when the event was built: treat it as unknown, never as zero, and look the payment up through the API rather than rejecting the event.
reasonstring | nullRefund reason: customer_request, duplicate, fraudulent, abandoned_payment_reversed or other. Any other value arrives as other; null when none was given. abandoned_payment_reversed means Von Payments gave the money back automatically, on a payment that already reads cancelled or failed and never sent you charge.succeeded. It is sent for a refund and for a released hold (then refund_id and vp_tx_id are null). Reconcile it; do not refund it again.
is_partialboolean | nullWhether this refund was for less than the full charge. ⚠ Do not use it to decide whether a charge is now fully refunded — see the note below.
cardobject | nullPCI-safe { brand, last4 } of the refunded card, or null when not available — same shape and the same missing-key rule as on charge.succeeded.
original_charge_amountinteger | nullFull charge total before any refund — lets you compute the remaining refundable balance without a round-trip.
processor_connectionobject | nullWhich of your payment connections processed this payment, as { id, name }. The same value as on the payment intent. null when no connection was reached.
Work out "fully refunded" from amount_refunded_total, never from is_partial or by summing amount

is_partial describes this one refund and is derived differently across providers — a second refund that completes the total can still report is_partial: true. amount is this refund on some connections and the running total on others, so summing it over-counts: a 100 charge refunded 60 then 30 can sum to 150. Compare amount_refunded_total on the latest event against original_charge_amount; if you need a delta, use refund_amount.

A refund you did not issue​

A checkout session takes one payment. If a second payment is captured anyway on a session that is already paid (for example a payment form left open in another tab), Von Payments refunds that second payment in full automatically. You receive an ordinary charge.refunded, and reason does not mark it. Recognise it this way: the event's session_id names a session whose completed payment is a different transaction (the vp_tx_id the session read returns, and the first charge.succeeded for that session), and the refund is the full amount of the second payment. The first payment is never touched, and the second never creates a store order. Do not charge the buyer again or open a new session: they have paid once. In GET /v1/refunds this refund has idempotency_key: null. A second payment that was only a hold is released instead, which sends payment_intent.cancelled.

This covers checkout sessions paid through the embedded card form and the hosted payment page. If you see two payments on one checkout session and no automatic refund follows within a few minutes, contact support with the session id.

refund.failed​

A refund you issued did not complete. The buyer has not been paid back, and the refund needs attention.

Switched on for you: like the dispute events, refund.failed is delivered to every active subscription whether or not you selected it. Listing it in enabledEvents is still accepted and changes nothing. Handle it (a 2xx is enough) rather than rejecting an event type you did not subscribe to.

A processor may report that outcome under more than one name. A refund that failed and a refund that was declined are both terminal, both mean the same thing to you (no money went back), and both arrive here. There is no separate declined event to subscribe to.

This is the failure twin of charge.refunded and deliberately mirrors its shape (including vp_tx_id, the Von transaction id of the charge), so you can reuse the same row mapping. It adds two fields: reason_code and retry_available.

Every key is always present; a value that is not known is null. No money moved on this event: amount is the refund amount that failed to move, and amount_refunded_total counts only the charge's other refunds, so the failed amount is never in it.

{
"id": "vp_evt_live_2k9m4x7p1q",
"type": "refund.failed",
"created": 1729022400,
"livemode": true,
"merchant_id": "b6b8d25f-80d5-4b31-8ac6-fd3c5727c4ce",
"data": {
"session_id": "vp_cs_live_kJq7Lp...",
"payment_intent_id": "vpi_live_9f2ndx7k...",
"transaction_id": "7c1f4e2a-9b3d-4f60-8e5a-2d1c0b9a8f7e",
"vp_tx_id": "vp_tx_live_9f2nd...",
"refund_id": "vpr_live_3kQpL2nM...",
"amount": 500,
"refund_amount": 500,
"amount_refunded_total": 0,
"currency": "USD",
"reason": "customer_request",
"reason_code": "refund_declined",
"is_partial": true,
"original_charge_amount": 1499,
"retry_available": true,
"card": null
}
}
data fieldTypeDescription
refund_idstring | nullRefund record id (vpr_*) — identifies which refund failed. null when we hold no refund record for it.
amountinteger | nullThe refund amount that failed to move, in minor units; the original charge amount only when the failure notice carried no amount. Nothing was transferred.
refund_amountinteger | nullThe amount this failed refund tried to move. null on a failed refund of a connected-store order: read amount there.
amount_refunded_totalinteger | nullRefunded against the charge so far by its other refunds. Unlike on charge.refunded, the amount on this event is never included, because it did not move. null on a failed refund of a connected-store order, and when it could not be read at the time: treat that as unknown, not zero.
reasonstring | nullThe refund's reason: customer_request, duplicate, fraudulent or other. null when none was supplied.
reason_codestring | nullWhy it failed. Branch on this — see below.
retry_availableboolean | nullWhether retrying is a supported action for this failure. false when the payment was disputed (the buyer already has the money back through the chargeback, so do not retry or refund another way), and when the account that took the payment is no longer connected to you.
is_partialboolean | nullWhether this refund was for less than the full charge. ⚠ Do not use it to decide whether a charge is now fully refunded — see the note under charge.refunded.
original_charge_amountinteger | nullFull charge total before any refund.
cardobject | nullAlways null on this event today.

session_id, payment_intent_id, transaction_id, vp_tx_id, vp_tx_id_source and currency mean the same as on charge.refunded; transaction_id is null on a failed refund of a connected-store order.

Branch on reason_code​

reason_codeWhat happenedWhat is safe to do
refund_declinedWe attempted the reversal and the provider refused it outright.Retrying unchanged will fail the same way. Find out why before retrying.
refund_not_receivedThe refund's outcome was not known, and our check with the provider found it never received it. The refund is canceled and no money moved; retry_available is true.Refund it again under a new Idempotency-Key.
refund_unresolvedNot sent today: this event currently carries only refund_declined or refund_not_received. The value stays in the set, and means we attempted the reversal and never got an answer: the money may or may not have moved.Do not retry blind: reissuing a refund that silently succeeded pays the buyer twice. Contact support to establish what happened before you retry.

A refund whose outcome is not known yet is answered 202 with status: "requested" on your POST /v1/refunds call. It ends in charge.refunded, in this event with refund_not_received, or is confirmed by our team; refund_not_received is not sent for every unknown refund (A 202 is not a failure). The vocabulary is an open set: handle an unrecognised value as "this refund needs a human" — surface it, do not auto-retry.

Connected-platform events​

mirror.order.created​

Fires when a mirrored payment has created the corresponding order in your connected store. Selectable in the dashboard picker under Connected platforms.

FieldTypeDescription
payment_intent_idstring | nullThe payment this order was mirrored from — use it to correlate with charge.succeeded.
order_numberstring | nullThe number the shopper and your store staff see: on Shopify the order name (for example #1001), elsewhere the platform's order number. A Shopify order created before 28 September 2026, or one recovered by an automatic retry, can carry the store's internal numeric id instead.
order_status_urlstring | nullWhere the buyer can view the order in your store. A private link: anyone holding it can see that order, including the shopper's name and address, so show it only to that shopper and do not log, store or share it.

A mirror can fail without this event firing, and a failed mirror never reverses the charge — do not treat its absence as "the payment failed". To check one charge, poll the mirror-order endpoint for the flow you used; see Connected Platforms.

Payment intent events​

The payment_intent.* family fires for the discrete-lifecycle API (POST /v1/payment_intents). If your integration uses the hosted-checkout sessions flow only, you can ignore these. If you call paymentIntents.create directly via the SDK, these are the events that confirm terminal state. Each one carries processor_connection, the payment connection that processed the payment, as on charge.succeeded.

payment_intent.succeeded​

A payment intent reached terminal succeeded status.

{
"id": "vp_evt_live_5p3q2t1u8v",
"type": "payment_intent.succeeded",
"created": 1728936000,
"livemode": true,
"merchant_id": "b6b8d25f-80d5-4b31-8ac6-fd3c5727c4ce",
"data": {
"session_id": null,
"payment_intent_id": "vpi_live_abc123x7...",
"transaction_id": "a4c8e1f3-7b2d-4d95-8e60-5c1b9a7d2f3e",
"amount": 1499,
"currency": "USD",
"payment_method_id": null,
"network_transaction_id": "381234567890123"
}
}

session_id is null for payment intents created outside the hosted-checkout flow. payment_method_id is the same saved-card id charge.succeeded carries, null when nothing was saved. network_transaction_id is the same card-network id as on charge.succeeded, and can likewise be null when the network reports it late.

payment_intent.failed​

A payment intent reached terminal failed status.

{
"id": "vp_evt_live_9w8x7y6z1a",
"type": "payment_intent.failed",
"created": 1728936010,
"livemode": true,
"merchant_id": "b6b8d25f-80d5-4b31-8ac6-fd3c5727c4ce",
"data": {
"session_id": null,
"payment_intent_id": "vpi_live_xyz789k2...",
"transaction_id": "e9b1d4a7-2c6f-4a13-9d58-7f3e0c2b1a6d",
"amount": 1499,
"currency": "USD",
"failure_reason": "Your card was declined.",
"failure_code": "card_declined",
"network_decline_code": "05",
"rule_code": null,
"retry": null
}
}

It carries the same decline fields as charge.failed, including retry: it is not final unless retry is { allowed: false, attempts_remaining: 0 }, and even then close the session before you cancel.

payment_intent.authorized​

The card was authorized on a manual-capture payment and the money is held, not taken. It is the only notification that a hold exists, and it never fires for an automatic-capture payment.

{
"id": "vp_evt_live_7k6j5h4g3f",
"type": "payment_intent.authorized",
"created": 1728936005,
"livemode": true,
"merchant_id": "b6b8d25f-80d5-4b31-8ac6-fd3c5727c4ce",
"data": {
"session_id": null,
"payment_intent_id": "vpi_live_ghi012p4...",
"transaction_id": "f2a9c6e1-3b7d-4e58-9a14-6d0c8b5e2f7a",
"amount": 1499,
"currency": "USD",
"capture_required": true
}
}

capture_required is always true, and amount is what may be captured, not what has been. There is no payment_method_id yet: a saved card is stored at capture and arrives on payment_intent.succeeded. Capture or void the hold before it lapses at the card's bank (roughly 7 days on Mastercard, American Express and Discover, about 5 days on a Visa merchant-initiated payment, and as little as 2 days for a card-present payment). Treat the shortest of those as your deadline unless you know the card brand.

If you do not capture in time, the sale is lost. The bank releases the held money to the buyer, nothing is charged, and you cannot capture the hold any more. To be paid, take a new payment from the buyer. A lapse may not be reported to you, so keep your own deadline: status: "authorized" alone does not prove that the hold is still good, and a capture that the payment connection refuses leaves the payment intent at authorized.

It is sent once per payment, when the hold is placed (directly, or after the buyer completes 3-D Secure), for a manual-capture payment made through POST /v1/payment_intents, the hosted checkout page on a captureMethod: "manual" session, the embedded payment fields in elements mode, or a wallet payment on those fields. Some payment connections do not send it yet; GET /v1/payment_intents/{id} still shows status: "authorized" on those.

When you capture the hold, charge.succeeded and payment_intent.succeeded are sent, once each; on a partial capture their amount is the amount captured. De-duplicate on the event id: each has one id however the capture is recorded.

payment_intent.cancelled​

A payment intent ended with no money taken. Sent in two cases: an authorized hold is voided before capture (the intent reads voided), or a payment still waiting on the bank's security check (3-D Secure) is cancelled, when the shopper closes a wallet's bank-check window (the intent reads cancelled). There is no charge.* event alongside it. cancellation_reason is merchant_cancel for a void (yours, or one we make for you), and buyer_abandoned when the shopper closed the bank-check window. One payment connection can pass its own reason through instead, so treat the field as an open set and never fail on a value you do not recognise.

{
"id": "vp_evt_live_2b1c4d3e5f",
"type": "payment_intent.cancelled",
"created": 1728936020,
"livemode": true,
"merchant_id": "b6b8d25f-80d5-4b31-8ac6-fd3c5727c4ce",
"data": {
"session_id": null,
"payment_intent_id": "vpi_live_def456m9...",
"transaction_id": "c3f7a2d9-5e1b-4c84-a7d2-9b0e6f4a3c1d",
"amount": 1499,
"currency": "USD",
"cancellation_reason": "buyer_abandoned"
}
}

payment_intent.held_for_review​

Opt-in: delivered only to an endpoint that lists it by name in its events.

The fraud filter on your own payment processor account is holding a payment until you approve or decline it there. The payment has not completed and we have not cancelled it: only you can move it. Do not fulfill on this event. Approve or decline the payment in your processor account before review_deadline, or the processor expires it and the sale is lost. While it is held, GET /v1/payment_intents/{id} shows status: "requires_action". It is sent for a hosted checkout payment too, not only a direct payment intent, so subscribe to it even if you otherwise ignore this family.

{
"id": "vp_evt_live_8d3f6a2c1b",
"type": "payment_intent.held_for_review",
"created": 1791189337,
"livemode": true,
"merchant_id": "b6b8d25f-80d5-4b31-8ac6-fd3c5727c4ce",
"data": {
"session_id": "vp_cs_live_k7x9m2n4p3q8",
"payment_intent_id": "vpi_live_rev381t5...",
"transaction_id": "7e2b9c41-6d3a-4f80-b5c7-2a9d8e1f4b63",
"amount": 2999,
"currency": "USD",
"review_reason": "processor_fraud_filter",
"review_opened_at": 1791102937,
"review_deadline": 1791534937
}
}
FieldTypeDescription
session_id, payment_intent_id, transaction_id, amount, currencyAs on payment_intent.succeeded. amount is the held payment, which has not completed.
review_reasonstring | nullWhy the payment is held. processor_fraud_filter: your processor said its fraud filter is holding the payment for your review. processor_no_response: your processor has not answered for over a day and gave no reason; check the payment in your processor account, where it is most likely held for review. Handle a value you do not recognise like processor_no_response.
review_opened_atinteger | nullWhen the hold started, in Unix seconds. Use this, not the envelope's created.
review_deadlineinteger | nullUnix seconds. Decide before this time: 5 days after the hold started for a payment held before authorization, 30 days for one authorized and then held; when the processor does not say which, the earlier deadline is given. null with processor_no_response: treat 5 days after review_opened_at as the limit.

It is sent once per payment, at least a day after the hold started; de-duplicate on the event id. It goes only to the endpoints subscribed when it is sent, so an endpoint added after that does not receive it, and it is not sent for a hold first found more than a day past its deadline. There is no closing event: your decision arrives as the normal outcome, payment_intent.succeeded and charge.succeeded when you approve, payment_intent.failed and charge.failed when you decline or the processor expires it.

Saved-card events​

payment_method.attached​

Opt-in: delivered only to an endpoint that lists it by name in its events; it is never added to an existing endpoint for you.

A saved card was linked to a payment after the payment was already reported as succeeded without it. Normally a card the buyer saves is linked before charge.succeeded and payment_intent.succeeded are sent, and both carry it as payment_method_id. Rarely, after a 3-D Secure check, the card cannot be linked in time, for example when the payment went through the bank's security-check page and the payment processor had not yet confirmed it stored the card. The payment is then reported on time with payment_method_id: null, and this event follows once the card is linked, usually within minutes. A card the processor says it never stored is never linked, and no event is sent. It is never sent when the success events already carried the card, and at most once per payment and card: de-duplicate on the event id. Until you subscribe to it, read the card back with GET /v1/payment_intents/{id}.

{
"id": "vp_evt_live_7c2d4e9f1a",
"type": "payment_method.attached",
"created": 1728936100,
"livemode": true,
"merchant_id": "b6b8d25f-80d5-4b31-8ac6-fd3c5727c4ce",
"data": {
"session_id": "vp_cs_live_k7x9m2n4p3q8",
"payment_intent_id": "vpi_live_def456m9...",
"payment_method_id": "vp_pmt_live_3xK9vQ2mNp7wRtY4",
"card": { "brand": "visa", "last4": "4242" },
"setup_for_future_use": "off_session",
"setup_for_future_use_method": "checkbox",
"vp_buyer_id": "vp_by_live_3f9a1c2b7d4e6f80"
}
}
FieldTypeDescription
session_idstring | nullThe checkout session the payment belonged to, when it had one.
payment_intent_idstring | nullThe payment (vpi_*) the card was linked to.
payment_method_idstring | nullThe saved card (vp_pmt_*), the same value GET /v1/payment_intents/{id} now returns as payment_method_id.
cardobject | null{ brand, last4 } of the saved card; null when they are not known.
setup_for_future_usestring | nullHow the card may be charged again: on_session or off_session; null when it was saved for single use.
setup_for_future_use_methodstring | nullHow the buyer agreed to that reuse, as stored on the card: checkbox, checkout_terms or platform_disclosure; the same value GET /v1/payment_methods returns. null when it was not recorded. More values may be added: treat one you do not recognise as "recorded, method unknown". See Recurring & saved cards.
vp_buyer_idstring | nullThe buyer (vp_by_*) the card belongs to, including one Von Payments created for the session. Read it with GET /v1/buyers/{id}. null when the card has no buyer. Not your own customer reference, which is buyer_id on other events. Events sent before this field existed leave it out: treat a missing key as null.

Session events​

The session.* pair is sent only for a payment made on the checkout page we host (the redirect flow). It is not sent for a session paid through the embedded payment fields (integrationMode: "elements"), a wallet button, or a hold you capture later, and never for a payment made directly through POST /v1/payment_intents. For those, use charge.succeeded / payment_intent.succeeded and charge.failed / payment_intent.failed. Use the session.* pair when you track the buyer's hosted checkout rather than the charge underneath it.

session.succeeded​

The buyer completed the hosted checkout. Delivered once per session, even if the confirmation is retried.

{
"id": "vp_evt_live_4n3m2l1k9j",
"type": "session.succeeded",
"created": 1728936030,
"livemode": true,
"merchant_id": "b6b8d25f-80d5-4b31-8ac6-fd3c5727c4ce",
"data": {
"session_id": "vp_cs_live_k7x9m2n4p3",
"payment_intent_id": null,
"transaction_id": "a4c8e1f3-7b2d-4d95-8e60-5c1b9a7d2f3e",
"amount": 1499,
"currency": "USD"
}
}

It carries the core of charge.succeeded without the card details, the saved card or vp_tx_id. Fulfill and refund against the matching charge.succeeded, which carries those. payment_intent_id is null when the session made no payment intent.

session.failed​

A payment attempt on the session was declined. Sent once per declined attempt, so a buyer who tries two cards produces two (and, like every event, it can be redelivered with the same id). The fields match charge.failed (the decline reason, decline_code, action, decline_message, network_decline_code, rule_code and retry), except vp_tx_id, vp_tx_id_source, card, avs_result_code, cvv_result_code and processor_connection, which it does not send. A session.failed does not mean the checkout failed unless retry is { allowed: false, attempts_remaining: 0 }; otherwise the buyer can still pay on it. Close the session before you cancel.

Dispute events​

dispute.created, dispute.won, dispute.lost​

Switched on for you: delivered to every active subscription whether or not you selected them — they are not in the dashboard picker, and an endpoint registered for charge.* alone still receives them, so handle them like any type you did not ask for. A subscription is still required. created fires when the processor notifies us that a cardholder has disputed a payment; won and lost as the dispute resolves. All three share one payload, and every key is always present: a value that is not known is null.

FieldTypeDescription
dispute_idstring | nullThe dispute, as the processor identifies it. The same id on dispute.created and on the later dispute.won / dispute.lost: key your dispute record on it.
transaction_idstring | nullThe processor's reference for the disputed charge. It can differ from the transaction_id that payment's charge.* events carried, so it is a fallback, not a key. Not a vp_tx_* id; see charge.succeeded.
payment_intent_idstring | nullThe disputed payment (vpi_*). null when the payment had none, or the dispute cannot be matched to exactly one payment.
session_idstring | nullThe checkout session (vp_cs_*) the payment belongs to. null when unmatched, or when the payment had no session.
buyer_idstring | nullYour own customer reference for the payment: the buyerId you sent when creating the session or, without a session, the external id of the buyer the payment was made for. null when the payment carried none, or the dispute cannot be matched to exactly one payment.
amountinteger | nullThe disputed amount, in minor units; the original charge amount when the dispute notice states none.
currencystring | nullISO 4217. Not case-normalized on this event: compare case-insensitively.

Match a dispute to your order with payment_intent_id or session_id. buyer_id tells you whose payment it is, which narrows the search, but one buyer can have many payments, so never match on it alone. When all three are null the dispute could not be matched to exactly one payment: fall back to transaction_id together with the amount, and send anything still unmatched to a person. There is no vp_tx_id on this family. The events are raised from the processor's own dispute notification, so they arrive only on connections that send us one: check dispute_reporting before relying on them as your only chargeback detector.

Fraud alerts​

merchant.card_testing_suspected​

Your checkout is showing a card-testing pattern: someone appears to be running stolen or guessed card details through it. This is a warning only. Nothing was blocked, the payments ran as normal, and blocked is always false. Review the payments in the window, and hold fulfillment of any approved ones you do not recognise.

You have to select it. It is delivered only to an endpoint whose enabledEvents names it. In the dashboard picker it is under Fraud alerts.

It covers live payments only, made by your customers (your own scheduled charges, such as renewals, are not counted). It is sent at most once per hour while the pattern continues, so a three-hour attack sends three. Deduplicate on id as usual.

{
"id": "vp_evt_live_6c2v8b1n4m",
"type": "merchant.card_testing_suspected",
"created": 1728939600,
"livemode": true,
"merchant_id": "b6b8d25f-80d5-4b31-8ac6-fd3c5727c4ce",
"data": {
"patterns": ["expiry_enumeration", "refusal_burst"],
"window_start": 1728936000,
"window_end": 1728939600,
"attempts": 39,
"refused": 28,
"accepted": 0,
"distinct_cards": 13,
"card": { "brand": "mastercard", "last4": "4444" },
"expiry_variants": 13,
"blocked": false
}
}
data fieldTypeDescription
patternsstring[]Which pattern was seen; one or both. expiry_enumeration: one card number tried with many different expiry dates. refusal_burst: a run of refused payments that make up most of the recent attempts, typical of many different stolen cards. Treat an unrecognised value as a reason to look, not an error.
window_start, window_endintegerThe period examined, in unix seconds (the hour before the alert).
attemptsintegerPayment attempts in the window.
refusedintegerAttempts refused, by the card's bank or by your own fraud rules.
acceptedintegerAttempts that succeeded, were authorized, or were captured.
distinct_cardsintegerDifferent cards seen in the window.
cardobject | null{ brand, last4 } of the card being guessed at. Set only with expiry_enumeration; null otherwise.
expiry_variantsinteger | nullHow many expiry dates were tried on that card. Set only with expiry_enumeration.
blockedbooleanAlways false.

Subscription events​

subscription.created, .renewed, .payment_failed, .cancelled, .updated​

A subscription that Von Payments renews for you changed. You have to select them: each is delivered only to an endpoint whose enabledEvents names it, and "*" does not include them. In the dashboard picker they are under Subscriptions.

EventSent when
subscription.createdA sign-up payment created a subscription.
subscription.renewedA renewal charge succeeded.
subscription.payment_failedA renewal charge was declined. The last one, when no retries are left, has status: "failed", and no subscription.cancelled follows it.
subscription.cancelledThe subscription was cancelled.
subscription.updatedAnything else changed, for example a pause, a skipped renewal or a new price. changed_fields names what; a skipped renewal sends ["next_bill_at"].

All five carry the same data. Each field, an example and the order rules are in the Subscriptions reference.

What is delivered to a subscription​

Every event except the dispute family and refund.failed is delivered only if its exact type is in your subscription's enabledEvents, filtered per endpoint. The events documented here that you subscribe to are Charges (charge.succeeded, charge.failed), Refunds (charge.refunded; refund.failed arrives whether or not you list it), Payment Intents (payment_intent.succeeded, payment_intent.failed, payment_intent.cancelled, payment_intent.authorized, payment_intent.held_for_review), Sessions (session.succeeded, session.failed), Order mirroring (mirror.order.created), Fraud alerts (merchant.card_testing_suspected) and Subscriptions (subscription.created, subscription.renewed, subscription.payment_failed, subscription.cancelled, subscription.updated). To match them to one order, store every id a payment's first event carries (session_id, payment_intent_id, vp_tx_id) and match later events on any of them: which are null depends on how the payment was taken and on the event, and a refund made through the API carries no session_id.

Event names come from this catalog. A create or update whose list contains any name not in it, such as session.expired (there is no such event) or a misspelling like charge.suceeded, is refused with 400 validation_error ("verify the URL and that every event type is a recognized event"), even when the other names are valid. Nothing is stored and no signing secret is issued. The message does not name the bad entry, so check each name against this page. A name that fails the format (lowercase, dotted) is refused with 400 before the catalog is consulted.