How to Build a Bitcoin Checkout API
Why Accept Bitcoin (or Crypto) Payments?
Before diving into code, it’s useful to understand why you might want to accept Bitcoin through an API.
Reach more customers
Some users prefer paying in crypto (for example, Bitcoin) instead of credit cards or bank transfers.
Lower fees and easier cross-border payments
Crypto transactions can reduce reliance on traditional processors and simplify international payments.
Flexibility via API integration
Using an API gives you control. You can connect directly to your order system, ledger, and webhooks, instead of embedding a third-party widget.
Non-custodial control
With a non-custodial setup, you control your wallet and funds — no third-party custody (depending on the gateway).
⚠️ Note: Crypto payments bring unique challenges: slower settlement times (especially on the base layer of Bitcoin), price volatility, and accounting or regulatory complexities. Build carefully.
Building with Blockonomics
We’ll use Blockonomics to create an API-driven Bitcoin checkout.
Below is a step-by-step workflow (based on their official documentation).
1. Create a Wallet and Sign Up
First, make sure you have a Bitcoin wallet you control (for example, Electrum).
Sign up for a Blockonomics merchant account.
After logging in, go to the Stores section to find your API Key — you’ll need it for all API requests.
2. Attach Your Wallet
In your Blockonomics dashboard, “Add a wallet” (via API or UI).
Example endpoint: POST /wallets.
Provide your wallet’s xpub (extended public key) so Blockonomics can generate addresses for you without holding custody of your funds.
3. Create a Store / Checkout Configuration
Use the API to create a store: POST /stores.
Attach one or more wallets to this store.
Configure:
Default currency (e.g., USD, EUR)
Order callback URL
Store name / description
This store represents your checkout configuration.
4. Build the Checkout / Payment Button
When a user is ready to pay:
Call the “Create Payment Address” or “Create Order” endpoint to generate a unique address and amount (for example: POST /payment_address).
Display the payment UI:
Use Blockonomics’ widget or build your own UI.
Show QR code, BTC address, amount in BTC (or USDT) to pay.
Blockonomics doc: “During checkout, merchant creates temporary products via API which are shown via payment button/widget.”
5. Monitor Payments and Handle Confirmations
Blockonomics provides payment monitoring via webhooks.
When payment is detected:
You’ll receive callback (e.g., status: unconfirmed → confirmed).
Callback parameters include: status, address, value, txid.
On your side:
Verify callback signature/secret.
Update your order database (mark paid)
Optionally wait for full confirmation before shipping or unlocking content.
6. Test and Deploy
Before going live:
Generate a payment request.
Send a small BTC payment from a test wallet.
Verify that the webhook triggers and the order gets marked as paid correctly.
UX tips:
Show a message like “Awaiting confirmation”.
Explain typical confirmation times.
After deployment:
Monitor logs.
Handle edge cases: payment to wrong address, under-payment, over-payment, delayed payments.
7. Optional Settings and Features
Blockonomics supports:
BTC and USDT (ERC-20) payments.
Choice of how many confirmations you require before treating payment as final.
Option to convert immediately to fiat (if you integrate with a conversion service) or hold crypto.
Important: Blockonomics is non-custodial — you control your wallet and private keys. You are responsible for custody and security.
Fees: Roughly ~1% after first ~20 free transactions (according to recent reviews).
Security best practices:
Use HTTPS endpoints.
Secure API keys.
Verify webhooks.
Secure your wallet / xpub private key.
Competitor Gateways: A Quick Comparison
Here are a few other crypto/Bitcoin payment gateway options, and why they may be less ideal for certain use-cases compared to the approach above.
BitPay
Why consider: Established gateway, broad crypto support.
Why it might be less ideal:
Primarily custodial in many functions — you may have less direct control of funds vs truly non-custodial setup.
May have higher fees or settlement constraints for small/medium merchants, especially if you want direct wallet control.
Some feature-lock-in: automatic fiat settlement may restrict flexible crypto-holding strategies.
CoinGate
Why consider: Accepts many cryptocurrencies, offers fiat settlement, global reach. Best Bitcoin & Crypto Payment Processor
Why it might be less ideal:
The full API and checkout integration experience may require more dependencies (e.g., conversion/settlement pipeline) which can reduce overall autonomy.
If you want full non-custodial control (you hold your wallet keys and funds) the implied settlement/fiat conversion process may introduce complexity or less control vs pure non-custodial.
Depending on your region, currency support and regulatory overhead may add friction.
CoinPayments
Why consider: Very broad coin support (many altcoins) which is useful if you want a wide variety of tokens. Vocal+1
Why it might be less ideal:
Broad coin support often means more complexity: more token types means more risk, more wallet types, more maintenance.
If your focus is strictly Bitcoin (or a minimal set of assets) then the “large-coin” support might be overkill and lead to higher overhead.
Some features (settlement, conversion, UX) may not be as slick or streamlined for purely Bitcoin checkout use-cases.
Why Blockonomics might be “better fit” for a pure Bitcoin checkout with API control
Blockonomics emphasises non-custodial flows (you provide your wallet xpub).
Great for merchants who want direct control of funds, minimal fiat conversion intermediary.
API-first checkout address generation + webhooks fits well for developers wanting deep integration.
If your use case is focused on Bitcoin (and maybe USDT) rather than dozens of altcoins, it simplifies the operational scope.
Comments ()