Blockonomics

@blockonomics/medusa-payment-blockonomics

Accept Bitcoin payments in Medusa v2 through Blockonomics. Payments go straight to the merchant's own wallet: Blockonomics generates a fresh address for each checkout and notifies Medusa as the transaction is seen and confirmed on-chain.

Blockonomics never holds funds. That makes refunds a manual step, covered under Refunds. Read that section before going live.

Requirements

• Medusa 2.19.0 or later
• A Blockonomics account with a store and a wallet (xPub) attached
• A Medusa server reachable from the internet, so Blockonomics can deliver callbacks

Install

Configure

1. Register the plugin and the provider

Add the plugin to plugins, then register the provider in the Payment Module:

Both entries are required. The plugins entry loads the callback route; the provider entry loads the payment provider. Without the plugins entry, checkout works but callbacks return 404, and no payment ever completes.

Generate the secret by running this in your Medusa project, after installing the plugin:

npx blockonomics-callback-secret

It prints a BLOCKONOMICS_CALLBACK_SECRET=MEDUSA_... line to add to .env. Or, without the plugin installed:

The MEDUSA_ prefix is required; Medusa refuses to start without it. The secret is not issued by Blockonomics.

2. Set the callback URL in Blockonomics

In the Blockonomics dashboard, open Stores, edit the store, and set its callback URL to:

https://your-store.com/hooks/blockonomics/blockonomics_blockonomics?secret=YOUR_CALLBACK_SECRET

Get this exactly right. A wrong URL fails silently: callbacks arrive, are rejected, and orders stay unpaid.

• The path is /hooks/blockonomics/blockonomics_{id}, where {id} is the provider's id in medusa-config.ts. With id: "blockonomics" that gives blockonomics_blockonomics. If you change the id, change the URL.
• secret must equal BLOCKONOMICS_CALLBACK_SECRET. Callbacks with a missing or different secret are logged and ignored.
• Use /hooks/blockonomics/..., not Medusa's /hooks/payment/.... Blockonomics sends callbacks as GET requests, which Medusa's own endpoint does not accept.

3. Enable the provider in a region

In the Medusa admin, go to Settings → Regions, edit the region, and add Blockonomics (pp_blockonomics_blockonomics) to its payment providers.

Options

Choosing confirmations

Whichever value you pick, the order is placed as soon as the transaction is seen and marked paid once it settles. See Orders.

Unconfirmed transactions that opted into Replace-By-Fee are never treated as paid, even with confirmations: 0, because the sender can still replace them.

Offering both instant and secure checkout

There is no settings screen for provider options, but you can register the provider twice under different ids and choose between them per region in the admin:

These register as pp_blockonomics_instant and pp_blockonomics_secure. Each needs its own callback URL, so use a separate Blockonomics store for each, with matchCallback set to tell them apart:

Payment lifecycle

The provider follows the payment model of the Blockonomics WooCommerce plugin. Every address handed out for a session is a payment with its own fiat quote, and the callback that reaches confirmations settles it:

What a settled payment paid is recorded in satoshis and in fiat, valued at the rate that address was quoted at: a customer who sent 40% of the BTC asked for has paid 40% of the fiat, whatever the rate has done since.

Underpayments. The remainder in fiat is quoted on a fresh address at the current rate the next time the quote is refreshed (see Re-quoting the amount). The settled address stays on the session as the record of the partial payment. The order is paid once the last address settles in full. Nothing is refunded automatically.

Overpayments. The payment settles as normal, and Medusa records the order total as captured. What was actually received is shown in the Bitcoin payment box on the order page in the admin, flagged Overpaid above overpaymentTolerance, and logged as a warning. Refund the difference from your wallet.

A settled address ignores further callbacks. An unconfirmed transaction that opted into Replace-By-Fee only has its transaction id recorded, since the sender can still cancel it.

Orders

