Skip to main content

Embedded Fields — 3D Secure

3D Secure (3DS / SCA) is the issuer's challenge that proves the buyer is the cardholder. The issuer decides whether to challenge, not your code. Where the challenge surfaces depends on which flow the session runs:

SessionWhen 3DS is requiredYou
Charge at submit / charge-and-save — the embed charges on submitsubmit() resolves early with chargeStatus: "requires_action" and a redirectUrl; nothing is chargedSend the buyer to redirectUrl. They return to the session's successUrl; the charge.* webhook is the outcome.
Tokenize-only — your server charges via POST /v1/payment_intentsThe intent comes back status: "requires_action" with next_actionSend return_url on the create call and redirect the buyer to next_action.redirect_to_url.url, or show the check in a pop-up on your page (vora.js 1.53.0). The charge.* webhook is the outcome.

An Apple Pay or Google Pay payment runs its bank check on the wallet path instead: the buyer comes back through a Von Payments page to your successUrl with status and, when known, payment_intent_id added, and you fulfill from the charge.* webhook, never from the URL. See Wallets and 3-D Secure.

Code the requires_action branch on every charge-at-submit integration even if you have never seen it fire — a card that needs a challenge lands nowhere else, and a buyer left on a spinner is an abandoned payment. Full contract: Charge at submit → 3-D Secure.

If the bank declines on its page​

On a charge-at-submit session the buyer comes back to your page after the bank's check, whatever its outcome. When the bank declined and retry on the same session is switched on for your account, the session is re-opened so the buyer can try another card on it. Read the session on your server (GET /v1/sessions/{id}) before you show anything:

SessionShow the buyer
paymentStatus: "paid"The order confirmation.
retry.allowed: trueThe card form again, on the same session: vora.sessions.retrieve() with the same session id. Do not create a new session.
retry.allowed: false, attempts_remaining above 0Nothing yet: the next card form is still being prepared. Read the session again after about a second.
retry.allowed: false, attempts_remaining: 0No more cards on this session. Start a new session for the buyer to pay again.

retry: null is not final by itself; see A failed charge is not always the end of the checkout. If the buyer submits a card before the session has finished re-opening, vora.js 1.39.0 rebuilds the card form and rejects submit() with frame_tokenization_failed and retryable: true: ask the buyer to enter the card again (Errors). With vora.js 1.38.1 the next card is charged once the page loads after the re-open; on that version, reload the page if the card is refused.

Tokenize-only: the hosted redirect​

submit() mints the vp_pmt_*; your server creates the intent. Send an absolute-HTTPS return_url on the create call — the page the provider returns the buyer to after they authenticate — and redirect the buyer when the intent needs a challenge, or show the check in a pop-up. This is the path for every card your server charges, on every connection:

// server/api/charge.ts — req.body.payment_method is the vp_pmt_* from submit()
// Load the order on your server (refused unless it is this shopper's):
// amount, session and return URL come from your record, not the request.
const order = await loadOrder(req.body.order_id, req);
const response = await fetch(`${API}/v1/payment_intents`, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${SECRET_KEY}`,
"Idempotency-Key": `${order.id}_charge`, // your order id; the same value on every retry
},
body: JSON.stringify({
amount: order.amount,
currency: order.currency,
payment_method: { id: req.body.payment_method }, // object form: { id: "vp_pmt_..." }
session_id: order.vonpaySessionId, // refused, not charged twice, if that session already charged
return_url: `https://yourstore.com/checkout/return?order=${order.id}`, // absolute HTTPS, with your order ref
}),
});
const intent = await response.json();

if (intent.status === "requires_action" && intent.next_action?.type === "redirect_to_url") {
// Send the buyer to the hosted challenge; the provider returns them to return_url on completion.
return res.json({ redirect: intent.next_action.redirect_to_url.url });
}
// requires_action with no next_action: still processing, nothing for the buyer to do.
// Do not retry the charge. Wait for the webhook, which can take up to a day.
res.json({ status: intent.status });
// Browser — send the buyer to the hosted challenge. `vora` is your page's
// `new window.Vora({ publishableKey })` instance, `result` is the resolved
// `collection.submit()` that minted the token, and `orderId` is your own order reference.
const res = await fetch("/api/charge", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ payment_method: result.token, order_id: orderId }),
});
const body = await res.json();
if (body.redirect) vora.redirectToChallenge(body.redirect);

If the redirect never reaches the buyer (a timeout, a crash, a closed tab), read GET /v1/payment_intents/{id}: it returns the same next_action, with issued_at for its age, for as long as the intent is requires_action. On a browser charge, resending with the same Idempotency-Key while the check is open also returns the same challenge link; a resent wallet charge does the same (Standalone wallets). Send the buyer to it once.

vora.redirectToChallenge() (vora.js 1.32.0 or later) checks that the URL is a genuine bank challenge before sending the buyer, and throws frame_3ds_required rather than navigate to a host it does not recognise, so do not replace it with a plain window.location assignment. It also accepts intent.next_action or the Node SDK's intent.nextAction as they are.

