Saving a Card and Charging It Later
Subscriptions, renewals, installments, and "charge my card next time" all rest on the same four steps. Each one is required. Skipping any of them produces an integration that looks correct (the card saves, the first payment succeeds) and then fails weeks later at the first renewal, when the buyer is gone and the card can no longer be re-collected.
This guide is the order to do them in. The detailed field references live on other pages and are linked at each step.
| Step | What you do | Where |
|---|---|---|
| 1 | Confirm the account can charge a saved card | GET /v1/capabilities |
| 2 | Declare what the stored card is for | POST /v1/sessions |
| 3 | Collect the buyer's consent as you save the card | your checkout surface |
| 4 | Charge the card later | POST /v1/payment_intents |
Step 1 — Confirm the account supports it
Read GET /v1/capabilities and require supported_operations.mit before you build. Branch on the response rather than assuming: what an account supports depends on how it was onboarded.
Step 2 — Declare what the stored card is for
Card networks require the payment that stores a card to say what the card will be used for. Send storedCredentialUse on POST /v1/sessions, the server-to-server call you make when the buyer signals they're ready to pay.
This is a factual statement to the card networks about the agreement you have with the cardholder, so make it from your server, alongside the rest of your session setup, not from code a shopper's browser can reach.
| Value | Use it for | Your later charge sends |
|---|---|---|
recurring | a fixed-interval subscription | mit.reason: "recurring" |
installment | a known number of scheduled payments for one purchase | mit.reason: "installment" |
unscheduled | a card kept on file and charged later with no fixed schedule | mit.reason: "unscheduled" |
Use the same word in both places. The two vocabularies are identical on purpose, so agreement is a plain string match with no mapping table to consult.
{
"amount": 2999,
"currency": "USD",
"buyerId": "user_8f3a2b",
"buyerEmail": "buyer@example.com",
"storedCredentialUse": "recurring"
}
There is no inferred default. If you omit storedCredentialUse, no declaration is made to the card networks and the payment goes out exactly as it would have before the field existed, even when the buyer consents to saving their card.
Consent looks identical for a subscription and for a card kept on file, so nothing is guessed on your behalf. An undeclared card saves and charges normally, but its later merchant-initiated charges carry no stored-credential lineage and may be declined.
A subscription must declare recurring explicitly.
Saving a card without charging it (mode: "setup", or an elements session with chargeAtSubmit: false) creates no payment to carry the declaration. It is recorded on the saved card instead. Which transaction then carries it depends on whether the save ran a $0 card check:
- With a $0 card check (your account is set up for it on its processor connection, and the session carries
buyerId), the check stores the card and carries the declaration. The card'scard_checkonGET /v1/payment_methodsreads{ "status": "approved", "stored_credential_use": "…" }. That value is what the check declared. A later save of the same card does not change it, even when it changes the card's ownstored_credential_use. A later merchant-initiated charge with nomit.original_transaction_id, on a card with no earlier customer-present payment, is linked to the check (where available on your account) only when itsmit.reasonequals this value. A check made for a different use does not count: the charge is then refused with422 mit_anchor_unknownand nothing is charged. Sendmit.original_transaction_id, or take a payment with the customer present first. - Without one,
card_checkisnull. The declaration is sent on the card's first approved charge throughPOST /v1/payment_intentswithout anmitblock, and latermitcharges are anchored to that charge.
A card stored through a $0 check before 13 November 2026 can also read null, when what that check declared is not on record. A merchant-initiated charge on such a card is not linked to the check: send mit.original_transaction_id, or take a payment with the customer present first.
To confirm your declaration landed, retrieve the session and read storedCredentialUse back. A null you did not expect is a bug in your create-session call, not a cosmetic detail.
If you vault through POST /v1/tokens rather than a checkout session, the same declaration is named stored_credential_use: snake_case on that surface, camelCase on session create. Reaching the card networks from there also needs currency and buyer_id on the request plus account-level enablement; when it doesn't, the card still vaults and the response carries a warnings entry instead of an error.
Step 3 — Collect the buyer's consent as you save the card
The call that vaults the card must carry setup_for_future_use: "off_session". Without it, the resulting token can never be charged on a merchant-initiated basis.
That gate is about merchant-initiated charges only. A saved card charged while the buyer is present (a one-click repeat purchase) goes through without off-session consent, because the buyer is consenting at that moment. A working one-click flow is therefore not evidence that consent was captured; the first rebill is where you find out.
There are two supported ways to get the buyer's agreement. Either one is consent; pick one per checkout:
- Our save-card checkbox, ticked by the buyer (below).
- Your own wording at the order button, with your code sending the consent (below).
Whichever you use, never show a pre-ticked box the buyer has to untick: the card networks do not accept that as consent.
Option 1: our save-card checkbox
On the embedded-fields surface, mount the consent element Von Payments ships. You do not have to build the checkbox yourself:
const save = elements.create('save-for-future-use', {});
save.mount('#save-card');
// submit() forwards the buyer's tick as setup_for_future_use: 'off_session'
It starts unchecked and cannot be pre-ticked: under the card networks' stored-credential rules a pre-ticked box is not consent, so the element gives you no way to set one.
submit() sends the box's tick with the card. The same tick goes with an Apple Pay or Google Pay payment from an express-checkout element in the same collection. If your wallet buttons are in another collection, pass the box to that element:
const ec = walletCollection.create('express-checkout', { saveForFutureUse: save });
Make the box a condition of paying
For a subscription, whose renewals need the saved card, create the box with required: true:
const save = elements.create('save-for-future-use', { required: true });
change.completeistrueonly while the box is ticked, so it can gate your Pay button on its own.- A card
submit()with the box unticked is refused before anything is sent, withframe_save_consent_required, and the box asks the buyer to tick it. - Wallet buttons reading the box are greyed while it is unticked; a tap asks the buyer to tick the box instead of paying.
- The built-in default look shows that prompt ("Tick this box to continue.") in red under the box and outlines the box in red while it waits. Your own CSS overrides both:
.vora-field--save-for-future-use [role=alert]for the text,.vora-field--save-for-future-use.vora-field--invalidfor the outline.
It never ticks the box for the buyer.
Put the box where the buyer commits
The consent box is its own element, so it does not have to sit with the card fields. Mount it in any container on your page. The pattern that works best is directly above the pay button, worded as the offer the buyer is accepting:
<div id="card-element"></div>
<!-- order summary, shipping, … -->
<div id="recurring-optin"></div>
<button id="pay-button">Subscribe</button>
const save = elements.create('save-for-future-use', {
label: 'Yes, bill me $29.99 every month until I cancel',
displayScope: 'limited',
});
save.mount('#recurring-optin');
- Write the label as the offer itself: the amount, how often, and how to stop. The buyer agrees to what the label says. A label that names one arrangement needs
displayScope: 'limited'(below). - Pair it with
storedCredentialUse: "recurring"on the session (Step 2). Send both: the tick alone makes no declaration to the card networks, and a declaration without the tick is dropped. - Style it with your own CSS. It renders as an ordinary checkbox and label inside your container, not in an iframe, and the container carries the classes
vora-fieldandvora-field--save-for-future-use(the full list). If your stylesheet draws.vora-fieldas an input box, leave this one out.
#recurring-optin { margin: 16px 0; font-size: 15px; color: #111827; }
#recurring-optin input[type="checkbox"] { accent-color: #2563eb; }
.vora-field:not(.vora-field--save-for-future-use) { border: 1px solid #d1d5db; }
Wherever you place it, it still starts unticked. In embed mode it also needs a session with a buyer and required: true (below).
Option 2: your own wording at the order button
Instead of a checkbox, the buyer can agree through your checkout's own terms, shown where they place the order. For example: "By placing this order you agree to be charged $29.99 every month until you cancel." The wording must:
- sit next to the order button, not only behind a link to your terms;
- state the price, how often the buyer is charged, any trial and when it ends, and how to cancel.
Keep a record of what each buyer saw and when they placed the order: that record is your evidence of consent if a rebill is disputed.
Your code then tells vora.js that your wording is the buyer's agreement:
| Where | Covers |
|---|---|
vora.elements.create({ setupForFutureUse: "off_session" }) | Every card payment and every Apple Pay / Google Pay payment from the collection. Read once, when the collection is created. |
submit({ setupForFutureUse: "off_session" }) | That one card payment. It does not reach wallet payments. In embed mode it is refused unless the form loaded saving (below). |
create("express-checkout", { setupForFutureUse: "off_session" }) | The wallet payments from that element. |
The card is saved for this arrangement only (allow_redisplay: "limited", below), and nothing is greyed. If the collection also has a save-card box, the box decides: a buyer's untick is never overridden. In elements mode with charge at submit, from vora.js 1.44.0 your wording is sent on a guest checkout too (a session with no buyer and no email), and the card is saved to a buyer Von Payments creates for the session; 1.43.x sent nothing on a guest session. In embed mode a guest's card is not saved, and the form decides when it loads (below). Saving an Apple Pay or Google Pay card without a payment still needs a buyerId on the session.
⚠️ Earlier vora.js versions ignored submit({ setupForFutureUse }) with a console warning. From 1.43.0 it saves the card on a session with a buyer, and from 1.44.0 on a guest session too, in elements mode with charge at submit (in embed mode a save asked at submit is refused unless the form loaded saving), so a page that already passes it on every payment starts saving cards: remove it if your wording is not the buyer's agreement.
Whichever option you use
Collecting the consent is yours to get right: we record it, we do not police it. setup_for_future_use is an ordinary optional field on a route that authenticates with the publishable key already shipped in your page. Whatever you send is recorded as the consent, and nothing checks that a buyer ticked anything. Sending consent from your own wording or your own control is a supported route. Asserting consent you never collected is not: it does not fail here, it fails later at the cardholder's bank, where a stored credential the buyer never agreed to is refused on rebill, and the liability for that is yours.
If you call the API yourself rather than through vora.js, you can also record which option you used: send setup_for_future_use_method as checkbox or checkout_terms beside setup_for_future_use on POST /v1/tokens, POST /v1/public/tokens or POST /v1/public/sessions/{sessionId}/charge. It is stored on the saved card and returned by GET /v1/payment_methods, alongside your own consent records. It is optional, it is recorded only when the same request sends setup_for_future_use, and it never changes what the card may be used for. A saved card can also read platform_disclosure, which you cannot send, or null when nothing was recorded; treat any value you do not recognise as "recorded, method unknown".
embed mode the consent control needs a session that already has a buyerThere must be someone to save the card to. In embed mode, a session created with neither a buyerId nor a buyer email saves nothing, whatever the box or your wording says. In elements mode, a session with no buyerId gets one when the card is saved, with or without a buyer email: Von Payments creates a buyer for the session and saves the card to it, never to an existing buyer with the same email. From vora.js 1.44.0, when the checkout refuses to save a guest's card, or the embedded form keeps no card for a guest, vora.js logs one console warning per page; the payment is not affected. A token in the result, or the payment_method.attached webhook, is what tells you the card was saved.
The charge still succeeds, so your page shows success and you only discover the missing card at the first rebill. In embed mode, create the session with buyerId (or a buyer email) before you render the control, or hide the control on guest checkouts. A buyer email alone saves the card to a buyer made for that one checkout.
⚠️ On some gateways the same situation is refused instead of ignored. Where the gateway vaults the card as part of taking the payment, it cannot charge at all without a buyer: submit() rejects with its own code, frame_buyer_required_for_saved_card, and nothing is charged. Do not fulfill on that one.
Consent is written at the moment the card is vaulted. No endpoint updates it: there is no PATCH, no PUT, no "promote consent" call. A retry loop built on re-stamping an existing token fails every time.
If a merchant-initiated charge returns payment_method_consent_missing (422), the card must be collected again with consent captured on that same call. See Fixing a missing consent for which endpoint to use for your flow.
In embed mode the payment form decides when it loads
From vora.js 1.44.0 the embedded payment form (embed mode, the default) saves the card only when the session names a buyer and, before the form loads, you either pass setupForFutureUse: "off_session" to elements.create() with no save box, or create the save box with required: true (Pay is refused until it is ticked). Otherwise the payment is charged without saving the card (charged: true, no token). A save asked only at submit cannot change that: a ticked optional box or submit({ setupForFutureUse }) on a form that loaded without saving, or an unticked box created after a form that loaded saving, makes submit() refuse with frame_unsupported_element, and nothing is sent. The separate card fields (elements mode) are unchanged.
There is a second permission, and it is also one-way
setup_for_future_use is permission to charge the card again. allow_redisplay is permission to show it back to the buyer in a later checkout. They are different agreements: a buyer who signs up for a subscription has not agreed to see that card offered as a one-click option on an unrelated purchase months later.
| Value | Meaning |
|---|---|
always | The card may be shown back to the buyer |
limited | Saved for one arrangement; never offer it back as a general saved card |
unspecified | You did not ask |
On the embedded-fields surface you do not send this yourself: the mounted consent element resolves it from the buyer's tick. An unticked box grants nothing (unspecified). A tick grants both permissions, and the display half defaults to always.
Set displayScope: "limited" on the element if the card is being saved for one arrangement and must never be offered back on an unrelated checkout:
const save = elements.create('save-for-future-use', {
label: 'Save my card for my Pro subscription',
displayScope: 'limited',
});
⚠ If you reword the label to name a specific arrangement, set limited. Leaving the default claims a broader permission than that buyer actually gave.
If you vault server-to-server instead, send allow_redisplay yourself on the vaulting call, and send unspecified when you did not ask, because that is a real answer and omitting the field is not.
Either way, this permission can only be recorded when the card is first saved. There is no path that adds it later: the buyer isn't present, and permission captured afterwards isn't permission given at save time. A card saved without it can never be shown back to its owner. See allow_redisplay.
Step 4 — Charge the card later
Send the mit block on POST /v1/payment_intents, anchored to the original payment where consent was captured. That page carries the field reference, worked renewal examples in both SDKs, and the chain-validity rules.
You own the rebill loop: the scheduler, the dunning on failure, and the subscription state machine are yours. Von Payments vaults the card and relays the charge. To have Von Payments run the schedule and the retries instead, use Subscriptions. Before each renewal from your own system, check subscription_billing.enabled: renew only when it is false.
Constraints worth knowing before you build
Attach a customer to every payment
On an account configured for network tokens, a payment that is not shaped to store a card is refused outright, not downgraded to a normal charge. The payment is shaped to store a card when the session identifies the buyer, through either buyerId or buyerEmail.
Send buyer identity on every payment, not only the ones where you intend to save the card. Observed on a live network-token connection in August 2026: an otherwise identical charge with no buyer attached was rejected with 400, while the same charge with a buyer succeeded and vaulted.
A declaration without consent is dropped silently
If you declare storedCredentialUse but the charge that stores the card carries no setup_for_future_use, the declaration is discarded and no error is returned. We will not assert an arrangement to the card networks on a signal the buyer never gave.
This is invisible from your side: the card saves, the payment succeeds, and nothing in the response indicates the declaration was dropped. It is the most common cause of a rebill that fails months after an integration was signed off. The read-back in step 2 is what catches it.
Not every connection accepts every arrangement
Matching your declaration to your later mit.reason is necessary but not always sufficient: what a connection will accept is set by your payment provider and the card issuer, not by us. On some connections only a fixed-interval subscription is accepted, and a correctly matched card-on-file pair is still refused.
The measured results and what they mean for your integration are on the payments page: Matching the values is necessary, not always sufficient.
A refusal may not tell you what went wrong
Some request-level faults arrive as an ordinary decline with the issuer's generic "revalidate payment information" advice. A charge you are debugging as a decline may in fact be a malformed request. If declines appear suddenly on a flow that previously worked, re-check the request before assuming the issuer refused it.
Troubleshooting
| What you see | Most likely cause | Go to |
|---|---|---|
payment_method_consent_missing (422) on a rebill | The card was vaulted without off-session consent, and it cannot be repaired | Step 3 |
| Rebills decline; the first payment was fine | Nothing was declared when the card was stored | Step 2 |
storedCredentialUse reads back null | Your create-session call omitted it, or it was dropped for want of consent | Step 2 |
400 on a charge that works elsewhere | No buyer identity on the session | Attach a customer |
| Matched declaration still declines | The connection does not accept that arrangement | Connection support |
What's next
- Tokenization: how the vault token is minted, and what reuse scopes mean
- Saved cards / merchant-initiated charges: the
mitfield reference and chain rules - Create a session: the full create-session field table