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 (on-chain) refers to Bitcoin on-chain payments. BTC (on-chain) is different from Bitcoin Lightning. BTC (on-chain) may take several minutes or longer to reach final completion because the payment depends on Bitcoin network confirmation.
For BTC (on-chain), 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 (on-chain) / 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 (on-chain), 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 fundsprocessing— funds have been detected and the payment is underway, but not finalcompleted— 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 (on-chain) / 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 (on-chain) / Bitcoin on-chain example
BTC (on-chain) 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 (on-chain), 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 (on-chain) / Bitcoin on-chain, final completion may take several minutes or longer after the transfer is detected
processingmeans the payment is underway, but not finalthe merchant should fulfill only after the payment reaches
completedfor BTC (on-chain), the customer can usually move to an order, invoice, receipt, or status screen after the payment is detected
If your integration supports BTC (on-chain), 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 (on-chain), 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 (on-chain) customer messaging
For BTC (on-chain) / 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 (on-chain):
Recommended message when the payment reaches processing:
Recommended message when fulfillment must wait:
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 (on-chain)
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 (on-chain) / 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 (on-chain) stay processing after the consumer sends payment?
BTC (on-chain) 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 (on-chain), 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 (on-chain)?
If the payment has reached processing, the transaction has been detected and is underway. In BTC (on-chain) 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 (on-chain) is still processing?
No, not just because the payment is still processing.
BTC (on-chain) 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
Last updated