Blockonomics

Bitcoin payments to your own wallet

@blockonomics/medusa-payment-blockonomics

Accept Bitcoin in Medusa v2 through Blockonomics. Payments go straight to your own wallet: each checkout gets a fresh address, and Blockonomics notifies Medusa as the transaction confirms.

Blockonomics never holds funds, so refunds are manual. See Refunds.

Requirements

Medusa Copy to clipboard2.19.0 or later
A Blockonomics account with a store and a wallet (xPub) attached
A Medusa server reachable from the internet, for callbacks

Install

1
npm install @blockonomics/medusa-payment-blockonomics

Configure

1. Register the plugin and the provider

1234567891011121314151617181920
// medusa-config.ts
module.exports = defineConfig({
  plugins: [
    { resolve: "@blockonomics/medusa-payment-blockonomics", options: {} },
  ],
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "@blockonomics/medusa-payment-blockonomics/providers/blockonomics",
            id: "blockonomics",
            options: {
              apiKey: process.env.BLOCKONOMICS_API_KEY,
              callbackSecret: process.env.BLOCKONOMICS_CALLBACK_SECRET,
              confirmations: 2,
            },
          },
        ],

Both entries are required. Without the Copy to clipboardplugins entry, callbacks return Copy to clipboard404 and no payment completes.

Generate the callback secret in your project and add the printed line to Copy to clipboard.env with your API key:

12
npx blockonomics-callback-secret
# BLOCKONOMICS_CALLBACK_SECRET=MEDUSA_...

The secret must start with Copy to clipboardMEDUSA_. It is yours, not issued by Blockonomics.

2. Set the callback URL in Blockonomics

In the Blockonomics dashboard, under Stores, set the store's callback URL to:

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

The path is Copy to clipboard/hooks/blockonomics/blockonomics_{id}, where Copy to clipboard{id} is the provider Copy to clipboardid. Callbacks with a wrong secret are ignored, so a typo leaves orders unpaid without any error.

3. Enable the provider in a region

In the Medusa admin, under Settings → Regions, add Blockonomics (Copy to clipboardpp_blockonomics_blockonomics) to the region.

Options

Option Default Description Copy to clipboardapiKey - Required. Blockonomics API key. Copy to clipboardcallbackSecret - Required. Secret on the callback URL, starting with Copy to clipboardMEDUSA_. Copy to clipboardconfirmations Copy to clipboard2 Confirmations before the order is marked paid: Copy to clipboard0, Copy to clipboard1 (~~10 min) or Copy to clipboard2 (~~20 min). Copy to clipboard0 risks double-spends. Copy to clipboardpriceLockSeconds Copy to clipboard600 How long the BTC quote is valid (300–1800). Copy to clipboardunderpaymentTolerance Copy to clipboard0 Shortfall still counted as paid. Copy to clipboard0.01 = 1%. Copy to clipboardoverpaymentTolerance Copy to clipboard0.05 Excess above which the payment is flagged as overpaid. Copy to clipboardmatchCallback - Substring of the store's callback URL. Required if the account has more than one store (else error Copy to clipboard1032). Copy to clipboardbaseUrl Copy to clipboardhttps://www.blockonomics.co API base URL, for testing.

Unconfirmed Replace-By-Fee transactions are never treated as paid. To offer several confirmation levels, register the provider more than once with different Copy to clipboardids, each with its own Blockonomics store and Copy to clipboardmatchCallback.

Orders

A transaction is seen: the order is placed with payment status Awaiting.
It reaches Copy to clipboardconfirmations and covers the amount: Captured. Only fulfil captured orders.
Underpaid: the order stays Awaiting. The remainder is quoted on a new address.
Overpaid: the order is captured, and the admin order page shows the amount received with an Overpaid flag. Refund the difference from your wallet.
Never confirms: the order stays Awaiting. Cancel it in the admin.

Storefront

There is no hosted payment page. Your storefront renders the payment from the session's Copy to clipboarddata. Copy to clipboardexamples/checkout-page.js is a complete payment screen in plain JavaScript that you can port.

Key Copy to clipboarddata fields: Copy to clipboardaddress, Copy to clipboardexpected_satoshis, Copy to clipboardexpected_fiat, Copy to clipboardpaid_fiat, Copy to clipboardbtc_price, Copy to clipboardprice_locked_until (Unix ms), Copy to clipboardpayment_status (Copy to clipboard0 none, Copy to clipboard1 in progress, Copy to clipboard2 settled), Copy to clipboardconfirmations, Copy to clipboardtxid, Copy to clipboardpayments (all addresses for the session).

The page should:

Show a QR code for Copy to clipboardbitcoin:{address}?amount={btc} and count down to Copy to clipboardprice_locked_until.
When the quote expires, or after an underpayment confirms, call the re-quote route below. Do not create a new payment session.
Listen on Copy to clipboardwss://www.blockonomics.co/payment/{address} to detect the payment.
Poll the cart until Copy to clipboardcompleted_at is set. Callbacks complete the order, so don't complete the cart from the storefront.

Re-quoting

12
POST /store/blockonomics/payment-sessions/{payment_session_id}
x-publishable-api-key: pk_...

This refreshes the amount once the price lock has expired. If the session has a settled underpayment, it returns a new Copy to clipboardaddress for the remainder.

Refunds

Bitcoin payments are irreversible, and refunds cannot go through the provider. Refund in the Medusa admin throws an error. Send refunds from your wallet and record them outside Medusa.

Testing

Expose your server (e.g. ngrok) and point the store's callback URL at it.
Enable Testmode on the store in Blockonomics.
Check out with Blockonomics, then send the amount from the Test Bench.

Callbacks arrive with status Copy to clipboard0 right away, Copy to clipboard1 after about 5 minutes and Copy to clipboard2 after about 10.

To test without a storefront:

12
MEDUSA_URL=http://localhost:9000 ADMIN_EMAIL=... ADMIN_PASSWORD=... node examples/create-cart.js
node examples/checkout-page.js <cart_id>   # http://localhost:8000, must be in storeCors

License

MIT