billplz

n8n community node to integrate with Billplz payment gateway API

Package Information

Downloads: 5 weekly / 11 monthly
Latest Version: 0.2.8
Author: nmhafiz

Available Nodes

Billplz icon
Billplz
Interact with Billplz payment gateway API

Documentation

n8n-nodes-billplz

npm version
CI/CD Pipeline
License: MIT

⚠️ Legal Disclaimer

This is an UNOFFICIAL community-developed n8n node for Billplz API integration.

  • ❌ NOT affiliated with Billplz Sdn Bhd
  • ❌ NOT endorsed by Billplz
  • ⚠️ Use at your own risk
  • 📚 For educational and development purposes
  • 🛡️ Users are responsible for compliance with Billplz Terms of Service
  • 💼 No warranty provided - use in production at your own discretion

For official Billplz support, please contact Billplz directly.

This is an n8n community node that integrates with Billplz, Malaysia's leading payment gateway. It enables businesses to automate payment collection, bill management, and transaction monitoring within n8n workflows.

Billplz is a comprehensive payment solution that allows Malaysian businesses to collect payments online through various channels including online banking (FPX), credit/debit cards, and e-wallets.

n8n is a fair-code licensed workflow automation platform that helps you automate tasks between different services.

Table of Contents

Installation

Community Nodes (Recommended)

  1. In your n8n instance, go to Settings > Community Nodes
  2. Click Install
  3. Enter @nmhafiz/n8n-nodes-billplz in the npm package field
  4. Accept the risks of installing community nodes
  5. Click Install

The node will be available immediately after installation.

Manual Installation

For npm-based n8n installations:

npm install @nmhafiz/n8n-nodes-billplz

For Docker deployments:

Add this line to your Dockerfile before the font installation:

RUN cd /usr/local/lib/node_modules/n8n && npm install @nmhafiz/n8n-nodes-billplz

For n8n Cloud:

Community nodes are not supported on n8n Cloud. Use the self-hosted version instead.

Quick Start

  1. Set up credentials: Add your Billplz API credentials in n8n
  2. Create a collection: Organize your bills by creating collections
  3. Generate bills: Create payment requests for your customers
  4. Monitor payments: Track transaction status and handle webhooks

Operations

📁 Collection Management

  • Create Collection: Organize bills into collections
  • Get Collection: Retrieve collection details
  • Get All Collections: List all collections with pagination

🧾 Bill Operations

  • Create Bill: Generate payment requests
  • Get Bill: Retrieve bill details and payment status
  • Delete Bill: Remove unpaid bills

💳 Transaction Tracking

  • Get All Transactions: Monitor payment history for bills

🏦 Banking Services

  • Get FPX Banks: Retrieve available online banking options

Credentials

Required Information

  1. Environment:

    • Production: For live payments
    • Sandbox: For testing (recommended for development)

  2. API Secret Key: Your Billplz API secret key

  3. X-Signature Key: For webhook signature verification (optional but recommended)

Getting Your Credentials

  1. Log in to your Billplz Dashboard
  2. Navigate to Settings > API
  3. Copy your API Secret Key
  4. For webhook verification, also copy your X-Signature Key

Setting Up in n8n

  1. Go to Credentials > New
  2. Search for "Billplz API"
  3. Fill in your credentials
  4. Test the connection
  5. Save

Examples

Basic Bill Creation

{
  "resource": "bill",
  "operation": "create",
  "collectionId": "col_123456789",
  "email": "customer@example.com",
  "name": "John Doe",
  "amount": 5000,
  "callbackUrl": "https://yoursite.com/webhook",
  "description": "Payment for Order #12345"
}

E-commerce Integration Workflow

  1. Trigger: New order received
  2. Billplz: Create bill for order amount
  3. Email: Send payment link to customer
  4. Webhook: Handle payment confirmation
  5. Database: Update order status

Subscription Management

  1. Schedule: Monthly trigger
  2. Database: Get active subscribers
  3. Billplz: Create bills for each subscriber
  4. Email: Send payment reminders
  5. Monitor: Track payment status

