bizappay

Package Information

Released: 7/5/2025

Downloads: 0 weekly / 0 monthly

Latest Version: 0.1.9

Author: nmhafiz

Available Nodes

Bizappay

Interact with Bizappay API

Bizappay

Interact with Bizappay API

Documentation

n8n-nodes-bizappay

Professional n8n community node for integrating with Bizappay API - Malaysia's leading digital payment platform. This node provides comprehensive support for bill management, payment processing, and webhook handling with enterprise-grade features.

🚀 Get Started with Bizappay

Ready to start using Bizappay? Sign up here and support the development of this n8n node!

By using this affiliate link, you're supporting the continued development of this n8n node.

Features

Core Features

Authentication: Secure API key authentication with environment support
Environment Support: Switch between Sandbox and Production environments
Category Operations: Create and retrieve categories for bill organization
Payment Banks: Retrieve available payment bank information
Payment Status: Check payment status for bills
Webhook Support: Enhanced webhook signature verification and payload processing

Advanced Features

Bulk Operations: Create multiple bills simultaneously with batch processing
Advanced Search: Search bills with multiple filters (status, amount range, date range, etc.)
Template System: Create bills from predefined templates (Invoice, Subscription, Service, etc.)
API Monitoring: Track API performance metrics and success rates
Enhanced Rate Limiting: Sliding window rate limiting with burst protection
Smart Token Management: Automatic token caching, refresh, and cleanup
Retry Logic: Intelligent retry with exponential backoff
Comprehensive Validation: Input validation for all data types including Malaysian phone numbers
Error Handling: Detailed error messages with proper error categorization
TypeScript Support: Full TypeScript support with comprehensive type definitions

Performance & Reliability

Caching: Token and configuration caching for improved performance
Rate Limiting: Sliding window algorithm with configurable limits
Monitoring: Built-in API metrics and performance tracking
Resilience: Automatic retry logic with intelligent backoff strategies

Installation

Follow the installation guide in the n8n community nodes documentation.

Available Operations

Authentication

Test Connection: Verify API credentials and connection

Payment Bank

Get All: Retrieve all available payment banks

Bill Operations

Create: Create a new bill with comprehensive validation
Get: Retrieve a specific bill by ID
Get All: Retrieve all bills with optional filters
Search: Advanced search with multiple filters (status, amount range, date range, payer email, text search)
Update: Update an existing bill with field validation
Delete: Delete a bill with ID validation
Bulk Create: Create multiple bills simultaneously with batch processing
Create from Template: Create bills using predefined templates

Webhook Operations

Verify Signature: Enhanced webhook signature verification with timing-safe comparison
Process Payload: Process incoming webhook data with detailed parsing

Monitoring

Get Metrics: Retrieve API performance metrics and statistics
Reset Metrics: Reset API performance counters

Templates Available

Invoice Template: Professional invoice with payment terms
Subscription Template: Monthly subscription billing
Service Fee Template: Professional service consultation
Product Sale Template: Product purchase with delivery
Event Ticket Template: Event registration and ticketing

Credentials

To use this node, you need to configure the Bizappay API credentials:

API Key: Your Bizappay API key (get it from Settings > Profile page in your Bizappay dashboard)
Environment: Choose between Production and Sandbox
- Production: https://bizappay.my
- Sandbox: https://stg.bizappay.my (for testing)

API Reference

This node is based on the Bizappay API v3 documentation.

Available Endpoints

Authentication

POST /api/v3/token - Generate authentication token

Category Management

POST /api/v3/category/create - Create new category
POST /api/v3/category - List all categories

Payment Banks

POST /api/v3/payment-bank-list - Get all available banks

Bill Management

POST /api/v3/bill/create - Create new bill
POST /api/v3/bill/{id} - Get bill details
POST /api/v3/bill/list - List all bills
POST /api/v3/bill/update/{id} - Update bill
POST /api/v3/bill/delete/{id} - Delete bill

Usage Examples

