> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/faqs-and-troubleshooting/payments-faqs/why-do-btc-on-chain-payments-take-longer.md). # Why do BTC (on-chain) payments take longer? BTC (on-chain) refers to **Bitcoin on-chain** payments: payments made using BTC on the Bitcoin network, rather than faster payment rails such as Bitcoin Lightning or other near-real-time tender types. BTC (on-chain) can be a useful tender type for the right payment environment, but it should be presented differently from tenders that complete in seconds. The key difference is that Bitcoin on-chain payments depend on blockchain confirmation timing, which can take several minutes or longer. ### Summary BTC (on-chain) payments take longer because Bead must wait for the Bitcoin network to detect and confirm the transaction before the payment can be treated as complete. When a BTC (on-chain) payment enters `processing`, Bead has detected funds and the transaction is underway. However, the payment should not be treated as final until it reaches `completed`. In Bead payment statuses, `processing` means funds have been detected and conversion or settlement processing is in progress, while `completed` means the customer sent the requested amount and the crypto has been converted and credited. For BTC (on-chain), integrators should usually move the customer out of the payment wait screen once the payment is `processing`, explain that the transaction is underway, and rely on webhooks or payment status checks to confirm completion. ### Why BTC (on-chain) is not instant Bitcoin on-chain payments are validated through the Bitcoin blockchain. When a customer sends BTC, the transaction is broadcast to the Bitcoin network. After that, the transaction must be included in a block and receive confirmations. A confirmation is added each time a new block is built on top of the block that includes the transaction. Bitcoin developer guidance notes that transactions paying sufficient fees need about 10 minutes on average to receive one confirmation, and that higher confirmation counts provide stronger protection against double-spend risk. Because of this, BTC (on-chain) is not designed to behave like a card-present authorization, wallet app approval, or instant access payment flow. It is a durable settlement-style payment method, but it is not always the best fit when goods or services must be released immediately. ### What the customer may experience A customer paying with BTC (on-chain) may see the payment move through these states: 1. **Created**\ The payment has been created and Bead is waiting for the customer to send funds. 2. **Processing**\ Bead has detected the incoming BTC transaction. The payment is underway, but it is not final yet. 3. **Completed**\ The payment has reached the required completion state and may be treated as successful. The important customer experience point is that `processing` is meaningful. It means the transaction is underway. For BTC (on-chain), the customer should not always be expected to keep staring at a loading screen until final completion. ### Recommended integrator behavior When a BTC (on-chain) payment reaches `processing`, show the customer a clear confirmation message and let them move on. Recommended customer-facing message: ``` Your BTC payment has been detected and is now processing. Bitcoin on-chain payments can take several minutes to confirm. You do not need to keep this page open. The merchant will confirm when the payment is complete. ``` For order, invoice, or service flows, the integrator should: * record the payment as **payment processing** or **payment pending confirmation** * show the customer that the transaction has been detected * move the customer to an order status, receipt, invoice, or next-step screen * use Payment Webhooks or payment status checks to detect the final `completed` state * wait for `completed` before releasing goods, granting access, shipping, or marking the invoice as paid ### Do not fulfill on `processing` `processing` means the payment is underway, but it is not the same as `completed`. For BTC (on-chain), do not use `processing` as the final fulfillment trigger. Only release goods, grant digital access, ship an order, or mark an invoice as paid after the payment reaches `completed`. This is especially important for: * high-value goods * irreversible fulfillment * digital goods that are delivered immediately * orders where the customer cannot be contacted later * any situation where the merchant would be exposed if the payment did not complete ### When BTC (on-chain) is a good fit BTC (on-chain) works best when payment completion does not need to happen instantly in front of the customer. Good examples include: | Environment | Why BTC (on-chain) can work | | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | Ecommerce orders with later shipment | The customer can place the order, move on, and the merchant can ship after payment completion. | | Service invoices paid before pickup | The customer can pay before arriving, giving the transaction time to complete. | | Auto repair invoices | The payment can process while the vehicle is still being prepared. | | Vehicle deposits | The transaction can complete before the next contractual or delivery step. | | Jewelry, luxury goods, or other high-ticket in-person sales | Staff may be able to provide a high-touch experience while waiting for completion. | | B2B or invoice-style payments | Payment confirmation can be handled asynchronously through operational workflows. | ### When BTC (on-chain) is not a good fit BTC (on-chain) is usually a poor fit when the customer expects immediate delivery and there is no natural waiting period. Avoid BTC (on-chain), or do not enable it by default, for: | Environment | Why BTC (on-chain) may not fit | | ---------------------------------------- | -------------------------------------------------------------------------------- | | Fast in-person checkout | The customer and staff may not be able to wait several minutes or longer. | | Quick-service retail | The payment experience can block the line or create confusion. | | Instant digital downloads | The merchant should not release the asset until `completed`. | | Immediate account access | Customers may expect access right away, but the payment may still be processing. | | Low-ticket, high-throughput environments | Operational friction may outweigh the benefit of accepting BTC (on-chain). | In these cases, consider faster tender types instead. ### BTC (on-chain) compared with faster tenders Other tender types may also briefly enter `processing`, but the window is usually much shorter. For most near-real-time tenders, it may be reasonable for the customer to wait on the screen until the final outcome appears. BTC (on-chain) is different because the confirmation window can be long enough that the payment experience should become asynchronous. A good rule of thumb: * For most tenders: keep the customer in the payment flow until final status. * For BTC (on-chain): once the payment is `processing`, acknowledge that the transaction is underway and let the customer continue. ### Implementation checklist Before enabling BTC (on-chain), confirm that your integration can support an asynchronous payment experience. Your integration should be able to: * identify when the selected tender is BTC (on-chain) / Bitcoin on-chain * display BTC-specific messaging when the payment reaches `processing` * store the payment `trackingId` * listen for Payment Webhooks or periodically check payment status * keep the order, invoice, or service request in a pending state until `completed` * notify the merchant or customer when the payment completes * prevent fulfillment while the payment is still `processing` ### Suggested customer messages Use language that sets expectations without making the customer feel stuck. #### When payment is detected ``` Payment detected. Your BTC payment is now processing on the Bitcoin network. This can take several minutes. You do not need to keep this page open. ``` #### For ecommerce orders ``` Your BTC payment has been detected and your order is pending payment confirmation. We’ll confirm your order once the payment is complete. ``` #### For invoices or service payments ``` Your BTC payment is underway. The merchant will be notified when the payment is complete. ``` #### For in-person sales ``` The BTC transaction has been detected and is processing. Bitcoin on-chain payments can take several minutes to confirm. The merchant will release the goods once the payment is complete. ``` ### Frequently asked questions #### Is BTC (on-chain) broken if it takes several minutes? No. Several minutes can be normal for Bitcoin on-chain payments. Timing depends on Bitcoin network confirmation behavior and transaction conditions. #### Does `processing` mean the customer paid? `processing` means Bead has detected funds and the payment is underway. It does not mean the payment is final. Use `completed` as the final success state. #### Can the customer close the payment page? In BTC (on-chain) flows, once the payment is `processing`, it is generally reasonable to tell the customer they can move on. Your integration should rely on webhooks or status checks to confirm final completion. #### Should merchants release goods when BTC (on-chain) is `processing`? No. Merchants should wait until the payment is `completed` before releasing goods, granting digital access, shipping, or marking an invoice as paid. #### Why was Bitcoin built this way? Bitcoin was designed as a decentralized peer-to-peer electronic cash system. Its security model depends on network validation and block confirmations, not on a centralized real-time authorization network. That design makes Bitcoin durable and decentralized, but it also means on-chain payments do not always behave like instant checkout payments. #### Why do other crypto or wallet tenders complete faster? Different tender types use different networks, confirmation models, or payment rails. Some are designed for faster payment confirmation or use networks with shorter settlement windows. BTC (on-chain) uses Bitcoin on-chain confirmation behavior, so it should be treated as a longer-running payment method. ### Related pages * [Payment Statuses](/payments/payment-statuses.md) * [Payment Webhooks](/payments/payment-webhooks.md) * [Crypto Wallet Flow and Amounts](/payments/crypto-wallet-flow-and-amounts.md) * [Create Payment](/payments/create-payment.md) * [Choosing Tender Types by Payment Environment](/reference-guide/payment-flows/choosing-tender-types-by-payment-environment.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers.bead.xyz/faqs-and-troubleshooting/payments-faqs/why-do-btc-on-chain-payments-take-longer.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.