• The order is placed as soon as a transaction is seen. It shows in the admin with payment status Awaiting.
• Once the payment settles in full, it changes to Captured. Only fulfil Captured orders.
• An underpaid order stays Awaiting until the remainder settles.
• If a transaction never confirms (e.g. double-spent), the order stays Awaiting. Cancel it in the admin.

Storefront

There is no hosted payment page. The storefront shows the customer where to send Bitcoin, using the payment session's data.

examples/checkout-page.js is a working payment screen that implements everything in this section, in plain JavaScript with no framework. Start from it and port it to your storefront. Without a storefront shows how to run it against a cart.

The session's data carries:

The flow the Blockonomics WooCommerce plugin uses, and what to build. The function names point to where the example does each step:

1. Find the cart's payment session whose provider_id starts with pp_blockonomics (findSession).
2. Show a QR code of bitcoin:{address}?amount={btc}, an "Open in wallet" link to the same URI, and the address and amount as copyable fields (renderPayment).
3. Count down to price_locked_until. When it runs out, re-quote through the plugin's store route below and update the amount, rate, and QR code (startTimer, refresh, requote). Do not create a new payment session for this: Medusa replaces the session, which hands the customer a new address.
4. Open wss://www.blockonomics.co/payment/{address}, and reconnect if it drops. The first message means the payment has been seen: switch to a receipt screen with the transaction id. Messages carry status (0 unconfirmed, 1, 2 confirmed), value in satoshis, and txid (connectSocket, showReceipt).
5. If value is short of expected_satoshis, show the shortfall in fiat (expected_fiat * (1 - value / expected_satoshis)). The remainder can be paid once the underpayment has confirmed: call the re-quote route, and when it comes back with a new address, return to the payment screen for it. Show paid_fiat and expected_fiat as the paid and remaining amounts (offerRemainder, the Pay remaining handler).
6. Do not complete the cart from the storefront. The callbacks place the order and mark it paid. Poll the cart until completed_at is set, and follow the socket for confirmations (watchOrder).
7. When the page is reloaded after paying, payment_status is no longer 0: show the receipt from the session data instead of the payment screen (the boot block at the end of the page script).

Re-quoting the amount

Runs the provider's price refresh on the session, what the WooCommerce plugin does when its checkout page loads:

• nothing seen yet: the amount is re-quoted at the current rate once the price lock has expired. The address is kept.
• payment in progress: nothing changes; the customer sent what they were quoted.
• settled underpayment: a new address is handed out for the remainder at the current rate. The response carries the new address.

Refunds

Bitcoin payments are irreversible, and Blockonomics holds no funds, so refunds cannot go through the provider. Clicking Refund in the Medusa admin throws an error.

To refund a customer, send the amount from the wallet that received the payment, and record the refund outside of Medusa.

Testing

Blockonomics has a test mode that fires real callbacks without moving funds.

1. Expose your local server with a tunnel such as ngrok, and set the store's callback URL to the tunnel address.
2. In the Blockonomics dashboard, enable Testmode on the store.
3. Place an order in your storefront and choose Blockonomics.
4. On the Test Bench, send the quoted amount from the Test Bitcoin Wallet.

Callbacks arrive with status 0 immediately, 1 after about 5 minutes, and 2 after about 10. The order appears in the admin as Awaiting after status 0, and turns Captured at confirmations.

Checkout failing with Blockonomics API responded with 400 for /api/new_address and error 1032 means the account has more than one store and matchCallback is unset. Set it to a substring of this store's callback URL that no other store in the account shares.

Without a storefront

The payment screen can be exercised before a storefront exists. examples/create-cart.js builds a cart and a Blockonomics payment session over the Store API, and examples/checkout-page.js serves the payment screen for it on port 8000.

The payment screen calls the Store API from the browser, so http://localhost:8000 has to be in the server's storeCors. A local Medusa allows it by default. Point MEDUSA_URL at a deployed store and you have to add that origin there yourself.

Both need Node 18 or later and have no dependencies. They sign in as an admin only to read a publishable key; everything after that goes through the Store API.

License

MIT