Authentication

Generate Authentication Token

{
  "resource": "authentication",
  "operation": "generateToken"
}

Category Management

Create a Bill Category

{
  "resource": "category",
  "operation": "create",
  "name": "Utilities",
  "description": "Utility bills and services"
}

Payment Banks

Get All Payment Banks

{
  "resource": "paymentBank",
  "operation": "getAll"
}

Get Bank by Code

{
  "resource": "paymentBank",
  "operation": "getByCode",
  "bankCode": "BCBB0235"
}

Bill Management

Create a Bill

{
  "name": "Monthly Subscription",
  "amount": 99.99,
  "category": "SUBSCRIPTION",
  "payer_name": "John Doe",
  "payer_email": "[email protected]",
  "payer_phone": "0123456789",
  "description": "Monthly subscription fee",
  "due_date": "2024-01-31 23:59:59"
}

Bulk Creating Bills

{
  "billsData": [
    {
      "name": "Invoice #001",
      "amount": 150.00,
      "category": "INVOICE",
      "payer_name": "Alice Smith",
      "payer_email": "[email protected]",
      "description": "Consulting services"
    },
    {
      "name": "Invoice #002",
      "amount": 200.00,
      "category": "INVOICE",
      "payer_name": "Bob Johnson",
      "payer_email": "[email protected]",
      "description": "Design services"
    }
  ],
  "batchSize": 5
}

Creating from Template

{
  "template": "invoice",
  "templateVariables": {
    "customerName": "John Doe",
    "customerEmail": "[email protected]",
    "customerPhone": "0123456789",
    "amount": 299.99,
    "reference": "INV-2024-001",
    "dueDate": "2024-02-15T00:00:00Z",
    "customDescription": "Additional project requirements included"
  }
}

Advanced Search

{
  "searchFilters": {
    "status": "pending",
    "amountRange": {
      "range": {
        "min": 100,
        "max": 500
      }
    },
    "dateRange": {
      "range": {
        "start": "2024-01-01T00:00:00Z",
        "end": "2024-01-31T23:59:59Z"
      }
    },
    "searchText": "invoice"
  }
}

Get Bill by ID

{
  "resource": "bill",
  "operation": "get",
  "billId": "BILL123456"
}

Get All Bills with Filtering

{
  "resource": "bill",
  "operation": "getAll",
  "page": 1,
  "limit": 10,
  "status": "pending",
  "category": "UTIL001"
}

Update Bill

{
  "resource": "bill",
  "operation": "update",
  "billId": "BILL123456",
  "billName": "Updated Monthly Subscription",
  "amount": 109.90,
  "description": "Updated monthly subscription fee"
}

Delete Bill

{
  "resource": "bill",
  "operation": "delete",
  "billId": "BILL123456"
}

Payment Status

Check Payment Status

{
  "resource": "paymentStatus",
  "operation": "getStatus",
  "billId": "BILL123456"
}

Webhook Operations

Verify Webhook Signature

{
  "resource": "webhook",
  "operation": "verifySignature",
  "webhookPayload": "{\"event_type\":\"payment.completed\",\"bill_id\":\"BILL123456\"}",
  "webhookSignature": "sha256=abc123...",
  "webhookSecret": "your-webhook-secret"
}

Process Webhook Payload

{
  "resource": "webhook",
  "operation": "processPayload",
  "webhookPayload": "{\"event_type\":\"payment.completed\",\"bill_id\":\"BILL123456\",\"status\":\"paid\"}"
}

Monitoring

Get API Metrics

{
  "resource": "monitoring",
  "operation": "getMetrics"
}

Response Example:

{
  "totalRequests": 150,
  "successfulRequests": 145,
  "failedRequests": 5,
  "successRate": "96.7%",
  "averageResponseTime": "245ms",
  "endpoints": {
    "bill_create": {
      "count": 50,
      "success": 48,
      "avgResponseTime": "320ms"
    },
    "bill_list": {
      "count": 75,
      "success": 75,
      "avgResponseTime": "180ms"
    }
  },
  "lastReset": "2024-01-15T10:30:00Z"
}

