Vonpay medusa

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 (vp_sk_test_… / vp_sk_live_…) and a publishable key (vp_pk_test_… / vp_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:

Then register the plugin and its payment provider in medusa-config.ts. This is a complete file for a new store; if you already have one, add the plugins entry, the payment module entry and admin.backendUrl to it. If you already configure the payment module (for another provider), add the Vonpay entry to its existing providers list.

With the id vonpay, Medusa names the provider pp_vonpay_vonpay. You will use that name in the admin, and the setup check reports it.

Set these in the server's .env (never in medusa-config.ts or any file you commit):

Then create the plugin's tables and start the server:

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 https. 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.

1. In the Medusa admin, open Settings → Regions.
2. Edit each region you sell in.
3. Add pp_vonpay_vonpay under 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:

1. Install and start the server without VONPAY_WEBHOOK_SECRET. Payments already work. Every notification is refused until the secret is set, and the setup check fails webhook_secret. Vonpay does not send a refused notification again, so finish these steps before you take live payments.

2. Register the endpoint in the Vonpay dashboard. The address is your server's public address followed by /hooks/payment/vonpay_vonpay:

   https://<your backend>/hooks/payment/vonpay_vonpay

   Choose all events (this includes payment_intent.authorized, which Apple Pay and Google Pay need). Only if Vonpay runs your subscriptions (subscriptions: "vonpay"), also add the five subscription events, which "all events" does not include: subscription.created, subscription.renewed, subscription.payment_failed, subscription.cancelled and subscription.updated.

3. Copy the signing secret into VONPAY_WEBHOOK_SECRET.

4. Restart the server and the worker.

5. 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:

The command expects Medusa's Next.js starter layout. It:

• writes src/lib/vonpay/actions.ts and src/lib/vonpay/index.tsx (the small files that connect the package to your storefront);
• adds the 3-D Secure return page at checkout/vonpay-return;
• adds the My saved cards account page, the one-click offer pages (order/[id]/offer and order/[id]/offer/return), and the route Apple Pay needs at /.well-known/apple-developer-merchantid-domain-association;
• adds vonpay-medusa to transpilePackages in your Next config and to Tailwind's content;
• names the payment method "Credit card" and puts the card form in the checkout's pay button;
• 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. --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 --force; those steps print as "manual", with the change to make by hand.

After it runs:

• Set NEXT_PUBLIC_VONPAY_PUBLISHABLE_KEY in the storefront's environment to your publishable key (vp_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 VONPAY_STOREFRONT_URL is this storefront's address.
• Add a "Saved cards" link to your account menu, pointing at /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). It loads Vonpay's vora.js from https://js.vonpay.com/v1/vora.js, so Vonpay's card-form fixes reach your store without a release.

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 (/<country>/order/<id>/offer and /offer/return). The package gives you the list:

Do not use 'strict-dynamic' in script-src: browsers then ignore the host list. Also allow your Medusa backend in connect-src. The list is bundled with the package; to follow Vonpay's live list between releases, call refreshVoraCspList() (same import) after the response, for example with event.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 medusa-config.ts, next to the payment module:

Medusa already includes the Redis caching provider; with pnpm (whose strict layout hides packages you did not add yourself), add @medusajs/caching-redis at your exact Medusa version. Then run two processes: the server with MEDUSA_WORKER_MODE=server, and the worker with MEDUSA_WORKER_MODE=worker and DISABLE_MEDUSA_ADMIN=true.

Check your setup

From your Medusa server folder:

npx vonpay-medusa-check

In an image built with medusa build, run it from .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; --strict also fails when a check could not run. It checks:

• provider: the Vonpay provider is registered and enabled.
• webhook_secret: the signing secret is set.
• regions: at least one region offers pp_vonpay_vonpay.
• recovery: the recovery job is on.
• key: Vonpay accepts your secret key. Read-only; nothing changes.
• endpoint: a notification endpoint for /hooks/payment/vonpay_vonpay is registered and active. The check names the address. If it cannot confirm the address is this store's (set admin.backendUrl, or use the admin button), it warns and sends no test notification.
• subscriptions: with subscriptions: "vonpay", the module is registered and the endpoint receives the five subscription events.
• wallets, wallet_domains: with wallets: true, the endpoint receives payment_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.
• event_bus, workflow_engine, locking: the production settings. Each fails or warns when missing (shared locking with Postgres also passes).
• 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 options in medusa-config.ts, next to the four settings from Install. All are optional.