API Documentation

For detailed API documentation, including all parameters, response formats, and advanced usage examples, see our API Documentation.

Development

Prerequisites

  • Node.js 16+
  • npm or yarn
  • n8n development environment

Setup

# Clone the repository
git clone https://github.com/nmhafiz/n8n-nodes-billplz.git
cd n8n-nodes-billplz

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run linting
npm run lint

Project Structure

n8n-nodes-billplz/
├── nodes/
│   └── Billplz/
│       ├── Billplz.node.ts          # Main node implementation
│       ├── types.ts                 # TypeScript interfaces
│       ├── constants.ts             # Configuration constants
│       ├── validators.ts            # Input validation
│       ├── operations.ts            # Operation handlers
│       └── GenericFunctions.ts     # API utilities
├── credentials/
│   └── BillplzApi.credentials.ts    # Credential configuration
├── tests/                           # Test suites
├── docs/                           # Documentation
└── package.json

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

Code Quality

This project maintains high code quality through:

  • TypeScript: Full type safety
  • ESLint: Code linting and formatting
  • Jest: Comprehensive testing
  • Prettier: Code formatting
  • GitHub Actions: Automated CI/CD

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Contribution Steps

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests for new functionality
  5. Ensure all tests pass
  6. Submit a pull request

Compatibility

  • n8n: Version 1.0+
  • Node.js: 16.x, 18.x, 20.x
  • Billplz API: v4

Changelog

v0.1.4 (Latest)

  • ✨ Enhanced code structure and maintainability
  • 🔒 Improved error handling and validation
  • 🧪 Added comprehensive testing suite
  • 📚 Enhanced documentation
  • 🚀 Added CI/CD pipeline
  • 🐛 Removed non-functional interfaces

v0.1.3

  • 🔧 Bug fixes and improvements
  • 📝 Updated documentation

v0.1.2

  • ➕ Added transaction operations
  • 🏦 Added FPX bank listing

v0.1.1

  • 🎉 Initial release
  • 📁 Collection management
  • 🧾 Bill operations

Terms of Use & Compliance

🔒 Security & Compliance

Before using this node in production:

  1. Review Billplz Terms of Service: Ensure your usage complies with Billplz's Terms of Service
  2. API Usage Limits: Respect Billplz API rate limits and usage policies
  3. Data Protection: Implement proper data handling according to Malaysian PDPA and other applicable laws
  4. Security Best Practices:
    • Store API credentials securely
    • Use HTTPS for all webhook endpoints
    • Validate webhook signatures
    • Implement proper error handling
  5. API Compliance: Follow Billplz API guidelines and rate limits
  6. Testing: Always test in sandbox environment before production use

📋 User Responsibilities

By using this community node, you agree that:

  • ✅ You have a valid Billplz account and API access
  • ✅ You will comply with all applicable laws and regulations
  • ✅ You understand this is an unofficial integration
  • ✅ You will not hold the maintainers liable for any issues
  • ✅ You will use the node responsibly and ethically

🚫 Prohibited Uses

  • ❌ Fraudulent or illegal activities
  • ❌ Violating Billplz's acceptable use policies
  • ❌ Excessive API calls that may impact service availability
  • ❌ Using the node for unauthorized payment processing

🛡️ Warranty Disclaimer

THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. THE AUTHORS AND CONTRIBUTORS DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

Support

📞 Support Channels

For this community node:

For official Billplz support:

For n8n platform support:

Getting Help

Common Issues

  • Authentication errors: Verify your API credentials
  • Validation errors: Check input parameter formats
  • Network errors: Ensure API endpoints are accessible

Resources

License

MIT License - see the LICENSE file for details.

Acknowledgments

  • Thanks to the n8n team for the excellent automation platform
  • Thanks to Billplz for providing a robust payment API
  • Thanks to all contributors who help improve this project

Made with ❤️ for the Malaysian developer community

Discussion