Billplz Integration Guide: How to Accept Payments on Your Malaysian Business Website

Billplz is one of the most affordable and straightforward payment gateways for Malaysian businesses. With no setup fees, no monthly charges, and a simple pay-per-transaction model, it's ideal for SMEs, schools, associations, and any business that needs to collect payments online.

This guide walks you through everything you need to know—from creating your account to accepting your first payment.

What Is Billplz?

Billplz is a Malaysian payment gateway that lets you collect payments through:

• FPX (Online Banking) — Direct bank transfers from all major Malaysian banks
• E-Wallets — GrabPay, Touch 'n Go, and more
• Bill Payment — Pay at 7-Eleven, KK Mart, and other outlets
• Bank Transfer — Manual bank transfer with automatic reconciliation
• Card Payments — Visa and Mastercard (subject to approval)

Why Choose Billplz?

Cost Structure:

• No setup fee
• No monthly fee
• No minimum commitment
• FPX: RM0.70 per transaction
• E-wallets: RM1.00 per transaction
• Card payments: 2.8% + RM0.50 per transaction
• Bank transfer collection: Free

Key Advantages:

• Pay only when you receive payments
• Simple API that developers can integrate quickly
• Bill payment feature unique to Billplz (customers pay at convenience stores)
• Transparent pricing with no hidden costs
• Malaysian company with local support
• Fast settlement (next business day for FPX)

Who It's Best For:

• SMEs and small businesses
• Schools and educational institutions collecting fees
• Associations and clubs collecting membership fees
• Event organizers collecting registration payments
• Landlords collecting rent
• Freelancers and service providers invoicing clients

Before You Start: What You Need

Business Requirements

1. Registered Business

   • SSM-registered business (sole proprietor, partnership, or Sdn Bhd)
   • Business bank account with a Malaysian bank
   • Business email address

