API quick-start guide

This guide walks you through your first Billplz API call: from authentication to creating a bill and verifying payment. By the end, you'll have a working bill with a payment URL your customer can use. The entire process takes about 5 minutes.

All examples use the sandbox environment so you can test safely without processing real payments.

Before you begin

• A Billplz sandbox account. See Create a sandbox account.
• Your sandbox Secret Key. See Get your Billplz Secret key.
• A Collection ID from your sandbox dashboard. See Create a Collection ID.
• A terminal or HTTP client (e.g., cURL, Postman, Insomnia).

All API requests must be made over HTTPS,, plain HTTP requests will fail. The Billplz API only accepts Malaysian Ringgit (MYR), and amounts are expressed in the smallest currency unit (cents).

Step 1: Test your authentication

Run the following cURL command, replacing {your_secret_key} with your sandbox Secret Key:

curl https://www.billplz-sandbox.com/api/v4/webhook_rank \
  -u {your_secret_key}:

If authentication succeeds, you'll receive a JSON response:

{
  "rank": 0.0
}

If you see an Unauthorized response, your Secret Key is incorrect. Confirm you're using the key from your sandbox dashboard, not production. See Get your Billplz Secret key.

Step 2: Create a bill

Use the Create a Bill endpoint to generate a payment request. Replace {your_secret_key} and {your_collection_id} with your own values:

curl https://www.billplz-sandbox.com/api/v3/bills \
  -u {your_secret_key}: \
  -d collection_id="{your_collection_id}" \
  -d email="[email protected]" \
  -d name="Ali Ahmad" \
  -d amount=500 \
  -d description="Test payment" \
  -d callback_url="https://example.com/webhook/" \
  -d redirect_url="https://example.com/redirect/"

A successful response returns the bill object:

{
  "id": "8X0Iyzaw",
  "collection_id": "inbmmepb",
  "paid": false,
  "state": "due",
  "amount": 500,
  "paid_amount": 0,
  "due_at": "2026-04-23",
  "email": "[email protected]",
  "mobile": null,
  "name": "Ali Ahmad",
  "url": "https://www.billplz-sandbox.com/bills/8X0Iyzaw",
  "reference_1_label": "Reference 1",
  "reference_1": null,
  "reference_2_label": "Reference 2",
  "reference_2": null,
  "redirect_url": "https://example.com/redirect/",
  "callback_url": "https://example.com/webhook/",
  "description": "Test payment"
}

Key fields to note:

• id — The unique Bill ID. Use this to check the bill's status later.
• url — The payment page URL. Redirect your customer here to pay.
• amount — Expressed in the smallest currency unit (cents). 500 = RM 5.00.

Step 3: Open the payment page

Copy the url value from the response and open it in your browser. In sandbox, you'll see a simulated payment page where you can complete the payment using test bank credentials.

After completing the simulated payment, Billplz does two things (in no fixed order):

1. Sends a POST request to your callback_url with the bill's updated status.
2. Redirects the customer to your redirect_url (if provided) with the bill ID and payment status as query parameters.

Your system should handle both independently and prevent duplicate updates.

Step 4: Verify the payment

After paying, confirm the bill status by calling the Get a Bill endpoint:

curl https://www.billplz-sandbox.com/api/v3/bills/8X0Iyzaw \
  -u {your_secret_key}:

The response now shows "paid": true and "state": "paid":

{
  "id": "8X0Iyzaw",
  "collection_id": "inbmmepb",
  "paid": true,
  "state": "paid",
  "amount": 500,
  "paid_amount": 500,
  "due_at": "2026-04-23",
  "email": "[email protected]",
  "mobile": null,
  "name": "Ali Ahmad",
  "url": "https://www.billplz-sandbox.com/bills/8X0Iyzaw",
  "reference_1_label": "Reference 1",
  "reference_1": null,
  "reference_2_label": "Reference 2",
  "reference_2": null,
  "redirect_url": "https://example.com/redirect/",
  "callback_url": "https://example.com/webhook/",
  "description": "Test payment"
}

What's next

You've completed the core payment flow: create a bill, collect payment, and verify the result. Here's what to set up before going live:

Secure your callbacks: Enable X Signature key verification to confirm that callbacks genuinely come from Billplz. See Enable X Signature key verification.

Handle callbacks properly: Set up your server to receive and process Billplz's POST callbacks reliably. See Webhook and callback setup.

Switch to production: When you're ready to accept real payments, swap your sandbox credentials for your production Secret Key and Collection ID, and change the base URL from https://www.billplz-sandbox.com/api/ to https://www.billplz.com/api/. All requests must use HTTPS. Sandbox and production use separate accounts and credentials, never mix them.

Explore the full API: The Billplz API documentation covers additional endpoints including Payment Order (disbursements), FPX bank lists, and more.