Docs
Open Console

Troubleshooting

Fixes for the issues that actually come up, grouped by surface. When in doubt, reproduce with the API's test-connection call before contacting support.

Checkout problems#

No payment methods appear

  • Most often a stale session cookie - open the checkout in a private window to confirm, then clear the site's cookies
  • Crypto tiles need at least one receive address (or an exchange connection generating addresses) for that coin - check Settings → Addresses
  • Card tile needs Stripe (or 2Checkout) active with a valid key; the PayPal tile needs paypal-active and your PayPal email
  • Fiat rails are hidden on crypto-denominated checkouts by design

"Payment sent" but the checkout still waits

  • Confirmations take time by design - the checkout shows the live requirement per chain (base 3; higher for some chains)
  • Lightning payments should confirm instantly; if not, your node may have lost the invoice - check node connectivity in Settings → Nodes
  • Force a re-scan with the API's check-transactions or the refresh action on the transaction

Underpaid but nothing happened

Differences under 0.1% auto-complete; beyond that, the transaction is only accepted if accept-underpayments is on and the shortfall is under 5%. See Underpayments.

Webhook problems#

  • Nothing arrives: the URL must be HTTPS on a public host (private/loopback addresses are rejected at save time). Confirm the URL saved under Settings → Webhooks or on the store
  • Signature fails: you must verify against the raw request body, using the t=<unix>,v1=<hex> scheme - see Webhooks
  • Timeouts: your endpoint has 7 seconds total; acknowledge 200 and process in the background
  • Duplicates: deduplicate on event_id - re-deliveries are manual and intentional
  • Diagnose: the delivery log on each transaction shows the HTTP code and response body; test-connection sends a live signed test

Console problems#

  • Logged out unexpectedly: sessions idle out bank-style; an expired login stays logged out by design - sign in again
  • Settings won't save: processor and wallet settings require the matching role permission (see Roles & Permissions)
  • Stripe test key warning: the console flags a _test_ key with Stripe active - test keys belong on a test store, not live checkouts
  • Custom token rejected: token codes must be alphanumeric (no underscores or symbols) - see Custom Tokens

API problems#

  • 401 invalid-api-key: send the key in the X-Api-Key header; confirm you are using the API key (server secret), not the Cloud Token, for authenticated calls
  • Unexpected JSON: responses are always {success:true,response} or {success:false,error_code,message} - branch on error_code, never on message text
  • Buyer checkout creation rejected: public creation with a Cloud Token is fee-gated on cloud accounts - a zero platform credit balance blocks new checkouts

Still stuck?#

Open a ticket from the console (Help → Support) with the transaction id or checkout URL and what you expected - tickets land with your account context attached. For platform status, see status.u.cash.