Skip to main content

Handle the Return

After payment the buyer is redirected to your successUrl. That redirect tells you the buyer came back. It does not tell you they paid.

Confirm the payment on your server, and fulfill the order from the webhook.

The return page is never the source of truth

Three things are true of every payment redirect, and each one costs money if you assume otherwise.

  1. Arriving at your success page is not proof of payment. The buyer reaches it after the attempt, whatever the outcome.
  2. The return may never happen at all. Buyers close the tab, lose signal, or hit back. The payment still went through.
  3. The return can arrive more than once. It is a URL — it can be reloaded, bookmarked, and shared.

Read the payment status from the API, and treat the webhook as the event that authorizes fulfillment.

Step 1 — Hand the return parameters to the SDK​

The redirect adds one parameter to your successUrl, the session ID:

https://mystore.com/order/123/confirm?session=vp_cs_live_k7x9m2n4p3

The link carries no payment status, no amount and no signature. Pass the whole query object through: the confirmation below reads only session. See Do not trust the URL.

Step 2 — Confirm with one call​

confirmReturn reads the session from the server with your secret key and reports paid only when the server agrees, so this is server-side only.

import { VonPayCheckout } from "@vonpay/checkout-node";

const client = new VonPayCheckout(process.env.VON_PAY_SECRET_KEY);

const params = Object.fromEntries(
new URL(req.url, `https://${req.headers.host}`).searchParams,
);

// The order this page is for, loaded on your server from your own records.
const order = await loadOrder(req.params.orderId, req);

const outcome = await client.sessions.confirmReturn(params, undefined, {
expectedSessionId: order.vonpaySessionId, // stored when you created the session
expectedAmount: order.amount,
expectedCurrency: order.currency,
});

if (outcome.paid) {
// Show the confirmation page.
}
from vonpay.checkout import VonPayCheckout

client = VonPayCheckout(os.environ["VON_PAY_SECRET_KEY"])

order = load_order(order_id) # your own records

outcome = client.sessions.confirm_return(
dict(request.args),
expected_session_id=order.vonpay_session_id,
expected_amount=order.amount,
expected_currency=order.currency,
)

if outcome.paid:
...

The three order values tie the answer to this order: Tie the answer to this order.

Do not pass a signing secret here

confirmReturn takes an optional second argument for a signing secret. Leave it out. The return link carries no signature, so a check against any secret fails every time.

Your session lookup is already authenticated by your API key, and that is what answers "did this buyer pay".

Tie the answer to this order​

On its own, paid: true means the session in the URL is one of your paid sessions, so a buyer could paste the return link of a different, cheaper order they paid for. From SDK 4.0.0, pass what your server recorded when it created the session, and a mismatch reads paid: false:

const outcome = await client.sessions.confirmReturn(params, undefined, {
expectedSessionId: order.vonpaySessionId, // from your own records, never the URL
});
outcome = client.sessions.confirm_return(
dict(request.args),
expected_session_id=order.vonpay_session_id,
)

You can pass the order's amount and currency instead of, or as well as, the session id (expectedAmount with expectedCurrency, always together).

Reading the outcome​

FieldWhat it tells you
paidThe field to branch on. The server reports this session succeeded, and its payment has not been fully returned.
needsReviewSDK 4.7.0 and later. true when the buyer paid but something needs checking first. Always false when paid is false.
reviewReasonPresent when needsReview is true. See Paid, but check first.
statusThe status read from the server.
reasonPresent only when paid is false. Which situation you are in.
amountThe amount as the server reports it. Render this one.
signatureValidnull when you pass no secret, which is the normal value. Do not gate your confirmation page on this field.

In Python these are needs_review, review_reason and signature_valid.

When paid is false, reason says what to do​

reasonWhat happenedWhat to show
still_pendingThe charge is still resolving — this is not a failure.A neutral "confirming your payment" page. HTTP 200, no retry button.
not_succeededThe payment reached a final state and did not succeed.A failure page, with the option to try again.
refundedSDK 4.7.0 and later. The buyer paid, but nothing is left of the payment: it was refunded in full (a full refund in progress counts until it fails), or refunded in part with the rest disputed.Do not fulfill. A neutral "this payment is being returned or has been returned" message, not "payment failed".
missing_sessionThe URL carried no session ID, so there was nothing to look up.Treat as a broken link, not a payment outcome.
session_mismatchThe URL names a different session than the one you stored for this order (only when you pass expectedSessionId).Not a confirmation of this order: show the order's status from your own records or webhook.
amount_mismatchThe paid session's amount or currency differs from this order's (only when you pass expectedAmount / expectedCurrency).Not a confirmation of this order: show the order's status from your own records or webhook.

On the 3-D Secure path the buyer is routinely returned to your success URL before the payment settles, so still_pending is the ordinary case there, not a failure: show the neutral confirming page from the table above, never a retry button, or the buyer pays again on a card that is already settling. Only failed and expired count as final. Anything else, including a status this SDK version has never heard of, reports as still_pending.

On a captureMethod: "manual" session, do not offer a retry on not_succeeded without reading the payment intent first. A session and a hold have different lifetimes: the session expires 30 minutes after you created it, while the hold lasts until you capture or void it. So a session that reads expired does not mean nothing was held. Read GET /v1/payment_intents/{id} for the paymentIntentId you stored at submit: authorized means the money is held and yours to capture, and showing that buyer a retry leaves a second hold on their card.

Paid, but check first​

A session's status keeps reading succeeded after a refund, a dispute or a second payment. From SDK 4.7.0, confirmReturn also reads the refund totals the session carries:

