Billplz Getting Started: Account, Keys, and First API Call (2026)

Getting started overview

Integrating with Billplz involves a sequence of steps designed to enable online payment collection. The primary objective is to obtain the necessary credentials and then use them to initiate API calls, such as creating a Bill (payment request). This guide outlines the process from account creation to a successful first API interaction.

Before making any API calls, users need to register for a Billplz account and configure their API keys. These keys are essential for authenticating requests and ensuring secure communication with the Billplz platform. The process generally follows these stages:

1. Account Registration: Signing up for a Billplz account via their official website.
2. API Key Generation: Accessing the Billplz dashboard to create and retrieve API Secret Keys.
3. Environment Setup: Configuring your development environment, potentially including an SDK or an HTTP client.
4. First API Request: Constructing and executing an authenticated API call to create a Bill.

Billplz primarily caters to the Malaysian market, offering integrations with local banks and payment methods. The API documentation provides details regarding the various endpoints and parameters required for different operations, such as creating bills, checking payment statuses, and managing collections. Developers can refer to the Billplz API reference for comprehensive endpoint details.

Create an account and get keys

To begin using Billplz, you must first create an account and generate your API keys. These keys serve as your authentication credentials for all API interactions.

1. Sign up for a Billplz account

Navigate to the Billplz homepage and register for a new account. Follow the on-screen instructions, which typically involve providing basic business information and verifying your email address. Billplz offers a free tier with no monthly fees for basic transactions, making it accessible for initial setup and testing, as outlined on their Billplz pricing page.

2. Access your Billplz dashboard

After successful registration and login, you will be directed to your Billplz merchant dashboard. This dashboard is the central hub for managing your payments, collections, and API settings.

3. Generate API Secret Keys

Within your Billplz dashboard, locate the section for API keys or developer settings. The exact path may vary but typically involves navigating to Settings > Developers or a similar tab. Here, you will find options to generate new API Secret Keys. It is crucial to treat these keys as sensitive information, similar to passwords. The Billplz documentation portal provides specific steps for key generation.

Billplz uses a single API Secret Key for authentication. This key should be kept confidential and never exposed in client-side code. When making API requests, you will typically include this key in the HTTP Basic Authentication header.

Your first request

Once you have obtained your API Secret Key, you can proceed to make your first API call. This example demonstrates creating a Bill, which is a fundamental operation in Billplz for requesting payments.

Prerequisites

• A Billplz API Secret Key.
• An HTTP client (e.g., cURL, Postman) or a Billplz SDK for your preferred language.
• A Billplz Collection ID. Collections are used to group related bills. You can create a new Collection in your Billplz dashboard under the 'Collections' section.

API Endpoint for creating a Bill

The endpoint for creating a Bill is /api/v3/bills (POST request).

Authentication

Billplz uses HTTP Basic Authentication. Your API Secret Key should be used as the username, and the password field should be left empty. For example, if your API key is skey_test_xxxxxxxxxxxx, the Authorization header would be Authorization: Basic BASE64_ENCODED(skey_test_xxxxxxxxxxxx:).

Request Body Example (JSON)

This example creates a bill for RM10.00, associated with a specific collection, and includes callback URLs.

{
  "collection_id": "your_collection_id",
  "email": "[email protected]",
  "mobile": "0123456789",
  "name": "John Doe",
  "amount": 1000, "RM10.00 in cents",
  "callback_url": "https://yourwebsite.com/billplz-callback",
  "description": "Payment for service X",
  "redirect_url": "https://yourwebsite.com/payment-success"
}

cURL Example

Replace YOUR_API_SECRET_KEY and your_collection_id with your actual credentials.

curl -X POST \ 
  https://www.billplz-staging.com/api/v3/bills \ 
  -H 'Authorization: Basic $(echo -n "YOUR_API_SECRET_KEY:" | base64)' \ 
  -H 'Content-Type: application/json' \ 
  -d '{ 
    "collection_id": "your_collection_id", 
    "email": "[email protected]", 
    "mobile": "0123456789", 
    "name": "John Doe", 
    "amount": 1000, 
    "callback_url": "https://yourwebsite.com/billplz-callback", 
    "description": "Payment for service X", 
    "redirect_url": "https://yourwebsite.com/payment-success" 
  }'

PHP SDK Example

If you are using the PHP SDK, the process is streamlined:

require_once 'vendor/autoload.php';

use Billplz\Client;

$client = new Client('YOUR_API_SECRET_KEY');

$response = $client->bill->create([
    'collection_id' => 'your_collection_id',
    'email' => '[email protected]',
    'mobile' => '0123456789',
    'name' => 'John Doe',
    'amount' => 1000, // RM10.00
    'callback_url' => 'https://yourwebsite.com/billplz-callback',
    'description' => 'Payment for service X',
    'redirect_url' => 'https://yourwebsite.com/payment-success'
]);

print_r($response);

For other language SDKs like Ruby, Python, Java, and Node.js, similar methods exist within their respective client libraries. Refer to the Billplz official documentation for specific examples for each SDK.

Expected Response

A successful request will return a JSON object containing details of the created Bill, including a url field which is the payment link you can redirect your users to. The HTTP status code will typically be 200 OK or 201 Created.

{
  "id": "bill_xxxxxxxxxxxx",
  "collection_id": "your_collection_id",
  "paid": false,
  "state": "due",
  "amount": 1000,
  "due_at": null,
  "email": "[email protected]",
  "mobile": "0123456789",
  "name": "John Doe",
  "url": "https://www.billplz.com/bills/bill_xxxxxxxxxxxx",
  "reference_1_label": "Reference 1",
  "reference_1": null,
  "reference_2_label": "Reference 2",
  "reference_2": null,
  "redirect_url": "https://yourwebsite.com/payment-success",
  "callback_url": "https://yourwebsite.com/billplz-callback",
  "description": "Payment for service X"
}

Common next steps

After successfully creating your first Bill, several common next steps enhance your Billplz integration:

• Handle Webhooks: Implement a webhook endpoint to receive real-time notifications about payment status changes (e.g., bill.paid). This is crucial for updating your system when a payment is completed. For general best practices in webhook security, refer to the Twilio webhook security guide.
• Manage Collections: Organize your payments by creating and managing different Billplz Collections for various products, services, or departments.
• Implement Redirect and Callback URLs: Ensure your redirect_url leads users to a success or failure page on your website after payment, and your callback_url correctly processes asynchronous payment notifications.
• Test in Sandbox Environment: Utilize Billplz's staging or sandbox environment for thorough testing without affecting live transactions. The base URL for the staging environment is https://www.billplz-staging.com.
• Error Handling: Implement robust error handling in your application to gracefully manage API errors, network issues, and invalid input.
• Explore Other Endpoints: Familiarize yourself with other Billplz API endpoints, such as retrieving Bill details, checking Collection status, and managing open Bills, as detailed in the Billplz API documentation.
• Recurring Payments: If your business requires subscription models, explore Billplz's features for recurring payments.

Troubleshooting the first call

Encountering issues during your first API call is common. Here's a table of common problems and their solutions:

Quick Reference: Getting Started Steps