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.

[Screenshot: Sandbox bill payment page showing the payment method selection with FPX test banks]

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 Open Collections, Payment Order (disbursements), FPX bank lists, and more.