recovery (default true)

Every 5 minutes, on the worker, the plugin looks for unfinished checkouts (10 minutes to 24 hours old) that Vonpay reports paid. 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.

This is the only thing that completes the order for a shopper who pays and closes the page. Leave it on. recovery: false turns it off, and the setup check fails while it is off.

holdRecheck (default true)

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. holdRecheck: false turns it off; those rows then wait for a person.

savedCards (default off)

"recurring" or "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): recurring, because the renewals charge it on a fixed schedule.
• On any other cart: 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 renewal_declaration_missing.) Vonpay notes that on some processor connections (network tokens) only recurring is accepted for later charges; an unscheduled 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).

savedCardsTerms (needs savedCards)

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 savedCardsTerms unset).

If you sell subscriptions with only the checkbox, the setup check warns (saved_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 (save_consent_recorded, with ids and the wording's fingerprint, never the wording or an email), because payment data can be read from the storefront.

subscriptions (default off)

Who runs your subscription renewals. Exactly one, so a customer is never charged by two systems.

• "store": your own subscription plugin (such as ReorderJS) renews, and this plugin charges the saved card when it asks. Needs savedCards.

• "vonpay": Vonpay's own subscription billing renews, and this plugin charges no renewal itself. Register the plugin's subscriptions module, run npx medusa db:migrate, 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.

Renewal charges ("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 data.off_session === true (the shape ReorderJS 1.1.0 uses);
• 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 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. 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": mark the order paid in Medusa, and do not charge again.

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.

Known gap in ReorderJS 1.1.0 (its code, not this plugin's): its automatic retry of a failed renewal never reaches any payment provider, so a renewal whose first attempt fails is not charged again, and "Retry now" on its dunning screen fails the same way. "Mark recovered" and "Mark unrecovered" only change the case status. Collect the payment another way first, and mark a case recovered only once the money has arrived. The first renewal attempt is unaffected.

wallets (default false)

true 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 setup-storefront, then run in the server folder:

npx vonpay-medusa-check --wallet-domains

It registers the host of storefrontUrl 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 payment_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 NEXT_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 https://js.vonpay.com/v1/vora.js serves): with live keys, or any value other than modal or redirect, 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, vonpayCspSources adds what the pop-up needs only when it is on. Do not use it on a live store.

upsells (default off)

One-click offers after the order:

variantIds lists 1 to 20 of your product variants, 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.

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 shopperIpHeader in createVonpayStorefrontServer (the setup command writes it from the VONPAY_SHOPPER_IP_HEADER environment variable) to the request header your hosting sets to the visitor's own address, one value it writes itself: x-real-ip on Vercel, cf-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 x-forwarded-for (its first entry can be typed by anyone; a header holding a list is ignored). Then set the same random value as VONPAY_SHOPPER_IP_SECRET in BOTH the storefront's environment (the setup command passes it as shopperIpSecret; server-only, never NEXT_PUBLIC_) and the Medusa server's (option shopperIpSecret): 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 shopper_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 VONPAY_SHOPPER_IP_SECRET is set on both sides. The address is never logged or stored by the plugin.

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. guests: 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 email channel, so you need an email provider configured in medusa-config (for example SendGrid or Resend); without one nothing is sent and the setup check warns. email: false turns it off (send your own). email: { template: "<id>" } uses your provider's template instead of the plugin's wording; the template receives store_name, order_id, order_display_id, item, amount, currency, price, subject and text.

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: statementDescriptor (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:

key is the field your Vonpay rule reads: order_id, subscription_id, customer_id, or your own field name. from 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:

When it shows:

• One-click offer charges and renewals use it now. The exception is an offer paid with Apple Pay or Google Pay: those offers are held and then taken rather than charged directly, so they carry no ending and show your plain descriptor.
• Checkout payments (card and Apple Pay / Google Pay) start using it automatically once Vonpay's next checkout release is live. Until then they show your plain descriptor. The plugin already sends the value, as it was when the shopper reached the payment step (for example, the product title of the cart at that moment). A cart change that does not start a new payment keeps that earlier value.
• What finally prints depends on your processor connection. Some connections print no per-payment ending at all, and some print only a short name. Vonpay drops accented letters and emoji (Café prints as Caf) and cuts the ending to fit (usually under 22 characters), so put the most telling words first.

No personal data is ever sent: there is no source for a shopper's name, email, phone or address, and a value that looks like an email address or a phone number (a product title, say) is left out. key must be a plain field name (a letter, then letters, digits, _, . or -). Names that suggest personal data (for example email, phone, address, card) and names the plugin or Vonpay already use (medusa_…, mirror, order, session_id, checkout_type) are refused when the server starts; the error says which word it found (for example contains "tel"). The setup check compares this option with your Vonpay setting.

Held payments (admin)

The admin's Orders → Held payments page lists every payment the plugin could not finish on its own, with what happened and what to do. For example: paid but no order was created, charged and then the cart changed, a wallet payment held with no order, a renewal or offer charge that needs a decision, or a cancelled order whose refund did not go through. Any signed-in admin can use it.

Depending on the row, you can:

• Refund the buyer (the button shows the amount it will refund);
• Check with Vonpay to bring the row in line with Vonpay's refund record (moves no money);
• Mark resolved once you have dealt with it elsewhere (you confirm by typing the Vonpay session id);
• Release a held wallet payment, or Complete the order from it;
• Open order to use Medusa's own Capture or Cancel.

Refunds made in the Vonpay dashboard are not mirrored into Medusa. Refund from Medusa to keep the two in step.

Keeping it up to date

Medusa cannot update itself: your store is your own code, built and deployed by you. To update:

1. Install the new version in both the server and the storefront folders (otherwise two versions run), then run npx medusa db:migrate in the server folder.
2. Redeploy the server, the worker and the storefront.

The package's code, including the storefront card step, comes with the update. The small files setup-storefront wrote into your storefront do not change. Running setup-storefront again adds anything new and lists, as "manual", any existing file that differs from what it would write now.

The admin tells you. When a newer version is out, the orders page shows "vonpay-medusa X is available" (or "Security fix: …") with the exact install command and a "What changed" link. The notice comes from a file Vonpay signs, checked from your server about twice a day (https://www.vonpay.com/medusa/update.json). Your store sends nothing about itself, and an unsigned or unreachable file is never shown. VONPAY_UPDATE_CHECK=off on the server turns it off.

Automatic update pull requests. npx vonpay-medusa setup-storefront offers to turn them on (default yes; --auto-updates or --no-auto-updates to choose without the question). It adds .github/dependabot.yml, a daily check for vonpay-medusa in every folder of the repository that installs it (for a workspace with one lock file at the top, that top folder), and a small workflow that turns on auto-merge for our patch (bug and security fix) releases, so they merge once your required checks pass. Turn on Settings → General → Allow auto-merge in GitHub. Minor and major releases always wait for a person. An existing dependabot.yml is never edited.

Or set it up yourself. Renovate (renovate.json):

Or Dependabot (.github/dependabot.yml; turn on auto-merge for its pull requests if you like):

Troubleshooting

Checkout does not offer Vonpay. Add pp_vonpay_vonpay to each region.

"Cannot find module '@medusajs/framework/utils'". Usually npm with the server and storefront in one project, especially after changing Medusa versions. Delete node_modules and the lock file, then install again. The package lists Medusa, Next.js and React as optional on purpose, because the same package serves both the server and the storefront.

The storefront's production build fails with React error #31. A known issue in Medusa's Next.js starter, not in this package: under npm, next is installed next to the backend's React 18. Use pnpm, as Medusa's starter does, or give the storefront its own install.

The setup check fails webhook_secret, or notifications are refused. Follow Payment notifications, then restart the server and the worker.

The endpoint check warns that it is "not this store's address". Set admin.backendUrl (MEDUSA_BACKEND_URL) to your server's public address, and make sure the endpoint registered at Vonpay uses that same address.

The test notification is delivered but "not processed". Check that the worker is running, that VONPAY_WEBHOOK_SECRET matches the endpoint's signing secret, and that the server and worker share the same Redis.

The checkout says "Card payments are unavailable right now." NEXT_PUBLIC_VONPAY_PUBLISHABLE_KEY is missing or not a publishable key (vp_pk_…). Set it and rebuild the storefront.

The server refuses to start. A setting is missing or malformed, and the error names which one, such as options_secret_key_invalid or options_mode_key_mismatch (mode and key do not match).

Wallet buttons do not show. Check wallets: true, run npx vonpay-medusa-check --wallet-domains and read its wallet_domains line. The buttons appear only on devices that support the wallet.

License

MIT. See LICENSE.