# Crypto Wallet Flow and Amounts Bead’s crypto payment experience uses a direct wallet-to-wallet transfer on chain. Depending on the asset and network, the consumer experience differs: * For many on-chain assets and networks, the QR code contains only a destination wallet address. In these cases, the consumer is expected to enter the amount manually in their wallet. This is normal and expected behavior. * Some rails, such as Bitcoin Lightning, commonly support a scannable invoice format that can include both the destination and the amount. In those cases, the wallet can populate the amount automatically. * BTC Classic refers to Bitcoin on-chain payments. BTC Classic is different from Bitcoin Lightning. BTC Classic may take several minutes or longer to reach final completion because the payment depends on Bitcoin network confirmation. For BTC Classic, integrators should design the customer experience so the customer can move on after the payment is detected and the status reaches `processing`. The merchant should still wait for `completed` before fulfilling the order, releasing goods, granting digital access, shipping, or marking an invoice as paid. ### Hosted payment page ownership When an integrator routes a consumer into the Bead hosted payment page for crypto, Bead controls that consumer experience end to end. Integrators do not control the hosted page UI, content, or flow. ### Integrator-owned pre-payment and post-payment experience Bead controls the hosted crypto payment page experience. Integrators still control the customer experience before redirecting the customer to Bead and after receiving payment status updates. Before redirecting the customer, set expectations about the selected tender. For many on-chain payments, the customer may need to manually enter the payment amount in their wallet. For BTC Classic / Bitcoin on-chain, tell the customer that payment confirmation can take several minutes and that the merchant will confirm completion. After the payment is detected, your integration should use Payment Webhooks or payment status checks to update the merchant order, invoice, or fulfillment workflow. For BTC Classic, do not depend on the customer keeping the payment page open until final completion. ### How the QR code works #### What the QR code contains For many crypto payments, the QR code contains: * a destination wallet address It typically does not include: * the amount to send Because the amount is not encoded in the QR code, the consumer will enter the amount in their wallet based on the amount shown on the payment screen. #### What the consumer does after scanning After scanning the QR code, the consumer typically: * opens their wallet * selects the same asset and network they chose on the payment screen * confirms the destination address * enters the amount shown on the payment screen * submits the transfer The consumer’s wallet is the system of record for the transfer submission. The consumer controls the final send action, including the entered amount. ### What happens after the consumer sends the transfer After the consumer submits the transfer from their wallet, Bead monitors the payment for funds and status changes. A crypto payment may move through these states: * `created` — Bead is waiting for the customer to send funds * `processing` — funds have been detected and the payment is underway, but not final * `completed` — the payment has reached the successful final state For most crypto tenders, the `processing` window may be short enough for the customer to remain in the payment flow. For BTC Classic / Bitcoin on-chain, `processing` can last several minutes or longer. In those flows, the recommended experience is to acknowledge that the payment has been detected, let the customer move on, and use webhooks or status checks to confirm when the payment reaches `completed`. Do not fulfill based on `processing`. Fulfill only after `completed`. ### Why amount entry varies by rail Different crypto rails support different payment payloads and wallet behaviors. #### Bitcoin Lightning example Bitcoin Lightning commonly uses an invoice-style payload that can include: * destination * amount This can streamline the scan-and-pay experience because the wallet can populate the amount automatically from the invoice. #### BTC Classic / Bitcoin on-chain example BTC Classic uses Bitcoin on-chain payments. The customer sends BTC from their wallet to the address shown on the payment page. The customer may need to: * scan or copy the destination address * confirm they are sending BTC on the Bitcoin network * enter the amount shown on the payment page * submit the transfer in their wallet After the transfer is detected, the payment may enter `processing` while Bead waits for the required Bitcoin confirmation behavior. This can take several minutes or longer. For BTC Classic, the customer does not need to remain on the payment page until final completion if your integration can show a pending payment state and rely on webhooks or status checks. #### On-chain transfer example For many on-chain transfers, the common pattern is: * destination address in the QR code * amount manually entered by the consumer in their wallet This is expected behavior across many wallets and networks. ### What integrators should expect #### Consumer experience expectations If your checkout flow includes crypto, set the expectation that: * scanning the QR code routes the consumer to a destination address * for many assets and networks, the consumer will enter the amount shown on the payment screen * the consumer must send using the same asset and network selected on the payment screen * for BTC Classic / Bitcoin on-chain, final completion may take several minutes or longer after the transfer is detected * `processing` means the payment is underway, but not final * the merchant should fulfill only after the payment reaches `completed` * for BTC Classic, the customer can usually move to an order, invoice, receipt, or status screen after the payment is detected If your integration supports BTC Classic, avoid messaging that requires the customer to wait on the payment page until final completion. Instead, tell the customer when the payment has been detected, explain that Bitcoin on-chain confirmation may take several minutes, and provide a next step such as an order status page, invoice page, receipt page, or merchant confirmation message. #### Common mismatch scenarios Manual entry introduces a risk of mismatch. Common causes include: * amount mistyped * wrong asset selected in the wallet * wrong network selected in the wallet * consumer sends from an exchange flow that introduces delays or uses a different send pattern Bead’s payment tracking and statuses reflect whether the received transfer matches what was requested. #### Ways to reduce miskeys and friction Integrators can reduce issues by: * setting expectations in their own checkout flow before redirecting to the Bead hosted page, such as a short note that the consumer may need to enter the amount in their wallet * reminding the consumer to use the same asset and network selected on the payment screen * reminding the consumer to enter the exact amount shown on the payment screen * ensuring support teams understand common mismatch scenarios and the likely root causes * linking consumers to troubleshooting guidance when needed * for BTC Classic, giving the customer clear next-step messaging once payment is detected, so they understand that the transaction is underway even if final completion takes longer ### BTC Classic customer messaging For BTC Classic / Bitcoin on-chain payments, the customer may need more guidance than they would need for faster tender types. Recommended message when the customer selects BTC Classic: ``` BTC Classic uses Bitcoin on-chain payment confirmation. After you send the payment, it may take several minutes to complete. The merchant will confirm when the payment is complete. ``` Recommended message when the payment reaches `processing`: ``` 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. ``` Recommended message when fulfillment must wait: ``` Your payment is pending confirmation. The merchant will complete your order once the BTC payment is confirmed. ``` ### Roadmap note Because Bead owns the hosted crypto payment page experience end to end, we can evolve the experience over time without requiring changes from integrators. We are actively exploring improvements to minimize friction and improve consumer success, including: * clearer on-screen guidance and coaching for asset, network, and amount entry * UX enhancements that reduce common miskeys * technical enhancements that streamline scan-and-send behavior where supported by wallets and networks * improved messaging for longer-running payment flows such as BTC Classic This page will be updated as capabilities evolve. ### Common questions #### Will the consumer always enter the amount? Not always. It depends on the coin and network. For many on-chain assets and networks, yes. The consumer enters the amount in their wallet after scanning a destination address. This is expected behavior. Some rails, such as Bitcoin Lightning, commonly support a scannable format that can include the amount, which can allow the wallet to populate it automatically. #### Why does Bead show an amount if the QR code does not include it? Bead shows the intended amount so the consumer knows what to send. The transfer itself is still initiated and confirmed in the consumer’s wallet. #### What should I tell a consumer who is confused? Use simple guidance: * Scan the QR code * In your wallet, select the same asset and network * Enter the exact amount shown on screen * Send the transfer * Return to the merchant screen For most tenders, the consumer may see the final payment result shortly after sending. For BTC Classic / Bitcoin on-chain, the payment may be detected first and then remain in `processing` while the Bitcoin network confirms the transaction. In that case, tell the consumer that the payment is underway and that the merchant will confirm when it is complete. #### Why does BTC Classic stay processing after the consumer sends payment? BTC Classic uses Bitcoin on-chain payments. After the consumer sends BTC, the transaction may be detected before it reaches final completion. When the status is `processing`, Bead has detected the payment and the transaction is underway. The payment is not final until it reaches `completed`. For BTC Classic, integrators should show the customer that the payment has been detected, allow them to move on from the payment screen, and use Payment Webhooks or status checks to confirm final completion. Do not release goods, grant digital access, ship an order, or mark an invoice as paid until the payment reaches `completed`. #### Can the consumer close the page after sending BTC Classic? If the payment has reached `processing`, the transaction has been detected and is underway. In BTC Classic flows, it is generally reasonable to tell the customer they can move on, as long as your integration can track final completion through Payment Webhooks or payment status checks. The merchant should still wait for `completed` before fulfillment. #### Should I create a new payment if BTC Classic is still processing? No, not just because the payment is still `processing`. BTC Classic can remain in `processing` for several minutes or longer. Do not create a duplicate payment unless the original payment reaches a final unsuccessful state, expires, is canceled, or the customer intentionally starts over. ### Related pages * [Payment Statuses](/payments/payment-statuses.md) * [Payment Webhooks](/payments/payment-webhooks.md) * [Create Payment](/payments/create-payment.md) * [Why do BTC Classic payments take longer?](/faqs-and-troubleshooting/payments-faqs/why-do-btc-classic-payments-take-longer.md) * [Choosing Tender Types by Payment Environment](/reference-guide/payment-flows/choosing-tender-types-by-payment-environment.md) --- # Agent Instructions: 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: ``` GET https://developers.bead.xyz/payments/crypto-wallet-flow-and-amounts.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.