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, WARNs when Vonpay refuses this key the list of payments (the key lacks Copy to clipboardpayment_intents.read). The held list's Check this order reads that list for a renewal whose result is unknown, so give the key that permission. Any other failure says nothing about the key and gives no line. - 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.
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 next page." That card is kept for this purchase only: it is never charged while the shopper is away, is not shown under My saved cards, does not count toward the card limit, and is removed once that order's offer has ended (about 90 minutes after the order, see below; a newer order's card waits for its own offer to end). Apple Pay and Google Pay payers see the wallet button on the offer: the tap holds the amount, then the item is added and the hold taken, or the hold is released if the item cannot be added.
The shopper's address on offer charges. Your store's server makes the offer charge, so Vonpay never sees the shopper; without their address, the processor's fraud checks look at a server instead. Your storefront can pass it on: set Copy to clipboardshopperIpHeader in Copy to clipboardcreateVonpayStorefrontServer (the setup command writes it from the Copy to clipboardVONPAY_SHOPPER_IP_HEADER environment variable) to the request header your hosting sets to the visitor's own address, one value it writes itself: Copy to clipboardx-real-ip on Vercel, Copy to clipboardcf-connecting-ip behind Cloudflare. It must be a header your host overwrites on every request; a header a visitor can send through unchanged lets them choose the address you report. Do not use Copy to clipboardx-forwarded-for (its first entry can be typed by anyone; a header holding a list is ignored). Then set the same random value as Copy to clipboardVONPAY_SHOPPER_IP_SECRET in BOTH the storefront's environment (the setup command passes it as Copy to clipboardshopperIpSecret; server-only, never Copy to clipboardNEXT_PUBLIC_) and the Medusa server's (option Copy to clipboardshopperIpSecret): the storefront signs the address with it, and the store ignores any address that is not signed, so someone calling your store directly cannot choose it. Only a public address is sent; private, local or malformed values are dropped. Either setting left unset, offer charges carry no address (the setup check WARNs; the store logs Copy to clipboardshopper_ip_sig_rejected when an address arrives that it cannot believe). Upgrading from 1.0.1: 1.0.1 sent the address unsigned; from 1.0.2 it is used only once Copy to clipboardVONPAY_SHOPPER_IP_SECRET is set on both sides. The address is never logged or stored by the plugin.
A repeated return from the bank still gets the offer (1.0.4). The offer page needs a pass the storefront gets while the cart is still open. From 1.0.4 the card step also gets it when the shopper presses Pay, before they can leave for their bank's check, so a return that is repeated (a lost answer, a reload) still finds the offer. Upgrading a storefront set up before 1.0.4: add this to Copy to clipboardsrc/lib/vonpay/actions.ts (the setup command leaves an existing file as it is); without it the checkout works exactly as before.
123export async function prepareVonpayOffer() {return vonpay.prepareVonpayOffer()}
With offers off, the checkout does not ask for the pass. The card step asks for the pass only when the payment shows the offer notice ("Your card may be charged for any offer you accept on the next page."). Without it, Pay marks the checkout instead, and neither Pay nor the order completion asks your store for a pass. Your store's log then shows no Copy to clipboardPOST /store/vonpay/upsells/pass answered 404 for each checkout. Upgrading a storefront set up with 1.2.0 or earlier: add this to Copy to clipboardsrc/lib/vonpay/actions.ts. Without it, the checkout works as before and asks once, at the order completion.
123export async function prepareVonpayNoOffer() {return vonpay.prepareVonpayNoOffer()}
Guest shoppers get offers too, by default: the checkout names them by the email they type, and their card is kept for that purchase's offers only, then removed once the offer ends. A guest's card is never added to an existing customer's account because the guest typed that customer's email. Copy to clipboardguests: false turns offers off for guests: a guest then pays exactly as with upsells off and sees no offer page. Signed-in customers are unaffected either way.
If the offer needs the shopper's bank to approve it, they go to their bank and come back to the offer page. If they leave the bank page unfinished, the offer page says the check isn't finished and keeps checking on its own; "No thanks" then tells them nothing is charged unless they finish it. If the bank approves before the offer ends, the item is still added and they get the email below.
Every offer has a clear end. It stops about 90 minutes after the order, or as soon as the order is fulfilled, whichever comes first. From then on nothing is added to that order and no more offers are shown. A bank check still open at that point is closed on the store's side (the order change is undone). In the rare case the bank approves it afterwards, the plugin refunds that charge in full automatically; the admin's Held payments page lists it for the record.
"Added to your order" email
When an offer's item is added, the plugin emails the shopper once: "{Store}: added to your order #{n}", "{item} — {price} was added to your order #{n} and charged to the same payment method. It ships with the rest of your order." It goes out through Medusa's own notifications on the Copy to clipboardemail channel, so you need an email provider configured in Copy to clipboardmedusa-config (for example SendGrid or Resend); without one nothing is sent and the setup check warns. Copy to clipboardemail: false turns it off (send your own). Copy to clipboardemail: { template: "<id>" } uses your provider's template instead of the plugin's wording; the template receives Copy to clipboardstore_name, Copy to clipboardorder_id, Copy to clipboardorder_display_id, Copy to clipboarditem, Copy to clipboardamount, Copy to clipboardcurrency, Copy to clipboardprice, Copy to clipboardsubject and Copy to clipboardtext.
Every time an offer's item is added, the plugin also emits the Medusa event Copy to clipboardvonpay.upsell.added, whether its email is on or off. The event carries ids only: Copy to clipboardprovider_id, Copy to clipboardorder_id, Copy to clipboardacceptance_id, Copy to clipboardvariant_id and Copy to clipboardoffer_id (null for an offer from medusa-config). Subscribe to it to send your own email or to record the purchase in your own analytics. Treat it as best effort: it is sent at most once per add, and if Medusa's event bus is down at that moment it is lost (the plugin logs it). With the plugin's email on, the clean-up job still sends a lost email; with it off, nothing is re-sent. For a complete record, read the order's items and payments in Medusa.
Offer results
Orders → One-click offers → Results shows how shoppers answered each offer, for the days you pick, for live or test payments. One line per offer, and one for its downsell:
Column What it counts Shown Orders the offer was offered to: it was on the shopper's screen, or the shopper answered it. Once per order (and once more for its downsell), however often the page reloads. It is not a count of page views. Added Orders where the shopper added it and paid. No thanks Orders where the shopper said No thanks. Didn't go through The payment was declined or the bank check was not finished, or the item could not be added. Take rate Added ÷ Shown. Charged What shoppers paid for the offers, tax included, per currency. Refunded What was refunded on those payments since, per currency, as Medusa records it: you in Medusa (a refund on the order, or cancelling it), or the plugin automatically (a late approval after the offer ended). A refund Vonpay did not complete is taken out again (below). Never more than Charged. Net Charged minus refunded.
A view counts as soon as the offer is on screen, or when the shopper answers it first. Answers and money count when the offer has ended, about 2 hours after the order; a refund made later raises Refunded as soon as Medusa records it. If that update is missed (the store was down at that moment), the plugin reads Medusa's refunds again 1, 2, 3, 7, 14, 30 and 60 days after the sale; a missed update for a refund made more than 60 days after the sale is not caught. Refunds made outside Medusa (for example in the Vonpay dashboard) are not in Medusa, so they are not in Refunded either. A refund Vonpay did not complete is not counted. When an offer's refund comes back as failed or unclear (Vonpay cancelled or failed it, or it was still not finished after two days), Results counts that offer as charged again, and lowers Refunded to what Vonpay actually completed. This applies to a refund you made in Medusa and to the plugin's own refund. If you then refund it again and Vonpay completes it, Refunded goes back up. Marking the row resolved does not count the refund. A payment on the Held payments page counts as it stood when it was held. For example, a late charge whose automatic refund failed usually shows as "Didn't go through" and as charged. If it was held within moments of the charge, Results may show nothing for it while it is held. If the plugin finishes it later, it counts as it finished. If you close it on the Held payments page, it is left out of Results: in no column and with no money, because the plugin cannot know what happened to it. Its view still counts. Removed offers keep their results, marked "(removed)".
Each row counts on the date of its own moment: a view when the offer was shown, an answer when the shopper gave it, and the money on the day it was charged. A refund counts on the date of the sale it refunds, not the day it was made (a decision of 2026-11-02): charged, refunded and net of one sale always fall in the same dates. Near the start or end of your dates, a view and its answer can fall on different sides.
Upgrading a storefront set up with an earlier version: views count only when the offer page tells the store. Add this to Copy to clipboardsrc/lib/vonpay/actions.ts:
123export async function upsellOfferShown(orderId: string, variantId: string) {return vonpay.upsellOfferShown(orderId, variantId)}
and pass it to the offer page in Copy to clipboardsrc/lib/vonpay/index.tsx, in the Copy to clipboardactions of Copy to clipboardVonpayUpsellOffer: Copy to clipboardshown: actions.upsellOfferShown. Copy to clipboardnpx vonpay-medusa setup-storefront names both lines if they are missing. Until then, Results counts answers and money but no views, and shows no take rate. The page tells the store about a second after the offer appears, never while the shopper's own tap is being handled.
Upgrading the store: run Copy to clipboardnpx medusa db:migrate (as after every update). It changes only the results table:
- It lets the table hold the charged and refunded rows.
- It widens the amount column and adds a Copy to clipboard
raw_amount_minorcolumn, so amounts stay exact. - It adds a check that amounts are whole numbers.
Results count offers from the update on. An offer whose clean-up had finished before the update is never counted. The clean-up runs shortly after an offer ends (usually within about half an hour), so an offer that ended just before the update may or may not be counted. This stays true if you refund or cancel that order later.
Rolling this migration back deletes the charged and refunded rows of Results. Your orders and payments do not change.
Wait before shipping: the offer window
An offer can add an item to the order for about an hour after it is placed (up to its 90-minute end while a shopper's bank check is still open). So that a parcel never leaves without that item, the order page in the admin shows "Wait to fulfil until {time} — an offer may still be added", and Medusa's Fulfil is refused until then — from the moment the order is placed. Fulfil is also refused while a shopper has paid for an offer whose item could not be added: check it on the Held payments page (add the item in Medusa or refund it in Vonpay), then use Ship now anyway. Ship now anyway on that banner lets you fulfil straight away (it is recorded on the order); fulfilling ends the order's offers. If the plugin cannot read the order's offer state, Fulfil is never blocked.
Statement descriptor: Copy to clipboardstatementDescriptor (default off)
The line on your customer's card statement has two parts. You set both in the Vonpay dashboard: your fixed brand line, and the rule for a short per-payment ending: which payment field it is read from (order id, subscription id, customer id, or a field name of your own) and what shows when that field is missing. This option tells the plugin what to put in that field, so shoppers recognise the charge:
1statementDescriptor: { key: "order_id", from: ["product_title", "store_name"] }
Copy to clipboardkey is the field your Vonpay rule reads: Copy to clipboardorder_id, Copy to clipboardsubscription_id, Copy to clipboardcustomer_id, or your own field name. Copy to clipboardfrom is where the value comes from, one source or up to three in order: the first one that exists for that payment is sent. If none exists, nothing is sent and your rule's "when missing" setting applies. The sources:
| Copy to clipboardfrom | What is sent
