Troubleshooting Guide

This guide helps you diagnose and resolve common issues with Moneybag integration.

Quick Diagnostics Checklist

Before diving into specific issues, run through this checklist:

Authentication Issues

Error: 401 Unauthorized

Symptoms:

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Solutions:

1. Verify API Key Format

   # Correct header format
   X-Merchant-API-Key: YOUR_API_KEY
   
   # Common mistakes
   Authorization: Bearer YOUR_API_KEY  # Wrong!
   API-Key: YOUR_API_KEY               # Wrong!

2. Check Environment Mismatch

   • Sandbox key with production URL → Will fail
   • Production key with sandbox URL → Will fail

   // Correct matching
   const API_KEY = process.env.SANDBOX_API_KEY;
   const API_URL = 'https://sandbox.api.moneybag.com.bd';

3. Verify Key Status

   • Log into dashboard
   • Check if key is active
   • Regenerate if necessary

Error: 403 Forbidden

Symptoms:

{
  "error": "Forbidden",
  "message": "IP not whitelisted"
}

Solutions:

• Add your server IP to whitelist in dashboard
• Check if using proxy/CDN (use origin IP)
• Verify IP hasn't changed (dynamic IP issues)

Payment Processing Issues

Payment Page Not Loading

Debug Steps:

1. Check Browser Console

   // Open browser console (F12)
   // Look for errors like:
   // - CORS errors
   // - Mixed content warnings
   // - JavaScript errors

