n8n-nodes-bizappay/README.md

Unofficial community n8n node for Bizappay API integration - NOT officially endorsed by Bizappay

# n8n-nodes-bizappay

[![npm version](https://badge.fury.io/js/n8n-nodes-bizappay.svg)](https://badge.fury.io/js/n8n-nodes-bizappay)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## ⚠️ IMPORTANT LEGAL NOTICE

**This project is NOT officially associated with, endorsed by, or supported by Bizappay.**

- 🏢 **Bizappay** is a trademark of its respective owners
- 🔧 This is an **independent, community-developed** integration
- 📋 Users must comply with Bizappay's Terms of Service
- 🚫 The author assumes no responsibility for API changes or service interruptions
- 💼 For official support, contact Bizappay directly

**Use at your own risk and responsibility.**

---

🚀 **Transform Your Payment Automation with Bizappay Integration**

Streamline your business operations with this powerful n8n node for Bizappay API integration. Experience seamless payment processing with Malaysia's most comprehensive e-wallet solution that supports all major payment methods through a single integration.

## Why Choose Bizappay?

✨ **All-in-One Payment Solution**: Access every major Malaysian e-wallet (GrabPay, Touch 'n Go, Boost, ShopeePay, and more) with just one Bizappay account registration

🎯 **Business-Ready Features**:
- **Intelligent Auto-Correction**: Smart input validation and formatting
- **Enterprise Authentication**: Secure token management with advanced caching
- **Comprehensive Bill Management**: Create and manage payment bills effortlessly
- **Category Organization**: Streamlined payment category management
- **Robust Error Handling**: Professional-grade error management with automatic retry logic
- **Performance Optimized**: Lightning-fast processing with intelligent caching

💼 **Perfect for Malaysian Businesses**: Whether you're a startup or enterprise, Bizappay provides the payment infrastructure you need to succeed in Malaysia's digital economy.

## 📋 Table of Contents

- [Installation](#installation)
- [Configuration](#configuration)
- [Supported Operations](#supported-operations)
- [Auto-Correction Features](#auto-correction-features)
- [Usage Examples](#usage-examples)
- [Error Handling](#error-handling)
- [API Reference](#api-reference)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)

## 🚀 Quick Start Guide

### Get Started in Minutes

**Step 1: Install the Node**

Choose your preferred installation method:

#### Via n8n Community Nodes (Recommended)
1. Open your n8n instance
2. Navigate to **Settings** > **Community Nodes**
3. Click **Install a community node**
4. Enter: `n8n-nodes-bizappay`
5. Click **Install**

#### Via npm
```bash
npm install n8n-nodes-bizappay
```

#### Via Docker
Add to your `Dockerfile`:
```dockerfile
RUN npm install -g n8n-nodes-bizappay
```

#### Manual Installation (Advanced)
```bash
# Clone repository
git clone https://github.com/nmhafiz/n8n-nodes-bizappay.git
cd n8n-nodes-bizappay

# Install dependencies
npm install

# Build project
npm run build

# Link to n8n
npm link
cd ~/.n8n/nodes
npm link n8n-nodes-bizappay
```

💡 **Need Professional Setup?** For complex integrations or custom automation workflows, [Sahabat Xpert](https://www.sahabatxpert.my/) offers expert implementation services with free consultation for Malaysian businesses.

**Step 2: Get Your Bizappay Account**

🎯 **Ready to revolutionize your payment processing?**

1. **Sign up for Bizappay**: [Get started here](https://www.bizappay.my/a/OTQxNg__) and unlock access to all major Malaysian e-wallets
2. **Access your dashboard**: Login to your professional Bizappay portal
3. **Get your credentials**: Navigate to your dashboard and obtain:
   - **API Key**: Your unique API identifier
   - **Secret Key**: Your secure authentication key
   - **Collection ID**: Your payment collection identifier

**Step 3: Configure n8n Integration**

1. In n8n, add **Bizappay API** credentials
2. Enter your authentication details:
   - **API Key**: Your API key from Bizappay dashboard
3. Click **Save**

🎉 **You're ready to automate payments like a pro!**

## 🔧 Powerful Operations at Your Fingertips

### 💳 Smart Bill Management

#### Create Professional Payment Bills
Generate sophisticated payment bills with intelligent auto-correction and validation.

**Essential Parameters:**
- **Product Name**: Professional product description (minimum 5 characters)
- **Amount**: Payment amount with automatic formatting (RM)
- **Customer Name**: Customer name with smart formatting (minimum 5 characters)
- **Customer Email**: Email with validation and correction
- **Customer Phone**: Customer phone number

**Advanced Options:**
- **Web Return URL**: Custom redirect URL for seamless user experience
- **Reference 1**: Primary reference for tracking
- **Reference 2**: Secondary reference for detailed categorization

**✨ Smart Features:**
- Automatic currency formatting
- Data validation and sanitization
- Email validation and correction
- Input sanitization and optimization

#### Get Bill Information & Status
Retrieve comprehensive bill details and payment status with advanced filtering capabilities.

**Essential Parameters:**
- **Bill Code**: Unique bill identifier (e.g., OiU6DTopBL1)
- **Payment Status**: Smart dropdown filter with auto-fill
  - Success (1) - Default selection
  - Pending (2)
  - Failed (3)
  - No Action/Not Paid (4)

**Professional Features:**
- Real-time bill status tracking
- Payment verification and confirmation
- Transaction history retrieval
- Business intelligence data
- Automated status monitoring

**✨ Smart Capabilities:**
- Intelligent bill code validation
- Auto-filled payment status (Success by default)
- Comprehensive transaction details
- Business-ready data formatting

### 📊 Advanced Category Management

#### Retrieve Payment Categories
Access comprehensive payment categories for organized transaction management.

**Professional Output:**
- Structured category array with ID and name
- Business metadata and status information
- Ready for dropdown integration
- Optimized for business workflows

## ✨ Intelligent Auto-Correction System

**Experience the power of AI-driven input optimization** - The advanced auto-correction system ensures your data is always perfectly formatted for Malaysian business standards.



### 📧 Advanced Email Validation

**Enterprise-Grade Email Processing**:

```javascript
// Professional email optimization:
"user@domain"      → "user@domain.com"     // Smart domain completion
"USER@DOMAIN.COM"  → "user@domain.com"     // Professional lowercase formatting
"user @domain.com" → "user@domain.com"     // Intelligent space removal
""                 → "customer@example.com" // Business-ready auto-fill
```

- 🔍 **Format Verification**: Comprehensive email format validation
- 🌐 **Domain Intelligence**: Smart domain existence checking
- 🔧 **Auto-Correction**: Fixes common typing errors automatically

### 👤 Smart Name Processing

**Professional Name Formatting**:

```javascript
// Business-standard name formatting:
"john"             → "John Doe"           // Professional surname addition
"  John Doe  "     → "John Doe"           // Space optimization
""                 → "Customer Name"      // Business-ready default
```

- ✂️ **Space Optimization**: Removes excessive whitespace
- 📝 **Proper Capitalization**: Professional name formatting
- 📏 **Length Validation**: Ensures minimum 5-character requirement

### 💰 Professional Amount Formatting

**Financial Data Optimization**:

```javascript
// Currency formatting excellence:
"10.5"             → "10.50"             // Precise decimal formatting
"abc"              → "10.00"             // Intelligent default handling
"0"                → "10.00"             // Minimum amount enforcement
```

- 💱 **Currency Symbol Handling**: Intelligent removal of currency symbols
- 📊 **Decimal Precision**: Automatic formatting to 2 decimal places
- ✅ **Value Correction**: Converts negative values to positive amounts

### 🏷️ Smart Product Description

**Professional Product Naming**:

```javascript
// Business-ready product descriptions:
"Tea"              → "Tea - Payment Bill" // Professional suffix addition
"Very long product name that exceeds the maximum length limit"
                   → "Very long product name that exceeds the maximum length li" // Smart truncation
""                 → "Payment Bill"       // Business-standard default
```

- 📝 **Length Optimization**: Smart truncation for long descriptions
- 🏷️ **Professional Suffixes**: Automatic business-appropriate additions
- ✨ **Default Handling**: Intelligent fallback for empty inputs

## 📖 Real-World Implementation Examples

### 🏢 **Sahabat Xpert Success Stories**

**Transforming Malaysian businesses with intelligent automation solutions:**

🎯 **E-commerce Integration**: Automated order-to-payment workflows connecting online stores with Bizappay, including inventory management and courier integration for seamless customer experience.

📊 **CRM Automation**: Complete sales funnel automation from lead capture to payment processing, with automated follow-ups and customer relationship management.

🚀 **Multi-Platform Solutions**: Integrated booking systems with payment processing, automated invoicing, and real-time business intelligence dashboards.

*Need similar automation for your business? [Contact Sahabat Xpert](https://www.sahabatxpert.my/) for a free consultation.*

### 🚀 Professional Bill Creation Workflow

**Create sophisticated payment bills with enterprise-grade automation:**

```json
{
  "nodes": [
    {
      "name": "Professional Bill Creation",
      "type": "n8n-nodes-bizappay.bizappay",
      "parameters": {
        "operation": "createBill",
        "description": "Premium Product Package A",
        "amount": "299.00",
        "customerName": "Ahmad Rahman",
        "customerEmail": "ahmad.rahman@company.com",
        "customerPhone": "012-345-6789",
        "webreturnUrl": "https://yourbusiness.com/payment-success"
      }
    }
  ]
}
```

### 🔍 Advanced Bill Information Retrieval

**Retrieve comprehensive bill details and payment status with real-time monitoring:**

```json
{
  "nodes": [
    {
      "name": "Bill Status Intelligence",
      "type": "n8n-nodes-bizappay.bizappay",
      "parameters": {
        "operation": "getBillInfo",
        "billCode": "OiU6DTopBL1",
        "paymentStatus": "1"
      }
    }
  ]
}
```

**Professional Response Structure:**
```javascript
// Comprehensive bill information output:
{
  "billCode": "OiU6DTopBL1",
  "status": "Success",
  "amount": "RM 299.00",
  "customerName": "Ahmad Rahman",
  "customerEmail": "ahmad.rahman@company.com",
  "paymentDate": "2024-01-15T10:30:00Z",
  "paymentMethod": "Touch 'n Go eWallet",
  "transactionId": "TXN123456789",
  "businessMetadata": {
    "reference1": "INV-2024-001",
    "reference2": "DEPT-SALES"
  }
}
```

### 📊 Smart Category Management

**Retrieve and organize payment categories for streamlined operations:**

```json
{
  "nodes": [
    {
      "name": "Category Intelligence",
      "type": "n8n-nodes-bizappay.bizappay",
      "parameters": {
        "operation": "getCategories"
      }
    }
  ]
}
```

### ✨ AI-Powered Auto-Correction Showcase

**Experience intelligent data optimization in action:**

```json
{
  "nodes": [
    {
      "name": "Smart Bill with Auto-Optimization",
      "type": "n8n-nodes-bizappay.bizappay",
      "parameters": {
        "operation": "createBill",
        "description": "Tea",                    // ✨ Becomes "Tea - Payment Bill"
        "amount": "10.5",                      // ✨ Becomes "10.50"
        "customerName": "john",                 // ✨ Becomes "John Doe"
        "customerEmail": "USER@DOMAIN",         // ✨ Becomes "user@domain.com"
        "customerPhone": "012-345-6789"         // ✨ Becomes "+60123456789"
      }
    }
  ]
}
```

**🎯 See the magic happen**: Input messy data, get professional results automatically!

## 🛡️ Enterprise-Grade Error Handling

**Professional error management with intelligent recovery mechanisms**

### 🔍 Comprehensive Error Types

#### 1. **Authentication Errors**
```json
{
  "error": "Invalid authentication",
  "code": 401,
  "message": "API credentials verification failed",
  "solution": "Verify your API key in Bizappay dashboard"
}
```

#### 2. **Validation Errors**
```json
{
  "error": "Validation failed",
  "code": 400,
  "details": {
    "amount": "Amount must be greater than 0",
    "customerEmail": "Invalid email format detected"
  },
  "autoCorrection": "Applied intelligent fixes where possible"
}
```

#### 3. **Network Errors**
```json
{
  "error": "Network timeout",
  "code": 500,
  "message": "Connection to Bizappay API failed",
  "retryInfo": "Automatic retry in progress"
}
```

### 🔄 Intelligent Retry System

**Advanced resilience with smart recovery:**
- 🔢 **Max retries**: 3 attempts with exponential backoff
- ⏱️ **Backoff strategy**: Progressive delays (1s → 2s → 4s)
- 🎯 **Smart conditions**: Network errors, 5xx status codes, rate limits
- 🧠 **Adaptive logic**: Learns from failure patterns

## 📚 Professional API Reference

### 🔐 Enterprise Authentication

**Secure token-based authentication with automatic management:**

```http
POST /api/v3/token
Content-Type: application/x-www-form-urlencoded

apiKey=your_bizappay_api_key
```

**Response:**
```json
{
  "status": "ok",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "ttl": 3600
}
```

### 💳 Professional Bill Creation

```http
POST /api/v3/bill/create
Authentication: {token}
Content-Type: application/x-www-form-urlencoded

apiKey=your_api_key&
description=Premium Product Package&
amount=299.00&
customerName=Ahmad Rahman&
customerEmail=ahmad@company.com&
customerPhone=+60123456789&
webreturnUrl=https://yourbusiness.com/success
```

### 🔍 Advanced Bill Information Retrieval

```http
POST /api/v3/bill/info
Authentication: {token}
Content-Type: application/x-www-form-urlencoded

apiKey=your_api_key&
search_str=OiU6DTopBL1&
payment_status=1
```

**Response Structure:**
```json
{
  "success": true,
  "data": {
    "billCode": "OiU6DTopBL1",
    "status": "Success",
    "amount": "299.00",
    "customerName": "Ahmad Rahman",
    "customerEmail": "ahmad@company.com",
    "paymentDate": "2024-01-15T10:30:00Z",
    "paymentMethod": "Touch 'n Go eWallet"
  }
}
```

### 📊 Category Management

```http
POST /api/v3/category
Authentication: {token}
Content-Type: application/x-www-form-urlencoded

apiKey=your_api_key
```

## 🔍 Professional Troubleshooting Guide

### 🛠️ Common Solutions

#### 1. **Authentication Issues**

**🔍 Symptoms:**
- "Invalid authentication" errors
- Token validation failures
- API access denied

**✅ Professional Solutions:**
- Verify API key in your [Bizappay Dashboard](https://www.bizappay.my/a/OTQxNg__)
- Ensure API key has proper permissions
- Node automatically handles token refresh
- Check network connectivity to Bizappay servers

#### 2. **Data Validation Errors**

**🔍 Symptoms:**
- "Validation failed" messages
- Field format errors
- Missing required data

**✅ Smart Solutions:**
- Leverage built-in auto-correction features
- Review input data format requirements
- Ensure all mandatory fields are populated
- Use intelligent defaults for missing data



### Debug Mode

For debugging, enable verbose logging:

```javascript
// In workflow settings
{
  "settings": {
    "executionOrder": "v1",
    "saveManualExecutions": true,
    "callerPolicy": "workflowsFromSameOwner",
    "errorWorkflow": "error-handler-workflow"
  }
}
```

## 🧪 Professional Testing Suite

### 🎯 Comprehensive Unit Testing

```bash
# Execute complete test suite
npm test

# Target specific functionality
npm test -- --grep "validation"

# Generate detailed coverage reports
npm run test:coverage
```

### 🚀 Advanced Integration Testing

```bash
# Production API integration tests
npm run test:integration

# Phone number processing validation
node test-validation.js

# AI auto-correction system testing
node test-auto-correction.js

# Real-world API scenario testing
node test-real-api.js
```

## 🤝 Join the Development Community

### 🚀 Professional Development Setup

```bash
# Fork and clone the repository
git clone https://github.com/nmhafiz/n8n-nodes-bizappay.git
cd n8n-nodes-bizappay

# Install enterprise dependencies
npm install

# Launch development environment
npm run dev

# Run quality checks
npm run lint && npm test
```

### 💎 Enterprise Code Standards

- **🔷 TypeScript Excellence**: 100% TypeScript implementation
- **⚡ ESLint Compliance**: Strict adherence to coding standards
- **✨ Prettier Formatting**: Automated code beautification
- **🧪 Test Coverage**: Mandatory testing for all new features
- **📚 Documentation**: Comprehensive inline documentation
- **🔒 Security First**: Security-focused development practices

### 🎯 Professional Contribution Workflow

1. **🍴 Fork** the repository to your account
2. **🌿 Create** feature branch (`git checkout -b feature/revolutionary-enhancement`)
3. **💻 Develop** with excellence and test thoroughly
4. **📝 Commit** with descriptive messages (`git commit -m 'feat: Add revolutionary enhancement'`)
5. **🚀 Push** to your branch (`git push origin feature/revolutionary-enhancement`)
6. **🎉 Submit** a comprehensive Pull Request

### 🏆 Contribution Recognition

**Your contributions matter!** Every enhancement helps Malaysian businesses automate their payment processes more effectively.

### 💼 Custom Development Services

**Need specialized n8n nodes or custom integrations?** [Sahabat Xpert](https://www.sahabatxpert.my/) offers professional development services:

- 🔧 **Custom Node Development**: Tailored n8n nodes for specific business requirements
- 🌐 **API Integration Services**: Connect any Malaysian service with n8n workflows
- 🚀 **Enterprise Automation**: Large-scale workflow automation for corporations
- 📊 **Business Intelligence**: Custom dashboards and reporting solutions
- 🎯 **Training & Consultation**: n8n expertise transfer to your development team

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Professional Support & Resources

### 🎯 Get Expert Help

- **🐛 Issues & Bugs**: [GitHub Issues](https://github.com/nmhafiz/n8n-nodes-bizappay/issues)
- **💬 Community Discussions**: [GitHub Discussions](https://github.com/nmhafiz/n8n-nodes-bizappay/discussions)
- **📧 Direct Support**: sifatsahabatsdnbhd@gmail.com
- **📖 Complete Documentation**: [API Documentation](./API_DOCUMENTATION.md)
- **🌐 n8n Community**: [n8n Community Forum](https://community.n8n.io/)
- **🏆 Professional Implementation**: [Sahabat Xpert](https://www.sahabatxpert.my/) - Expert consultation and custom development services

### 🚀 Transform Your Business Today

**Ready to revolutionize your payment processing?**

🎯 **Get Your Bizappay Account**: [Sign up here](https://www.bizappay.my/a/OTQxNg__) and unlock access to all major Malaysian e-wallets instantly!

💼 **Need Professional Implementation?**

**Partner with the experts**: [Sahabat Xpert](https://www.sahabatxpert.my/) - Your trusted digital transformation partner specializing in comprehensive automation solutions and Bizappay integrations.

✨ **Why choose Sahabat Xpert?**
- 🏆 **Expert n8n Workflow Development**: Custom automation solutions tailored to your business
- 🔧 **Complete Bizappay Integration Setup**: End-to-end payment automation implementation
- 🚀 **Sales Process Automation**: From sales pages to booking systems with courier integration
- 📊 **Business Intelligence Integration**: Connect with CRM, e-commerce, and inventory systems
- 💬 **Ongoing Technical Support**: Dedicated Malaysian business expertise and support
- 🌐 **Comprehensive Digital Solutions**: Professional website development and business automation

**🎯 Specialized Services:**
- Custom n8n node development and optimization
- Multi-platform payment gateway integrations
- Automated workflow design for Malaysian businesses
- E-commerce automation with local courier services
- Real-time business intelligence dashboards

---

**🇲🇾 Proudly built for the Malaysian n8n community with ❤️**

*Empowering businesses across Malaysia with seamless payment automation*

**🤝 Developed in partnership with [Sahabat Xpert](https://www.sahabatxpert.my/)** - Your trusted automation specialists for comprehensive digital transformation solutions.