2. Website Requirements

   • Live website with clear business information
   • SSL certificate (HTTPS enabled)
   • Contact page with phone number and email
   • Terms and conditions page
   • Privacy policy page
   • Product or service catalog (or description of what you're selling)

3. Documents to Prepare

   • SSM certificate (or business registration document)
   • Director/owner IC (front and back)
   • Bank statement (latest 3 months)
   • Company logo
   • Website URL

Technical Requirements

• Basic understanding of how APIs work (or a developer who can help)
• Web hosting that supports PHP, Node.js, Python, or any backend language
• Ability to configure environment variables on your server
• HTTPS on your website (required for security)

Step 1: Create Your Billplz Account

Registration Process

1. Visit billplz.com and click "Sign Up"
2. Fill in business details:
   • Business name (as registered with SSM)
   • Business registration number
   • Business address
   • Contact person name and email
   • Phone number
3. Upload required documents:
   • SSM certificate
   • Director/owner IC
   • Bank statement
4. Connect your bank account:
   • Bank name
   • Account number
   • Account holder name (must match business name)
5. Wait for approval — typically 1-3 business days

Account Verification

Billplz will verify your documents and business registration. You may be asked for:

• Additional business documents
• Proof of address
• Clarification on business activities

Once approved, you'll receive an email confirmation and can access your Billplz dashboard.

Understanding Your Dashboard

Your Billplz dashboard gives you access to:

• Collections — Create payment pages and bills
• Transactions — View all payments received
• Payouts — Track settlements to your bank account
• Reports — Download transaction and settlement reports
• Settings — API keys, callback URLs, and account configuration

Step 2: Understand Billplz Concepts

Before integrating, understand these key Billplz concepts:

Collections

A Collection is a payment page that groups related bills together. Think of it as a category for the type of payment you're collecting.

Examples:

• "Website Store Orders" — for product purchases
• "Class Registration Fees" — for school enrollments
• "Monthly Membership" — for club dues

You create collections in your dashboard or via API.

Bills

A Bill is a single payment request within a collection. When a customer needs to pay, you create a bill with:

• Customer name and email
• Amount to pay
• Description of what they're paying for
• Reference number (your order or invoice number)

The bill generates a payment link you send to the customer.

Callbacks (Webhooks)

A Callback is a URL that Billplz calls to notify your website when a payment is completed. This is how your website knows an order has been paid.

How it works:

1. Customer pays on Billplz payment page
2. Billplz processes the payment
3. Billplz sends a POST request to your callback URL
4. Your website receives payment confirmation
5. Your website updates the order status

Important: Callbacks are server-to-server communication. They happen in the background and are more reliable than redirect-based confirmation.

Redirects

A Redirect is the URL customers are sent back to after completing payment on the Billplz payment page.

You should set up two redirect URLs:

• Success page — Where customers land after successful payment (e.g., yourwebsite.com/payment/success)
• Failed page — Where customers land if payment fails (e.g., yourwebsite.com/payment/failed)

Step 3: Get Your API Keys

1. Log in to your Billplz dashboard

2. Go to Settings > API Keys

3. You'll see two sets of keys:

   • Sandbox (Test) — For development and testing
   • Production (Live) — For real transactions

4. Copy and save these securely:

   • API Key — Your authentication key
   • Collection ID — Identifies which collection to use
   • X Signature Key — Used to verify callback authenticity

Security note: Never expose your API keys or X Signature key in client-side code (HTML, JavaScript). Always keep them on your server.

Step 4: Integration Methods

Billplz supports several integration methods. Choose the one that fits your technical capability and business needs.

Method 1: Payment Link (No Coding Required)

Best for: Freelancers, small businesses, one-time payments

How it works:

1. Create a collection in your Billplz dashboard
2. Create a bill manually in the dashboard
3. Copy the payment link
4. Send the link to your customer via WhatsApp, email, or SMS
5. Customer clicks the link and pays

Pros:

• No technical knowledge needed
• Set up in minutes
• Works for any business type

Cons:

• Manual bill creation for each payment
• No automatic order processing
• Customer leaves your website to pay

When to use: Starting out, low transaction volume, invoicing individual clients

Method 2: Hosted Payment Page (Basic Integration)

Best for: Small businesses with a website, simple online stores

How it works:

1. Your website has a "Pay Now" button
2. When clicked, your server creates a bill via Billplz API
3. Customer is redirected to Billplz's hosted payment page
4. Customer completes payment on Billplz
5. Billplz redirects customer back to your website
6. Billplz sends callback to your server to confirm payment

What you need:

• A server-side script (PHP, Node.js, etc.) to create bills
• A callback handler to receive payment confirmations
• Success and failure pages on your website

Pros:

• Automated bill creation
• Payment confirmation via callback
• Professional checkout experience
• Billplz handles payment security

Cons:

• Requires basic server-side coding
• Customer briefly leaves your website for payment

When to use: Most small business websites, event registrations, service bookings

Method 3: API Integration (Advanced)

Best for: E-commerce stores, high-volume businesses, custom applications

How it works:

1. Full API integration with your website's checkout
2. Bills created automatically when customers check out
3. Webhooks handle payment status updates in real time
4. Customer experience is seamless

Pros:

• Fully automated payment processing
• Real-time order status updates
• Scalable for high transaction volumes
• Complete control over customer experience

Cons:

• Requires developer expertise
• More complex to implement
• Needs ongoing maintenance

When to use: Online stores, SaaS platforms, businesses with custom web applications

Step 5: Setting Up Hosted Payment Page (Detailed Guide)

This is the most common integration method for small business websites. Here's a detailed walkthrough.

5.1 Install Dependencies

For PHP websites:

composer require billplz/billplz-php

For Node.js websites:

npm install billplz

5.2 Configure Environment Variables

Create a .env file on your server (never commit this to version control):

BILLPLZ_API_KEY=your_api_key_here
BILLPLZ_COLLECTION_ID=your_collection_id_here
BILLPLZ_X_SIGNATURE_KEY=your_x_signature_key_here
BILLPLZ_ENVIRONMENT=sandbox

Change BILLPLZ_ENVIRONMENT to production when you go live.

5.3 Create a Bill (Server-Side)

PHP Example:

require 'vendor/autoload.php';

use Billplz\Client;

$client = Client::make(
    getenv('BILLPLZ_API_KEY'),
    getenv('BILLPLZ_X_SIGNATURE_KEY'),
    getenv('BILLPLZ_ENVIRONMENT') === 'production'
);

$collection = $client->collection();

$bill = $client->bill()->create(
    getenv('BILLPLZ_COLLECTION_ID'),
    'customer@email.com',       // Customer email
    'Customer Name',            // Customer name
    'ORDER-12345',              // Your reference number
    'Product Purchase',         // Description
    15000,                      // Amount in cents (RM150.00)
    [
        'callback_url' => 'https://yourwebsite.com/payment/callback',
        'redirect_url' => [
            'return' => 'https://yourwebsite.com/payment/success',
        ],
    ]
);

// Redirect customer to Billplz payment page
header('Location: ' . $bill['url']);
exit;

Node.js Example:

const billplz = require('billplz');

const client = billplz({
  apiKey: process.env.BILLPLZ_API_KEY,
  xSignatureKey: process.env.BILLPLZ_X_SIGNATURE_KEY,
  isProduction: process.env.BILLPLZ_ENVIRONMENT === 'production',
});

async function createBill() {
  const bill = await client.bill.create({
    collectionId: process.env.BILLPLZ_COLLECTION_ID,
    email: 'customer@email.com',
    name: 'Customer Name',
    reference1Label: 'Order',
    reference1: 'ORDER-12345',
    description: 'Product Purchase',
    amount: 15000, // Amount in cents (RM150.00)
    callbackUrl: 'https://yourwebsite.com/payment/callback',
    redirectUrl: {
      return: 'https://yourwebsite.com/payment/success',
    },
  });

  return bill;
}

5.4 Handle the Callback (Webhook)

When a customer completes payment, Billplz sends a POST request to your callback URL. You must:

1. Verify the signature — Ensure the callback is really from Billplz
2. Process the payment — Update your order status
3. Return HTTP 200 — Acknowledge receipt

PHP Callback Handler:

require 'vendor/autoload.php';

use Billplz\Client;
use Billplz\Webhook;

$client = Client::make(
    getenv('BILLPLZ_API_KEY'),
    getenv('BILLPLZ_X_SIGNATURE_KEY'),
    getenv('BILLPLZ_ENVIRONMENT') === 'production'
);

$webhook = new Webhook(getenv('BILLPLZ_X_SIGNATURE_KEY'));
$data = $webhook->verify();

if ($data['paid'] === true) {
    // Payment successful
    $billId = $data['id'];
    $amount = $data['amount']; // In cents
    $reference = $data['reference_1'];

    // Update your database
    // Mark order as paid
    // Send confirmation email to customer
}

http_response_code(200);

5.5 Create Payment Success and Failure Pages

Success page (payment/success):

• Thank the customer for their payment
• Show order details and reference number
• Provide next steps (delivery timeline, contact info)
• Include a receipt or invoice download link

Failure page (payment/failed):

• Explain that the payment was not completed
• Offer the option to try again
• Provide alternative payment methods (e.g., WhatsApp for manual bank transfer)
• Include your contact information for assistance

Step 6: Testing Your Integration

Sandbox Testing

Before going live, test thoroughly in the sandbox environment:

1. Create a sandbox bill and verify it redirects to the test payment page
2. Complete a test payment using sandbox credentials
3. Verify the callback is received and processed correctly
4. Check the redirect sends customers to the correct page
5. Test payment failure scenarios
6. Test on mobile devices to ensure the payment page works well

Testing Checklist

• [ ] Bill creation works without errors
• [ ] Payment page displays correct amount and description
• [ ] Successful payment triggers callback correctly
• [ ] Callback signature verification passes
• [ ] Order status updates in your database
• [ ] Customer is redirected to success page
• [ ] Failed payment redirects to failure page
• [ ] Email notifications are sent
• [ ] Mobile payment flow works smoothly
• [ ] Amount calculations are correct (remember: Billplz uses cents)

Step 7: Go Live

Switching to Production

1. Update your environment variables:

   • Change BILLPLZ_API_KEY to your production API key
   • Change BILLPLZ_COLLECTION_ID to your production collection ID
   • Change BILLPLZ_ENVIRONMENT to production

2. Test with a real transaction:

   • Create a small test payment (RM1.00)
   • Complete the payment
   • Verify everything works as expected
   • Check that funds appear in your settlement report

3. Monitor closely:

   • Watch for callback failures
   • Verify settlement reports match your records
   • Check customer feedback on the payment experience
   • Monitor transaction success rates

Post-Launch Tasks

• Set up email notifications for new payments
• Configure daily or weekly settlement reports
• Create a process for handling payment disputes
• Train your customer service team on common payment issues
• Set up accounting software integration (if applicable)

Common Integration Issues and Solutions

Issue 1: Callback Not Received

Symptoms: Customer paid but order shows unpaid.

Causes:

• Callback URL is incorrect
• Server firewall blocking Billplz requests
• SSL certificate issues
• Server returns non-200 response

Solutions:

• Double-check callback URL in your code
• Ensure your server accepts POST requests from Billplz IP addresses
• Verify SSL certificate is valid
• Check server logs for incoming requests
• Use a tool like webhook.site to test callback delivery

Issue 2: Signature Verification Failed

Symptoms: Callback received but signature doesn't match.

Causes:

• Wrong X Signature key
• Incorrect data parsing
• Encoding issues

Solutions:

• Verify you're using the correct X Signature key (sandbox vs. production)
• Follow the exact verification process in Billplz documentation
• Ensure data is parsed correctly from the POST body

Issue 3: Amount Mismatch

Symptoms: Payment amount doesn't match order total.

Cause: Billplz uses cents (multiply RM by 100).

Solution: Always convert Ringgit to cents before sending to Billplz:

RM150.00 = 15000 cents
RM1,200.00 = 120000 cents

Issue 4: Redirect Not Working

Symptoms: Customer not returned to your website after payment.

Causes:

• Redirect URL not configured
• URL is not publicly accessible
• HTTPS certificate issues

Solutions:

• Configure redirect_url in bill creation
• Ensure URLs are publicly accessible (not localhost)
• Verify HTTPS is working correctly

Issue 5: Duplicate Payment Processing

Symptoms: Customer charged twice or order processed multiple times.

Causes:

• Callback received multiple times (normal behavior—Billplz retries)
• No idempotency check in your code

Solution: Always check if a bill has already been processed before updating your database:

// Before processing, check if this bill ID was already processed
if (isBillAlreadyProcessed($data['id'])) {
    http_response_code(200);
    exit;
}

Security Best Practices

1. Never Expose API Keys

• Store keys in environment variables, not in code
• Never commit .env files to version control
• Use different keys for development and production

2. Always Verify Callbacks

• Verify the X Signature on every callback
• Never trust callback data without verification
• This prevents fake payment confirmations

3. Use HTTPS Everywhere

• Your entire website should use HTTPS
• Billplz requires HTTPS for callback and redirect URLs
• Free SSL: Let's Encrypt

4. Implement Idempotency

• Billplz may send the same callback multiple times
• Your code should handle duplicate callbacks gracefully
• Check if a bill has been processed before taking action

5. Validate Amounts

• Always verify the callback amount matches your order amount
• Don't trust the amount in the redirect URL parameters
• Compare against your database records

6. Log Everything

• Log all API requests and responses
• Log all callbacks received
• Keep logs for at least 6 months for dispute resolution

Billplz Dashboard Tips

Setting Up Multiple Collections

Create separate collections for different payment types:

• "Online Store" — for product purchases
• "Service Invoices" — for professional services
• "Event Registration" — for workshops and events

This makes reporting and reconciliation easier.

Using the Billplz App

Download the Billplz mobile app to:

• Receive instant payment notifications
• View daily settlement reports
• Monitor transaction success rates
• Access reports on the go

Automated Reports

Set up automated email reports in your dashboard:

• Daily transaction summary
• Weekly settlement report
• Monthly revenue report

These help you stay on top of your finances without manual checking.

Comparing Billplz with Alternatives

| Feature | Billplz | Stripe | iPay88 | ToyyibPay | |---------|---------|--------|--------|-----------| | Setup Fee | Free | Free | RM600-1,200 | Free | | Monthly Fee | Free | Free | RM600/year | Free | | FPX Fee | RM0.70 | 1.0% (max RM10) | RM1.00-1.50 | RM1.00 | | Card Fee | 2.8% + RM0.50 | 3.0% + RM0.50 | 2.8-3.5% | N/A | | Bill Payment | Yes | No | No | No | | Settlement | Next day | 7 days | T+3 to T+7 | Next day | | API Quality | Good | Excellent | Average | Basic |

When to choose Billplz:

• You want the lowest FPX transaction fees
• You need bill payment (convenience store) option
• You want zero fixed costs
• You're a small business or organization

When to consider alternatives:

• You need international card processing (use Stripe)
• You need comprehensive e-wallet support (use iPay88)
• You need subscription management (use Stripe)
• You need high-value flat-rate transactions (use ToyyibPay)

How Aivoranex Can Help

At Aivoranex, we integrate Billplz (and other payment gateways) into business websites:

What We Handle

• Billplz account setup guidance
• Collection and bill configuration
• Server-side integration development
• Callback and webhook implementation
• Payment success/failure page design
• Mobile-responsive checkout flow
• Security implementation (HTTPS, signature verification)
• Testing and quality assurance
• Post-launch monitoring and support

Our Payment Integration Package

Starting from RM3,500, we deliver a complete payment-ready website:

• Professional business website
• Billplz (or other gateway) integration
• Automated payment processing
• Email notifications for orders
• Mobile-optimized checkout
• Google Analytics setup
• SEO optimization

Already Have a Website?

We also offer standalone payment gateway integration starting from RM1,500 if you already have a website and just need to add payment functionality.

Contact us today to discuss your payment integration needs.

Frequently Asked Questions

How long does Billplz approval take?

Typically 1-3 business days. Some applications may take up to a week if additional documents are required.

Is Billplz safe and regulated?

Yes. Billplz is registered with Bank Negara Malaysia and complies with all Malaysian financial regulations. They use bank-grade encryption and security practices.

Can I use Billplz without a website?

Yes. You can create bills manually in the dashboard and send payment links via WhatsApp, email, or SMS. This works well for freelancers and service providers.

What happens if a payment fails?

The customer can try again using the same bill link. You can also create a new bill and send a fresh link. Billplz does not charge for failed transactions.

How do I handle refunds?

Process refunds through your Billplz dashboard. Go to the transaction, click "Refund", and specify the amount. Refunds are credited back to the customer's bank account within 3-7 business days.

Can Billplz handle recurring payments?

Billplz does not have built-in subscription management. For recurring payments, you'll need to create bills manually or programmatically for each billing cycle. If you need automated subscriptions, consider Stripe.

What currencies does Billplz support?

Billplz primarily supports Malaysian Ringgit (MYR). For international transactions, consider Stripe or Razorpay.

Conclusion

Billplz is one of the best payment gateway options for Malaysian businesses. Its zero-cost setup, affordable per-transaction fees, and simple API make it accessible for businesses of any size.

Whether you're a freelancer sending invoices, a shop selling products online, or a school collecting fees, Billplz provides the tools you need to accept payments professionally.

Start with the simple payment link method, and upgrade to hosted payment page integration as your business grows. The key is to start accepting digital payments now—every day you wait is a day of potential lost sales.

Ready to add Billplz to your website?

Contact Aivoranex for professional Billplz integration. From setup to testing to launch, we handle everything so you can focus on running your business.