> 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/faqs-and-troubleshooting/payments-faqs/troubleshooting-couldnt-create-payment-error.md).

# Troubleshooting "Couldn't Create Payment" Error

When you choose a cryptocurrency tender (e.g., Bitcoin, Ethereum, USDC) in **Sandbox**, the checkout performs two actions:

1. **Create the payment** in Bead's sandbox gateway.
2. **Generate a QR code** that the consumer scans with their crypto wallet to run a *test transaction* on the correct test-net or partner sandbox.

If step 1 fails the UI shows the *Couldn't Create Payment* dialog instead of the QR code.

<figure><img src="/files/Zzy2If4IpQV7SFwtrxtx" alt=""><figcaption></figcaption></figure>

#### Why it happens

| Cause                                                    | Where it originates       | Typical duration                      |
| -------------------------------------------------------- | ------------------------- | ------------------------------------- |
| Terminal missing `useSandboxSharedWallet: true`          | Bead terminal config      | Permanent until terminal is recreated |
| Test-net instability (e.g., Bitcoin Testnet)             | External blockchain nodes | Minutes to a few hours                |
| Third-party sandbox outage (processor / wallet provider) | External service          | Varies by provider                    |
| Config drift in our crypto sandbox gateway               | Bead Sandbox              | Rare; fixed quickly once detected     |

#### Recommended workflow

**1. Check terminal configuration first (USDC)**

If you are testing USDC tenders, confirm the terminal was created with `useSandboxSharedWallet: true`. This is a Sandbox-only setting required for USDC payment creation. It must be set at creation time — it cannot be added to an existing terminal via the edit endpoint.

To check: retrieve the terminal via `GET /Terminals/{id}` and look for `"useSandboxSharedWallet": true` in the response.

If the flag is missing, create a new terminal with it included:

```json
{
  "name": "My Virtual Terminal",
  "locationId": "<your-location-id>",
  "type": "virtual",
  "tenderTypes": ["usdcSolana", "usdcBase"],
  "useSandboxSharedWallet": true
}
```

Terminals created automatically from a boarding approval have this set by default. Only manually created terminals are at risk of missing it.

**2. Switch to a known-good tender**

Use another payment tender to confirm the issue is tender-specific rather than a broader environment problem.

**3. Retry later**

If the terminal is correctly configured and the issue persists, most blockchain test-nets recover on their own within minutes to a few hours.

**4. Let us know**

Send a support ticket with your `merchantId` and `terminalId`. We'll confirm if we also see downstream issues and post status updates.


---

# 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/faqs-and-troubleshooting/payments-faqs/troubleshooting-couldnt-create-payment-error.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.