How to Accept Crypto Payments in a Medusa.js Store

Introduction

Install the Cryptonly payment provider, enable it on a region, and your Medusa store accepts crypto. Customers pay in Bitcoin or stablecoins while your catalog stays priced in fiat. Cryptonly handles the hosted checkout, wallet handoff, and blockchain confirmation. Payment status syncs to Medusa through signed webhooks — you do not touch wallets or reconcile anything by hand.

Why Medusa merchants add crypto checkout

Medusa merchants often run global or vertical stores. Crypto checkout shows up in two practical ways: higher cart values from buyers who already hold crypto, and fewer payment headaches on international orders.

Three concrete reasons to add crypto payments to Medusa:

• No card chargebacks. Blockchain transactions settle once they confirm. You are not absorbing card fraud and dispute fees on those orders.
• Lower transaction costs. Cryptonly charges 0.5% for verified merchants versus the 2.9%+ many stores pay on cards. On a $1,000 order, that difference is about $24.
• Access to locked-out buyers. Customers in regions where cards fail, or buyers who will not hand over card details, convert when crypto checkout is actually there.

A Medusa store selling software licenses or premium goods also skips the 30–90 day card settlement window. Payment confirms on-chain, often in minutes. Funds can then be withdrawn from your merchant account instead of waiting weeks on a card processor.

Crypto also pulls in a demographic traditional rails miss. DeFi users, remote workers paid in stablecoins, international freelancers — people who hold digital currency and prefer spending it directly. They convert better when you meet them at checkout.

How Cryptonly works with Medusa

Cryptonly plugs into Medusa v2 the same way Stripe or PayPal does. You register it as a provider, enable it on a region, and it appears at checkout. When the customer picks crypto, Medusa creates a Cryptonly invoice, then the storefront redirects them to a hosted payment page. They pick their coin, scan a QR or connect a wallet, pay, and land back on your store. Signed webhooks tell Medusa the payment cleared, and the order moves forward.

Your storefront never sees private keys or wallet logic. API credentials stay server-side. Customers get a payment page without accounts or signups. You get a captured session and can fulfill the order.

What's in the box:

• Fiat catalog, crypto checkout. Prices stay in dollars or euros. Cryptonly calculates the coin amount at payment time.
• Hosted checkout. Cryptonly runs the page — wallet selection, QR codes, chain monitoring.
• Webhook-driven capture. Medusa gets a signed webhook when payment lands. No polling, no manual admin checks.
• Full sandbox mode. Test the flow with simulated payments before going live.
• 0.5% if you are verified, 1.3% if not. No setup cost, no monthly retainer.

The plugin lives on the official Medusa marketplace. It is open-source and maintained.

What makes Cryptonly different

Most crypto payment tools either make you run your own wallets or force customers through a clunky third-party flow. Cryptonly is custodial on the merchant side — they hold and settle funds for you — but the buyer experience stays clean. No signups, no accounts. Pay and go.

The Medusa integration uses the platform's native provider hooks. You call initiatePaymentSession, grab the paymentPageUrl, and redirect. When payment clears, the webhook hits your backend, the provider verifies the signature, and Medusa captures the session. No custom capture code, no balance polling, no admin babysitting.

Developer experience on Medusa matters. Cryptonly ships TypeScript types, docs, and a storefront icon component. It works with the Next.js starter. Add the provider config and you are ready to test.

Getting started

Accepting crypto on your Medusa store breaks down into four steps:

1. Sign up at merchant.cryptonly.net. Grab your API key, account ID, and webhook signing key.
2. Install @cryptonly/medusa-plugin-cryptonly and drop your credentials into medusa-config.ts.
3. Enable the provider on a region in Medusa Admin.
4. Wire your storefront. Call initiatePaymentSession on checkout and redirect to the payment URL Cryptonly returns.

Follow the Medusa setup guide for config options, webhook details, return URLs, and storefront snippets. There is no extra middleware layer and no database migration. The provider hooks into Medusa's payment module.

Try the flow yourself at medusa-demo.cryptonly.net. Add something to cart, hit checkout, pick a coin, and walk through the hosted page. Sandbox mode, so no real money moves.

The GitHub repo has examples and an issue tracker if you get stuck.

FAQ

Do I need to run my own wallets?

No. Cryptonly is custodial on the merchant side. Customers pay on the hosted page; funds settle to your Cryptonly merchant balance.

Does my catalog have to be priced in crypto?

No. Keep prices in dollars or euros. Cryptonly converts the amount to the selected coin at checkout.

Can I test before going live?

Yes. Turn on sandbox in the provider config, or walk through the public demo store. Simulated payments, no real funds.

Which Medusa version does this support?

Medusa v2.8 and above. The plugin registers as a native payment provider — not a v1-style plugin.

Bottom line

Crypto payments on Medusa.js are a normal checkout option, not an experiment. Cryptonly gives you the same kind of provider integration you expect from Stripe — lower fees than cards, no chargebacks on those orders, and access to buyers card rails miss. Install it, run sandbox, then enable it on a region. Your next sale can settle in Bitcoin instead of waiting days on a card processor.