return_url must be absolute HTTPS (javascript: / data: / plain http: are rejected; localhost is accepted for local development). It is ignored when no challenge is required, so it is safe to always send, and it is not used for merchant-initiated charges (mit.initiator: "merchant") — an off-session rebill has no buyer browser to redirect. The return is UX only: the authoritative outcome is the charge.succeeded / charge.failed webhook (or GET /v1/payment_intents/{id}), never the query string the provider appends to your return_url.

A payment your server created: the check in a pop-up​

From vora.js 1.53.0, vora.handleNextAction() shows the bank's check for a payment your server created, in a pop-up on your page. Your server creates the payment with next_action_presentation: "in_page" and a return_url on this page's origin, and passes the payment id and its client_read_secret to the page.

const { paymentIntentId, clientReadSecret } = await yourServer.chargeSavedCard();
try {
const result = await vora.handleNextAction({
paymentIntent: paymentIntentId,
clientReadSecret,
});
showStatus(result.status); // "requires_action" is not unpaid: see below
} catch (err) {
if (err.code === "frame_payment_declined") showDecline(err.declineCode);
// Any other error: the outcome is not known here, and the payment may be paid.
// The read below decides.
}
await yourServer.confirmPayment(paymentIntentId); // fulfill from your server's read

The SDK reads the payment first: a payment that is already settled resolves at once, with nothing shown. The result always comes from Von Payments' read of the payment, never from the bank's page. Use it for what your page shows, and fulfill the order only from your server's own read or the webhook.

result.statusMeaning
succeeded, capturedPaid.
authorizedApproved and held (a manual-capture payment). Not paid until your server captures it.
voided, cancelledThe payment ended and no charge remains.
requires_actionNot "unpaid". The outcome is not known here. result.reason is closed (the shopper closed the pop-up, your signal aborted, or a later call replaced it), expired (the check's time passed, or the bank's page finished and Von Payments had not recorded the answer two minutes later), or unreadable (the secret stopped working, for example after a cancel, or Von Payments reported a status this version of vora.js does not know).

After requires_action, your server reads the payment. While it is still requires_action, your server may cancel it. Take payment another way only when the cancel succeeds and the payment reads cancelled or failed. A 409 payment_recorded, or a payment that reads authorized or succeeded, means the payment went through: do not take payment another way, and capture an authorized one from your server. Any other 409, a 503, or a payment still requires_action means: wait for the payment's webhook.

  • A decline throws frame_payment_declined with declineCode, as the card form does. authentication_failed and authentication_not_completed mean the bank's check was not passed: nothing was charged.
  • No outcome throws frame_next_action_outcome_unknown. The payment may already be paid, so read it from your server before you take any new payment.
  • Close it from your page with signal (an AbortSignal). The call then resolves requires_action with reason: "closed".
  • Your Content Security Policy needs the next-action rows of vora.cspSources() in frame-src (the bank's page and the Von Payments return page), and the Von Payments API in connect-src. The return page reports only to the origin of the payment's return_url. On another page the pop-up still works, but the outcome arrives more slowly.

Test cards​

Test payments run on a sandbox account, which runs 3-D Secure on every card payment. To test a challenge, pay with 4111 1111 1118 1072 (Visa) or 5240 0000 0000 1072 (Mastercard): the test page lets you pass or fail it. 4111 1111 1110 1203 and 5200 0000 0000 1203 verify without a challenge. Test cards has the full list, and the totals that decline. A merchant account's test key cannot take a test payment at all: it is refused with sandbox_account_required.

Error codes​

CodeWhen
frame_3ds_requiredCharge at submit only — the fail-closed case: 3DS was required but no usable challenge URL could be produced. Re-running submit() will not help. From vora.js 1.39.0 error.reason says why; for try_another_payment_method, ask the buyer to pay another way (a card or method that does not need a bank check can succeed), and report the session id to support. (Tokenize-only has no SDK error for this — the server's status: "requires_action" is the signal; see the hosted redirect.)
provider_request_rejectedNot an SDK code — HTTP 422 from the charge endpoint. The provider rejected the request; the card was neither charged nor declined, so a different card fails the same way until the request is corrected. selfHeal.retryable: false, nextAction: "fix_request".
frame_3ds_challenge_failedThe challenge ran and was rejected, or failed technically. Not buyer cancellation.
frame_3ds_challenge_timeoutThe buyer did not complete within challengeTimeout.
frame_3ds_challenge_cancelledThe buyer closed the challenge. Nothing charged, the card is fine — an abandoned checkout, not a failure. On the wallet buttons with the bank check in a pop-up, retryable: false means the session has ended: start a new one.
frame_tokenization_failedThe processor rejected the card before any challenge.
frame_payment_declinedThe issuer declined the charge on a charge-and-save / charge-only submit. Also raised when the buyer did not finish the bank check, where the same card can work: error.declineCode is then authentication_not_completed. When the check did not pass, it is authentication_failed: nothing was charged and the checkout session usually ends: when error.retryable is false, start a new session; when it is true, the card form was reset and the buyer can try again on it (see Decline reasons in the browser).

Full handling reference: Errors.

What's next​

  • Charge at submit — the redirect contract, AVS/CVV results, recovering the saved card
  • Quickstart — end-to-end card-only happy path (no 3DS)
  • Errors — full VoraMirrorError reference