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.

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:

{
  "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.