# Crypto payments, environment and testing This page explains how to test crypto payments with Bead, with a focus on environments, networks, funding test wallets, and common issues you may see when running end-to-end flows. It is written for integrators and internal testers, not for end customers. Bead Sandbox crypto payments use live blockchain networks. This means Sandbox crypto testing uses real crypto assets and real network fee tokens, and test amounts should remain small. For USDC on Base and USDC on Solana, the minimum Bead payment amount is $1.00 USD. This minimum is separate from any live-network fee the payer’s wallet may require to submit the transaction. **Environments and networks** The table below summarizes how crypto tender types map to environments and networks at a high level. Project configuration determines which tenders are enabled for a merchant, location, or terminal, but Sandbox crypto payment testing still uses live networks. | Tender type | Asset and network | Environment expectation | | ----------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | USDC on Base | USDC on Base mainnet, fees in ETH | Sandbox and Production both use Base mainnet. Testing requires real USDC and ETH on Base. Minimum Bead payment amount is $1.00 USD. | | USDC on Solana | USDC on Solana mainnet, fees in SOL | Sandbox and Production both use Solana mainnet. Testing requires real USDC and SOL. Minimum Bead payment amount is $1.00 USD. | | Bitcoin on chain | BTC on the Bitcoin network | Sandbox and Production both use the live Bitcoin network. Testing requires real BTC. | | Bitcoin Lightning | BTC routed through Lightning channels | Sandbox and Production both use the live Lightning network. Testing requires a Lightning-capable wallet funded with real BTC. | > If you are unsure which crypto tenders are enabled for your Sandbox merchant, location, or terminal, confirm with your Bead contact before funding wallets. **Test prerequisites** Before running crypto tests in any environment, confirm the following. **Merchant and tender configuration** * The partner and merchant you are testing have the expected crypto tenders enabled, for example USDC Base and USDC Solana. * Any rate or fee configuration required for those tenders is present. * Your test application is using the correct API credentials for Sandbox versus Production. * The hosted payment page URL you are using matches the environment of your API calls. * If testing USDC on Base or USDC on Solana, your payment amount is at least $1.00 USD. **Wallets and balances** * You have a compatible self-custody wallet for each tender you plan to test. * For USDC on Solana, Phantom is the recommended default. * For USDC on Base, Phantom, Base Wallet, MetaMask, or Trust Wallet are common choices. * You have funded the wallet with both the payment asset and the fee asset on the correct live network. * For USDC on Base, hold USDC on Base and ETH on Base. * For USDC on Solana, hold USDC on Solana and SOL. * For Bitcoin on chain, hold BTC in a wallet that can send to external Bitcoin addresses. * For Bitcoin Lightning, hold BTC in a Lightning-capable wallet that can pay Lightning invoices. * For Bitcoin and Lightning tests, you have a wallet that can send to external addresses or Lightning invoices, not only internal transfers. > For guidance on setting up Phantom for USDC payments, see Test Crypto Transactions. **Preparing test funds** Because Sandbox crypto payments use live networks, you should treat test balances as real value and keep amounts small. **USDC on Base** * Acquire a small amount of USDC on Base. * Acquire a small amount of ETH on Base to cover network fees. * For USDC on Base, the minimum Bead payment amount is $1.00 USD. * For most functional tests, small amounts such as a few dollars equivalent in USDC are sufficient. * Run a few small payments first, then increase only if you need to validate higher ticket flows. **USDC on Solana** * Acquire a small amount of USDC on Solana mainnet. * Acquire a small amount of SOL for network fees. * For USDC on Solana, the minimum Bead payment amount is $1.00 USD. * Functional tests can usually be run with small USDC amounts due to low fee overhead on Solana. **Bitcoin and Lightning** * For Bitcoin on chain, acquire BTC in a wallet that can send to external Bitcoin addresses. * For Lightning, acquire BTC in a Lightning-capable wallet that can pay Lightning invoices. * Keep test amounts small until you have confirmed your merchant configuration and payment status handling. Bead does not provide on-ramp or exchange services. Funding paths are handled by wallets and exchanges. From Bead’s perspective, funds become visible only when they are sent to the address or invoice generated for a specific payment. **Running a basic end-to-end crypto test** The high-level steps for a typical crypto payment test are the same across tenders. 1. Create a payment through the Payments API for a supported crypto tender in your target environment. * For USDC on Base and USDC on Solana, create a payment of at least $1.00 USD. * For Bitcoin and Bitcoin Lightning, use a small live-network BTC amount appropriate for your test. 2. Redirect your test client application or browser to the hosted payment page URL returned by Bead. 3. On the hosted payment page, select the crypto tender you want to test, for example USDC on Base or USDC on Solana. 4. The page will show the requested asset, network, amount, and a QR code. 5. In your wallet, select the same asset and network that the hosted payment page shows, scan the QR, and confirm the send. 6. In your backend or tooling, monitor the payment status through the Payment API, webhooks, or portal views until you see the expected terminal status such as Complete, Underpaid, or Expired. For detailed payment creation and status semantics, refer to the core Payments documentation. This page focuses on environment and test setup. **Common testing issues and checks** The table below lists common issues you may encounter in crypto testing and the first checks to perform. | Symptom | Likely cause | What to check first | | -------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | API returns a validation error for a small USDC payment | Payment amount is below the USDC minimum | For USDC on Base and USDC on Solana, confirm the requested amount is at least $1.00 USD. | | Wallet shows an insufficient network fee or gas-related error | Wallet has payment asset but not enough fee asset | Confirm ETH on Base for USDC Base, or SOL on Solana for USDC Solana. Confirm balances are on the same network as the hosted page. | | Hosted page shows USDC on Base, wallet only shows USDC on Solana | Asset exists in wallet but on a different network | In the wallet, look for network selection and switch to Base. Confirm that USDC on Base is visible before scanning. | | Hosted page shows USDC on Solana, wallet only shows USDC on Base | Same as above, network mismatch in the opposite direction | Switch network in wallet to Solana, confirm that USDC on Solana is visible. | | Customer tries to pay from an exchange account | Exchange interface cannot behave like a real-time checkout wallet | Confirm whether the user is in an exchange app or a self-custody wallet. If they are in an exchange, move funds to a wallet first, then retry. | | Payment remains in a pending or processing state longer than expected | Network congestion, underpayment, or funds sent on a different network | Check the payment status details through the API or portal. Confirm the transaction hash on block explorers matches the expected network and amount. | | Payment appears as Underpaid or Overpaid | Sent amount does not match invoice amount | Compare the requested amount on the hosted page with the amount actually sent. Verify that the wallet did not adjust the send amount due to a max or slider control. | | Lightning payment fails immediately in the wallet | Wallet does not support the Lightning invoice or cannot route the payment | Confirm that the wallet supports Lightning invoices, has sufficient BTC balance, and can route live Lightning payments. | | API returns that the tender is not available for this merchant or location | Merchant or configuration does not have the tender enabled | Check partner, merchant, location, and terminal configuration for the expected tender keys. Confirm you are calling the correct environment. | If these checks do not resolve the issue, capture: * The environment you are using, Sandbox or Production. * The tender type and network. * The wallet and version. * The payment identifier, and any transaction hash reported by the wallet. Then escalate internally or to Bead Support with these details. **How this page relates to other documentation** * For an overview of how wallets, fees, and networks work in general, see [Crypto and Wallet Concepts for Integrators](/reference-guide/core-concepts/crypto-and-wallet-concepts-for-integrators.md). * For a current matrix of supported assets, networks, and example wallets, see [Compatible Crypto Wallets](/reference-guide/operational-guides/compatible-crypto-wallets.md). * For step-by-step functional testing of specific flows, including the hosted payment page, see [Test Crypto Transactions](/payments/test-crypto-transactions.md) in the [Payments](/payments.md) section. --- # 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/faqs-and-troubleshooting/environment-and-testing/crypto-payments-environment-and-testing.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.