Skip to content
All integrations

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.

Plugin overview

Version
0.1.7
Last Updated
Medusa
v2.8+
Source
GitHub
npm
Marketplace

How to start accepting crypto payments on Medusa

  1. Sign up for a Cryptonly account

    Create a merchant account in the Cryptonly dashboard. Each account has its own API keys and webhook signing key. The API key selects the account.

  2. Generate an API key

    Create a key on the account Security settings with currencies.list, invoices.create, invoices.list, and invoices.cancel. Keep the API key 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 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
FAQ

Medusa plugin questions

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

Ready to accept crypto payments?

Tell us about your use case. Use the form or email us.

Contact us