Implementing Bitcoin Payments

To accept bitcoin payments reliably, generate a unique address for each order. The first and most critical mistake we see in integrating Bitcoin payments is using a single address for all customers. Two users could send the same amount in one transaction, generate multiple UTXOs partially covering the sum, or encounter batching from the exchange. The correct approach is to generate a unique address for each payment. In our practice, when integrating for a marketplace, we solved the address duplication issue, reducing payment processing time by 30% and eliminating confusion with credits.

Bitcoin: A Peer-to-Peer Electronic Cash System — Satoshi Nakamoto

How address derivation works

The BIP-32/BIP-44 standard allows generating an infinite tree of addresses deterministically from a single master seed. For receiving payments, we use an xpub (extended public key) – the public part stored openly on the server to generate addresses. The private key remains separate (cold storage, hardware wallet) and is only needed for withdrawals.

Master Seed → xpub (m/44'/0'/0') ↓ index=0: 1A1zP1... (payment #1) index=1: 1B2zP2... (payment #2) index=N: ... (payment #N) 

The BIP-44 derivation path for Bitcoin mainnet: m/44'/0'/account'/change/index. For receiving, change=0, index is incremented. For Native SegWit, we use BIP-84 with path m/84'/0'/0'. BIP84 (Native SegWit) is 37% cheaper than BIP44 (Legacy) and 20% cheaper than BIP49 (Wrapped SegWit).

How to ensure a unique address for each payment?

Use the extended public key (xpub) and an index corresponding to the order ID in your database. This guarantees that a customer cannot reuse an old address and you avoid payment overlaps. Never generate addresses randomly – always deterministically.

Address types comparison

Native SegWit (bc1q) saves up to 40% on fees compared to Legacy – almost twice as cost-effective for the customer. Taproot with Schnorr signatures allows transaction aggregation, further reducing block size by 20% relative to Native SegWit.

Implementation: Node.js + bitcoinjs-lib

import * as bitcoin from 'bitcoinjs-lib' import { BIP32Factory } from 'bip32' import * as ecc from 'tiny-secp256k1' bitcoin.initEccLib(ecc) const bip32 = BIP32Factory(ecc) const NETWORK = bitcoin.networks.bitcoin // or networks.testnet // One-time: generate xpub from seed (performed in cold storage) // const seed = bip39.mnemonicToSeedSync(mnemonic) // const root = bip32.fromSeed(seed, NETWORK) // const account = root.derivePath("m/84'/0'/0'") // BIP-84 for Native SegWit // const xpub = account.neutered().toBase58() // console.log(xpub) // store in .env as BITCOIN_XPUB // On server: generate address by index function getPaymentAddress(xpub: string, index: number): string { const node = bip32.fromBase58(xpub, NETWORK) const child = node.derive(0).derive(index) // external chain, index N const { address } = bitcoin.payments.p2wpkh({ pubkey: Buffer.from(child.publicKey), network: NETWORK, }) if (!address) throw new Error('Failed to derive address') return address } 

Follow these steps to setup a bitcoin payment gateway using an HD wallet BIP32:

1. Generate an xpub from a master seed in cold storage using BIP32 or BIP84.
2. Store the xpub in your server environment.
3. For each new order, derive a unique address using the order index.
4. Save the payment details in the database.
5. Monitor the address for incoming transactions via electrs.
6. Update payment status based on confirmations.
7. Handle edge cases like overpayment and underpayment.

Database schema for payments

CREATE TABLE bitcoin_payments ( id BIGSERIAL PRIMARY KEY, order_id UUID NOT NULL REFERENCES orders(id), address VARCHAR(62) NOT NULL UNIQUE, hd_index INTEGER NOT NULL UNIQUE, amount_sat BIGINT NOT NULL, -- amount in satoshis status VARCHAR(20) DEFAULT 'pending', -- pending/underpaid/confirmed/expired created_at TIMESTAMPTZ DEFAULT NOW(), expires_at TIMESTAMPTZ NOT NULL, confirmed_at TIMESTAMPTZ, tx_hash VARCHAR(64) ); CREATE INDEX ON bitcoin_payments(address); CREATE INDEX ON bitcoin_payments(status) WHERE status = 'pending'; 

Transaction monitoring

For production, we use our own Bitcoin node with electrs. Public APIs (Blockstream) are only suitable for prototypes. For bitcoin transaction monitoring, we subscribe via WebSocket. Example:

import ElectrumClient from 'electrum-client' const client = new ElectrumClient(50002, 'your-electrs-host', 'tls') await client.connect('payment-monitor', '1.4') async function watchAddress(address: string, onPayment: (tx: any) => void) { const scriptHash = addressToScriptHash(address) // sha256 reversedLE await client.subscribe.on('blockchain.scripthash.subscribe', async (updates) => { const [scripthash, status] = updates if (scripthash === scriptHash && status !== null) { const history = await client.blockchainScripthash_getHistory(scriptHash) onPayment(history) } }) await client.blockchainScripthash_subscribe(scriptHash) } 

Number of confirmations

Zero-conf is acceptable only for physical points with small amounts and RBF=false. In e-commerce, we wait for at least one confirmation.

How to handle edge cases correctly?

Bitcoin overpayment handling – we credit the full amount and keep the difference on the user's balance. Refund is only possible if the customer provides a return address.

Underpayment – we freeze the payment and ask to top up to the same address within the order lifetime. We never treat a partial amount as full.

Expiry – the address has "expired" but a transaction still arrives. We keep such addresses active for another 24 hours for crediting, but do not show them for new payments.

Do not trust unconfirmed transactions with BIP125-opt-in-RBF=true. Wait for at least one block.

The built-in logic should differentiate statuses: pending, underpaid, confirmed, expired. For underpaid, automatically extend the wait time by 15 minutes. For expired, cancel the order but retain the ability to credit on late transaction (manually).

Withdrawals

For UTXO withdrawal, we use PSBT with proper coin selection. We recommend sweeping once a day with a script, rather than triggering automatically on every payment – this reduces the number of transactions and fees.

What's included in the work

• Design of HD wallet architecture
• Server-side implementation on Node.js with bitcoinjs-lib (Bitcoin payment gateway Node.js)
• Integration of electrs for transaction monitoring
• Database schema and payment logic (overpayment, underpayment, expiry)
• API documentation and operation manual
• Administrator training on the panel
• 30-day warranty on correct payment gateway operation

Our engineers hold blockchain certifications and have implemented payments for 20+ projects. We offer a free assessment for your project. Get a consultation for your project — write to us. Order a turnkey payment gateway implementation.