Skip to main content

One-click add-ons on Medusa

For the developer of a Medusa store that takes Von Payments. Install and configure the payment provider first: Von Payments for Medusa.

Offer a product right after checkout, paid with one click and added to the order the shopper just placed. Set upsells in the provider options to the product variants you want to offer, 1 to 20 Medusa variant ids:

upsells: { variantIds: ["variant_01...", "variant_01..."] },

Medusa prices each offer, tax included; the browser never sets a price. npx vonpay-medusa setup-storefront adds the offer page at /<country>/order/<id>/offer and its bank-check return page at /<country>/order/<id>/offer/return. Both load vora.js, so give them the same Content Security Policy as your checkout.

What the shopper sees:

  • On the payment step: "Your card may be charged for any offer you accept on the next page."
  • After paying, the offer page: Add this to your order?, a button to add it at the shown price, and No thanks, view my order. One offer at a time, up to three per order, for a limited time (below).
  • An accepted offer joins the original order as an order edit with its own payment, refundable on its own, and ships with the rest of the order (wait before you ship).

An order whose card is held until fulfillment (1.5.0 and later) gets no offer page.

The offer pages take their own copy (any line of UPSELL_COPY) and a locale, like the checkout (Your own words and language). From 1.6.0 the locale also reaches the wallet button. A tag the browser cannot read is ignored.

Offers stay with the shopper's browser (1.6.0 and later)​

Update the storefront part together with the plugin. A storefront on an earlier vonpay-medusa gets no offer page; checkout and orders work as before. When such a storefront asks for an offer, your store refuses it and logs vonpay_log_upsell_token_refused with "why":"no_claim".

Then export a prepareVonpayClaim() action from the actions.ts file setup-storefront added to src/lib/vonpay, returning vonpay.prepareVonpayClaim(), like the other actions in that file. npx vonpay-medusa setup-storefront names it if it is missing. Without it offers still work. With it, the secret below is made when the payment step shows, so a double press on Pay does not turn the shopper's own offer off.

How it works: the storefront keeps a random secret for each checkout in the shopper's browser (an httpOnly cookie) and sends it when it asks for the offer. Your store keeps the first secret it sees for that checkout. If a different one asks, for example someone who got hold of the checkout's cart id, offers are turned off for that order and no new offer charge starts. Your store logs vonpay_log_upsell_offer_contested. The order's completion carries the secret too: a different one, or none once one was seen, turns the offer off and never stops the order.

  • When your storefront completes an order and the completion's check earns it no offer, your store logs vonpay_log_upsell_offer_proof_skipped with the reason in why. An expected reason (a storefront part from an earlier version, a repeated completion) is logged as info. An offer lost on an up-to-date storefront (a busy lock, a failed read or write, a check that ran out of time) is logged as a warning.
  • An order your storefront did not complete gets no offer page: one placed by the plugin's background recovery, or completed from Held payments. The same holds when the completion's check could not finish in time (a very slow database at that moment).
  • The setup check warns Storefront part too old: offers off when none of the last 7 days' orders that could get an offer came through the current storefront part.
  • An offer page open when the new plugin starts disappears, and the shopper sees their order. An offer payment already under way is still finished or undone. Update when few shoppers are checking out.

How it is paid:

  • Card: each checkout asks Von Payments to keep the card for this purchase only, so the offer is charged without the shopper typing it again. That card is never charged when the shopper is away, is not shown under My saved cards, does not count toward the 10-card limit, and is removed by the plugin once that order's offer has ended.
  • Declined: nothing is added and the order is unchanged. The page shows Try again, and the shopper can tap it for the same offer up to three attempts in all.
  • 3-D Secure: the shopper confirms with their bank and comes back to the offer's return page, which shows the outcome.
  • Apple Pay and Google Pay: the shopper sees the wallet button straight away. The tap only holds the amount; the item is added and the hold taken, or the hold is released when the item cannot be added (sold out, price moved). Nothing is charged and then refunded.

