API Reference

Welcome to the Moneybag API documentation. Our RESTful API provides a simple and secure way to integrate payment processing into your application.

Base URLs

All API requests should be made to one of the following base URLs:

• Sandbox Environment: https://sandbox.api.moneybag.com.bd/api/v2
• Production Environment: https://api.moneybag.com.bd/api/v2

Redirect URLs and Transaction Status

After a transaction is completed, Moneybag redirects the customer to one of the merchant's specified URLs based on the transaction outcome. Moneybag appends query parameters to these URLs with the transaction details.

Redirect URL Format

https://yourdomain.com/payment/{status}?transaction_id={transaction_id}&status={STATUS}

Example redirect URLs:

# Successful payment
https://example.com/payment/success?transaction_id=txn691765dba92741829f72de6eacec8a76&status=SUCCESS

# Failed payment
https://example.com/payment/fail?transaction_id=txn691765dba92741829f72de6eacec8a76&status=FAILED

# Cancelled payment
https://example.com/payment/cancel?transaction_id=txn691765dba92741829f72de6eacec8a76&status=CANCELLED

Redirect URL Types

Query Parameters

Moneybag appends the following query parameters to your redirect URLs:

Authentication

All API requests require authentication using your merchant API key:

X-Merchant-API-Key: your_api_key_here

Learn more about Authentication →

Available Endpoints

Integration Flow

Understanding the complete payment flow helps you implement a robust integration:

Key Steps

1. Create Checkout Session - Initialize payment with customer and order details
2. Redirect Customer - Send customer to Moneybag's secure payment page
3. Process Payment - Customer completes payment with their preferred method
4. Receive Notification - Get real-time webhook for payment status
5. Verify Payment - Confirm payment details before fulfilling order
6. Complete Order - Deliver goods/services after successful verification

API Playground

Test our API endpoints interactively with real responses:

The playground allows you to:

• Test endpoints with your sandbox credentials
• See real-time request and response data
• Export code snippets in multiple languages
• Debug integration issues quickly

Request & Response Format

Request Headers

All API requests should include these headers:

X-Merchant-API-Key: your_api_key
Content-Type: application/json
Accept: application/json

Response Format

All responses follow a consistent JSON structure:

Success Response

{
  "success": true,
  "message": "Operation completed successfully",
  "data": {
    // Response data specific to the endpoint
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "field": "field_name" // Optional, for validation errors
  }
}

HTTP Status Codes

Rate Limiting

To ensure fair usage and system stability:

• Sandbox: 100 requests per minute
• Production: 60 requests per minute

Rate limit headers in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640995200

Handling Rate Limits

async function makeAPICall(data, retries = 3) {
  try {
    const response = await callAPI(data);
    return response;
  } catch (error) {
    if (error.status === 429 && retries > 0) {
      const resetTime = error.headers['X-RateLimit-Reset'];
      const waitTime = resetTime - Date.now() / 1000;
      await sleep(waitTime * 1000);
      return makeAPICall(data, retries - 1);
    }
    throw error;
  }
}

Security Best Practices

API Key Security

• Store keys in environment variables
• Never expose keys in client-side code
• Rotate keys regularly
• Use different keys for different environments

Data Protection

• Always use HTTPS
• Implement webhook signature verification
• Validate all input data
• Log security events

PCI Compliance

• Never store card details
• Use tokenization when possible
• Follow PCI DSS guidelines
• Regular security audits

Error Handling

Implement robust error handling for all API calls:

try {
  const response = await moneybagAPI.createCheckout(data);
  // Handle success
} catch (error) {
  if (error.code === 'INVALID_AMOUNT') {
    // Handle specific error
  } else if (error.code === 'RATE_LIMIT_EXCEEDED') {
    // Implement retry logic
  } else {
    // Handle generic error
    console.error('API Error:', error.message);
  }
}

View all Error Codes →

Testing

Sandbox Environment

Use our sandbox for safe testing:

• Test card numbers for different scenarios
• Mobile banking test accounts
• Webhook testing tools
• No real money processed

Learn more about Sandbox Testing →

Test Data

Support Resources

Next Steps

Ready to start integrating? Here's what to do:

1. Create a Sandbox Account
2. Get Your API Keys
3. Make Your First API Call
4. Test Your Integration
5. Go Live with Production