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 clipboard
2.19.0or later - A Blockonomics account with a store and a wallet (xPub) attached
- A Medusa server reachable from the internet, for callbacks
Install
1npm install @blockonomics/medusa-payment-blockonomics
Configure
1. Register the plugin and the provider
1234567891011121314151617181920// medusa-config.tsmodule.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:
12npx 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:
1https://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
Required
- Copy to clipboard
apiKey: your Blockonomics API key. - Copy to clipboard
callbackSecret: the secret in the callback URL. Starts with Copy to clipboardMEDUSA_.
Optional
- Copy to clipboard
confirmations(default Copy to clipboard2): confirmations needed before an order is paid. Copy to clipboard1takes about 10 min, Copy to clipboard2about 20 min. Copy to clipboard0risks double-spends. - Copy to clipboard
priceLockSeconds(default Copy to clipboard600): how long the BTC quote stays valid, from 300 to 1800. - Copy to clipboard
underpaymentTolerance(default Copy to clipboard0): how much of a shortfall still counts as paid. Copy to clipboard0.01= 1%. - Copy to clipboard
overpaymentTolerance(default Copy to clipboard0.05): how much excess is allowed before the order is flagged as overpaid. - Copy to clipboard
matchCallback: part of the store's callback URL. Needed if your account has more than one store, otherwise you get error Copy to clipboard1032. - Copy to clipboard
baseUrl(default Copy to clipboardhttps://www.blockonomics.co): the API base URL. Only change it for testing.
Orders
- A transaction is seen: the order is placed with payment status Awaiting.
- It reaches Copy to clipboard
confirmationsand 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 clipboard
bitcoin:{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 clipboard
wss://www.blockonomics.co/payment/{address}to detect the payment. - Poll the cart until Copy to clipboard
completed_atis set. Callbacks complete the order, so don't complete the cart from the storefront.
Re-quoting
12POST /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:
12MEDUSA_URL=http://localhost:9000 ADMIN_EMAIL=... ADMIN_PASSWORD=... node examples/create-cart.jsnode examples/checkout-page.js <cart_id> # http://localhost:8000, must be in storeCors
License
MIT
