> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/testing/test-crypto-payments.md).

# 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](/testing/test-with-klarna-recommended.md). For a comparison of all test methods, see [Choosing a Test Method](/testing.md).

### 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**

```bash
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": "customer@example.com",
"tenderTypes": ["usdcBase"]
}'
```

Example response:

```json
{
"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`

```bash
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](/testing.md)
* [Crypto Testing and Fees](/faqs-and-troubleshooting/payments-faqs/crypto-testing-and-fees.md)
* [Compatible Crypto Wallets](/reference-guide/operational-guides/compatible-crypto-wallets.md)
* [Under and Over Payment Handling](/reference-guide/payment-scenarios/under-and-over-payment-handling.md)
* [Reclaiming Unconverted Crypto](/reference-guide/payment-scenarios/reclaiming-unconverted-crypto.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://developers.bead.xyz/testing/test-crypto-payments.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.