Advanced Features

Rate Limiting

The node implements intelligent rate limiting to respect Bizappay API limits:

Sliding Window Algorithm: More accurate rate limiting than simple counters
Configurable Limits: Customize requests per minute and burst limits
Automatic Throttling: Requests are automatically delayed when limits are approached
Burst Protection: Prevents sudden spikes from overwhelming the API
Request Queuing: Queues requests during high-traffic periods

Token Management

Automatic Generation: Tokens are generated automatically when needed
Intelligent Caching: Tokens are cached with proper TTL management
Automatic Refresh: Expired tokens are refreshed transparently
Memory Efficient: Optimized token storage with cleanup routines
Thread Safe: Concurrent request handling with proper synchronization

Error Handling & Resilience

Comprehensive Categorization: Errors are properly categorized by type
Intelligent Retry Logic: Exponential backoff with jitter for failed requests
Circuit Breaker Pattern: Prevents cascading failures
Detailed Error Messages: Clear, actionable error descriptions
HTTP Status Mapping: Proper handling of all HTTP response codes
Timeout Management: Configurable timeouts for different operations

Data Validation & Security

Input Sanitization: All inputs are sanitized to prevent injection attacks
Email Validation: RFC-compliant email format validation
Phone Number Validation: Malaysian phone number format validation
Bank Code Validation: Validates against known Malaysian bank codes
Amount Validation: Ensures positive numbers with proper decimal precision
Required Field Validation: Comprehensive validation of mandatory fields
Webhook Security: Timing-safe signature verification to prevent timing attacks

Performance Optimization

Connection Pooling: Reuses HTTP connections for better performance
Response Caching: Caches frequently accessed data
Batch Processing: Efficient bulk operations with configurable batch sizes
Memory Management: Automatic cleanup of cached data and metrics
Compression: Supports response compression for faster data transfer

Configuration

Environment Variables

You can configure the node behavior using these optional environment variables:

# Rate Limiting
BIZAPPAY_RATE_LIMIT_RPM=60          # Requests per minute (default: 60)
BIZAPPAY_RATE_LIMIT_BURST=10        # Burst limit (default: 10)

# Timeouts
BIZAPPAY_TIMEOUT_MS=30000           # Request timeout in milliseconds (default: 30000)
BIZAPPAY_RETRY_MAX=3                # Maximum retry attempts (default: 3)

# Caching
BIZAPPAY_TOKEN_TTL=3600             # Token cache TTL in seconds (default: 3600)
BIZAPPAY_CACHE_MAX_SIZE=1000        # Maximum cache entries (default: 1000)

Best Practices

For Production Use

Use Production Environment: Always set environment to "Production" for live transactions
Implement Webhook Verification: Always verify webhook signatures for security
Monitor API Metrics: Regularly check API performance using the monitoring operations
Handle Rate Limits: Implement proper error handling for rate limit responses
Secure Credentials: Store API keys securely and rotate them regularly

For Development

Use Sandbox Environment: Test all operations in sandbox before production
Test Webhook Endpoints: Verify webhook handling with test payloads
Validate Templates: Test all template variations before deployment
Monitor Performance: Use metrics to optimize batch sizes and timing

Bulk Operations

Optimal Batch Size: Use batch sizes between 5-10 for best performance
Error Handling: Always check individual results in bulk operations
Rate Limiting: Allow extra time for bulk operations to complete
Data Validation: Validate all data before starting bulk operations

Template Usage

Customize Templates: Modify templates to match your business needs
Validate Variables: Ensure all required template variables are provided
Test Templates: Test template generation with various input combinations
Version Control: Keep track of template changes for consistency

Error Handling

The node provides comprehensive error handling with detailed error messages:

Error Categories

