Skip to main content

Accept Apple Pay & Google Pay

Add standalone Apple Pay and Google Pay buttons — the buyer taps a wallet and authorizes with Face ID / a fingerprint. Wallets ride on the same Elements session as your card field, so you can offer "wallets on top, or pay with card below" from one integration.

The tap charges the buyer

On the default wallet path, the authorized wallet is charged there and then — money moves during the tap, before your server is involved. Do not charge the result again; that bills the buyer twice. Branch on the charge result, never on the presence of a token. This applies to both paths below.

The wallet button is the express-checkout element

Looking for a wallet button / Apple Pay button / Google Pay button? It's the express-checkout element — one element renders both wallets. There is no wallet-button, applePay, or googlePay element name. In the default integrationMode: "embed" you don't add any element at all: the wallet buttons appear inside the card mount automatically when the buyer's device and your domain are eligible (see Elements reference → Apple Pay & Google Pay). Use the standalone express-checkout element below when you create the session with integrationMode: "elements".

There are two ways to do it:

Before you start

Verify your domain first. Apple Pay and Google Pay only show a button on a domain registered for that wallet — complete Wallet domain setup before anything else. On an unverified domain the button simply doesn't appear.

Availability is per-gateway. Apple Pay is available once your domain is verified; Google Pay's charge step additionally depends on your gateway connection, so verify Google Pay end-to-end on your own account before relying on it in production.


Mount the express-checkout element in its own collection (separate from the card field — see the two-collection rule). On a successful tap the SDK registers the authorized wallet and submit() resolves the charge result.

// Same Elements session as the card field (integrationMode: "elements").
await vora.sessions.retrieve(sessionId);

const walletCollection = vora.elements.create();

const express = walletCollection.create("express-checkout", {
wallets: ["apple_pay", "google_pay"], // default
buttonLayout: "horizontal", // or "vertical"
label: "My Store",
});

express.on("change", async (e) => {
if (e.error) {
// Buttons unavailable — domain not verified for this wallet,
// device unsupported, or wallets not enabled. Card is your fallback.
return;
}
if (!e.complete) return; // buyer hasn't authorized yet

// result.wallet is "apple_pay" | "google_pay" (for your analytics).
const result = await walletCollection.submit();

if (result.chargeStatus === "requires_action") {
// 3-D Secure. NOTHING has been charged.
// From vora.js 1.22.0 the element sends the buyer to `redirectUrl` FOR YOU.
// Only navigate here yourself if you created the element with
// `handleRedirect: false` — see "Wallets and 3-D Secure" below.
return;
}

if (result.charged) {
// Money has ALREADY moved. Do NOT charge result.token.
return awaitWebhookThenFulfil();
}

if (result.chargeStatus === "pending") {
// In flight — the outcome arrives on the charge.* webhook.
return awaitWebhookThenFulfil();
}

if (result.chargeStatus === "succeeded") {
// The payment is placed, so never charge again (there is no token here).
if (result.charged === false && result.paymentIntentId && !result.recovered) {
// captureMethod: "manual". Authorised and held: your server captures
// (or voids) result.paymentIntentId before the hold lapses.
return holdForCapture(result.paymentIntentId);
}
// Read back after a lost reply (recovered: true), or no charged value.
return confirmOnYourServer(sessionId);
}

// Vault-only accounts only: a token and no charge. This one you charge.
await chargeOnYourServer(result.token, result.wallet); // vp_pmt_*
});

express.mount("#wallets"); // your own <div id="wallets">

To save the wallet's card for later charges, the element needs the buyer's agreement: a save box (saveForFutureUse, for a box in another collection) or your own wording (setupForFutureUse). See Collect the buyer's consent.

What submit() resolves to​

Check the arms in the order above. charged and chargeStatus are what tell the arms apart — token does not, because a charge that had a buyer to save against returns one and has already taken the money.

