Troubleshooting Guide

🔴 Payment Not Detected

Symptoms: Customer says they sent payment, but it doesn't appear in your dashboard.

Common Causes:

• Transaction hasn't received confirmations yet (normal for new transactions)
• Wrong amount sent (underpayment by more than 1%)
• Payment sent to wrong address (customer error)
• Network congestion delaying confirmation

Solutions:

1. Check transaction on blockchain explorer:
   • Bitcoin: blockchair.com/bitcoin
   • Ethereum: etherscan.io
   • Litecoin: blockchair.com/litecoin
2. Verify the destination address matches what's shown in your CryptoGate payment request
3. Wait for confirmations: Most issues resolve once the transaction receives 1-2 confirmations
4. If transaction is confirmed but still not showing: Contact support with the transaction ID

⚠️ Payment Stuck in "Pending"

Symptoms: Payment shows as "Pending" for longer than expected.

Common Causes:

• Low transaction fee causing slow confirmation
• Network congestion (especially Bitcoin during high-volume periods)
• Required confirmation count not yet reached

Solutions:

1. Check confirmation count: Go to transaction details in dashboard
2. Expected confirmation times:
   • BTC: 2-6 confirmations (20-60 minutes)
   • ETH: 12-35 confirmations (2-7 minutes)
   • LTC/DASH: 4-6 confirmations (10-15 minutes)
3. If stuck for hours: Transaction may have insufficient fee. Customer can try RBF (Replace-By-Fee) or CPFP (Child-Pays-For-Parent) if wallet supports it
4. For merchants: You can manually approve low-value transactions with 1 confirmation if you accept the risk

❌ Payment Marked as "Underpaid"

Symptoms: Transaction received but marked as underpaid, status stuck.

Common Causes:

• Customer's wallet didn't account for network fees
• Customer manually typed amount instead of scanning QR code
• Currency conversion rate changed between invoice creation and payment

Solutions:

1. Check underpayment amount: Dashboard shows exact shortfall
2. If shortfall is < 1%: You can manually approve the transaction
3. If significant underpayment: Options:
   • Request additional payment from customer (generate new invoice for difference)
   • Accept partial payment and adjust order
   • Refund transaction
4. Prevent future issues: Emphasize to customers to scan QR code or copy exact amount

⏰ Payment Expired

Symptoms: Payment window closed before customer completed transaction.

Common Causes:

• Default 15-minute expiration too short for customer
• Customer inexperienced with cryptocurrency wallets
• Network congestion causing delays

Solutions:

1. Generate new payment request with same or extended expiration time
2. Increase default expiration: Dashboard → Settings → Payment Settings → Expiration Time (max 24 hours)
3. If customer already sent to expired address: Payment may still be detected and credited (contact support to verify)
4. For high-value transactions: Use longer expiration (60+ minutes) to reduce pressure on customers

🔌 Plugin Not Connecting to CryptoGate

Symptoms: E-commerce plugin (WooCommerce, Shopify) shows connection errors.

Common Causes:

• Incorrect API key or secret
• Test mode API key used in production (or vice versa)
• Server firewall blocking outbound connections to CryptoGate
• Plugin not updated to latest version

Solutions:

1. Verify API credentials:
   • Dashboard → Developers → API Keys
   • Ensure you're using the correct environment (Test vs Live)
   • API key should start with cgk_live_ or cgk_test_
2. Test connection manually:
   curl -X GET "https://api.cryptogate.live/v1/ping" \ -H "Authorization: Bearer YOUR_API_KEY" // Expected response: {"status":"ok"}
3. Check server requirements:
   • PHP 7.4+ (for PHP-based plugins)
   • cURL or file_get_contents enabled
   • Outbound HTTPS connections allowed
4. Update plugin: Ensure you're running the latest version
5. Check error logs: Most plugins log errors to wp-content/debug.log (WordPress) or similar

🔒 CORS Errors (Cross-Origin Request Blocked)

Symptoms: Browser console shows CORS policy errors when making API requests.

Common Causes:

• Making API requests directly from frontend JavaScript (not allowed)
• Domain not whitelisted in API settings

Solutions:

1. API requests must come from your backend server, not directly from browser JavaScript
2. Correct architecture:
   • ❌ Browser → CryptoGate API (causes CORS error)
   • ✅ Browser → Your Server → CryptoGate API
