Skip to content
Sign InSign Up

Accept Crypto Payments with Medusa Payment Gateway

A Cryptonly account and an API key are enough. Install the plugin, enable it on a region, and your Medusa store can take crypto payments. The steps below are the whole setup.

How to start accepting crypto payments on Medusa

  1. Sign up for a Cryptonly account

    Create a merchant account in the Cryptonly dashboard. That account issues the API key, account id, and webhook signing key used in the steps below.

  2. Generate an API key

    Create a key that can create, list, and cancel invoices: invoices.create, invoices.list, and invoices.cancel. Keep the key, the account id, and the webhook signing key for the Medusa config.

  3. Install the Medusa plugin

    Add the Cryptonly payment provider to your Medusa app, then register @cryptonly/medusa-plugin-cryptonly/providers/cryptonly in medusa-config.ts with the API key, account id, and webhook signing key. The config sample is in the Medusa integration guide.

    npm install @cryptonly/medusa-plugin-cryptonly

  4. Start accepting payments

    Enable Cryptonly for a region in Medusa Admin. Customers pay on the hosted page, and the signed webhook captures the payment session in Medusa when the payment confirms.

  5. Connect the storefront

    On checkout, call initiatePaymentSession and redirect the customer to the paymentPageUrl Cryptonly returns. They pay on the hosted page and come back to your store.

What is Medusa

Medusa is an open-source commerce framework for Node.js. A store built with it uses a headless backend and a storefront you own, rather than a hosted theme.

Payments, regions, and fulfillment are modules. In Medusa v2 a gateway is a payment provider: you register it, then turn it on for the regions that should offer it.

Cryptonly uses that provider hook. Prices stay in your store currency. The customer pays on a Cryptonly page, and a signed webhook captures the session in Medusa when the payment confirms.

What crypto can you accept with Medusa and Cryptonly?

View all currencies
BitcoinBTC$82,537.31-1.71%EthereumETH$2,516.08-1.47%TetherUSDT$0.998941-0.01%USD CoinUSDC$1.0011+0.01%BNBBNB$744.54-1.67%TRONTRX$0.3309-0.24%ChainlinkLINK$12.888-3.76%

Medusa FAQ

  • Which Medusa versions does the plugin support?

    Medusa v2.8 or newer, running on Node.js 20 or newer. The provider hooks into Medusa's payment module, so older v1 apps are not supported.

  • Do I need to build a crypto checkout page?

    No. The customer pays on a Cryptonly hosted page and returns to your store. You do not build a wallet screen or watch the chain yourself.

  • What does it cost?

    0.5% per payment, with no setup fee.

  • Can I test the plugin before taking real payments?

    Yes. Sandbox mode runs the hosted page and the webhook without moving funds. Turn sandbox off when you are ready to accept live payments.

  • Do product prices have to be in crypto?

    No. Keep the catalog in your store currency. Cryptonly converts the amount when the customer checks out.

  • How does Medusa know an order is paid?

    Cryptonly sends a signed webhook to your backend. The provider checks the signature, and Medusa captures the payment session.

Accept crypto payments with Medusa and Cryptonly

Hosted checkout, signed webhooks, and a 0.5% fee. Medusa keeps the order status in sync, and your catalog stays priced in fiat.