ResultWhat happenedWhat you do
chargeStatus: "requires_action" + redirectUrlThe issuer wants the buyer to authenticate. No money moved, no token minted. Not a success.Nothing, from vora.js 1.22.0 — the element navigates to redirectUrl itself. On an earlier pinned build, or if you set handleRedirect: false, the redirect is still yours. See Wallets and 3-D Secure.
charged: true (with chargeStatus: "succeeded")The buyer has been charged. A reusable vp_pmt_* may also be present — it is real, but it is not a handle to bill this payment later.Nothing. Fulfill on the charge.* webhook. Never call POST /v1/payment_intents with result.token for this payment.
chargeStatus: "pending"Placed but not confirmed; the bank may still approve or decline. No token yet. After a bank check in a pop-up it carries pendingReason.Wait for the charge.* webhook. Don't fulfill, don't retry.
token, no chargedNothing was charged: your account is set up to save wallet cards without charging them (vault-only, below).Charge it yourself, exactly as in the card flow, Step 5.
chargeStatus: "succeeded" + charged: false + paymentIntentIdA captureMethod: "manual" session: the money is authorized and held, not taken. No token.Capture or void paymentIntentId from your server before the hold lapses. The id comes from the buyer's browser: read that payment with your secret key and check its metadata.session_id is this session, and that its amount, currency and status: "authorized" match your order, before you capture, void or fulfill. Never charge again.
chargeStatus: "succeeded" with recovered: true, with charged absent (whatever paymentIntentId says), or with charged: false and no paymentIntentIdThe payment was already placed (a retry, or an outcome read back after a lost reply), but the result does not say whether it was taken or held.Read the session on your server with GET /v1/sessions/{id}: paymentStatus is paid or held. Never charge again.

Charge-direct is the default on every account where wallet payments are enabled. Saving the wallet's card without charging it (vault-only) is a per-account setting that is off unless Von Payments turns it on. Ask us before you build for it. Creating the session differently does not switch it on. Writing the branch above handles either.

Saving a wallet card for renewals​

Vault-only is not the way to save a wallet card for renewals. A card saved that way has no payment made with the shopper present, so a renewal on it is refused with mit_anchor_unknown until such a payment has gone through. For a wallet card that renews, use the charge at the tap. With a buyerId on the session and the shopper's agreement to later charges (Collect the buyer's consent), the tap pays for the order and saves the card, and renewals link to that payment. Do not charge that order again from your server.

Renewals on a saved Apple Pay or Google Pay card depend on your processor. Ask us before you sell subscriptions paid with wallets.

Declines don't reach these arms: they throw frame_payment_declined, the same code as the card path.

On a page with only wallet buttons (no card form), a decline that leaves the session open comes back retryable: true with attemptsRemaining: the buttons stay up and the buyer can tap again, with nothing to re-mount. Once a payment has been placed on the session, a further wallet tap is refused before anything is sent (frame_session_not_ready). From vora.js 1.45.2, a tap that no payment connection on your account accepts stops payment on the page: frame_provider_request_rejected, retryable: false, nothing charged. Fix the cause, then start a new session.

Why the button might not appear. If the wallet isn't verified for your domain, the device doesn't support it, or your processor connection has no Express Checkout support, the element renders zero buttons and fires a change event with an error code (e.g. frame_wallet_domain_unverified) — it does not render buttons the device or your domain cannot use. If the payment provider still refuses to start the wallet when the buyer taps (most often because the site is not registered for wallet payments), the element reports frame_wallet_unavailable from vora.js 1.44.0, and nothing is charged: show your card form. A tap can still fail, for example in an app's built-in browser that will not start an Apple Pay session: from vora.js 1.45.1 the element then reports frame_wallet_unavailable with a reason and the buttons stay, so show your card form beside them. Always keep pay-by-card as the fallback.

Knowing when a wallet payment is under way​

The element emits click when the buyer taps a wallet button and exactly one close when that attempt is over, with an outcome: succeeded, unresolved, tokenized, failed or cancelled. Use the pair to keep another payment method from charging on top of a wallet payment, and keep the order held on unresolved. Details and the full outcome table: Element events.

Buyer details and shipping in the wallet sheet​