API Errors: Detailed error messages from Bizappay API with proper HTTP status codes
Validation Errors: Clear validation error descriptions with field-specific messages
Network Errors: Proper handling of network timeouts, connection issues, and DNS failures
Authentication Errors: Clear messages for invalid credentials, expired tokens, and permission issues
Rate Limit Errors: Informative messages when rate limits are exceeded with retry suggestions
Template Errors: Specific errors for template validation and variable substitution
Bulk Operation Errors: Individual error tracking for batch operations

Error Response Format

{
  "error": {
    "type": "ValidationError",
    "message": "Invalid email format",
    "field": "payer_email",
    "code": "INVALID_EMAIL",
    "details": {
      "provided": "invalid-email",
      "expected": "Valid email format (e.g., [email protected])"
    }
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "requestId": "req_123456789"
}

API Rate Limits

Bizappay API has rate limits. The node handles these automatically:

Rate Limit: 100 requests per minute per API key
Retry Logic: Automatic retry with exponential backoff
Error Messages: Clear indication when rate limits are exceeded
Reset Time: Provides exact time when limits reset
Proactive Checking: Prevents requests when limits are reached

Errors are returned in a structured format with descriptive messages.

Testing

Sandbox Environment

Use the sandbox environment for testing:

Set environment to sandbox in credentials
Use test API key from Bizappay dashboard
Test all operations without real transactions
Sandbox data is reset periodically

Testing Checklist

Authentication token generation
Category operations (Create, Get All)
Bill CRUD operations with all fields
Payment bank retrieval
Payment status checking
Webhook signature verification
Error handling scenarios
Rate limiting behavior

Sample Test Data

{
  "testCategory": {
    "name": "Test Category",
    "description": "Test category for development"
  },
  "testBill": {
    "billName": "Test Bill",
    "amount": 10.00,
    "categoryCode": "TEST001",
    "payerName": "Test User",
    "payerEmail": "[email protected]",
    "payerPhone": "0123456789"
  }
}

Troubleshooting

Common Issues

Authentication Issues

Problem: "Invalid API key" or "Authentication failed"
Solution:

Verify your API key is correct
Ensure you're using the right environment (Sandbox vs Production)
Check if your API key has the required permissions
Try regenerating your API key from Bizappay dashboard

Rate Limiting

Problem: "Rate limit exceeded" errors
Solution:

Reduce the frequency of API calls
Implement proper delays between requests
Use bulk operations for multiple items
Monitor your API usage with the metrics endpoint

Webhook Verification Failures

Problem: Webhook signature verification fails
Solution:

Ensure webhook secret matches exactly
Check that payload is not modified in transit
Verify timestamp is within acceptable range
Use raw payload for signature verification

Template Issues

Problem: Template creation fails or produces unexpected results
Solution:

Validate all required template variables are provided
Check variable formats (email, phone, dates)
Ensure template type exists
Test with minimal variable set first

Bulk Operation Failures

Problem: Some items in bulk operations fail
Solution:

Check individual error messages in the response
Validate all data before starting bulk operation
Reduce batch size if experiencing timeouts
Implement retry logic for failed items

Performance Optimization

Slow Response Times

Use Bulk Operations: For multiple items, use bulk create instead of individual calls
Optimize Batch Sizes: Test different batch sizes (5-10 typically optimal)
Cache Results: Cache frequently accessed data like categories and bank lists
Monitor Metrics: Use the monitoring endpoint to identify bottlenecks

Memory Usage

Clear Metrics Regularly: Reset metrics periodically to prevent memory buildup
Limit Cache Size: Configure appropriate cache limits for your environment
Monitor Token Cache: Ensure token cleanup is working properly

Debug Mode

Enable debug logging in n8n:

# Set environment variable
N8N_LOG_LEVEL=debug

# Or in n8n settings
Settings > Log Level > Debug

API Response Times

Authentication: ~200ms
Category Operations: ~150ms
Bill Operations: ~300ms
Payment Status: ~100ms
Webhook Processing: ~50ms

Migration Guide

From v1.x to v2.x

Update Credentials: Add environment field
Update Operations: Some operation names have changed
Check Webhooks: Webhook handling is now more secure
Review Validation: Input validation is now stricter

Breaking Changes

uri parameter renamed to url in requests
IRequestOptions replaced with IHttpRequestOptions
Enhanced error response format
Stricter input validation

Development

Prerequisites

Node.js 16.x or higher
npm or yarn
n8n installed

Setup

# Clone the repository
git clone <repository-url>
cd n8n-nodes-bizappay

# Install dependencies
npm install

# Build the node
npm run build

# Link for local development
npm link

Building

# Build TypeScript and copy icons
npm run build

# Watch for changes during development
npm run dev

Linting

# Check for linting errors
npm run lint

# Fix linting errors automatically
npm run lintfix

API Authentication Flow

The Bizappay API uses a two-step authentication process:

Token Generation: First, generate a token using your API key
Authenticated Requests: Use the token in the Authentication header for subsequent requests

This node handles this flow automatically:

For each API call (except token generation), it first obtains a fresh token
The token is then used for the actual API request
All requests use application/x-www-form-urlencoded content type

Supported Banks

The Payment Bank endpoint returns information about Malaysian banks including:

Affin Bank
Alliance Bank
AmBank
Bank Islam
Bank Muamalat
Bank Rakyat
BSN
CIMB Clicks
Hong Leong Bank
HSBC
KFH
Maybank2U
OCBC Bank
Public Bank
RHB Bank
Standard Chartered
UOB

Each bank entry includes:

Bank code
Bank name
Status (online/offline)

API Reference

For detailed API documentation, refer to:

Contributing

We welcome contributions! Please follow these guidelines:

Development Setup

Fork the repository
Clone your fork: git clone https://github.com/nmhafiz/n8n-nodes-bizappay.git
Install dependencies: npm install
Create a feature branch: git checkout -b feature/your-feature-name
Make your changes and add tests
Run tests: npm test
Build the project: npm run build
Submit a pull request

Code Standards

Follow TypeScript best practices
Add comprehensive error handling
Include input validation
Write unit tests for new features
Update documentation for API changes
Follow existing code style and patterns

Testing

Test all operations in both sandbox and production environments
Verify webhook handling with real payloads
Test bulk operations with various data sets
Validate template generation with different variables
Check error handling for edge cases

License

MIT License - see LICENSE file for details.

Developer & Support

About the Developer

Developer: nmhafiz
GitHub: @nmhafiz
Website: Sahabat Xpert

Affiliate Program

Support the development of this node by signing up for Bizappay through our affiliate link:
Get Bizappay

By using this affiliate link, you're supporting the continued development and maintenance of this n8n node.

For more details, see AFFILIATE.md

Support

Getting Help

GitHub Issues: For bug reports and feature requests
Documentation: Check this README and inline code comments
API Documentation: Refer to Bizappay's official API docs
Community: Join n8n community discussions
Developer Website: Sahabat Xpert

Reporting Issues

When reporting issues, please include:

Node version and n8n version
Environment (Sandbox/Production)
Complete error message
Steps to reproduce
Expected vs actual behavior
Sample data (with sensitive information removed)

License

MIT License - see LICENSE file for details.

Changelog

v0.2.0 (Latest)

New Features:
- Bulk bill creation with batch processing
- Advanced search with multiple filters
- Template system with 5 predefined templates
- API monitoring and metrics tracking
- Enhanced webhook signature verification
Improvements:
- Sliding window rate limiting
- Better error handling and validation
- Performance optimizations
- Comprehensive TypeScript support
- Enhanced security measures
Bug Fixes:
- Fixed token refresh issues
- Improved memory management
- Better handling of edge cases

v0.1.0

Initial release
Basic operations for categories and bills
Payment bank information retrieval
Webhook support
Rate limiting and token caching
Comprehensive error handling and validation