2. Verify Domain Whitelist

   • Dashboard → Settings → Allowed Domains
   • Add your domain (without https://)
   • Include both www and non-www versions

3. Check Required Parameters

   // Minimum required fields
   {
     "order_id": "unique_order_123",
     "order_amount": 100.00,
     "currency": "BDT",
     "success_url": "https://yoursite.com/success",
     "cancel_url": "https://yoursite.com/cancel",
     "fail_url": "https://yoursite.com/fail"
   }

Payment Stuck in Processing

Common Causes:

1. Webhook Not Responding

   • Your webhook must return HTTP 200
   • Check server logs for incoming webhooks
   • Verify webhook URL is correct

2. Network Timeout

   // Increase timeout for payment verification
   $client = new Client([
     'timeout' => 30, // 30 seconds
     'connect_timeout' => 10
   ]);

3. Session Expired

   • Payment sessions expire after 30 minutes
   • Implement session refresh logic

Webhook Issues

Webhooks Not Received

Diagnostic Steps:

1. Test Webhook Endpoint

   # Test your webhook endpoint directly
   curl -X POST https://yoursite.com/webhook \
     -H "Content-Type: application/json" \
     -d '{"test": "data"}'

2. Check Firewall/Security

   • Whitelist Moneybag IPs: 103.XXX.XXX.XXX/24
   • Disable rate limiting for webhook endpoint
   • Check WAF rules (Cloudflare, etc.)

3. Verify URL Format

   ✓ https://yoursite.com/webhook
   ✗ http://yoursite.com/webhook (no HTTPS)
   ✗ https://localhost/webhook (not public)
   ✗ https://192.168.1.1/webhook (private IP)

Webhook Signature Verification Failing

Debug Code:

function verifyWebhookSignature($payload, $signature, $secret) {
    // Common mistake: using wrong encoding
    $calculated = hash_hmac('sha256', $payload, $secret);
    
    // Debug output
    error_log("Received signature: " . $signature);
    error_log("Calculated signature: " . $calculated);
    error_log("Payload: " . $payload);
    
    return hash_equals($calculated, $signature);
}

Common Issues:

• Using wrong secret key
• Modifying payload before verification
• Encoding/decoding issues
• Time sync problems

API Response Errors

Error: 400 Bad Request

Common Causes:

1. Invalid JSON

   // Wrong - trailing comma
   {
     "amount": 100,
   }
   
   // Correct
   {
     "amount": 100
   }

2. Missing Required Fields Check API documentation for required fields per endpoint

3. Invalid Field Values

   // Common validation errors
   {
     "amount": "100",      // Should be number, not string
     "email": "invalid",   // Invalid email format
     "phone": "123",       // Invalid phone format
   }

Error: 422 Unprocessable Entity

Symptoms:

{
  "error": "Validation failed",
  "details": {
    "amount": ["Amount must be greater than 10"],
    "currency": ["Invalid currency code"]
  }
}

Solutions:

• Check field validation rules
• Verify data types (string vs number)
• Check min/max limits

Error: 500 Internal Server Error

What to do:

1. Retry with exponential backoff
2. Check status.moneybag.com.bd
3. Contact support with request ID

Testing Issues

Test Transactions Not Working

Sandbox Environment Checks:

1. Using Test Credentials

   // Sandbox test card
   const testCard = {
     number: "4111111111111111",
     exp_month: 12,
     exp_year: 2025,
     cvv: "123"
   };

2. Test Amount Triggers

   100.00 → Success
   200.00 → Insufficient funds
   300.00 → Card declined
   400.00 → Network error

3. Reset Test Data

   • Sandbox data resets weekly
   • Clear browser cache/cookies
   • Try incognito mode

Performance Issues

Slow API Response

Optimization Tips:

1. Implement Caching

   // Cache verification responses
   const cache = new Map();
   
   async function verifyPayment(transactionId) {
     if (cache.has(transactionId)) {
       return cache.get(transactionId);
     }
     
     const result = await api.verifyPayment(transactionId);
     cache.set(transactionId, result);
     return result;
   }

2. Use Connection Pooling

   // Reuse HTTP connections
   const agent = new https.Agent({
     keepAlive: true,
     maxSockets: 10
   });

3. Implement Retry Logic

   async function apiCallWithRetry(fn, maxRetries = 3) {
     for (let i = 0; i < maxRetries; i++) {
       try {
         return await fn();
       } catch (error) {
         if (i === maxRetries - 1) throw error;
         await sleep(Math.pow(2, i) * 1000); // Exponential backoff
       }
     }
   }

Mobile SDK Issues

iOS Integration Problems

Common Issues:

• Info.plist not updated with required permissions
• ATS (App Transport Security) blocking HTTP
• Certificate pinning issues

Solutions:

<!-- Info.plist -->
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSExceptionDomains</key>
    <dict>
        <key>moneybag.com.bd</key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <false/>
            <key>NSIncludesSubdomains</key>
            <true/>
        </dict>
    </dict>
</dict>

Android Integration Problems

Common Issues:

• ProGuard obfuscating SDK classes
• Network security config issues
• Missing permissions

Solutions:

// ProGuard rules (add to proguard-rules.pro)
-keep class com.moneybag.** { *; }
-keepclassmembers class com.moneybag.** { *; }

Debug Tools & Commands

cURL Debug Commands

# Test API connectivity
curl -I https://api.moneybag.com.bd/health

# Verbose output for debugging
curl -v -X POST https://sandbox.api.moneybag.com.bd/api/v2/payments/checkout \
  -H "X-Merchant-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d @payment.json

# Test webhook endpoint
curl -X POST https://yoursite.com/webhook \
  -H "X-Webhook-Signature: test_signature" \
  -d '{"event":"payment.success","data":{}}'

Browser Console Commands

// Check if API is reachable
fetch('https://api.moneybag.com.bd/health')
  .then(r => console.log('API Status:', r.status))
  .catch(e => console.error('API Error:', e));

// Debug payment form
console.log('Form data:', new FormData(document.getElementById('payment-form')));

Getting Help

If you're still experiencing issues after following this guide:

1. Collect Debug Information:

   • Request/Response headers
   • Error messages
   • Transaction IDs
   • Timestamps

2. Check Resources:

   • API Status
   • FAQ
   • API Documentation

3. Contact Support:

   • Email: support@moneybag.com.bd
   • Include debug information
   • Provide steps to reproduce

Common Error Codes Reference

Prevention Tips