Vonpay
Cards, Apple Pay and Google Pay payments
vonpay-medusa
Vonpay payments for Medusa v2. One package adds card payments to your Medusa store and its Next.js storefront, with 3-D Secure. It can also add Apple Pay and Google Pay, saved cards for signed-in customers, renewal charges for your subscription plugin, and one-click offers after the order. Your Medusa admin gets a Held payments page for anything that needs a person, a setup check, and a notice when a new version is out.
The same package goes into your Medusa server and your storefront, so one update covers both.
Requirements
- Medusa 2.15.5 or later (tested on 2.15.5 through 2.21.x).
- Node.js 20.19+ or 22.12+.
- A storefront built on Medusa's Next.js starter (Next.js 15 or later), for the card step.
- A Vonpay account: a secret key (Copy to clipboard
vp_sk_test_…/ Copy to clipboardvp_sk_live_…) and a publishable key (Copy to clipboardvp_pk_test_…/ Copy to clipboardvp_pk_live_…) from the Vonpay dashboard. - For production: Redis, and a Medusa worker process (see Production settings).
Start with your test keys. Switch to live keys when the setup check passes.
Install (server)
In your Medusa server folder:
1npm install vonpay-medusa
Then register the plugin and its payment provider in Copy to clipboardmedusa-config.ts. This is a complete file for a new store; if you already have one, add the Copy to clipboardplugins entry, the payment module entry and Copy to clipboardadmin.backendUrl to it. If you already configure the payment module (for another provider), add the Vonpay entry to its existing Copy to clipboardproviders list.
1234567891011121314151617181920import { loadEnv, defineConfig, Modules } from "@medusajs/framework/utils"loadEnv(process.env.NODE_ENV || "development", process.cwd())// Refuse to start without a setting rather than run on a guessable default.const required = (name: string): string => {const v = process.env[name]if (!v) throw new Error(`${name} is not set`)return v}module.exports = defineConfig({projectConfig: {databaseUrl: required("DATABASE_URL"),http: {storeCors: required("STORE_CORS"),adminCors: required("ADMIN_CORS"),authCors: required("AUTH_CORS"),jwtSecret: required("JWT_SECRET"),cookieSecret: required("COOKIE_SECRET"),
With the id Copy to clipboardvonpay, Medusa names the provider Copy to clipboardpp_vonpay_vonpay. You will use that name in the admin, and the setup check reports it.
Set these in the server's Copy to clipboard.env (never in Copy to clipboardmedusa-config.ts or any file you commit):
Variable Required What it is Copy to clipboardDATABASE_URL yes Medusa's Postgres connection. Copy to clipboardJWT_SECRET, Copy to clipboardCOOKIE_SECRET yes Medusa's own signing secrets for admin and customer sessions. Each a long random value (for example Copy to clipboardopenssl rand -hex 32), never a default such as Copy to clipboardsupersecret. Copy to clipboardSTORE_CORS, Copy to clipboardADMIN_CORS, Copy to clipboardAUTH_CORS yes Medusa's allowed origins (your storefront, your admin). Copy to clipboardVONPAY_SECRET_KEY yes Your Vonpay secret key, Copy to clipboardvp_sk_test_… or Copy to clipboardvp_sk_live_…. Copy to clipboardVONPAY_MODE yes Copy to clipboardtest or Copy to clipboardlive. Must match the key. Copy to clipboardVONPAY_STOREFRONT_URL yes Your storefront's address, such as Copy to clipboardhttps://shop.example.com. Must be Copy to clipboardhttps; Copy to clipboardhttp://localhost is allowed with test keys. Shoppers come back here from their bank's 3-D Secure check. Copy to clipboardVONPAY_WEBHOOK_SECRET after setup The signing secret Vonpay shows when you register your notification endpoint. Leave it empty for the first start (see Payment notifications). Copy to clipboardVONPAY_SHOPPER_IP_SECRET optional With one-click offers: a long random value of your own (Copy to clipboardopenssl rand -hex 32), the SAME value in the storefront's environment. It proves the shopper's address on offer charges is real (see Copy to clipboardupsells, "The shopper's address on offer charges"). Never your Vonpay key or the webhook secret. Copy to clipboardMEDUSA_BACKEND_URL recommended Your Medusa server's public address, such as Copy to clipboardhttps://api.example.com. Lets the setup check confirm the notification endpoint is this store's. Copy to clipboardVONPAY_UPDATE_CHECK no Copy to clipboardoff turns off the update notice (for a server with no outbound internet).
Then create the plugin's tables and start the server:
12npx medusa db:migratenpx medusa develop # or your usual start command
The server refuses to start if a required setting is missing or malformed: a key that is not a secret key, a mode that does not match the key, or a storefront address that is not Copy to clipboardhttps. The error names the problem, never the value.
Turn it on in your regions
Medusa offers a payment provider only in the regions you add it to. Until you do, checkout never shows Vonpay.
- In the Medusa admin, open Settings → Regions.
- Edit each region you sell in.
- Add Copy to clipboard
pp_vonpay_vonpayunder payment providers, and save.
The setup check fails ("regions") while no region offers Vonpay.
Payment notifications
Vonpay sends your server a notification when something happens to a payment. Your store accepts only notifications signed with your endpoint's signing secret, and Vonpay gives you that secret only after you register the endpoint. So the order is:
- Install and start the server without Copy to clipboard
VONPAY_WEBHOOK_SECRET. Payments already work. Every notification is refused until the secret is set, and the setup check fails Copy to clipboardwebhook_secret. Vonpay does not send a refused notification again, so finish these steps before you take live payments. - Register the endpoint in the Vonpay dashboard. The address is your server's public address followed by Copy to clipboard
/hooks/payment/vonpay_vonpay: Choose all events (this includes Copy to clipboardpayment_intent.authorized, which Apple Pay and Google Pay need). Only if Vonpay runs your subscriptions (Copy to clipboardsubscriptions: "vonpay"), also add the five subscription events, which "all events" does not include: Copy to clipboardsubscription.created, Copy to clipboardsubscription.renewed, Copy to clipboardsubscription.payment_failed, Copy to clipboardsubscription.cancelledand Copy to clipboardsubscription.updated.
1https://<your backend>/hooks/payment/vonpay_vonpay
- Copy the signing secret into Copy to clipboard
VONPAY_WEBHOOK_SECRET. - Restart the server and the worker.
- Run the setup check (see Check your setup).
Keep one endpoint per store. If two active endpoints point at the same path, Vonpay sends every event to both, and the setup check warns.
The shopper's own checkout page creates the order, never a notification. If a shopper pays and closes the page first, the plugin's recovery job creates it about 10 minutes after the payment.
Storefront
In your storefront folder:
12npm install vonpay-medusa # or pnpm add / yarn addnpx vonpay-medusa setup-storefront
The command expects Medusa's Next.js starter layout. It:
- writes Copy to clipboard
src/lib/vonpay/actions.tsand Copy to clipboardsrc/lib/vonpay/index.tsx(the small files that connect the package to your storefront); - adds the 3-D Secure return page at Copy to clipboard
checkout/vonpay-return; - adds the My saved cards account page, the one-click offer pages (Copy to clipboard
order/[id]/offerand Copy to clipboardorder/[id]/offer/return), and the route Apple Pay needs at Copy to clipboard/.well-known/apple-developer-merchantid-domain-association; - adds Copy to clipboard
vonpay-medusato Copy to clipboardtranspilePackagesin your Next config and to Tailwind's Copy to clipboardcontent; - names the payment method "Credit card" and puts the card form in the checkout's pay button;
- moves that pay button into the checkout's Payment step for a Vonpay payment: it edits the starter's Payment step, Review step and checkout form (all three, or none of them), so the card form shows directly above Place order and a Vonpay payment has no Review step. Other payment methods keep the starter's Review step. The terms sentence your Review step shows above its button is copied above Place order too; if you change that wording later, change it in both steps;
- offers to turn on automatic update pull requests (see Keeping it up to date).
Each step runs only if it is still needed, so the command is safe to run again. Copy to clipboard--dry-run writes nothing. It never edits a file it does not recognise, and never replaces an existing file that differs from what it would write unless you pass Copy to clipboard--force; those steps print as "manual", with the change to make by hand.
After it runs:
- Set Copy to clipboard
NEXT_PUBLIC_VONPAY_PUBLISHABLE_KEYin the storefront's environment to your publishable key (Copy to clipboardvp_pk_…). Never put the secret key in the storefront. Without a valid publishable key the checkout shows "Card payments are unavailable right now." - Make sure the server's Copy to clipboard
VONPAY_STOREFRONT_URLis this storefront's address. - Add a "Saved cards" link to your account menu, pointing at Copy to clipboard
/account/saved-cards. The menu is your own file, so the command prints where instead of editing it.
The card form appears in the Payment step, directly above Place order (no separate Review step). Choosing "Credit card" starts the payment, so the card form appears at once; where Vonpay is the only way to pay, it is chosen for the shopper. While a payment is under way, the payment method choice cannot be changed. It loads Vonpay's vora.js from Copy to clipboardhttps://js.vonpay.com/v1/vora.js, so Vonpay's card-form fixes reach your store without a release.
Upgrading a storefront set up with 1.2.0 or earlier: those versions put the card form in the Review step. Run Copy to clipboardnpx vonpay-medusa setup-storefront again; it moves it into the Payment step when your Payment step, Review step and checkout form are still the starter's. If you changed one of them, the command changes none of them and prints the step to make by hand. In your Payment step (a client component, after its state):
123456789101112131415161718import { useVonpayPaymentStep, vonpayStaysActive } from "vonpay-medusa/storefront"const activeSession = cart.payment_collection?.payment_sessions?.find((s) => s.status === "pending" || vonpayStaysActive(s) // a Vonpay payment stays active past "pending")// …the step's own useState calls…const vonpay = useVonpayPaymentStep({cart,availablePaymentMethods,activeSession,selectedPaymentMethod,setSelectedPaymentMethod,step: searchParams.get("step"),initiatePaymentSession, // from @lib/data/cartsetIsLoading,setError,})const isOpen = searchParams.get("step") === "payment" || vonpay.opensStep
Then: return early from the method choice while Copy to clipboardvonpay.locked and call Copy to clipboardawait vonpay.start(method) when a method is chosen; disable the method list while Copy to clipboardvonpay.locked; return from "Continue" when Copy to clipboardvonpay.selected; and while Copy to clipboardvonpay.cardHere, render your terms and your pay button (Copy to clipboard<PaymentButton cart={cart} … />) in place of the "Continue" button. In your Review step, render nothing when Copy to clipboardvonpayHidesReview(cart, availablePaymentMethods) (from Copy to clipboardvonpay-medusa/storefront/shared) is true, and pass it Copy to clipboardavailablePaymentMethods from the checkout form.
The typed card stays when the total changes. Medusa replaces the cart's payment whenever its total changes: an order bump, a coupon, another delivery option. The card form now stays on screen and moves to the new payment, so the shopper does not type the card again. While it moves, the form says "Updating your total…" and Place order waits. The move is checked against the total your page shows; if anything does not match, the form is built again, empty, and says "Your total changed. Enter your card again." A ticked "save my card" box comes back unticked, so the shopper confirms it again for the new total.
How it works on your server: each card payment of a checkout is created in one group (the checkout's payment collection), and the page gets that payment's client secret, the key the card form is read with, while the payment can still take a card. Once anything may have been charged, the key is no longer given out. The plugin never logs it.
- This needs Vonpay's card-form transfer, which is rolling out. Until it reaches your store, the form is built again as before. You do not need to change anything for that.
- Copy to clipboard
setup-storefrontwires it into the starter's pay button: the Vonpay case also renders while Copy to clipboardkeepsVonpayCardForm(cart)is true. Running the command again on a store it set up earlier adds that one condition. A pay button you changed by hand is left as it is, with the line to add printed. - Your own checkout (for example, an order bump shown after the card is typed): keep Copy to clipboard
<VonpayCardPayment>rendered, in the same place, while Copy to clipboardkeepsVonpayCardForm(cart)is true (from Copy to clipboardvonpay-medusa/storefront/shared). That is the moment the cart has no payment and the card form is waiting for the next one. If you unmount the card form, the typed card is gone.
Content Security Policy
Medusa's starter sends no Content Security Policy. If you add one, the pages that show the card form need Vonpay's sources: the checkout, the 3-D Secure return page, and the offer pages (Copy to clipboard/<country>/order/<id>/offer and Copy to clipboard/offer/return). The package gives you the list:
12345import { readVonpayBrowserConfig, vonpayCspSources } from "vonpay-medusa/storefront/shared"const vp = vonpayCspSources(readVonpayBrowserConfig())// Add vp.script, vp.connect, vp.frame, vp.img, vp.font and vp.style// to script-src, connect-src, frame-src, img-src, font-src and style-src.
Do not use Copy to clipboard'strict-dynamic' in Copy to clipboardscript-src: browsers then ignore the host list. Also allow your Medusa backend in Copy to clipboardconnect-src. The list is bundled with the package; to follow Vonpay's live list between releases, call Copy to clipboardrefreshVoraCspList() (same import) after the response, for example with Copy to clipboardevent.waitUntil(refreshVoraCspList()) in your middleware. A page never waits for it.
Production settings
A production Medusa store runs a server and a separate worker that share Redis. The plugin's background jobs and payment notifications run on the worker, and both processes must share one lock so two of them never complete the same checkout at once. Add these modules to Copy to clipboardmedusa-config.ts, next to the payment module:
1234567891011121314151617181920// in defineConfig({ ... })projectConfig: {// ...your existing settingsredisUrl: process.env.REDIS_URL,workerMode: process.env.MEDUSA_WORKER_MODE as "shared" | "worker" | "server",},admin: {disable: process.env.DISABLE_MEDUSA_ADMIN === "true", // add this line to your admin blockbackendUrl: process.env.MEDUSA_BACKEND_URL,},modules: [// ...the payment module from above{ key: Modules.EVENT_BUS, resolve: "@medusajs/medusa/event-bus-redis", options: { redisUrl: process.env.REDIS_URL } },{ key: Modules.WORKFLOW_ENGINE, resolve: "@medusajs/medusa/workflow-engine-redis", options: { redis: { redisUrl: process.env.REDIS_URL } } },{key: Modules.LOCKING,resolve: "@medusajs/medusa/locking",options: {providers: [{ resolve: "@medusajs/medusa/locking-redis", id: "locking-redis", is_default: true, options: { redisUrl: process.env.REDIS_URL } },
Medusa already includes the Redis caching provider; with pnpm (whose strict layout hides packages you did not add yourself), add Copy to clipboard@medusajs/caching-redis at your exact Medusa version. Then run two processes: the server with Copy to clipboardMEDUSA_WORKER_MODE=server, and the worker with Copy to clipboardMEDUSA_WORKER_MODE=worker and Copy to clipboardDISABLE_MEDUSA_ADMIN=true.
Check your setup
From your Medusa server folder:
1npx vonpay-medusa-check
In an image built with Copy to clipboardmedusa build, run it from Copy to clipboard.medusa/server, where the built config lives. The same check runs from the Check Vonpay setup button on the admin's Held payments page.
Each line is PASS, WARN, FAIL or SKIP (could not be checked), with what to do. The command exits with code 1 when anything fails; Copy to clipboard--strict also fails when a check could not run. Copy to clipboard--move-to-held <Vonpay payment id> first moves a payment the Copy to clipboardpaid_without_order line lists to the Held payments page (see below), then runs the check. It checks:
- provider: the Vonpay provider is registered and enabled.
- webhook_secret: the signing secret is set.
- regions: at least one region offers Copy to clipboard
pp_vonpay_vonpay. - recovery: the recovery job is on.
- key: Vonpay accepts your secret key. Read-only; nothing changes.
- endpoint: a notification endpoint for Copy to clipboard
/hooks/payment/vonpay_vonpayis registered and active. The check names the address. If it cannot confirm the address is this store's (set Copy to clipboardadmin.backendUrl, or use the admin button), it warns and sends no test notification. - subscriptions: with Copy to clipboard
subscriptions: "vonpay", the module is registered, its table is up to date (FAIL until you run Copy to clipboardnpx medusa db:migrateafter an update), and the endpoint receives the five subscription events. - subscription_signup: with Copy to clipboard
subscriptionSignup: true, every variant you sell as a subscription has an active Vonpay subscription product with its id as the Store product number (FAIL when one does not, or when Subscriptions is off at Vonpay); WARNs about a Vonpay product whose variant is not marked, a number that matches no variant, or a store subscription plugin still configured. With the setting off, it WARNs when variants are still marked (they then sell as one-time purchases). - wallets, wallet_domains: with Copy to clipboard
wallets: true, the endpoint receives Copy to clipboardpayment_intent.authorized, and your storefront's domain is registered and verified. - descriptor: your statement descriptor setting in Vonpay reads the field the plugin sends: PASS when they match (and what feeds it), WARN when they differ. Nothing is shown when neither uses a per-payment ending.
- paid_without_order: checkouts more than a day old that Vonpay reports paid (or holds), with no order and not on the Held payments page: a checkout whose page asked for the order while Vonpay was still confirming the payment and then gave up, or a shopper who paid and left before the page asked at all. (The recovery job finishes or lists every other paid checkout within a day.) It looks back 90 days (option Copy to clipboard
paidWithoutOrderLookbackDays). The check itself only reads, with test and live keys. A FAIL lists each Vonpay payment id. Move each one to the Held payments page: press Move to Held payments beside it in the admin, or run Copy to clipboardnpx vonpay-medusa-check --move-to-held <id>. The plugin checks the payment with Vonpay again and makes sure no order holds it. Then it lists the payment on the Held payments page, where you refund it, or mark it resolved if you settled it another way (for example a dispute, or an order you sent by hand). A held wallet payment is released or completed there instead. Pressing it twice lists the payment once. The server log records who moved it (Copy to clipboardpaid_without_order_moved). The line then clears. A payment refunded in full in the Vonpay dashboard is not listed. A payment whose full refund is still in progress at Vonpay gets its own WARN line (nothing to do yet; if the refund fails, it is listed to move). How far it looks in one run: it looks first at the checkouts whose page asked for an order, which are rare, then at the others, which include every abandoned checkout. Each run reads up to 25 payments from Vonpay from the admin (200 from the command) and up to 2,000 of your records per group. When it has not finished, it warns and says how far it got. Run it again from the admin: it continues below where it stopped, and it starts again from the newest once it finishes. That place, and what it has already found settled, are kept in the server's memory, so a server restart starts it again from the newest. The command is a new process each time, so each command run starts from the newest; use the admin button to go further down. It passes only when a whole search finished with nothing left to check. It also warns when Vonpay or your database cannot be read, and on every run while a payment shows money but cannot be proven to be that checkout's (check it in the Vonpay dashboard). Separately, it warns when unfinished payments are older than the look-back, or when that look could not finish on your database: after a slow or failed answer it rests for 30 minutes, and the warning names the index to add. That rest is kept in the server's memory, per process, so a restart ends it; the terminal command is a new process each time, so it never rests. It never passes a payment it could not read. A pass means "as of the search's passes", not one instant. The command's move finds the payment through Vonpay, so it works wherever the search stands. It needs the shared lock from the production settings (the Copy to clipboardlockingline: Redis or Postgres as Medusa's default provider); without it the command moves nothing (Copy to clipboardmove_lock_not_shared), so use the admin button. - renewal_search: with Copy to clipboard
subscriptions: "store"and saved cards on, FAILs when Vonpay refuses this key the list of payments with Copy to clipboardapi_key_permission_denied(the key lacks Copy to clipboardpayment_intents.read), because every renewal would then be refused and nothing charged. Any other refusal of the list is a WARN that shows Vonpay's code. Before each renewal charge the plugin asks Vonpay whether that period was already paid (one charge per period), and with this key it cannot ask. The held list's Check this order reads the same list. Give the key that permission. Any other failure says nothing about the key and gives no line. - renewal_period: with Copy to clipboard
subscriptions: "store"and saved cards on, the plugin's record of paid subscription periods must be there (run Copy to clipboardnpx medusa db:migrate; a store that registers the plugin's modules itself adds Copy to clipboardvonpay-medusa/modules/vonpay-jobs). Without it, every renewal of a ReorderJS period is refused. FAILs when one of the store's newest 100 orders is a ReorderJS renewal; otherwise a WARN (nothing is refused yet, but the first ReorderJS renewal will be). A read that failed just now is a WARN: run the check again. - job_status: where the background job finishes paid renewals (Copy to clipboard
recoveryon, saved cards on), FAILs when the plugin's job status module is not loaded or its table does not exist (run Copy to clipboardnpx medusa db:migrate; a store that registers the plugin's modules itself adds Copy to clipboardvonpay-medusa/modules/vonpay-jobs), and when the table could not be read just now (a timeout or a database error: run the check again). Without it the held list cannot tell whether the job runs. - event_bus, workflow_engine, locking: the production settings. Each fails or warns when missing (shared locking with Postgres also passes). With several locking providers listed, the shared one must be marked Copy to clipboard
is_default: true: Medusa otherwise uses its in-memory one. - caching: WARNs when Redis caching is missing; the notification test then cannot run.
- worker_mode: the command cannot see a worker. The admin button warns when it runs on a server-only process; that is expected, as long as your worker is running.
- processed: with test keys only, Vonpay sends a test notification and the check waits for the store to verify and process it (needs Redis caching). With live keys it sends nothing.
Options
These go in the provider's Copy to clipboardoptions in Copy to clipboardmedusa-config.ts, next to the four settings from Install. All are optional.
Copy to clipboardrecovery (default Copy to clipboardtrue)
Every 5 minutes, on the worker, the plugin looks for unfinished checkouts (10 minutes to 24 hours old) that Vonpay reports paid. This includes a checkout whose page asked for the order while Vonpay was still confirming the payment (for example, during the shopper's bank check) and then stopped waiting. For each one it runs Medusa's own payment step and confirms an order exists. If Medusa still makes no order, the payment goes on the Held payments page as "Paid, order not created". It never refunds.
Checkouts more than 24 hours old are not finished automatically. The setup check lists any that Vonpay reports paid (Copy to clipboardpaid_without_order), and you can move each one to the Held payments page.
A payment refunded in full never becomes an order. Before Medusa makes the order (from the shopper's page or from this job), the plugin asks Vonpay for the payment's refunds. If refunds that went through cover the whole payment (for example, you refunded it in the Vonpay dashboard), no order is made. The checkout is closed as "refunded, no order", and the shopper's page says the payment was refunded. If a refund of the whole payment is still in progress (or Vonpay's refund record cannot be read), no order is made yet: the job looks again, the order goes ahead if the refund fails, and at the job's last look (about 24 hours) the payment goes on the Held payments page as "Paid, order not created" — it is never dropped. A partial refund does not stop the order. While a checkout's other payment (its card, or its Apple Pay / Google Pay hold) can still be paid, the refunded one is not closed, so that payment can still become an order. If a refund in full lands just after the order is made, the server logs an error (Copy to clipboardrefunded_after_order) naming the order; nothing is cancelled.
This is the only thing that completes the order for a shopper who pays and closes the page. Leave it on. Copy to clipboardrecovery: false turns it off, and the setup check fails while it is off.
Copy to clipboardpaidWithoutOrderLookbackDays (default Copy to clipboard90)
How many days back the setup check's Copy to clipboardpaid_without_order line looks for a paid checkout with no order (and how old a payment Move to Held payments accepts). A whole number from 2 to 3650. Checkouts younger than a day are the recovery job's. If unfinished payments exist further back, the line warns and names this option. Raise it once to look further back (for example right after updating from 1.2.0 or older, if your store is older than 90 days), run the check, then set it back: the search then covers your store's payment records for that whole period.
Copy to clipboardholdRecheck (default Copy to clipboardtrue)
When a cart changes during payment, Vonpay may not close a just-declined payment straight away, and the payment goes on the Held payments page as "outcome unknown". Every 5 minutes, on the worker, the plugin asks Vonpay again. Once Vonpay closes it with nothing charged, it leaves the list ("closed automatically"). It never refunds and never touches a payment that may carry money. Copy to clipboardholdRecheck: false turns it off; those rows then wait for a person.
Copy to clipboardsavedCards (default off)
Copy to clipboard"recurring" or Copy to clipboard"unscheduled" turns on saved cards for signed-in customers. Both values do the same thing: the cart decides what Vonpay tells the card networks about each card saved:
- On a subscription cart (a cart line your subscription plugin marks as a subscription, as ReorderJS does): Copy to clipboard
recurring, because the renewals charge it on a fixed schedule. - On any other cart: Copy to clipboard
unscheduled, a card kept on file and charged later with no fixed schedule.
Vonpay applies this only when the payment really saves the card with the shopper's agreement. Each card keeps what it was saved with, and a renewal repeats that card's own value, so changing this option never changes cards already saved. (A card saved before Vonpay recorded this falls back to the option's value, and the plugin logs Copy to clipboardrenewal_declaration_missing.) Vonpay notes that on some processor connections (network tokens) only Copy to clipboardrecurring is accepted for later charges; an Copy to clipboardunscheduled card there may be declined when charged later.
With it on, a signed-in customer's checkout shows Vonpay's "Save my card for future orders" checkbox, never pre-ticked. Guests never see it. A customer keeps at most 10 saved cards; at 10, checkout stops offering to save and asks them to remove one. On a subscription cart the checkbox is required and the limit is 50. The same card saved twice (same brand, last four digits and expiry) counts as one card.
Customers see and remove their cards on the My saved cards page. Each card appears once, even if it was saved by several payments. A card they did not agree to have shown back is listed as "A saved card", with no brand or digits (such cards cannot be matched, so each is listed on its own). Removing a card revokes it at Vonpay for good, including every other saved copy of the same card the customer holds; a subscription that was renewing on one of those copies then needs a new card. The plugin sends Vonpay only your own customer reference, never the customer's email. When you delete a customer in Medusa, the plugin revokes their cards and erases any email Vonpay still holds for them (sent by plugin versions before 2026-10-19).
Copy to clipboardsavedCardsTerms (needs Copy to clipboardsavedCards)
Consent by your own terms instead of the checkbox. The value is your exact wording: plain text, 20 to 1,000 characters, saying the card is kept and charged for the renewals. For example: "Your card is saved and charged automatically for this subscription's renewals until you cancel."
With it set, checkout shows no checkbox. On a subscription cart the page shows "By placing your order you agree to:" and your wording, above the Apple Pay / Google Pay buttons when they show, otherwise just above the pay button. Completing that checkout saves the card for the renewals. A one-time purchase saves nothing. The plugin records your configured wording with each payment it applied to, when the payment is confirmed. It records what the store was configured to show, not a capture of the shopper's screen, so change the wording deliberately. Cards saved this way are listed as "A saved card". This needs vora.js 1.43.0 or later; with an older one, a subscription cart shows the required checkbox as well as your wording.
Your responsibility with terms mode. Rules for saving a card for renewals and for automatic renewals (the card networks' stored-credential rules; in the US, state automatic-renewal laws such as California's and the federal ROSCA) expect clear terms next to the action, the shopper's agreement, and a record. The plugin supplies the placement, the lead-in and the record; the wording is yours. It must state the price (or how it is set), how often it renews, that it continues until cancelled, and how to cancel. Send your own confirmation email with those terms after the order, keep cancellation simple, and have your wording reviewed by your legal counsel: whether completing checkout under the terms counts as consent where you sell is a legal question this plugin cannot answer. Outside the US other rules apply. If in doubt, keep the checkbox (leave Copy to clipboardsavedCardsTerms unset).If you sell subscriptions with only the checkbox, the setup check warns (Copy to clipboardsaved_cards_terms): the checkbox alone does not show the price, how often, any trial or how to cancel. Each recorded payment is also written to the server log (Copy to clipboardsave_consent_recorded, with ids and the wording's fingerprint, never the wording or an email), because payment data can be read from the storefront.
Copy to clipboardsubscriptions (default off)
Who runs your subscription renewals. Exactly one, so a customer is never charged by two systems.
- Copy to clipboard
"store": your own subscription plugin (such as ReorderJS) renews, and this plugin charges the saved card when it asks. Needs Copy to clipboardsavedCards. - Copy to clipboard
"vonpay": Vonpay's own subscription billing renews, and this plugin charges no renewal itself. Run Copy to clipboardnpx medusa db:migrate(Medusa loads the plugin's subscriptions module itself when the plugin is listed under Copy to clipboardplugins; otherwise register it as below), and add the five subscription events to your endpoint: Vonpay's subscription notifications then appear in the admin under Orders → Vonpay subscriptions. They do not create or change orders yet.
1234modules: [// ...{ resolve: "vonpay-medusa/modules/vonpay-subscriptions" },],
Renewal charges (Copy to clipboard"store"). The plugin charges only when all of these hold; anything else is refused and nothing is charged:
- the payment belongs to an existing order, has no cart, and was opened with Copy to clipboard
data.off_session === true(the shape ReorderJS 1.1.0 and 1.1.1 use); - saved cards are on, and the session's customer is the order's customer;
- that customer has a Vonpay buyer created by this plugin, and the card is one that may be charged while the customer is away, in the store's current mode (test or live);
- right before the charge, Vonpay confirms it does not bill this store's subscriptions itself and supports charges started without the shopper. Any other answer, or none, means nothing is charged (logged as Copy to clipboard
renewal_subscription_billing), and the next attempt asks again.
Each order is charged at most once. An attempt whose result is unknown, that Vonpay reports as not yet settled, or whose amount or buyer does not match goes on the Held payments page, and every later attempt on that order is refused until a person closes it there (see below). The plugin keeps reading a payment the row names, for a week, while the background job is on and only if it had not finished when read: when it ends with no money the row closes by itself and the next attempt may charge, and when it succeeds the order is finished. A row whose amount or customer did not match is not read again: a person closes it. Connection errors are retried up to three times with the same request key. A declined attempt leaves the next one free. If Vonpay charged a renewal but the store stopped before Medusa recorded it, the recovery job finishes it without charging again; if it cannot, the renewal is listed as "Renewal charged, order unpaid": refund it in full in Vonpay and press Check this order, or close the row to keep the order blocked. Do not charge again, and do not mark the order paid by hand in Medusa: the check reads that as the order paid twice.
In ReorderJS: a held or refused renewal comes back as "not authorized", so ReorderJS records a failed payment and opens a dunning case, even when a held charge may in fact have gone through. Check the payment in the Vonpay dashboard before acting on a failed renewal.
Use ReorderJS 1.1.1 or later. In ReorderJS 1.1.0 (its code, not this plugin's), the automatic retry of a failed renewal and "Retry now" on its dunning screen stopped before they reached any payment provider, so a renewal whose first attempt failed was never charged again. ReorderJS 1.1.1 fixes this: a retry now opens a new payment on the renewal order with the subscription's saved card, marked as charged without the shopper present, and asks this plugin to charge it. A store on 1.1.0 should upgrade. "Mark recovered" and "Mark unrecovered" still only change the case status: mark a case recovered only once the money has arrived.
One charge per subscription period. The plugin charges each subscription period once, even when your subscription plugin asks again on a new order. Why: in ReorderJS 1.1.1 (its code, not this plugin's), a renewal that failed and was then paid by a dunning retry stays "failed". ReorderJS's 5-minute renewal job then runs it again, creates a new renewal order, and asks for a second charge for the same period. This was seen in test mode on 10 November 2026.
Upgrade: run Copy to clipboardnpx medusa db:migrate. The plugin keeps its own record of paid periods in a new table. Until the migration runs, the plugin refuses every renewal charge of a ReorderJS period (nothing is charged) and logs an ERROR line naming the command. The background job also logs one ERROR line (Copy to clipboardrenewal_period_table_missing) at its first run after the server starts, so you hear it before the next renewal. The setup check says so too (Copy to clipboardrenewal_period). A store that lists the plugin's modules itself in medusa-config needs Copy to clipboardvonpay-medusa/modules/vonpay-jobs there.
What the plugin does:
- ReorderJS writes the renewal cycle (one cycle is one period) on every renewal order. The plugin sends that cycle with each renewal charge. It reads the cycle only on an order ReorderJS created itself (an order with no cart). A shopper can put any value in a cart's metadata, and Medusa copies it to the order, so an order placed from a cart is never read as a renewal.
- Before it sends a renewal charge, the plugin writes the period in its own record ("sending"). When Vonpay answers, it writes the result: paid, not finished, unknown, or nothing charged. Before each later charge it reads that record, and it also asks Vonpay for the charges of that cycle.
- If the period is paid, the plugin refuses the new charge. Nothing is charged. A full refund does not change this: only a person can reopen a paid period (see below). The refusal comes back to ReorderJS as "not authorized", and ReorderJS's dunning stops retrying it.
- If a charge of the period is not finished yet, or its result is unknown, the plugin refuses for now. It never sends a second charge on a guess. ReorderJS tries again later: if the earlier charge ends with no money, the next try charges.
- Two renewals of one period at the same moment (ReorderJS's renewal job and its dunning job run on the same 5-minute tick) take turns, and the record lets only one charge go, also across a server and a worker.
- A retry of the same order after a decline still charges. A new period is a new cycle, so it charges as normal.
- If the record or Vonpay cannot be read, the plugin does not charge, and ReorderJS tries again later (Copy to clipboard
renewal_period_unreadable). So give the key the Copy to clipboardpayment_intents.readpermission. Without it, every ReorderJS renewal is refused, and the setup check FAILs (Copy to clipboardrenewal_search). - A ReorderJS order that names a subscription but no renewal cycle is refused too (ERROR line, Copy to clipboard
renewal_period_unreadable, Copy to clipboardno_cycle_id): the plugin cannot tell which period it is for.
The log:
- The first refusal of a paid period writes an ERROR line Copy to clipboard
renewal_period_already_chargedthat names the new order and the earlier payment. Later refusals of the same period are WARN lines with the running count (Copy to clipboardrefusals), so an alert pages once, not every 5 minutes. The count is kept in the record, so a restart or a second server does not page again. - A charge whose result is unknown, with no payment found for it after an hour, writes one ERROR line Copy to clipboard
renewal_period_lost_answer(once per period). The period stays blocked until a person acts.
On Held payments:
- Renewal refused — this period is already paid. ReorderJS asked to charge a paid period again. The customer has paid. In ReorderJS the renewal stays failed and makes a new unpaid order every 5 minutes until that renewal is closed there. Cancel the extra unpaid orders in Medusa. Then press Keep blocked, or Reopen this period if the earlier payment was refunded and the customer must pay for the period again. Keep blocked moves the row to Resolved for 24 hours. More refusals in that time only add to the count. The first refusal after your close writes one ERROR line (Copy to clipboard
first_since_close), because the period is still being asked for after someone looked; later ones are WARN lines, also after a restart. If ReorderJS still asks after 24 hours, the row comes back. - Earlier renewal charge not finished. A charge of the period has no result after an hour, or has not finished after 24 hours. Find it in the Vonpay dashboard. If it must not go through, cancel it there, then press Check with Vonpay: the period is then free and the next renewal charges. The plugin never frees such a period by itself. A charge with no result may still be deciding, so its row offers only Check with Vonpay until it is 24 hours old; Reopen comes after that.
- Reopen this period asks you to type the order id (or, when the row names no order, the Vonpay payment id) and tick "I checked Vonpay". A row that names neither offers no Reopen: press Check with Vonpay first. Before it reopens, the plugin checks every payment of the period in Vonpay, back to 30 days before the record began: each must be refunded in full or have ended with no money. If not, nothing changes. Your name and the time are kept on the record.
- Resolved period rows leave the list after 30 days. The record itself is kept.
Limits:
- A charge made by plugin 1.3.0 or older is not in the record and does not carry the cycle, so the plugin cannot find it.
- Before a charge, Vonpay's list looks back 30 days. The record has no time limit.
- Reopen checks Vonpay back about a year (13 windows of 30 days). A period whose record began earlier than that cannot be reopened.
- An order without a renewal cycle and without a subscription (another subscription plugin) is charged as before, once per order.
After a declined renewal, only ReorderJS's own retries charge that card. In ReorderJS 1.1.1, a renewal that DECLINED is run again every 5 minutes as a new order, and each run charges the card that just declined. This is on top of ReorderJS's own retries of the declined order (its dunning). It was seen in test mode on 11 November 2026: three extra declined charges in 16 minutes. Card networks count each new charge on a declined card as a retry, and the merchant can be billed for too many (Visa: at most 20 in 30 days).
Upgrade: run Copy to clipboardnpx medusa db:migrate (a new migration adds the card and its declines to the plugin's period record).
What the plugin does. It remembers each card's own decline for a subscription period, and judges every renewal charge only against the decline of the card it charges:
- When a charge declines, the plugin records it under that card: the order that first declined on it, when, Vonpay's decline code, its Copy to clipboard
action, and the card network's advice and wait. A payment that was cancelled or voided counts as a decline too. - A NEW order for that period on a declined card is refused, for good. Nothing is sent. Only the order that declined may charge that card again. That is the order ReorderJS's dunning retries: its retry charges the same order (ReorderJS Copy to clipboard
run-dunning-retry.js:360). - Those retries go through at least 24 hours apart. If the card network named a longer wait, the plugin waits that long instead.
- A decline that Vonpay or the card network marks final is never retried on that card, not even by the declined order: Copy to clipboard
actionCopy to clipboardhard, Copy to clipboardgenericor Copy to clipboardfix_and_retry, or network advice Copy to clipboarddo_not_try_again, Copy to clipboardstop_recurringor Copy to clipboardconfirm_card_data. - A re-saved copy of the declined card counts as the same card. Vonpay gives every save a new card id, so the plugin matches the customer's cards by brand, last four digits and expiry. It never matches the cards of two different customers. If it cannot read a card's details while a card of the same customer has a decline, it refuses the charge for now and tries again on the next run. It also refuses when that declined card's own details are not known (a decline found later, or one only Vonpay's list shows the card of): the declined card may be this one. Reopen for one order (below) is the way out.
- A card with no decline (the customer's new one) charges as normal, at once. Only the "already paid" check applies to it. If that card declines too, both cards' declines are kept.
- A payment that is still pending never erases a decline. A paid charge clears only its own card's decline (a paid period is not charged again anyway).
- The refusal goes back to ReorderJS as a temporary failure, so its dunning keeps its schedule. The ReorderJS 1.1.1 default schedule is a first retry 1 day after the failure, then 3 days and 7 days after each previous retry. A store can change it (the store in the 11 November test had a first retry 7 days out).
- The plugin also reads Vonpay's list of the period's payments, so it sees a decline from before this upgrade. Such a decline does not say which card it was on: a card with no decline of its own waits up to 24 hours after it. A card with its own decline is judged by that alone.
- The log: the first refused charge of a period writes an ERROR line Copy to clipboard
renewal_retry_limited, naming the card, the decline, why it refused (Copy to clipboardnew_order, Copy to clipboardrecent_declineor Copy to clipboarddo_not_retry) and the order whose retries may charge. Later ones are WARN lines with the count. The count is kept in the record, so a restart or a second server does not write the ERROR again.
When ReorderJS's dunning has ended, ReorderJS still makes a new unpaid order every 5 minutes, and the plugin refuses each one. Nothing charges that card for the period until a person acts. The period shows on Held payments as Renewal declined — ReorderJS keeps asking:
- after a decline marked final, at the first refused charge after it (that card is refused for good, ReorderJS's retries included, so waiting helps nothing);
- after any other decline, eight days after the last decline, if ReorderJS is still asking (so its dunning has time to work).
What to do:
- Ask the customer for a new card in ReorderJS. A new card charges.
- Or retry the declined renewal in ReorderJS (the same order, at least 24 hours after its last try). It can still charge the card, unless that card's decline was marked final.
- Or close the renewal or cancel the subscription in ReorderJS.
- Or press Reopen for one order on the row. Type the order id it names, tick "I checked Vonpay", and type a short reason (3 to 200 characters). Never type a card number there: a reason with 12 or more digits in a row is refused, whatever is typed between them (spaces, dashes, dots, slashes, commas …), and nothing is saved. A phone number with 12 or more digits is refused too; write it with words, or leave it out. The plugin then lets ONE charge of that order through, once, within 24 hours — ReorderJS's next retry of that order. It never lets a charge through for a period that is already paid. The confirmation names the card on file, and after a decline marked final it warns that charging the same card again can bring card-network fees. Your name, the time and the reason are kept on the record. The log names you, the order and the card, and how long the reason is, never its text (when you reopen, and again when the order uses it). You can reopen again later if you need to; every time is logged. Keep blocked, or a charge of another order of the period, cancels a reopen that was not used yet.
- Cancel the extra unpaid orders in Medusa.
- Keep blocked hides the row for 24 hours. If ReorderJS is still asking after that, it comes back.
Copy to clipboardsubscriptionSignup (default off)
Sell subscriptions at checkout: the shopper's one card payment starts a Vonpay subscription, which Vonpay then renews. Needs Copy to clipboardsubscriptions: "vonpay" (Vonpay renews what it starts) and Copy to clipboardsavedCards. Vonpay must also have switched subscription checkouts on for your account; until it has, a subscription cart says "Subscriptions can't be bought right now" and nothing is charged.
Set up each subscription product.
- In the Vonpay dashboard, create a subscription product (its price and how often it renews). Type the Medusa variant id (Copy to clipboard
variant_…) into its Store product number. Sell each plan as its own variant (for example a "Monthly" variant beside a "One-time" one): one variant is one Vonpay product. - In Medusa's admin, open the product variant and press Sell as a Vonpay subscription (the Vonpay subscription panel). It works only once Vonpay has an active product for that variant.
- Run the setup check: Copy to clipboard
subscription_signupcompares the two.
What the shopper sees. On a subscription cart the payment step shows Vonpay's own sentence for it right above the pay button, for example "$5.00 today, then $9.99 every month until you cancel." The save box is required (or, with Copy to clipboardsavedCardsTerms, the sentence sits with your wording). Apple Pay and Google Pay are not offered for that payment (Vonpay cannot start a subscription from a wallet yet). The cart may hold other items too: they are charged once, with the first payment.
- One subscription per order. A cart with two subscription items, or two of the same one, is asked to remove the others.
- Signed-in shoppers only. A guest is asked to sign in first (the card is saved to their account for the renewals).
- One of each subscription per customer. If the customer already has this subscription (still active, paused, on hold or behind on payment), Vonpay would restart the one they have, with the new price and card, instead of starting another. So before the payment step opens, the plugin asks Vonpay for that customer's subscriptions. If one of them is for this product and has not ended, the payment step says "You already have this subscription. Manage it from your account." and no payment can be made. If Vonpay can't be asked just then, the payment step says "We couldn't set up this subscription. Press Try again." and a warning is logged. This is one extra Vonpay request each time the payment step opens for a subscription cart.
- The price. The first period is the item's price in the cart after discounts (with tax only where your prices include tax). Below Vonpay's renewal price, it is an intro price and Vonpay's sentence says both. Above it, or discounted to nothing, the subscription cannot be bought: the payment step says "contact the store" and the server log says why (Copy to clipboard
vonpay_log_signup_blocked). Compare your Medusa price with the product's price in the Vonpay dashboard. Renewals charge Vonpay's product price only: Vonpay adds no tax or shipping, so set the product's price to what each renewal should charge. - The email. On a subscription checkout only, the plugin sends Vonpay the signed-in shopper's ACCOUNT email (Vonpay sends the subscription's receipts there). Beside it the sign-up carries only ids: your customer's id, the variant's id and the payment's ids. Nothing else of the shopper's is sent, and the email is never logged or stored by the plugin.
- Only checkouts start subscriptions. An item you sell as a subscription that an admin adds to an existing order (an order edit, an exchange, a claim) is charged once, like any other item.
- Your statement descriptor key. With Copy to clipboard
subscriptionSignupon, Copy to clipboardstatementDescriptor.keymay not be one of the names Vonpay keeps for itself on a subscription checkout (Copy to clipboardsource, Copy to clipboardsubscription_id, Copy to clipboardbilling_cycle, Copy to clipboardsession_id, Copy to clipboardpayment_intent_id, Copy to clipboardcheckout_session_id, Copy to clipboardvault_session_id, Copy to clipboardvon_pay): the server refuses to start and says so.
One-click offers can start a subscription too. With Copy to clipboardupsells on, an offer of a variant you sell as a subscription shows Vonpay's sentence and a box the shopper must tick before Add. It is shown only to signed-in shoppers who paid by card, within 20 minutes of their order (Vonpay accepts the card saved at checkout for 30 minutes), and only with Copy to clipboardshopperIpSecret set (Vonpay requires the shopper's address for it). The plugin reports the shopper's agreement to Vonpay with the charge: the sentence it showed, when the box was ticked, and the shopper's browser. The offer page reuses Vonpay's sentence for up to 5 minutes (Vonpay limits how often it is read); pressing Add always reads it again, and a sentence that changed is shown again for a new tick, with nothing charged. The card used for a subscription offer is kept (Vonpay renews with it), even after the offer's clean-up.
If your storefront's Copy to clipboardsrc/lib/vonpay/actions.ts was written by an earlier Copy to clipboardsetup-storefront, its Copy to clipboardacceptUpsellOffer must pass the fourth argument through (Copy to clipboardacceptUpsellOffer(orderId, variantId, shown, subscription)): run Copy to clipboardnpx vonpay-medusa setup-storefront again and copy the change it lists as "manual". Until then a subscription offer ends "this item can't be added" and nothing is charged.
A customer who already has the subscription is not offered it again. When a customer buys a subscription product they already have (still active, paused, on hold or behind on payment), Vonpay does not start a second one: it restarts the one they have, with the new price, card and date. So before it shows a subscription offer, the plugin asks Vonpay for that customer's subscriptions. If one of them is for the offer's product and has not ended, the subscription offer is not shown, and the next offer shows instead. If Vonpay can't be asked just then, the subscription offer is not shown either, and a warning is logged. This is one extra Vonpay request for each view of a subscription offer, and one more when the customer presses Add.
Cancelled or refunded orders. Cancelling or refunding the order that started a subscription does not end the subscription. It keeps renewing until someone cancels it in your Vonpay dashboard. The held-payments page and the Vonpay subscriptions page say so too.
Offers the plugin refunds by itself. One exception: when the plugin itself refunds a subscription offer (the bank approved it after the offer had ended, or the item could not be added to the order), it also cancels the subscription that offer started, once the refund is confirmed. It cancels only a subscription Vonpay itself tied to that payment (Vonpay's answer to the charge, or its Copy to clipboardsubscription.created notification), after reading it again to check it belongs to that order's offer and this key's mode. It never cancels one it cannot prove, and never one by order id alone. A refund you make by hand never cancels anything. It also never cancels a subscription another payment of the same offer also names, unless that payment was refunded by the plugin too. A refund Vonpay accepts as still in progress (Copy to clipboardrequested) counts as confirmed, so the cancel goes ahead.
It also never cancels a subscription the customer had before this offer. If the offer's payment restarted a subscription the customer already had (rare: it needs two orders at almost the same moment), the plugin checks Vonpay's own record before it cancels: the subscription must be in its first period and must have been created no earlier than the offer's payment. If not, the plugin refunds the offer's payment, does not cancel the subscription, and logs an error. Held payments then shows the row with plain words: this offer restarted a subscription the customer already had, the offer's payment was refunded, and the subscription was not cancelled. Decide with the customer whether they keep it. The row offers Check with Vonpay and Close. The customer's page says the subscription stays active until it is cancelled.
A refund the plugin made that later fails comes back on Held payments. When Vonpay accepts one of the plugin's own offer refunds but has not finished it, the plugin keeps checking it: its background job reads the payment's refunds until the refund completes, and Vonpay's Copy to clipboardrefund.failed notification makes it check at once. If the refund fails, the payment comes back on Held payments as a refund that did not go through, and the buyer still has the charge: refund it in Vonpay, or close the row once you have dealt with it. If the refund is still not finished after two days, the row comes back too, asking you to check it in Vonpay before refunding again. A subscription the plugin already cancelled stays cancelled.
Until the cancel is confirmed, the held-payments page lists "Offer refund — cancel its subscription" with the subscription's id. The row closes once Vonpay reports the subscription ended. While the plugin is still refunding the payment or still trying to cancel, the row offers only Check with Vonpay (when the subscription's id is known): the plugin owns it then. The plugin gives up after about two hours of failed tries (sooner if the order is nearly three days old, because its background job stops looking at older orders), and the row then stays open for you. Close appears then, and also when the plugin's refund failed or is unclear (you refund by hand, which never cancels). Check with Vonpay reads the subscription and closes the row if it has ended; Close closes the row with no change to money, for a subscription the store keeps on purpose or one you dealt with in the dashboard.
The shopper is told about the subscription only what is already true: "is being cancelled too" once the plugin's refund is confirmed and it is cancelling; "has ended too" once it has ended; otherwise "stays active until it is cancelled".
The subscriptions page (Orders → Vonpay subscriptions) shows which order started each subscription. Run Copy to clipboardnpx medusa db:migrate after updating: the plugin's subscriptions module gains four columns. Every store with Copy to clipboardsubscriptions: "vonpay" needs this, sign-up on or off: until it runs, Vonpay's subscription notifications are not kept (the setup check FAILs and says so).
Copy to clipboardwallets (default Copy to clipboardfalse)
Copy to clipboardtrue adds Apple Pay and Google Pay buttons above the card form. A wallet tap only holds the money; the order is created, and then the plugin takes the money (Medusa shows the payment as captured). If the order cannot be created, or the cart changes, the hold is released: nothing was taken, so nothing is refunded. A shopper who taps and closes the page still gets an order, about 10 minutes later, from the recovery job. If taking the money fails, the plugin retries for 2 hours, and the Held payments page shows it.
The buttons show only where the shopper's device supports the wallet and your storefront's domain is registered. To register it (once, and again if the storefront's address changes or you switch from test to live keys), deploy the storefront with the Apple Pay route from Copy to clipboardsetup-storefront, then run in the server folder:
1npx vonpay-medusa-check --wallet-domains
It registers the host of Copy to clipboardstorefrontUrl for Apple Pay and Google Pay, saves Apple's domain file in your store, and asks Vonpay to verify both. Your storefront then serves that file. Make sure your endpoint receives Copy to clipboardpayment_intent.authorized ("all events" does).
For testing only — the bank check in a pop-up. When a wallet payment needs a bank check, the shopper normally goes to the bank's page and comes back. To try Vonpay's preview pop-up instead (the bank's page opens over your checkout), set Copy to clipboardNEXT_PUBLIC_VONPAY_WALLET_CHALLENGE=modal in the storefront's environment and rebuild it. It works only with test keys and vora.js 1.43.0 or later (what Copy to clipboardhttps://js.vonpay.com/v1/vora.js serves): with live keys, or any value other than Copy to clipboardmodal or Copy to clipboardredirect, it is ignored (one warning in the server log) and the bank check stays a full page. While the pop-up is open the card form cannot be used. If the shopper closes it and Vonpay confirms nothing was charged, the checkout says so and they can try again or pay by card; if Vonpay cannot confirm that yet, the checkout shows "We couldn't confirm a payment" with Check again, never a new payment. If you use the Content Security Policy above, Copy to clipboardvonpayCspSources adds what the pop-up needs only when it is on. Do not use it on a live store.
Copy to clipboardupsells (default off)
One-click offers after the order:
1upsells: { email: {} }
Then set up the offers in the Medusa admin: Orders → One-click offers. Add an offer (a name only you see and a product variant id), switch it on or off, put the offers in order, or remove one, with no redeploy. Up to 20 offers, each priced by Medusa with tax included. Right after paying, the shopper lands on the offer page: one offer at a time, up to three per order, for about an hour, with "Add to my order" and "No thanks". An accepted item joins the original order as an order edit with its own payment, refundable on its own. "No thanks" leaves the order unchanged. A shopper already paying for an offer (at their bank's check, say) finishes even if you switch it off. The page's Results tab shows how each offer did (see Offer results).
Who sees it. Each offer's Who sees it narrows who is shown it; leave it empty and every shopper is. All the conditions you set must match:
- Products / collections — the shopper bought one of these products (or a product from one of these collections) at checkout. An offer they add afterwards never counts, so one offer can't unlock another.
- Customers — guests only, or signed-in customers only. A guest who types a member's email at checkout is still a guest here.
- Customer groups — the signed-in shopper is in one of these groups.
- Amount paid at checkout (tax and shipping included), one row per currency with an optional least and most, typed as in your store ("49.95", "5000" for yen). An order in a currency you didn't list doesn't see the offer.
Conditions never change a price. When you change them, the order page's shipping hold ends at once for an order no offer can reach any more.
If they say No thanks. Each offer can have one downsell: another product variant (usually a smaller or cheaper option) shown only after the shopper says "No thanks" to that offer, under the heading "How about this instead?". It uses the offer's own Who sees it, and it counts toward the three offers per order. After a "No thanks" with no downsell (or on the downsell itself), the shopper sees your next offer, up to three, then their order. A variant is one thing in the list: an offer, or one offer's downsell — the admin refuses anything else.
Wording. Each offer can have its own headline (up to 80 characters, in place of "Add this to your order?") and pitch (up to 300, in place of the product's description under its name; a phone shows about two lines). Plain text only: line breaks become spaces, and characters that change the reading direction are refused. Leave both empty for the standard wording. The payment line, the buttons and every result message stay the same, and a downsell keeps "How about this instead?" with its own product's description.
Changing or translating the page's words (developers). The offer page, its loading page and the return page take a Copy to clipboardcopy prop: any line of Copy to clipboardUPSELL_COPY (exported from Copy to clipboardvonpay-medusa/storefront), changed or translated; a line you leave out keeps the standard one. The lines with a price or an order number are functions, and Next.js can't pass a function from a server page to these browser components, so set Copy to clipboardcopy in the browser-side file the setup command wrote, Copy to clipboardsrc/lib/vonpay/index.tsx (it starts with Copy to clipboard"use client"):
12345const offerCopy: Partial<VonpayUpsellCopy> = { heading: "Ajouter à votre commande ?", add: (price) => `Ajouter — ${price}`, noThanks: "Non merci, voir ma commande" }export function VonpayUpsellOffer(props: …) {return <PackagedUpsellOffer {...props} copy={offerCopy} actions={…} ui={upsellUi} />}
Do the same for Copy to clipboardVonpayUpsellOfferLoading and Copy to clipboardVonpayUpsellReturn in that file. A line that fails (throws, or gives back something that isn't text) shows the standard line instead.
Keep what the standard lines promise the shopper: a decline says nothing was added and the order is unchanged; an unclear result says not to pay again; nothing counts down or pressures. An offer's own headline and pitch from the admin still win over Copy to clipboardheading and the product's description.
The offers live in the plugin's own tables, created by Copy to clipboardnpx medusa db:migrate (run it after every update, as the install steps say); until it has run, no offer is shown and the setup check fails with that fix.
Offers in medusa-config (1.0.x). Copy to clipboardupsells: { variantIds: ["variant_…", …] } still works: until you create the first offer in the admin, those variants are the offers, in that order. The admin page lists them with an Import from medusa-config button; once any offer exists in the admin, the admin's list is used and Copy to clipboardvariantIds is ignored (the setup check warns while both exist — remove Copy to clipboardvariantIds then). Copy to clipboardvariantIds is optional from 1.1. Rolling back to 1.0.x needs Copy to clipboardvariantIds in the option again.
Card payers get true one-click. With upsells on, the payment step says "Your card may be charged for any offer you accept on the
