Billplz Authentication: API Keys & Secure Access (2026)

Authentication overview

Billplz secures access to its API through a straightforward authentication mechanism primarily relying on API keys. This approach ensures that only authorized applications and users can initiate payment requests, manage invoices, and interact with other Billplz services. The Billplz API is designed for Malaysian businesses, offering a programmatic way to integrate online payment collection and management directly into applications.

Authentication credentials, specifically secret API keys, are generated and managed within the Billplz merchant dashboard. These keys serve as a unique identifier and secret for an application, allowing the Billplz system to verify the legitimacy of incoming API requests. All communications with the Billplz API must occur over HTTPS, which encrypts data in transit and protects sensitive information, including authentication credentials, from interception. This practice aligns with general recommendations for securing web APIs, as detailed by the Mozilla Developer Network's guide on HTTP security.

The system supports server-side integrations where API keys are securely stored and used to make direct calls to the Billplz API. Client-side applications should avoid directly exposing API keys. Instead, they should route requests through a secure backend server that can handle authentication securely. This architectural pattern is a standard security practice for payment gateways and other APIs handling sensitive data, as outlined in Stripe's security checklist for developers.

Billplz offers various API endpoints for creating bills, checking bill status, managing collections, and handling various payment-related operations. Each API call requiring authentication expects the secret key to be provided in a specific format, typically via HTTP Basic Authentication. This mechanism provides a balance between ease of implementation for developers and the necessary security measures for financial transactions.

Supported authentication methods

Billplz primarily uses API keys for authentication, implemented via HTTP Basic Authentication. This method involves encoding the API key and sending it in the Authorization header of each API request. The simplicity of HTTP Basic Authentication makes it accessible for developers to integrate while maintaining a foundational level of security when combined with HTTPS.

A secret API key is a unique string generated for each Billplz account. This key acts as the password for API access and must be kept confidential. When making an API request, the secret key is used as the username in the Basic Authentication header, with an empty string often used as the password, or sometimes the secret key is used for both username and password, depending on the specific implementation details described in the Billplz API documentation.

The following table summarizes the primary authentication method supported by Billplz:

For development and testing, Billplz also provides a sandbox environment where developers can use test API keys. These test keys allow developers to simulate transactions and API interactions without affecting live accounts or processing real payments. This separation of environments is crucial for safe and effective API integration, as highlighted in the PayPal developer onboarding guide, which emphasizes the use of sandbox credentials.

Getting your credentials

To authenticate with the Billplz API, you need to obtain your secret API key from your Billplz merchant account. The process typically involves logging into your Billplz dashboard and navigating to the settings or API section. The steps are as follows:

1. Log in to your Billplz Account: Access your merchant dashboard at Billplz's official website.
2. Navigate to Settings/API Keys: Look for a section related to 'Settings', 'API', or 'Developer' within your dashboard. The exact path may vary slightly but is generally intuitive.
3. Generate/Retrieve API Key: Within the API section, you will find options to view existing API keys or generate new ones. Billplz usually provides both a 'Secret Key' and a 'Collection ID' or similar identifiers. The 'Secret Key' is the primary credential used for authentication.
4. Copy Your Secret Key: Carefully copy the generated secret key. It is crucial to treat this key as sensitive information, similar to a password. Once generated, some platforms may only show the key once, requiring regeneration if lost.

Billplz typically provides separate API keys for its live (production) environment and its sandbox (staging/development) environment. Ensure you are using the correct key for the environment you are targeting. Using a live key in a development environment or vice versa will result in authentication failures. The Billplz API documentation provides specific instructions for obtaining and managing these keys, including details on how to regenerate keys if they are compromised or if you need to rotate them for security purposes.

It is recommended to generate a new API key for each application or service that integrates with Billplz, rather than reusing a single key across multiple systems. This practice improves security by limiting the scope of compromise if a particular key is exposed and simplifies key rotation and revocation processes.

Authenticated request example

When making an authenticated request to the Billplz API, the secret API key is typically included in the HTTP Authorization header using Basic Authentication. This involves encoding your API key (and an optional password, often empty) in Base64 format.

Here's an example of how to construct an authenticated request using the curl command-line tool, which demonstrates the underlying HTTP request structure. This example assumes you are making a request to the /api/v3/bills endpoint to create a new bill.

