Billplz icon

Billplz

Billplz using API for payment gateway
Join our community

Actions6

Overview

This node integrates with the Billplz payment gateway API to create and manage bills within collections. Specifically, the Create a Bill operation allows users to generate a new bill for a recipient by providing details such as email or mobile number, name, amount, description, and a callback URL. This is useful in scenarios where businesses want to automate billing processes, send payment requests to customers, and track payment statuses via webhooks.

Practical examples include:

  • Sending a payment request to a customer’s email or mobile phone.
  • Automating invoice generation for online orders.
  • Integrating payment collection into workflows that require real-time payment status updates through callbacks.

Properties

Name Meaning
Email The email address of the bill's recipient. Required if mobile number is not provided. Example: mail@example.com.
Mobile The recipient's mobile number including country code without spaces or dashes (e.g., +60123456789). Required if email is not provided. Use libraries like Google libphonenumber to validate format.
Name The recipient's full name, used for identification on the bill. Maximum 255 characters. Example: Ahmad Maszlan.
Amount The amount to be charged, expressed as a positive integer in the smallest currency unit (e.g., 100 cents to charge RM 1.00).
Callback URL A webhook URL that Billplz will POST to after the payment transaction completes. It receives the Bill object, allowing further automation based on payment status.
Description A description of the bill shown on the bill template. String format with a maximum of 200 characters. Useful for clarifying the purpose of the bill to the recipient.

Output

The node outputs a JSON array containing the response from the Billplz API after creating the bill. This response typically includes details about the newly created bill such as its ID, status, payment URL, and other metadata returned by the API.

If the operation succeeds, the output JSON structure will represent the Bill object as returned by Billplz, which can be used downstream in workflows for tracking or further processing.

The node does not output binary data.

Dependencies

  • Requires an API key credential for authenticating with the Billplz API.
  • The node makes HTTP requests to the Billplz API endpoints (https://www.billplz.com/api/v3/bills).
  • Proper configuration of the API credentials (username and password) is necessary.
  • The user must provide a valid Collection ID under which the bill will be created.
  • The callback URL must be accessible publicly to receive webhook POSTs from Billplz.

Troubleshooting

  • Missing required fields: Ensure either Email or Mobile is provided, along with all other required properties (Name, Amount, Callback URL, Description).
  • Invalid mobile number format: Mobile numbers must include country code and no spaces/dashes. Use validation libraries to avoid errors.
  • Authentication errors: Verify that the API credentials are correctly configured and have sufficient permissions.
  • Callback URL unreachable: If the webhook URL is invalid or inaccessible, payment notifications will fail.
  • API rate limits or downtime: Temporary failures may occur due to API limits or service issues; retry logic may be needed in workflows.
  • Amount formatting: Amount must be a positive integer representing the smallest currency unit; decimals or negative values will cause errors.

Links and References

Discussion