Logo

Office Address

123/A, Miranda City Likaoli
Prikano, Dope

Phone Number

+0989 7876 9865 9

+(090) 8765 86543 85

Email Address

info@example.com

example.mail@hum.com

HomeDocumentationHelp & Support

Help & Support

Troubleshooting guides and support resources

Troubleshooting Guide

Diagnose and resolve common issues with your BitPrimax integration. Find solutions to the most frequent problems merchants encounter.

Quick Diagnosis

Use this quick checklist to identify the most common issues:

Check These First:

  • Are you using the correct API keys?
  • Is your webhook URL accessible?
  • Is your app active in the dashboard?
  • Are you making too many concurrent requests?

Common Error Types:

  • 401 Unauthorized
  • Webhook delivery failures
  • Payment creation errors
  • Rate limit exceeded

Authentication Issues

Error: 401 Unauthorized

This error occurs when your API keys are invalid or missing.

Solution: Check your API key configuration and ensure you're using the correct keys for your environment.

API Key Configurationjavascript
// Check your API key format
const apiKey = 'sk_test_...'; // Test environment
const apiKey = 'sk_live_...'; // Production environment

// Ensure proper authorization header
headers: {
  'Authorization': `Bearer ${apiKey}`,
  'Content-Type': 'application/json'
}

Error: Invalid API Key

Your API key format is correct but the key itself is invalid.

Solution: Regenerate your API keys in the merchant dashboard and update your application configuration.

Webhook Issues

Webhooks Not Being Received

Your webhook endpoint is not receiving payment notifications.

Check These:
  • • Is your webhook URL publicly accessible?
  • • Is your server responding with 200 status code?
  • • Are you using HTTPS in production?
  • • Is your webhook secret configured correctly?
Webhook Handler Examplejavascript
// Example webhook endpoint
app.post('/webhooks/bitprimax', (req, res) => {
  try {
    const signature = req.headers['x-bitprimax-signature'];
    const payload = req.body;
    
    // Verify webhook signature
    if (!verifyWebhookSignature(payload, signature, webhookSecret)) {
      console.error('Invalid webhook signature');
      return res.status(400).send('Invalid signature');
    }
    
    // Process webhook
    console.log('Payment status:', payload.status);
    
    // Always respond with 200
    res.status(200).send('OK');
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(500).send('Internal error');
  }
});

Webhook Signature Verification Failing

Your webhook signature verification is failing.

Solution: Ensure you're using the correct webhook secret from your app dashboard and implementing proper signature verification.

Payment Issues

Payment Creation Fails

You're unable to create new payments.

Common Causes:
  • • Invalid amount format (use string, not number)
  • • Unsupported currency or network
  • • Missing required fields
  • • App is inactive or suspended
Correct Payment Creationjavascript
// Correct payment creation
const paymentData = {
  amount: "100.50", // String format
  currency: "USDT",
  network: "BEP-20",
  description: "Payment for order #123",
  customerEmail: "customer@example.com",
  // Optional fields
  metadata: {
    orderId: "123",
    customerId: "456"
  }
};

const response = await fetch('https://api.bitprimax.com/v1/payments', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(paymentData)
});

Payment Status Not Updating

Payment status remains pending or doesn't update.

Solution: Check your webhook implementation and ensure you're properly handling status updates. You can also poll the payment status manually.

Network & Connectivity Issues

API Timeout Errors

API requests are timing out or taking too long to respond.

Solution: Implement proper timeout handling and retry logic in your application.

Retry Logic Examplejavascript
// Implement retry logic
async function createPaymentWithRetry(paymentData, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch('https://api.bitprimax.com/v1/payments', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${apiKey}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(paymentData),
        timeout: 10000 // 10 second timeout
      });
      
      if (response.ok) {
        return await response.json();
      }
    } catch (error) {
      if (attempt === maxRetries) {
        throw error;
      }
      // Wait before retrying
      await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
    }
  }
}

Rate Limit Exceeded

You're hitting API rate limits.

Solution: Implement exponential backoff and respect rate limits. Check the Rate Limits section for current limits.

Debugging Tools

Dashboard Tools:

  • Transaction logs and history
  • Webhook delivery status
  • API key management
  • Network status monitoring

Testing Tools:

  • Test token faucet
  • Webhook testing endpoints
  • API response validation
  • Error code reference

Still stuck? Get personalized help from our support team.