One network, one asset
Bitcoin is the simplest of the networks halfin settles on, because there is exactly one of each. The Bitcoin network carries one native asset — BTC — and nothing else: no token standard, no smart-contract layer issuing other assets, no second deployment of the same coin on a competing chain. When a customer says they are paying in bitcoin, there is no ambiguity about which rail the payment takes, which is the opposite of a stablecoin like USDT that lives on Tron, Ethereum, and Solana at once.
BTC is what a customer holds and sends; the Bitcoin network is the protocol underneath that decides when that BTC is actually yours. For a payment processor those network mechanics are the load-bearing part, because they are what separate a transaction that looks paid from one that has settled. A wallet showing a payment as sent and a balance you can safely book against are two different states, and the gap between them is measured in blocks.
Bitcoin is also a base-layer network: a BTC payment is real bitcoin moving on the Bitcoin blockchain, not a wrapped representation riding on another chain. The payer is never asked to bridge or to trust an issuer's version of bitcoin. That keeps the trust model narrow — the only thing you and the customer are relying on is the Bitcoin network itself reaching agreement on which blocks are canonical.
The UTXO model: how a Bitcoin transaction is built
Bitcoin does not track balances the way an account-based network like Ethereum does. There is no ledger row that says an address holds a number. Instead, every spendable piece of bitcoin is an unspent transaction output — a UTXO — created by a previous transaction and locked to a recipient. Your balance on Bitcoin is the sum of the UTXOs your keys can unlock, not a single figure stored somewhere.
A transaction consumes one or more existing UTXOs as inputs and creates new UTXOs as outputs. Inputs are spent whole, so a transaction that needs less than an input is worth produces a change output back to the sender — which is why a Bitcoin payment often shows two outputs, one to the recipient and one returning change. This matters for reconciliation: halfin matches the output paid to the invoice's address and amount, and the customer's change output is simply none of your concern.
The UTXO model is also why an address is best thought of as single-use for a given payment. halfin issues a distinct deposit address per invoice rather than reusing one address across customers, so an incoming output maps cleanly to one expected payment. There is no shared mutable balance to disentangle — each invoice watches for its own output landing on-chain.
- A UTXO is an unspent output locked to a recipient; spendable bitcoin is a set of UTXOs, not an account balance.
- Inputs are consumed whole, so spends usually emit a change output back to the sender alongside the payment.
- halfin matches the output sent to the invoice's address and expected amount; the sender's change output is irrelevant to you.
- A per-invoice deposit address keeps each incoming output mapped to exactly one expected payment.
Mempool, blocks, and confirmations
When a customer broadcasts a Bitcoin transaction it does not go straight into the chain. It first enters the mempool — the network-wide pool of valid transactions waiting to be mined. halfin sees a payment at this stage and can report it as in-flight, but a mempool transaction is not settled: it has not yet been included in a block and could still be replaced or dropped.
Miners then assemble transactions into a block and add it to the chain. Bitcoin targets a new block roughly every ten minutes — a deliberate, well-known property of the network, not a number to design around precisely. The first time a transaction appears in a block it has one confirmation. Each subsequent block mined on top of it adds another confirmation, and confirmations are the unit of certainty: the more blocks stacked above a transaction, the more expensive it would be for any reorganization to undo it.
This is why a Bitcoin payment is deliberate rather than instant, and why halfin exposes the wait as observable states instead of a black box. A payment moves from seen in the mempool, to confirming as blocks accumulate, to settled once it meets the network's confirmation threshold. The only state that should trigger fulfilment is the settled one — acting on a mempool sighting or a single confirmation is how merchants get caught by a transaction that later vanishes.
| Stage | What it means on the Bitcoin network | Settlement status |
|---|---|---|
| In mempool | The transaction is broadcast and valid but not yet mined into any block. | Seen, not settled — it can still be replaced or dropped. |
| First confirmation | The transaction is included in a freshly mined block. | Confirming — a reorg this early can still unwind it. |
| Confirmations accumulating | More blocks are mined on top, deepening the transaction in the chain. | Confirming — hardening toward the threshold. |
| Threshold met | Enough blocks sit above the transaction for halfin's Bitcoin gate. | Settled — credited reorg-aware to your balance. |
Finality is probabilistic: reorgs and reorg-aware crediting
Bitcoin does not have a moment of absolute finality the way a settlement system with a central clearer does. Its finality is probabilistic: a transaction becomes practically irreversible as the cost of rewriting the chain above it grows, but in the first few blocks the network can still reorganize. A reorg happens when two miners produce competing blocks at the same height and the network later converges on the longer chain — the losing block's transactions are dropped back into the mempool, and a payment that briefly looked confirmed is unwound.
Crediting too eagerly is exactly how this bites a merchant. halfin's defence is a per-chain confirmation threshold plus reorg-aware crediting: a BTC payment is not marked paid until it is deep enough that a reorg is no longer a practical concern, and if the chain does reorganize and undo a transaction halfin was tracking, that is reflected rather than silently treated as still-paid. The figure you see as settled is one that held on the canonical chain — you are not exposed to the early window where finality is still soft.
You do not implement any of this yourself. Mempool watching, confirmation counting, threshold enforcement, and reorg handling all live inside halfin's Bitcoin gate. Your integration reacts to a small set of states through the dashboard, the REST API, or a signed webhook, and the contract is simple: treat the early states as in-flight, and only the settled state as money you can act on.
The Bitcoin fee market
Bitcoin block space is limited, so a transaction competes for inclusion by attaching a fee that miners prioritise. The fee is paid by the sender to the network — it is a property of the Bitcoin rail, not a halfin charge — and it floats with how much the network is being used: when demand for block space is high the going rate to confirm promptly rises, and when the network is quiet it falls. A transaction that attaches too little for current conditions waits longer for its first confirmation.
For a payer this is the practical character of the Bitcoin network: confirmation is deliberate and the cost to be confirmed quickly is variable rather than fixed. It is why a customer paying a small amount may prefer a faster, cheaper rail, while a customer settling from cold storage pays on Bitcoin regardless because that is where their value lives. None of this changes what you book — the fee is the customer's transaction cost to the network, separate from the fiat amount your invoice locked.
Because UTXOs are spent whole, the fee also scales with how many inputs a transaction has to gather, which is a wallet-side concern for the payer and not something your invoice controls. From halfin's side the only thing that matters is that the correct amount lands on the invoice's address; how the payer's wallet constructed and fee-rated the transaction is its own business.
How halfin accepts and pays out on Bitcoin
Acceptance on the Bitcoin network runs through the same surfaces as every other rail, with the network mechanics handled underneath. You bill a fiat amount and the customer chooses to pay in BTC; halfin issues a Bitcoin deposit address, locks the rate so the booked figure does not drift while the customer fetches their wallet, watches the network for the matching output, and credits the deposit reorg-aware once it clears the confirmation threshold. The same Bitcoin gate sits behind an invoice, a hosted-checkout page, and a static deposit address — you pick the surface that matches the flow rather than rebuilding on-chain plumbing.
Settlement flows the other way too. A single payout or a mass payout batch sends BTC to a destination address on the Bitcoin network, and an outgoing payment is the same UTXO construction in reverse — inputs gathered, an output to the destination, change returned. Payouts are deliberate, authorised actions; there is no automatic reversal on Bitcoin, so returning funds to a customer is an explicit refund rather than a chargeback. The network's lack of reversibility is the same property that makes a confirmed inbound payment final.
The create call below commits to no asset or network — it bills a flat fiat figure, and the customer's choice of BTC at pay time resolves the Bitcoin rail. The amount is a string end to end, never a float, and an idempotency_key in the request body keeps a retried call from creating a duplicate invoice. The resolved asset and network come back on the invoice record and on each signed webhook event, so your ledger always knows a given payment settled on Bitcoin. Verify the webhook's HMAC signature before acting, and read the field schemas in the docs rather than guessing them.
curl -X POST https://api.thehalfin.com/api/v1/invoices \
-H "X-API-Key: $HALFIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount_fiat": "120.00",
"fiat_currency": "USD",
"deferred": true,
"description": "Order #4471",
"idempotency_key": "00000000-0000-4000-8000-000000000002"
}'
# The invoice commits to no network. The customer choosing BTC at pay
# time resolves the Bitcoin rail; halfin issues a Bitcoin address, locks
# the rate, and credits the deposit reorg-aware once it meets the
# confirmation threshold. Field schemas live at docs.thehalfin.com.