By default the sheet asks for nothing but the card, and the tap charges at once. Four options on the element let a buyer pay in one tap from a checkout whose form is still empty, and let you create the order before any money moves. Each is opt-in; leave them all out and the element behaves exactly as above. They need vora.js 1.35.0 or later.

OptionWhat it does
collectAsks the sheet for the buyer's email, name, phone, billingAddress and/or shippingAddress. Each defaults to false.
shippingOptionsShipping choices shown in the sheet, the first one pre-selected: { id, label, amount, detail? }, with amount in minor units. Needs collect.shippingAddress: true and an onShippingOptionChange handler.
onShippingAddressChange / onShippingOptionChangeCalled when the buyer picks an address or a shipping option. Answer with the new total in minor units (and, for an address, optionally a new shippingOptions list), or with { error }.
onConfirmRuns after the buyer approves and before any money moves, with everything the buyer gave the sheet. Create or check your order here.

collect, shippingOptions and onShippingAddressChange need an integrationMode: "elements" session and a payment connection whose wallet buttons the SDK draws itself; not every connection supports that. Where it is not supported the element refuses them at mount with frame_unsupported_element and renders no buttons, rather than ignoring them. Mount once on your own account to confirm. onConfirm works on every session.

const express = walletCollection.create("express-checkout", {
collect: { email: true, name: true, phone: true, shippingAddress: true },
// The session amount is the total the sheet opens with, so create the
// session with an amount that already includes the FIRST option.
shippingOptions: [
{ id: "standard", label: "Standard shipping", amount: 500, detail: "3-5 business days" },
{ id: "express", label: "Express shipping", amount: 1500 },
],

// Your server prices the order AND moves the session's total before answering.
onShippingAddressChange: async ({ shippingAddress }) => {
const res = await fetch("/api/checkout/reprice", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ shippingAddress }), // your server finds the cart and session
});
if (!res.ok) {
const { reason } = await res.json();
if (reason === "not_open") return { error: "This order is already being paid." };
// concurrent_update: other changes to the session kept landing; nothing
// changed and the session is still open. Your server can resend the same
// update once; otherwise ask the buyer to choose again.
if (reason === "concurrent_update") return { error: "Please choose your address again." };
return { error: "We can't ship to that address." };
}
return res.json(); // { total, shippingOptions? }
},
onShippingOptionChange: async ({ shippingOptionId }) => {
const res = await fetch("/api/checkout/reprice", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ shippingOptionId }),
});
if (!res.ok) return { error: "That shipping option is not available." };
return res.json(); // { total }
},

// Create the order as PENDING. Nothing has been charged yet. Your server
// prices it again from the cart; it never takes a total from the browser.
onConfirm: async ({ payer, shippingAddress, shippingOptionId }) => {
const res = await fetch("/api/orders", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ payer, shippingAddress, shippingOptionId }),
});
return res.ok ? { ok: true } : { ok: false, message: "We couldn't place your order." };
},
});

On your server, the reprice route changes the session's total with PATCH /v1/sessions/{sessionId} and answers the sheet only once that has succeeded:

// POST /api/checkout/reprice (your server, secret key)
// The cart comes from the shopper's server-side session, not the request body.
// It holds the Von Payments session id you created for this cart.
const cart = await loadCart(req);
const { total, shippingOptions } = priceOrder(cart, req.body);