curl -X POST \ 
  https://www.billplz-sandbox.com/api/v3/bills \ 
  -u "YOUR_SECRET_KEY:" \ 
  -H "Content-Type: application/json" \ 
  -d '{ 
    "collection_id": "COLLECTION_ID", 
    "email": "[email protected]", 
    "name": "John Doe", 
    "amount": 2000, 
    "description": "Payment for services", 
    "callback_url": "https://your-website.com/billplz-callback", 
    "redirect_url": "https://your-website.com/payment-success" 
  }'

In this example:

• -X POST specifies the HTTP method.
• https://www.billplz-sandbox.com/api/v3/bills is the target API endpoint. Note the use of the sandbox domain for testing.
• -u "YOUR_SECRET_KEY:" is where the Basic Authentication credentials are provided. Replace YOUR_SECRET_KEY with your actual Billplz secret key. The colon : after the key signifies an empty password, which is a common convention for API key-based Basic Authentication schemes.
• -H "Content-Type: application/json" sets the request header to indicate that the body is in JSON format.
• -d '{...}' contains the JSON payload for creating a bill. You would replace COLLECTION_ID with a valid collection ID from your Billplz account.

When using Billplz's official SDKs (PHP, Ruby, Python, Java, Node.js), the SDKs abstract away the details of constructing the HTTP Basic Authentication header. Developers typically initialize the SDK with their secret key, and the SDK handles the authentication for subsequent API calls. For instance, in a Python SDK, the initialization might look like:

import billplz

billplz.api_key = "YOUR_SECRET_KEY"
billplz.x_signature = "YOUR_X_SIGNATURE_KEY" # If applicable for webhooks
billplz.sandbox = True # Set to False for production

bill = billplz.Bill.create(
    collection_id="COLLECTION_ID",
    email="[email protected]",
    name="John Doe",
    amount=2000,
    description="Payment for services",
    callback_url="https://your-website.com/billplz-callback",
    redirect_url="https://your-website.com/payment-success"
)

print(bill)

This example demonstrates how SDKs simplify the process, allowing developers to focus on the business logic rather than the low-level HTTP details. For detailed examples across different languages, refer to the Billplz API documentation.

Security best practices

Securing your Billplz integration is paramount to protect sensitive payment information and maintain the integrity of your financial operations. Adhering to security best practices helps prevent unauthorized access and data breaches.

1. Keep API Keys Confidential: Your Billplz secret API key is equivalent to a password. Never hardcode it directly into client-side code (e.g., JavaScript in a web browser or mobile app). Store it securely on your server or in environment variables. If a key is compromised, immediately revoke it from your Billplz dashboard and generate a new one.
2. Use HTTPS for All API Communications: Always ensure that all communications with the Billplz API occur over HTTPS (TLS). This encrypts data in transit, protecting your API key and other sensitive information from eavesdropping. Billplz enforces HTTPS, but it's good practice to verify your client applications are configured to use secure connections.
3. Implement Server-Side Authentication: All API calls that require your secret key should originate from your secure backend server. Client-side applications should communicate with your backend, which then relays authenticated requests to Billplz. This prevents your secret key from being exposed to end-users or malicious actors who might inspect client-side code.
4. Restrict API Key Permissions (if applicable): While Billplz's primary authentication uses a single secret key, if future versions or specific features offer granular permissions for API keys, use the principle of least privilege. Grant only the necessary permissions for each key based on the function of the application using it.
5. Regularly Rotate API Keys: Periodically rotate your API keys, typically every 90 days or annually, as a proactive security measure. This limits the window of exposure if a key is compromised without your immediate knowledge. The Billplz dashboard should provide functionality for key rotation.
6. Validate Webhook Signatures: If your integration uses Billplz webhooks for real-time notifications (e.g., payment status updates), always verify the authenticity of incoming webhooks. Billplz sends a signature (e.g., X-Signature header) with each webhook event. Compare this signature with one you generate using your webhook secret key and the webhook payload. This ensures that the webhook originated from Billplz and has not been tampered with. Refer to the Billplz documentation for specific instructions on webhook signature verification.
7. Monitor API Usage: Regularly monitor your Billplz API usage for any unusual activity or spikes in requests that could indicate unauthorized access or abuse. Implement logging and alerting for authentication failures or suspicious patterns.
8. Secure Your Development Environment: Ensure that your development and staging environments are as secure as your production environment. Avoid using production API keys in non-production environments. Use environment variables or secure configuration management tools to store credentials.
9. Comply with PCI DSS: As Billplz is a payment gateway, ensure your application adheres to relevant Payment Card Industry Data Security Standard (PCI DSS) requirements, especially if you handle or store any cardholder data. Billplz itself is PCI DSS compliant, but your integration must also maintain compliance. The Billplz documentation can provide guidance on your responsibilities.