Moneybag
Getting Started

Authentication

Learn how to authenticate with the Moneybag API

Authentication

Secure API authentication is essential for protecting your integration and your customers' data. This guide covers everything you need to know about authenticating with the Moneybag API.

API Key Authentication

Moneybag uses API key authentication for all API requests. Your API key identifies your account and determines your access level.

How It Works

  1. API Key Generation: Keys are generated in your dashboard
  2. Request Header: Include key in X-Merchant-API-Key header
  3. Server Validation: Moneybag validates the key with each request
  4. Access Granted: Valid keys grant access to API resources

Getting Your API Keys

Sandbox Keys

  1. Log into Sandbox Dashboard
  2. Navigate to Developer Settings → API Keys
  3. Click Generate New Key
  4. Copy and securely store your key

Production Keys

  1. Log into Production Dashboard
  2. Complete business verification
  3. Navigate to Developer Settings → API Keys
  4. Generate production key (requires approval)

Important

API keys are shown only once when generated. Store them securely immediately.

Using API Keys

Request Format

Include your API key in the request header:

X-Merchant-API-Key: sk_test_abcdef123456789

Example Requests

cURL

curl -X POST https://sandbox.api.moneybag.com.bd/api/v2/payments/checkout \
  -H "X-Merchant-API-Key: sk_test_abcdef123456789" \
  -H "Content-Type: application/json" \
  -d '{"amount": 100}'

JavaScript

const response = await fetch('https://sandbox.api.moneybag.com.bd/api/v2/payments/checkout', {
  method: 'POST',
  headers: {
    'X-Merchant-API-Key': 'sk_test_abcdef123456789',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ amount: 100 })
});

Python

import requests

headers = {
    'X-Merchant-API-Key': 'sk_test_abcdef123456789',
    'Content-Type': 'application/json'
}

response = requests.post(
    'https://sandbox.api.moneybag.com.bd/api/v2/payments/checkout',
    headers=headers,
    json={'amount': 100}
)

PHP

$headers = [
    'X-Merchant-API-Key: sk_test_abcdef123456789',
    'Content-Type: application/json'
];

$ch = curl_init('https://sandbox.api.moneybag.com.bd/api/v2/payments/checkout');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['amount' => 100]));
$response = curl_exec($ch);

API Key Security

Best Practices

✅ DO

  • • Store keys in environment variables
  • • Use server-side code only
  • • Rotate keys regularly
  • • Use different keys for environments
  • • Implement IP whitelisting
  • • Monitor key usage

❌ DON'T

  • • Expose keys in client-side code
  • • Commit keys to version control
  • • Share keys via email/chat
  • • Use production keys in development
  • • Store keys in plain text
  • • Use same key for multiple apps

Environment Variables

Store your API keys in environment variables:

.env file

# Development
MONEYBAG_API_KEY_SANDBOX=sk_test_abcdef123456789

# Production
MONEYBAG_API_KEY_PRODUCTION=sk_live_xyz987654321

Node.js

require('dotenv').config();

const apiKey = process.env.NODE_ENV === 'production' 
  ? process.env.MONEYBAG_API_KEY_PRODUCTION
  : process.env.MONEYBAG_API_KEY_SANDBOX;

Python

import os
from dotenv import load_dotenv

load_dotenv()

api_key = os.getenv('MONEYBAG_API_KEY_PRODUCTION' 
                     if os.getenv('ENV') == 'production' 
                     else 'MONEYBAG_API_KEY_SANDBOX')

Key Types & Permissions

Sandbox Keys

  • Prefix: sk_test_
  • Environment: Sandbox only
  • Permissions: Full API access in sandbox
  • Use Case: Development and testing

Production Keys

  • Prefix: sk_live_
  • Environment: Production only
  • Permissions: Full API access in production
  • Use Case: Live transactions

Restricted Keys (Coming Soon)

  • Prefix: rk_live_
  • Environment: Production
  • Permissions: Limited scope
  • Use Case: Third-party integrations

Key Rotation

Regular key rotation is a security best practice:

When to Rotate

  • Every 90 days (recommended)
  • After employee departure
  • If key exposure suspected
  • After security audit

How to Rotate

  1. Generate New Key: Create new key in dashboard
  2. Update Application: Deploy with new key
  3. Test Integration: Verify everything works
  4. Revoke Old Key: Disable old key in dashboard

Zero-Downtime Rotation

// Support multiple keys during rotation
const PRIMARY_KEY = process.env.MONEYBAG_API_KEY_PRIMARY;
const SECONDARY_KEY = process.env.MONEYBAG_API_KEY_SECONDARY;

async function makeAPICall(data) {
  try {
    // Try primary key first
    return await callAPI(data, PRIMARY_KEY);
  } catch (error) {
    if (error.code === 'INVALID_API_KEY' && SECONDARY_KEY) {
      // Fallback to secondary key
      return await callAPI(data, SECONDARY_KEY);
    }
    throw error;
  }
}

IP Whitelisting

Add an extra layer of security by restricting API access to specific IP addresses:

Setup

  1. Log into dashboard
  2. Navigate to Security Settings
  3. Add your server IP addresses
  4. Enable IP whitelisting

Considerations

  • Use static IP addresses
  • Include all production servers
  • Update when infrastructure changes
  • Keep list minimal

Authentication Errors

Common Error Responses

Invalid API Key

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired",
    "status": 401
  }
}

Missing API Key

{
  "success": false,
  "error": {
    "code": "API_KEY_MISSING",
    "message": "No API key provided in request headers",
    "status": 401
  }
}

Wrong Environment

{
  "success": false,
  "error": {
    "code": "INVALID_ENVIRONMENT",
    "message": "Sandbox key used with production API",
    "status": 403
  }
}

Troubleshooting

ErrorCauseSolution
INVALID_API_KEYWrong or expired keyCheck key in dashboard
API_KEY_MISSINGHeader not includedAdd X-Merchant-API-Key header
INVALID_ENVIRONMENTKey/URL mismatchMatch sandbox/production
IP_NOT_WHITELISTEDIP restrictionAdd IP to whitelist
RATE_LIMIT_EXCEEDEDToo many requestsImplement rate limiting

Webhook Security

Webhooks require additional authentication:

Signature Verification

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return `sha256=${expectedSignature}` === signature;
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Process webhook
  res.status(200).json({ received: true });
});

Security Checklist

Before going to production:

  • API keys stored in environment variables
  • No keys in version control
  • HTTPS enforced everywhere
  • IP whitelisting configured
  • Key rotation schedule set
  • Webhook signatures verified
  • Error logging implemented
  • Monitoring configured
  • Rate limiting implemented
  • Security audit completed

Next Steps

Getting Started

Your journey to integrating Moneybag payments starts here

Quick Start

Get up and running with Moneybag in 5 minutes