3. If you need frontend requests: Use our JavaScript SDK which handles proxying automatically:
   // Install SDK npm install @cryptogate/sdk // Initialize with public key only (safe for frontend) import CryptoGate from '@cryptogate/sdk'; const cg = new CryptoGate({ publicKey: 'cgk_pub_...', // Public key, not secret key! mode: 'test' });
4. Never expose your API secret key in frontend code!

📦 SDK Installation Failures

Symptoms: npm install, composer install, or pip install fails.

Solutions by platform:

JavaScript/Node.js:

PHP:

Python:

401 Unauthorized

Error message: {"error": "Invalid API key"}

Common Causes:

• API key incorrect or expired
• Using test key in production environment
• Missing Authorization header
• Incorrect header format

Solutions:

1. Verify API key format:
   // Correct format Authorization: Bearer cgk_live_1234567890abcdef... // ❌ Wrong: Missing "Bearer" Authorization: cgk_live_1234567890abcdef... // ❌ Wrong: Extra spaces Authorization: Bearer cgk_live_1234567890abcdef...
2. Regenerate API key: Dashboard → Developers → API Keys → Regenerate
3. Check environment: Ensure cgk_test_ keys go to test API, cgk_live_ to production

429 Too Many Requests

Error message: {"error": "Rate limit exceeded"}

Rate Limits:

Solutions:

1. Implement exponential backoff:
   async function requestWithRetry(url, options, maxRetries = 3) { for (let i = 0; i < maxRetries; i++) { const response = await fetch(url, options); if (response.status === 429) { const retryAfter = response.headers.get('Retry-After') || (2 ** i); await new Promise(resolve => setTimeout(resolve, retryAfter * 1000)); continue; } return response; } throw new Error('Max retries exceeded'); }
2. Cache responses: Don't repeatedly fetch same data
3. Use webhooks instead of polling: Get notified when events happen rather than checking repeatedly
4. Contact support for higher limits if you have legitimate high-volume needs

422 Unprocessable Entity

Error message: {"error": "Validation failed", "details": {...}}

Common Causes:

• Missing required fields
• Invalid field format (e.g., invalid email, negative amount)
• Field value out of allowed range

Solutions:

1. Check error details: The details field tells you exactly what's wrong
2. Common validation errors:
   • amount: Must be positive number, max 2 decimal places
   • currency: Must be one of: BTC, ETH, LTC, DASH, DOGE
   • email: Must be valid email format
   • webhook_url: Must be valid HTTPS URL
3. Validate data before sending:
   // Example validation const paymentData = { amount: parseFloat(amount).toFixed(2), // Ensure 2 decimals currency: currency.toUpperCase(), // Ensure uppercase email: email.trim().toLowerCase() // Normalize email };

500 Internal Server Error

Error message: {"error": "Internal server error"}

This indicates a problem on our end.

Solutions:

1. Check status page: status.cryptogate.live for ongoing incidents
2. Retry with exponential backoff: Temporary issues usually resolve within seconds
3. If persisting: Contact support with:
   • Request ID (from X-Request-ID header)
   • Timestamp
   • Endpoint URL
   • Request payload (sanitized)

📡 Webhooks Not Received

Symptoms: Payment completed but your server never received webhook notification.

Common Causes:

• Webhook URL not configured
• Server firewall blocking incoming requests
• HTTPS certificate errors on your server
• Your endpoint returning non-200 status code

Solutions:

1. Verify webhook URL: Dashboard → Developers → Webhooks
2. Test webhook endpoint:
   curl -X POST https://yourdomain.com/webhooks/cryptogate \ -H "Content-Type: application/json" \ -d '{"event":"test","data":{}}' // Should return HTTP 200
3. Check webhook logs: Dashboard shows delivery attempts and responses
4. Common issues:
   • Endpoint must be HTTPS (not HTTP)
   • Must have valid SSL certificate
   • Must respond within 30 seconds
   • Must return 2xx status code (200, 201, 204)
5. Test with webhook.site: Use webhook.site temporarily to verify CryptoGate is sending webhooks

🔐 Webhook Signature Verification Failing

Symptoms: Receiving webhooks but signature validation fails.

Common Causes:

• Using wrong webhook secret
• Modifying request body before verification
• Incorrect signature calculation

Solutions:

