Test Crypto Payments

Crypto testing validates a crypto tender end to end: create payment, hosted checkout, on-chain transfer, and completion. Unlike Klarna, Venmo, and PayPal, Sandbox crypto payments run on live blockchain networks and require real assets plus a network fee token. Use this method only when a crypto tender is in scope for your integration.

For the recommended default test that needs no real assets, see Test with Klarna. For a comparison of all test methods, see Choosing a Test Method.

Sandbox crypto uses live networks

Bead Sandbox changes the API environment, merchant configuration, credentials, and hosted payment environment. It does not move crypto to blockchain testnets. Test payments settle on live networks with real assets.

• Test payments require real assets and real network fee tokens.

• Keep test amounts small.

• For USDC on Base and USDC on Solana, the minimum Bead payment amount is $1.00 USD. This is separate from any network fee the payer's wallet needs to submit the transaction.

1 – Prerequisites

Item	Notes
Sandbox base URL	https://api.test.devs.beadpay.io
Terminal API key	You need the real API key value. The masked API key is not usable.
merchantId and terminalId	Must match the terminal API key you were issued.
Funded wallet	A compatible wallet holding the real asset and the real network fee token for the tender you are testing.
Webhook endpoint (recommended)	Publicly reachable and registered in the Bead dashboard.

Authentication note: Payments endpoints use header based authentication. Send your API key as X-Api-Key on every request.

2 – Choose a test tender

For most initial tests, USDC on Base is recommended: low fees, fast confirmation, and wide wallet support. USDC on Solana is also a good choice, especially with Phantom, because Solana fees are typically very low. Once you have validated the hosted flow with USDC, you can extend testing to Bitcoin and Bitcoin Lightning if those tenders are enabled for your project.

Fee assets required per tender:

Payment token and network	Fee asset	Notes
USDC on Base	ETH on Base	Minimum Bead payment amount is $1.00 USD.
USDC on Solana	SOL on Solana	Minimum Bead payment amount is $1.00 USD. Wallet may need a small SOL balance as a network minimum.
Bitcoin on chain	BTC	Fees are deducted in BTC per transaction and vary with congestion. Keep extra BTC above the invoice amount.
Bitcoin Lightning	BTC in Lightning channels	Fees are handled by the Lightning network and wallet routing. Fund channels before testing.

Acquire only what you need for functional testing. As a rough guide, a few cents of the fee asset per transaction is often enough under typical conditions. Always review the fee estimate shown in your wallet before sending.

3 – Create Payment Request

Send a POST /Payments/crypto to generate the hosted checkout URL. For USDC on Base or USDC on Solana, use requestedAmount of 1.00 or higher.

Required headers:

• X-Api-Key: {apiKey}

• Content-Type: application/json

To target a specific crypto tender, include it in tenderTypes (for example, usdcBase).

Example request

curl -s -X POST "https://api.test.devs.beadpay.io/Payments/crypto" \
-H "X-Api-Key: {apiKey}" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"merchantId": "{merchantId}",
"terminalId": "{terminalId}",
"requestedAmount": 1.00,
"reference": "ORDER-0001",
"refundEmail": "[e-mail]",
"tenderTypes": ["usdcBase"]
}'

Example response:

{
"paymentId": "pay_c10b29e3c8104e0f8dc139c20d9eeb6c",
"trackingId": "c10b29e3c8104e0f8dc139c20d9eeb6c",
"paymentUrls": [
"https://pay.qa.beadpay.io/crypto?paymentPageId=a12b34c56d789e01"
]
}

Save these values:

• paymentId your primary lookup key for status checks, webhooks, reporting, and support

• paymentUrls[0] the hosted checkout URL to present to the customer

Providing refundEmail is recommended. If a payment is underpaid, overpaid, expired, or invalid, the crypto remains unconverted and is returned to the payer through the reclaim process, and Bead emails reclaim instructions to that address.

4 – Present the Hosted Payment Page

Open paymentUrls[0] for the payer. In a typical crypto wallet flow the payer:

1. Selects an asset, such as USDC or BTC.

2. Views a QR code or payment details.

3. Opens their wallet app and scans the QR code.

4. Manually enters the crypto amount in their wallet app.

5. Submits the transfer.

Because the wallet requires the payer to enter the amount manually, miskeyed amounts can result in underpaid or overpaid. The payer's wallet must hold the correct asset on the correct live network, plus the fee token (for example, USDC on Base for the amount and ETH on Base for fees).

5 – Verify Result

Option A: Webhook verification

Confirm your webhook endpoint receives a payment event indicating completion.

Option B: API status check (optional)

Endpoint: GET /Payments/{paymentId}/tracking

curl -s -X GET "https://api.test.devs.beadpay.io/Payments/{paymentId}/tracking" \
-H "X-Api-Key: {apiKey}" \
-H "Accept: application/json"

The payment status is returned in statusCode. Fulfill only when it reaches completed. Treat underpaid, overpaid, expired, invalid, and cancelled as not successful.

Common testing reminders

• Sandbox crypto payments use live networks, not testnets.

• Test payments require real assets and real network fee tokens. Keep amounts small.

• For USDC on Base and USDC on Solana, use requestedAmount of 1.00 or higher.

• Make sure the asset and network in the wallet match the asset and network shown on the hosted payment page.

• Do not send funds to a recently used address from your wallet history. Always scan or copy the address shown on the current Bead hosted payment page.

Related

• Choosing a Test Method

• Crypto Testing and Fees

• Compatible Crypto Wallets

• Under and Over Payment Handling

• Reclaiming Unconverted Crypto