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.

USDC tenders currently operate only on live networks in both Sandbox and Production. This means all USDC testing uses real USDC and real fee tokens, and test amounts should remain small.

Environments and networks

The table below summarizes how crypto tender types map to environments and networks at a high level. Exact network settings for your project will be confirmed during onboarding.

Tender and network overview

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.
USDC on Solana	USDC on Solana mainnet, fees in SOL	Sandbox and Production both use Solana mainnet. Testing requires real USDC and SOL.
Bitcoin on chain	BTC on Bitcoin network	Network usage is configured per project. You must know whether your Sandbox is using mainnet with small test amounts or a test network for pilot work.
Bitcoin Lightning	BTC routed through Lightning channels	Network usage and Lightning environment are configured per project. You must know whether your Sandbox uses Lightning on mainnet or a dedicated test environment.

If you are unsure which network or Lightning environment your Sandbox is using for Bitcoin based tenders, 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.

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 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 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 USDC testing uses 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 most functional tests, small amounts such as a few dollars equivalent in USDC are sufficient.

• Run a few tiny 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.

• Functional tests can usually be run with very 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 addresses.

• For Lightning, acquire BTC in a Lightning capable wallet that can pay Lightning invoices.

• Keep test amounts small until you have confirmed your environment configuration and payment status handling, especially if your Sandbox uses mainnet.

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.

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.

Symptoms and likely causes

Symptom	Likely cause	What to check first
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 type of Lightning invoice or network used	Confirm that the wallet supports Lightning invoices and that the wallet is on the correct Lightning environment for your project.
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, and location 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.

• For a current matrix of supported assets, networks, and example wallets, see Compatible Crypto Wallets.

• For step by step functional testing of specific flows, including the hosted payment page, see Test Crypto Transactions in the Payments section.