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.
Building with Blockonomics
We’ll use Blockonomics to create an API-driven Bitcoin checkout. Below is a clear step-by-step workflow based on their official documentation.
1. Setup Your Account
First, make sure you have a Bitcoin wallet you control (for example, Electrum).
Sign up for a Blockonomics merchant account. After logging in:
- Add a wallet using your xpub.
- Go to the Stores section to get your API Key — you’ll need it for all API requests.
2. Create a Store
Create a Store in the dashboard and link your wallet to it.
Configure the following:
- Default currency (e.g., USD, EUR)
- Callback URL (your webhook endpoint)
- Store name and description
This store becomes your checkout configuration.
3. Generate Payment Address at Checkout
When a user is ready to pay, call the Create or Get Payment Address endpoint:
POST https://www.blockonomics.co/api/new_address
Required Parameter: match — String used to match part of your callback URL to identify the correct wallet. Partial matches are supported.
Optional Parameters:
- crypto — BTC or USDT (defaults to BTC). When set to USDT, the same payment address will always be returned.
- reset — 0 (default): Creates a new BTC address by moving to the next index. 1: Reuses the most recent BTC address.
Important Note from Docs: Addresses do not expire.
Display to the customer the returned Bitcoin address, amount due, and QR code. You can either build your own UI or use Blockonomics’ Payment Button / Checkout Widget.
4. Monitor Payments and Handle Confirmations
Use the WebSocket channel wss://www.blockonomics.co/payment/<address> to detect incoming payments in real-time.
Blockonomics will then post a callback to your server. The callback includes crucial data like:
- status (0 = unconfirmed, 2 = confirmed)
- address
- value (amount in satoshis)
- txid
- RBF flag (if applicable)
Blockonomics automatically retries failed callbacks with exponential backoff. You can secure your callback URL using a secret parameter.
On your server:
- Verify the callback
- Update order status in your database
- Wait for one or two blockchain confirmations before delivering goods (zero-conf can be reversed if RBF is used)
Reference: Receiving Payments
5. Testing
Blockonomics provides a Test Bench where you can simulate transactions without risking real BTC.
You can trigger unconfirmed, partially confirmed, and confirmed states to test your webhook and WebSocket handlers thoroughly.
6. Security Best Practices
- Only deliver goods once you have at least one or two blockchain confirmations.
- Use a secret parameter in your callback URL for authentication.
- Store order metadata in your database and link each order to its unique BTC address.
- Secure your API key and wallet private keys.
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 ()