1. Correct verification process:
   // Node.js example const crypto = require('crypto'); function verifyWebhook(payload, signature, secret) { const hash = crypto .createHmac('sha256', secret) .update(payload) // Raw body, not parsed JSON! .digest('hex'); return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(hash) ); } // Express.js middleware app.post('/webhooks', express.raw({type: 'application/json'}), (req, res) => { const signature = req.headers['x-cryptogate-signature']; const payload = req.body.toString('utf8'); if (verifyWebhook(payload, signature, WEBHOOK_SECRET)) { const data = JSON.parse(payload); // Process webhook... res.sendStatus(200); } else { res.sendStatus(401); } });
2. Get webhook secret: Dashboard → Developers → Webhooks → Show Secret
3. Common mistakes:
   • ❌ Using API key instead of webhook secret
   • ❌ Parsing JSON before verification
   • ❌ Using SHA1 instead of SHA256
   • ❌ Not using timing-safe comparison

🔄 Webhook Retries Exhausted

Symptoms: Dashboard shows webhook delivery failed after all retries.

Retry Schedule:

• Attempt 1: Immediate
• Attempt 2: +1 minute
• Attempt 3: +5 minutes
• Attempt 4: +15 minutes
• Attempt 5-10: +1 hour each

Solutions:

1. Fix your endpoint issues (see above)
2. Manual replay: Dashboard → Webhooks → Select event → Replay
3. Fetch missed events via API:
   // Get recent events GET /v1/events?since=2024-01-01T00:00:00Z // Process events your webhook handler missed
4. Implement idempotency: Handle duplicate webhooks gracefully (we send idempotency keys)

🔑 Can't Log In

Common Causes:

• Incorrect password
• 2FA code expired or wrong
• Account locked due to failed login attempts
• Email not verified

Solutions:

1. Reset password: Click "Forgot Password" on login page
2. 2FA issues:
   • Ensure device clock is synchronized (TOTP requires accurate time)
   • Try backup codes if authenticator app not working
   • Contact support if you've lost both authenticator and backup codes
3. Account locked: Wait 30 minutes or contact support
4. Email not verified: Check spam folder for verification email, or request new one

📧 Not Receiving Emails

Symptoms: Not receiving verification, password reset, or notification emails.

Solutions:

1. Check spam/junk folder
2. Add to safe senders: [email protected] and [email protected]
3. Verify email address: Dashboard → Account Settings → Email
4. Try different email provider: Some providers aggressively filter crypto-related emails
5. Check email logs: Dashboard → Settings → Email Logs (shows delivery status)

💰 "Invalid Address" Error

Symptoms: Can't save wallet address in dashboard.

Common Causes:

• Address format doesn't match cryptocurrency (e.g., BTC address for ETH)
• Typo in address
• Using testnet address in production
• Address contains invalid characters

Solutions:

1. Verify address format:
   • Bitcoin: Starts with 1, 3, or bc1 (39-42 characters)
   • Ethereum: Starts with 0x (42 characters)
   • Litecoin: Starts with L or M (34-43 characters)
   • Dash: Starts with X (34 characters)
   • Dogecoin: Starts with D (34 characters)
2. Copy address directly from your wallet - don't type manually
3. Verify checksum: Use address validation tools to ensure it's valid
4. No spaces or line breaks at start/end of address

🔒 Can't Change Wallet Address

Symptoms: Dashboard won't let you update wallet address.

Common Causes:

• 2FA not enabled (required for wallet changes)
• Recent address change (24-hour cooldown period)
• Pending transactions using current address

Solutions:

1. Enable 2FA: Dashboard → Security → Two-Factor Authentication
2. Wait for cooldown period: Security feature to prevent unauthorized changes
3. Wait for pending transactions to complete
4. If urgent: Contact support with verification documents

⚡ High Network Fees

Symptoms: Customers complaining about high transaction fees.

This is normal during network congestion. Fees are set by blockchain networks, not CryptoGate.

Solutions:

1. Use faster, cheaper coins: Litecoin and Dash typically have lower fees than Bitcoin
2. For Bitcoin:
   • Use SegWit addresses (start with bc1) for ~30% lower fees
   • Batch transactions when possible
   • Accept payments during low-traffic periods (weekends often cheaper)
3. Check current fee rates: mempool.space (Bitcoin)
4. Offer fee estimation: Our API provides fee estimates for different confirmation speeds