SituationOutcomeWhat to do
Refunded in partpaid: true, needsReview: falseYour decision: what a partial refund means for the order is yours to set.
Two or more payments on the sessionpaid: true, needsReview: true, reviewReason: "second_payment"Check both payments before you fulfill or refund.
Refund totals not sent, for example just after the payment or while a manual-capture payment is on holdpaid: true, needsReview: true, reviewReason: "refund_state_unknown"Treat it as unknown: it does not mean nothing was refunded. Just after a payment, read again in a moment. Otherwise check the payment before you fulfill.

A dispute with no refund does not show on the session. Listen for the dispute.* webhooks.

A lookup that fails is not a buyer who did not pay​

If the session lookup itself fails, confirmReturn throws — it does not return paid: false. Retry or show a neutral page, never a failure. Catch broadly. API errors arrive as VonPayError, but a network failure surfaces as the underlying transport error, so narrowing your catch to VonPayError lets a connection blip escape and return a 500 to a buyer who just paid.

try {
const outcome = await client.sessions.confirmReturn(params);
if (outcome.paid) return renderSuccess(outcome);
if (outcome.reason === "still_pending") return renderPending(outcome);
return renderNotPaid(outcome); // See the reason table for what each one shows.
} catch {
// We could not reach the answer — that is not the same as "they did not pay".
return renderPending();
}

Step 3 — Fulfill from the webhook, not from this page​

Subscribe to charge.succeeded and do your fulfillment there — grant access, ship goods, send the receipt.

This is required, not a nicety: a buyer who pays and closes their laptop never loads your return page. The webhook is the only delivery path that does not depend on the browser coming back.

Use the return page for what it is good at — showing the buyer something immediately. If you want that confirmation to feel instant, run the same fulfillment routine here too, as long as it is safe to run twice. On the return page, wrap it: try { await fulfil(order, sessionId); } catch { return renderPending(); }. A throw there means another caller is still working on the order, not that the payment failed.

Fulfill exactly once​

Both the webhook and the return page can fire for the same order, more than once, and possibly at the same moment. Your fulfillment routine must be safe to run repeatedly.

paid: true tells you the session completed: the payment was taken, or on a captureMethod: "manual" session, authorized and held. So on a manual-capture session, read the session's paymentStatus before you fulfill: fulfill on paid, never on held (capture first). paid: true also does not tell you whether you have already acted on it — the lookup keeps returning succeeded forever.

Record which session IDs you have fulfilled and refuse to fulfill one twice. A UNIQUE constraint on the session ID in your orders table, plus a short claim time, is enough.

// Safe to call from the webhook AND the return page. `order` is your own
// record, loaded on your server; `sessionId` is the one the caller was given.
async function fulfil(order: Order, sessionId: string) {
const outcome = await client.sessions.confirmReturn({ session: sessionId }, undefined, {
// A session that is not this order's reads paid: false (session_mismatch).
expectedSessionId: order.vonpaySessionId,
expectedAmount: order.amount,
expectedCurrency: order.currency,
});
if (!outcome.paid) return;
if (outcome.needsReview) return holdForReview(sessionId, outcome.reviewReason);

// On a captureMethod: "manual" session, paid: true also covers a card that is
// only authorised and held. Fulfil only once the money is taken.
const session = await client.sessions.get(sessionId);
if (session.paymentStatus !== "paid") return; // "held": capture it first

// 1. CLAIM the order. UNIQUE(session_id) makes this the concurrency lock:
// whichever caller gets here first wins, the other gets a violation.
try {
await db.orders.insert({ session_id: sessionId, state: "claimed", claimed_at: new Date() });
} catch (err) {
if (!isUniqueViolation(err)) throw err;
// Someone already claimed it. Take the claim over ONLY if it is stale
// (a previous attempt died mid-way). A fresh claim means another caller
// is working on it right now: completing it here would fulfil twice.
const takenOver = await db.orders.updateWhere(
{ session_id: sessionId, state: "claimed", claimed_at_before: minutesAgo(5) },
{ claimed_at: new Date() },
);
if (!takenOver) {
const existing = await db.orders.findOne({ session_id: sessionId });
if (existing?.state === "fulfilled") return;
// Another caller holds a fresh claim. Throw: the webhook answers 5xx and
// is sent again later; the return page shows "confirming".
throw new Error("fulfilment in progress");
}
}

await grantAccessAndSendReceipt(sessionId);

// The 5-minute lease must be longer than your slowest fulfilment. If a run can
// outlast it, a second caller can take over, so the work itself must be safe
// to repeat. (updateWhere / minutesAgo stand for your own database calls.)

// 2. Only now is it done. A crash before this line leaves state 'claimed',
// so the next delivery retries instead of skipping.
await db.orders.update({ session_id: sessionId }, { state: "fulfilled" });
}

Claim first, do the work, then mark it finished — a single "handled" row inserted before the work means a failure after the insert is never retried, and the buyer never gets what they paid for. grantAccessAndSendReceipt still has to be safe to run twice.

Do not trust the URL​

The return link arrives through the buyer's browser, and the buyer can see and edit it. It is a pointer to a session, never a fact about money:

  • Never read the payment outcome from a query parameter. Read paid from the outcome, as in step 2.
  • Render outcome.amount, which comes from the server. If your page still reads status or amount from the link, change it: the link no longer carries them.

If your integration calls verifyReturnSignature (or verify_return_signature), replace it now. The link no longer carries a signature, so the function returns false for every return, and a fulfillment path that depends on it breaks. Use confirmReturn as in step 2, with no secret argument. The function still compiles and logs a warning; SDK 5.0 removes it. Signature verification belongs on webhooks: Verifying webhooks.

What's next​