const res = await fetch(`https://checkout.vonpay.com/v1/sessions/${cart.vonpaySessionId}`, {
method: "PATCH",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${process.env.VON_PAY_SECRET_KEY}`,
},
body: JSON.stringify({ amount: total }),
});
if (!res.ok) {
// Nothing changed. Pass the reason on so the sheet can say what happened:
// `not_open` means a payment is already in progress on this session.
const err = await res.json();
return reply(res.status, { code: err.code, reason: err.reason });
}

return reply(200, { total, shippingOptions });

Your /api/orders route works the same way: it reads the session id from the cart, prices the order again on your server, and stores the order as pending with that session id, so the return page and the webhook can tie the payment to this order.

Keep the session's total in step with the sheet. When any of these options is used, the element sends the total the buyer approved with the payment, and the checkout charges exactly that total or refuses the payment without charging. If you answer the sheet with a new total but never change the session, the payment is refused with 409 expected_amount_mismatch, which the element reports as frame_wallet_total_mismatch. Nothing is charged either way. Changing the session inside your shipping handlers also keeps onConfirm short.

If the total changes outside the sheet (the buyer edits their cart, say), change the session on your server and then call fetchUpdates() on the wallet's collection (vora.js 1.36.0 and later). The next sheet opens at the new total. A sheet that is already open keeps the total it opened with, and a payment approved at that total after the session moved is refused without charging. The card collection needs its own fetchUpdates(): see Charge at submit.

Answer in time. The wallets give the whole approval step about 30 seconds:

  • The shipping handlers must answer within 20 seconds. A late answer, a thrown error or a malformed answer is shown to the buyer as a failure. An { error } from onShippingOptionChange closes the sheet on Apple Pay (nothing is charged) and is shown in the sheet on Google Pay.
  • onConfirm gets 15 seconds, and the charge uses the rest. { ok: false, message } charges nothing, and the sheet shows message where the wallet supports it. A thrown error, a timeout or any other answer also charges nothing and emits frame_wallet_confirm_failed.

{ ok: true } does not mean the payment will succeed. It can still be declined or sent to a bank check. Create the order as pending in onConfirm, and complete it on the payment webhook.

The address in the shipping handlers is partial. Before the buyer approves, both wallets hide the street line and may shorten the postcode. You get enough to price shipping and tax. The full address arrives after approval.

What comes back. The confirm event carries payer, billingAddress, shippingAddress and shippingOptionId, and submit() carries the same four under result.expressCheckout, with only the fields you asked for. These come from the buyer's browser, so use them to fill in the order but read what you fulfill against from the server:

  • The shipping address is returned as shippingAddress by GET /v1/sessions/{sessionId} once the session has succeeded.
  • The shipping option is recorded on the payment as metadata.shipping_option_id, readable with GET /v1/payment_intents/{id}.
  • Contact details are stored with the session once the payment is accepted, never from a declined attempt, and are not returned in the payment response or in webhooks. Keep the copy you received in onConfirm.

Path B — bring your own button​

If you need full control over the button and the wallet sheet, render the native wallet API yourself and call the public wallet endpoints directly. Both wallet-session calls and the charge use your publishable key (a secret key is rejected with 403).

As in Path A, the wallet charge is immediate: POST /v1/public/tokens with instrument: "wallet" charges the session in one call (a wallet cryptogram is single-use, so it can't be pre-vaulted). Do not also call /v1/payment_intents for the same session — that double-charges. The difference here is only that you make the call yourself.

Apple Pay (native)​

Apple Pay runs in Safari on Apple devices only. Gate the button on window.ApplePaySession?.canMakePayments().

const session = new ApplePaySession(3, {
countryCode: "US",
currencyCode: "USD",
merchantCapabilities: ["supports3DS"],
supportedNetworks: ["visa", "masterCard", "amex", "discover"],
total: { label: "My Store", amount: "49.99" },
});

// 1. Validate the merchant — forward Apple's validationURL to Von Payments.
session.onvalidatemerchant = async (event) => {
const res = await fetch("https://checkout.vonpay.com/v1/public/wallets/apple-session", {
method: "POST",
headers: { "Content-Type": "application/json", Authorization: `Bearer ${PUBLISHABLE_KEY}` },
body: JSON.stringify({ session_id: sessionId, validationUrl: event.validationURL }),
});
session.completeMerchantValidation(await res.json()); // pass the response through verbatim
};

// 2. Charge the authorized payment — instrument:"wallet" charges immediately.
session.onpaymentauthorized = async (event) => {
const res = await fetch("https://checkout.vonpay.com/v1/public/tokens", {
method: "POST",
headers: { "Content-Type": "application/json", Authorization: `Bearer ${PUBLISHABLE_KEY}` },
body: JSON.stringify({
instrument: "wallet",
session_id: sessionId,
wallet_type: "apple_pay",
wallet_token: event.payment.token, // Apple's PKPaymentToken
}),
});
const charge = await res.json();

// The session's total changed after the buyer approved. Only reachable if
// your integration changes it (PATCH /v1/sessions). Nothing was charged.
if (charge.code === "expected_amount_mismatch") {
session.completePayment(ApplePaySession.STATUS_FAILURE);
return;
}

// The session already completed (a retry or a double tap after it was
// paid or held). The buyer paid once: never charge again, never show a
// failure. `charge.charged` says whether money moved. Confirm on the webhook.
if (charge.code === "session_already_completed") {
session.completePayment(ApplePaySession.STATUS_SUCCESS);
awaitWebhookThenFulfil();
return;
}

// Another payment on this session is still running (a double tap, or a
// wallet payment still at the buyer's bank). This request charged nothing,
// but the other one's outcome is not known yet: show neither success nor a
// decline, do not retry, and wait for the charge.* webhook.
if (charge.code === "session_payment_in_progress") {
session.completePayment(ApplePaySession.STATUS_FAILURE); // closes the sheet; Apple Pay has no "pending"
showConfirmingPayment();
awaitWebhookThenFulfil();
return;
}

// Any other error answer carries `code` and no `status`: the payment was
// refused. It is never a success. Read charge.code before any retry.
if (charge.code) {
session.completePayment(ApplePaySession.STATUS_FAILURE);
return;
}

// Only a DECLINE closes the sheet as a failure. `pending` and
// `requires_action` are live outcomes — telling the buyer they failed
// invites a retry, and a retry here is a second real charge.
if (charge.status === "declined") {
session.completePayment(ApplePaySession.STATUS_FAILURE);
return;
}

session.completePayment(ApplePaySession.STATUS_SUCCESS);

if (charge.status === "requires_action") {
// 3DS — nothing charged yet. Dismiss the sheet first, then send them.
window.location.href = charge.next_action.redirect_to_url.url;
return;
}
if (charge.status === "succeeded" && charge.charged === false) {
// captureMethod: "manual". Authorised and held, nothing taken: your server
// captures (or voids) charge.payment_intent_id. Never charge again.
holdForCapture(charge.payment_intent_id);
return;
}
// succeeded or pending: money is moving. Confirm on the charge.* webhook
// before fulfilling — never on this result.
};

session.begin();

The wallet domain is derived server-side from the request Origin — you don't send it. Von Payments allowlists Apple's validationUrl to *.apple.com before calling it, so a forged URL is rejected.

Google Pay (native)​

Load Google's pay.js, then ask Von Payments for the gateway parameters and pass them straight into the Google Pay request — forward them verbatim; never hardcode a gateway name or merchant id. gateway and gatewayMerchantId go in tokenizationSpecification; merchantId, merchantOrigin and token (as authJwt) go in merchantInfo, and merchantOrigin must match byte for byte.

// 1. Get the gateway parameters for this session.
const gw = await fetch("https://checkout.vonpay.com/v1/public/wallets/google-session", {
method: "POST",
headers: { "Content-Type": "application/json", Authorization: `Bearer ${PUBLISHABLE_KEY}` },
body: JSON.stringify({ session_id: sessionId }),
}).then((r) => r.json());

// 2. Build the payment-data request with the values Von Payments returned.
const paymentData = await paymentsClient.loadPaymentData({
apiVersion: 2,
apiVersionMinor: 0,
allowedPaymentMethods: [{
type: "CARD",
parameters: {
allowedAuthMethods: ["PAN_ONLY", "CRYPTOGRAM_3DS"],
allowedCardNetworks: ["AMEX", "DISCOVER", "MASTERCARD", "VISA"],
},
tokenizationSpecification: {
type: "PAYMENT_GATEWAY",
parameters: { gateway: gw.gateway, gatewayMerchantId: gw.gatewayMerchantId },
},
}],
// Forward these three verbatim when present. Production Google Pay refuses
// the request (OR_BIBED_11) if any is missing or altered.
merchantInfo: {
merchantName: "Your Store", // yours: the name shown on the sheet
...(gw.merchantId ? { merchantId: gw.merchantId } : {}),
...(gw.merchantOrigin ? { merchantOrigin: gw.merchantOrigin } : {}),
...(gw.token ? { authJwt: gw.token } : {}),
},
transactionInfo: { totalPriceStatus: "FINAL", totalPrice: "49.99", currencyCode: "USD", countryCode: "US" },
});

// 3. Charge — same immediate POST /v1/public/tokens as Apple Pay.
const charge = await fetch("https://checkout.vonpay.com/v1/public/tokens", {
method: "POST",
headers: { "Content-Type": "application/json", Authorization: `Bearer ${PUBLISHABLE_KEY}` },
body: JSON.stringify({
instrument: "wallet",
session_id: sessionId,
wallet_type: "google_pay",
wallet_token: paymentData.paymentMethodData.tokenizationData.token,
}),
}).then((r) => r.json());

// 4. Branch on the RESULT. Every arm below is reachable.
if (charge.code === "expected_amount_mismatch") {
showCurrentTotal(); // the total moved after approval; nothing charged
} else if (charge.code === "session_already_completed") {
awaitWebhookThenFulfil(); // already paid or held once: never charge again, never show a failure
} else if (charge.code === "session_payment_in_progress") {
showConfirmingPayment(); // another payment is still running: no success, no decline, no retry
awaitWebhookThenFulfil();
} else if (charge.code) {
showError(charge.code); // refused, never a success: read the code before any retry
} else if (charge.status === "declined") {
showDeclineMessage(); // nothing charged
} else if (charge.status === "requires_action") {
window.location.href = charge.next_action.redirect_to_url.url; // 3DS
} else if (charge.status === "succeeded" && charge.charged === false) {
holdForCapture(charge.payment_intent_id); // captureMethod: "manual": held, not taken
} else {
// succeeded or pending — money is moving. Do NOT charge again, and
// confirm settlement on the charge.* webhook before fulfilling.
awaitWebhookThenFulfil();
}

Google Pay in production requires merchantInfo.merchantId, merchantOrigin and authJwt, and google-session returns all three for your session. Without them loadPaymentData fails with OR_BIBED_11 and the sheet never opens.

The wallet charge result​

POST /v1/public/tokens with instrument: "wallet" returns a charge result, not a token:

{
"charged": true,
"status": "succeeded",
"payment_intent_id": "vpi_test_abc123",
"token": "vp_pmt_test_abc123",
"wallet_type": "apple_pay",
"id": "vp_pmt_live_…",
"card": { "brand": "visa", "last4": "4242" }
}
FieldNotes
chargedtrue only when status is succeeded. Branch on this, not the HTTP code: a decline is 200 with charged: false. A wallet payment or save that no payment connection on your account accepts is not a decline: it answers 422 provider_request_rejected with no status, and nothing is charged or saved. On a captureMethod: "manual" session a hold is succeeded with charged: false: capture payment_intent_id from your server. The id comes from the buyer's browser: read that payment with your secret key and check its metadata.session_id is this session, and that its amount, currency and status: "authorized" match your order, before you capture, void or fulfill.
statussucceeded | declined | requires_action | pending (202 while genuinely in-flight; the other three are 200). A resend while the first attempt waits on the bank check answers requires_action again: see below.
next_actionPresent only on requires_action — redirect_to_url.url is the page the buyer must be sent to. See Wallets and 3-D Secure.
wallet_typeapple_pay | google_pay.
idA reusable vp_pmt_* when the buyer's credential was stored for reuse. It is null when nothing was stored: a tap nobody agreed to save, or a guest charge. A session with no buyerId is not a guest charge when the card is saved: with no buyer email, when the buyer sent setup_for_future_use: "off_session"; with a buyer email, when anyone asked to save it (the buyer, or your setupForFutureUse: "on_session"). The card is saved to a buyer Von Payments creates for that checkout, never to an existing buyer with the same email. A tap whose payment connection refuses to save a wallet is charged without saving, so id is null (see wallet_not_saved). On a non-succeeded result (declined, pending, requires_action) the key is absent entirely — so test truthiness, not !== null, or a decline will read as a token. This payment is already paid for — the token is for a later, separate purchase, not for settling this one. Charging it for this order double-charges.
cardPCI-safe { brand, last4 }, present on success.
payment_intent_idThe payment record for this wallet charge. Present on every outcome, including requires_action — so you can record the payment before the buyer leaves to authenticate, and reconcile it when the charge.* webhook arrives. null on a genuinely in-flight pending (no outcome to record yet), on the vault-only path (no charge happens, so no record exists by design), and when the processor rejected the request before creating a transaction. ⚠️ On a duplicate tap the response is also pending, but it deliberately carries the original attempt's payment_intent_id rather than null — so a second tap resolves to the same payment instead of reading as "no payment happened".
tokenThe reusable stored card — the same value as id, under a second name so one field carries the vaulted card across every wallet response whichever arm answered. ⚠ null on requires_action, and that is correct rather than missing: nothing is vaulted until the buyer completes the challenge and the charge captures. Read the saved card afterwards from payment_method_id on GET /v1/payment_intents/{id} or on the charge.succeeded webhook — both keyed by the payment_intent_id returned here.

The charge is session-bound and replay-safe: the session flips pending → processing before charging, so a retried request never double-charges. A retry against a session that already completed answers 409 session_already_completed, with charged saying whether money moved: treat it as the earlier result, never as a failure. A resend while the first attempt is still waiting on the buyer's 3-D Secure check (a lost response, a double tap) returns that attempt's answer again: 200, requires_action, the same payment_intent_id and the same next_action link, with nothing new charged. Send the buyer to the link once, including when you handle the redirect yourself (handleRedirect: false) and see the same link twice. Do not create a new session to retry after session_already_completed (that would charge twice).

Sending the buyer's details and the approved total​

The native sheet can return the buyer's contact details and addresses beside the payment token. They reach us only if you add them to the POST /v1/public/tokens body:

FieldNotes
billing_addressThe billing address the buyer confirmed in the sheet: address_line1, postal_code and country required; address_line2, city, state optional.
payer{ email, name, phone }, each optional. name is stored whole, never split into first and last names.
shipping_addressThe billing-address fields plus the recipient's name and phone. Returned as shippingAddress by GET /v1/sessions/{sessionId} once the session has succeeded.
shipping_option_idYour id for the option the buyer picked (1 to 64 printable ASCII characters). Recorded on the payment as metadata.shipping_option_id.
expected_amount{ amount, currency }: the total the buyer approved in the sheet. Always send it if your integration changes the session's total with PATCH /v1/sessions/{sessionId}.

The details are stored only once the payment is accepted, never from a declined attempt, and none of them are echoed back in the response. With expected_amount, the payment is taken only if the session still holds exactly that total; otherwise it is refused with 409 expected_amount_mismatch and the buyer is not charged. Close the sheet as a failure on that answer and show the buyer the current total.


Wallets and 3-D Secure​

A wallet payment can still be challenged by the buyer's bank. When it is, the charge comes back asking the buyer to authenticate — the same vocabulary the card path uses, so you can branch on it identically.

The wallet element redirects for you — the card element does not

From vora.js 1.22.0, the wallet (express-checkout) element navigates the page to redirectUrl itself on this arm. You do not write the redirect.

The card path is unchanged and still expects you to perform it. The wallet element closes the sheet showing success, so a buyer nobody redirected would believe they paid while the charge expires unpaid.

Path A — submit() resolves. Your handler runs before the navigation:

const result = await walletCollection.submit();

if (result.chargeStatus === "requires_action") {
// Nothing has been charged. The element navigates to result.redirectUrl
// for you — unless you opted out with handleRedirect: false.
return;
}

Path B — the raw response carries status: "requires_action" and next_action.redirect_to_url.url. On this path the redirect is yours.

Opting out — handleRedirect: false​

const express = elements.create("express-checkout", { handleRedirect: false });

The element then emits confirm and stops; the navigation is yours, exactly as on the card path.

Opt out if your confirm handler awaits anything

The element delivers the confirm and change events before it navigates, so a synchronous listener always observes the outcome. But anything your handler is still awaiting when the navigation begins is cancelled by the browser — an order write, a fraud check, an analytics call. You lose those records silently while the payment succeeds.

If your handler does server-side bookkeeping, set handleRedirect: false and navigate once your own work has finished.

On this arm:

  • No money has moved. No token is minted and charged is false. It is not a success — don't record it as one.
  • The buyer coming back is not proof of payment. They return through a Von Payments page to the session's successUrl (or our hosted pending page) with only status (succeeded, authorized on manual capture, failed or pending) and, when known, payment_intent_id added. A save-only check always returns pending; the card arrives on your webhook. Fulfill on the charge.* webhook or GET /v1/payment_intents/{id}, never from the URL.

If authentication is required but no usable challenge URL comes back, the SDK fails closed with frame_3ds_required and nothing is charged. Re-running submit() won't help. From vora.js 1.39.0 the error's reason is 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.

The bank check in a pop-up on your page​

To keep the buyer on your page, create the element with walletChallenge: "modal" (vora.js 1.43.0). The bank's page then opens in a pop-up over your checkout. The default, "redirect", is the full-page flow above.

const express = walletCollection.create("express-checkout", { walletChallenge: "modal" });

With the pop-up, confirm and change (with complete: true) fire once, after the check, and submit() resolves to its outcome:

OutcomeWhat you do
chargeStatus: "succeeded"The payment is placed, confirmed with the checkout before it was reported, so never charge again. charged: true: paid, fulfill on the charge.* webhook. charged: false: a captureMethod: "manual" session, authorized and held, not taken: capture or void paymentIntentId from your server. That id comes from the browser, so first read the payment on your server and check its metadata.session_id is this session, and that its amount, currency and status: "authorized" match your order (Authorize now, capture later). No charged value: read the session on your server with GET /v1/sessions/{id}, whose paymentStatus is paid or held.
chargeStatus: "pending", with pendingReasonNot confirmed yet, and the bank may still approve. Hold the order and let the charge.* webhook decide; never tell the buyer they were not charged. pendingReason only helps you word your message: challenge_closed (the buyer closed the check), challenge_failed (the check reported a failure, which usually ends as a decline) or challenge_unconfirmed (the check finished, the payment is not confirmed yet). The session takes no other payment meanwhile; if the webhook reports a failure, start a new session.
change error frame_3ds_challenge_cancelledThe buyer pressed Cancel and the checkout confirmed nothing was charged. With retryable: true the buttons stay up and the buyer can tap again (or pay by card, if your page has a card form). With retryable: false the session has ended: start a new one.

The element switches to the full-page check on its own, reporting requires_action first as above, when your Content-Security-Policy refuses the bank's page, when your page runs inside another site's frame or is cross-origin isolated, or when the pop-up cannot load. To allow the pop-up, add all of the wallet-modal sources from the CSP list. With only some of them, the check can run but its result cannot reach your page, so it ends as pending with challenge_unconfirmed unless the checkout has already confirmed the payment.


Constraints at a glance​

ConstraintDetail
BrowserApple Pay → Safari on macOS/iOS. Google Pay → a Chromium browser signed into a Google account.
DomainMust be verified for the wallet (setup). Derived server-side from Origin.
KeysWallet endpoints are publishable-key only — a secret key returns 403.
Availability501 endpoint_not_implemented while wallet sessions are switched off.
Card dataPAN/CVC never reach you; wallet device tokens are single-use cryptograms vaulted server-side. You hold only the vp_pmt_* + display metadata.

What's next​