Skip to main content

Reconciliation — redirect vs. webhook

Von Payments sends two signals for every completed payment:

SignalTypeDeliveredAuthority
Return redirectSynchronous redirectThe moment the buyer returns to your successUrlA prompt, not a fact. It tells you the buyer came back, not that they paid — look the session up with your API key to learn the outcome. See Handle the return.
charge.succeeded webhookDurable async POSTUsually within a few seconds; can be delayed during outagesSigned with your endpoint's whsec_* secret — cryptographically authoritative once you verify it

Only the webhook is authoritative on its own. They exist for different failure modes:

  • The redirect fails if the buyer closes their browser before returning.
  • The webhook fails if your endpoint is unreachable, slow, or returns non-2xx.

The pattern​

Use the redirect to advance the buyer's UX immediately; before any irreversible fulfillment, confirm payment status server-side and guard idempotency, and treat the second signal as a no-op when it arrives.

A client or redirect error does NOT mean the payment failed

A closed tab, a browser hiccup, or a network error on the return can happen after the charge already succeeded. Never mark an order failed/unpaid on a client-side or redirect error alone — reconcile against the charge.succeeded webhook (or a server-side sessions.get) before treating a payment as failed.

Redirect arrived but webhook hasn't​

The most common case. The buyer returned to your successUrl — look the session up before you show anything final, and before fulfilling anything irreversible:

GET /v1/sessions/{sessionId}
Authorization: Bearer vp_sk_live_…

This endpoint requires a secret key; a publishable key (vp_pk_*) is rejected with 403 auth_key_type_forbidden. A 200 with status: "succeeded" confirms settlement fresh from the server — then idempotency-guard (below) so a replayed redirect can't fulfill the same order twice. The webhook arriving later (or never) doesn't change the outcome.

Webhook arrived but redirect didn't​

The buyer closed their browser before returning to successUrl. You only learn about the payment from the charge.succeeded webhook. That's fine — the webhook is authoritative. Fulfill the order; email the buyer separately.

Both arrived (the happy path)​

Make your handler idempotent by deduping on the webhook envelope's top-level id (the vp_evt_* field). That id is the dedupe key by design: a redelivery carries the same id, so a single unique constraint on it collapses duplicates safely.

Do not dedupe on data.session_id. It is a correlation key, not a dedupe key — it is nullable, scoped to one session rather than unique per event, and a single payment movement can legitimately fan out into two distinct events (for example a charge.* and a payment_intent.* event) that share one session_id but carry different id values. Deduping on session_id would wrongly collapse those distinct events.

Two keys, and mixing them up double-ships: dedupe events on the envelope id, and key the order on a correlation id (an orders table keyed on the event id gets two rows for one payment). The order key must never be null — session_id, payment_intent_id and vp_tx_id are each nullable depending on how the payment was taken, and a UNIQUE column does not constrain NULLs — so take the first non-null of the three. And only the success family may claim an order: a refund carries no session_id, so a handler that claims on every event derives a fresh key for charge.refunded and ships the order again on a refund. Gate on event.type first:

// 0. A "Send test event" delivery can carry a real session's ids: acknowledge
// it and stop, before any lookup or write.
if (event.test_event === true) return res.status(200).json({ received: true });

// 1. Does this event fulfil anything? ONLY the success family claims an order.
// ⛔ Without this gate the handler also claims on `charge.refunded` and
// `dispute.created`. Those carry a DIFFERENT correlation id from the charge
// — a refund has no `session_id` at all — so step 3 sees a key it has never
// stored, inserts a second row, and you ship the order again on a refund.
// (`session.succeeded` carries no vp_tx_id; fulfil on `charge.succeeded`.)
const FULFILS = new Set(["charge.succeeded", "payment_intent.succeeded"]);
if (!FULFILS.has(event.type)) return res.status(200).json({ received: true });

// 2. Which id identifies the PAYMENT? All three are nullable, and WHICH one is
// null depends on the integration path, so take the first non-null.
// ⛔ A UNIQUE constraint does NOT constrain NULLs — SQL treats every NULL as
// distinct, so a null key inserts every time and the lock silently does
// nothing.
const orderKey =
event.data.session_id ??
event.data.payment_intent_id ??
event.data.vp_tx_id;
if (!orderKey) throw new Error("no correlation id on " + event.type + " " + event.id);

// 3. Have I already processed this DELIVERY? Keyed on the envelope id.
const seen = await db.query(
`INSERT INTO processed_events (event_id) VALUES ($1) ON CONFLICT DO NOTHING RETURNING 1`,
[event.id],
);
if (seen.rowCount === 0) return res.status(200).json({ received: true }); // redelivery

try {
// 4. Have I already fulfilled this PAYMENT? The same claim as on
// Handle the return: take over only a STALE claim, never a fresh one.
try {
await db.orders.insert({ order_key: orderKey, state: "claimed", claimed_at: new Date() });
} catch (err) {
if (!isUniqueViolation(err)) throw err;
const takenOver = await db.orders.updateWhere(
{ order_key: orderKey, state: "claimed", claimed_at_before: minutesAgo(5) },
{ claimed_at: new Date() },
);
if (!takenOver) {
const existing = await db.orders.findOne({ order_key: orderKey });
if (existing?.state === "fulfilled") return res.status(200).json({ received: true });
throw new Error("fulfilment in progress"); // another caller holds a fresh claim
}
}

// ... fulfil, then mark the order `fulfilled`.
} catch (err) {
// 5. The work did not finish. Release the delivery row, or the redelivery is
// matched in step 3 as a duplicate and the work never runs. Then answer 5xx
// so the event is sent again.
try {
await db.query(`DELETE FROM processed_events WHERE event_id = $1`, [event.id]);
} catch (releaseErr) {
console.error("could not release event", event.id, releaseErr); // alert on this: the resend will be skipped
}
return res.status(500).json({ error: "processing failed" });
}

Handle the return shows the same two-phase claim, callable from the webhook and the return page alike.

Neither arrived (the rare failure)​

The redirect didn't fire AND the webhook didn't fire within your tolerance window. The buyer may or may not have paid. Don't fulfill. Instead:

  1. Poll GET /v1/sessions/{sessionId} to retrieve server-side state.
  2. If status: "succeeded" — both signals failed in delivery. Check paymentStatus before you fulfill: paid means the money is taken, so fulfill and log the dual failure for monitoring. held means a manual-capture payment is only authorized: capture or void it, and do not fulfill yet.
  3. If status: "pending" — the buyer hasn't completed. Don't fulfill.
  4. If status: "expired" or "failed" — the buyer didn't complete. Don't fulfill.

A reasonable tolerance window is 5–15 minutes depending on how time-sensitive your fulfillment is. Past that window, the payment is either succeeded (and the signals were lost) or never happened.

One more dedupe trap: data.session_id + type is not a key either — a charge refunded in two parts emits charge.refunded twice with the same session and type, and that key drops the second refund from your ledger. A 5xx or timeout from your handler redelivers the same event id; return 200 for an already-processed event.