Your server makes the offer charge, so the processor's fraud checks see your server's address unless the storefront passes on the shopper's. Two settings do that:

  • VONPAY_SHOPPER_IP_HEADER, in the storefront's environment: the header your hosting overwrites on every request with the visitor's own address, x-real-ip on Vercel, cf-connecting-ip behind Cloudflare. Never use x-forwarded-for: a visitor can type its first entry.
  • VONPAY_SHOPPER_IP_SECRET, the same value in the storefront's environment and the Medusa server's .env: a random value of at least 32 characters, at least 10 of them different (openssl rand -hex 32 gives both). The storefront signs the address with it, and your store ignores any address that is not signed, so someone calling your store directly cannot choose it. In the storefront it stays server-side: never a NEXT_PUBLIC_ variable. The Medusa server refuses to start if the value is too short, repeats too few characters, or is one of your Von Payments keys or the webhook signing secret.

With either setting missing, offers are charged without the shopper's address and nothing else changes. The setup check warns when the server's secret is missing; it cannot see the storefront's. If you wired the storefront by hand, pass shopperIpHeader and shopperIpSecret to createVonpayStorefrontServer.

Upgrading from 1.0.1: 1.0.1 sent the shopper's address unsigned. From 1.0.2 it is used only once VONPAY_SHOPPER_IP_SECRET is set on both the Medusa server and the storefront.

Offers go to guests as well as signed-in customers. A guest is known only by the email they type at checkout, so their card is never added to a customer's account, even when they type that customer's email. Set guests: false in upsells to show offers to signed-in customers only; a guest then pays as usual and sees no offer page. Anything the plugin could not finish shows under Held payments with what to do.

Offers are shown for about an hour after the order. An offer payment already under way when that hour ends (a bank check, an item being added) can finish for about 30 minutes more. After that, or as soon as the order is fulfilled, whichever comes first, nothing is added to the order. A shopper's bank check still open at that point is closed on the store's side; if the bank approves it afterwards, the plugin refunds that charge in full.

Wait before you ship​

While an offer can still add an item, the order page in the admin shows when you can fulfill, and Medusa's Fulfill is refused until then. It is also refused while an offer payment is being confirmed, or when a shopper paid for an offer whose item could not be added: check that one under Held payments (Renewal and offer charges). Ship now anyway on the order page lets you fulfill straight away and ends the order's offers. If the plugin cannot read the order's offer state, Fulfill is not blocked.

Email to the shopper​

When an offer's item is added, the plugin emails the shopper once, with the subject {Store}: added to your order #{n}. It goes through Medusa's own notifications on the email channel, so configure an email provider in medusa-config; without one nothing is sent and the setup check warns. Set email: false in upsells to send your own instead, or email: { template: "<id>" } to use your provider's template.

Offer results (1.3.0 and later)​

Orders › One-click offers › Results shows how shoppers answered each offer, for the days you pick, in live or test mode. Each offer has one line, and its downsell has another.

ColumnWhat it counts
ShownOrders the offer was shown to, once per order however often the page reloads. Not a count of page views.
AddedOrders where the shopper added it and paid.
No thanksOrders where the shopper said No thanks.
Didn't go throughThe payment was declined, the bank check was not finished, or the item could not be added.
Take rateAdded ÷ Shown.
ChargedWhat shoppers paid for the offers, tax included, per currency.
RefundedWhat was refunded on those payments, as Medusa records it: by you in Medusa, or by the plugin when it refunds a late bank approval. A refund made in the Von Payments dashboard is not counted.
NetCharged minus refunded.

Answers and money count when the offer has ended, about 2 hours after the order. A refund counts on the date of the sale it refunds. A refund that Von Payments cancels or fails counts as charged again. A payment you close on Held payments is left out of Results. Results count offers from your update to 1.3.0 on.

A storefront set up before 1.3.0 counts no views until you add two lines. Export an upsellOfferShown(orderId, variantId) action from the actions.ts file setup-storefront added to src/lib/vonpay, returning vonpay.upsellOfferShown(orderId, variantId), like the other actions in that file. Then pass it to the offer page in that folder's index.tsx, in the actions of VonpayUpsellOffer: shown: actions.upsellOfferShown. npx vonpay-medusa setup-storefront names both lines if they are missing. Until then, Results counts answers and money, but no views and no take rate.