Authentication overview

The Billplz API uses multiple authentication and verification mechanisms depending on what you're doing. This article explains each one, when to use it, and how they work together.

API authentication (Secret key + Basic Auth)

Every API request to Billplz must be authenticated using your Secret key via HTTP Basic Auth. Your Secret key acts as the username — there is no password.

All requests must be made over HTTPS. Plain HTTP requests will fail.

How it works:

Pass your Secret key as the Basic Auth username with an empty password. In cURL, append a colon (:) after the key:

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

Alternatively, base64-encode your Secret key (with the trailing colon) and pass it in the Authorization header:

curl https://www.billplz.com/api/v4/webhook_rank \
  -H "Authorization: Basic {base64_encoded_key}"

A successful response returns a JSON object. An Unauthorized response means the key is incorrect or mismatched with the environment.

Key points:

• Your Secret key is found in your Billplz dashboard under Settings > Keys & Integration. See Get your Billplz Secret key.
• Sandbox and production accounts have separate Secret keys. Sandbox keys only work with billplz-sandbox.com; production keys only work with billplz.com.
• If your Secret key is compromised, reset it immediately from the dashboard. This invalidates the old key — all integrations using it will stop working until updated.

Callback verification (X Signature key)

The X Signature key is a separate credential used to verify that webhook callbacks and redirects genuinely came from Billplz. It is not used to authenticate API requests.

When X Signature is enabled, Billplz signs callback and redirect payloads using HMAC_SHA256 with your X Signature key. Your server computes the same signature from the received data and compares it against the x_signature value in the payload.

How it works:

1. Construct a source string from the callback parameters — key-value pairs sorted in ascending order (case-insensitive), separated by | (pipe).
2. Sign the source string using HMAC_SHA256 with your X Signature key.
3. Compare your computed signature against the x_signature value in the callback. If they match, the callback is authentic.

For the full calculation method and examples, see the X Signature section in the API documentation.

Key points:

• Enable and copy your X Signature key from Settings > Keys & Integration. See Enable X Signature key verification.
• The X Signature key and Secret key are different credentials. Do not use one in place of the other.
• Enable X Signature before going live with any integration that uses callbacks or redirects.

V5 endpoint authentication (Checksum)

V5 API endpoints require an additional checksum alongside your Secret key. Every V5 request must include an epoch (UNIX timestamp) and a checksum value.

How it works:

1. Form a raw string by joining the values of the required checksum arguments in the strict order specified by each endpoint.
2. Sign the raw string using HMAC_SHA512 with your X Signature key.
3. Include the resulting checksum and epoch values in your request.

For endpoint-specific checksum arguments and examples, see the V5 Checksum section in the API documentation.

OAuth 2.0 (partner integration)

OAuth 2.0 allows platform partners to connect merchants with Billplz without requiring them to manually copy their Secret key, Collection ID, or X Signature key. Merchants authorise the connection by logging in with their Billplz account.

Quick reference