NAV

Introduction

API Endpoint:


https://www.billplz.com/api/v2/
        

Welcome to the Billplz API! You can use our API to access Billplz API endpoints to start sending bills and collection payment.

Our API is organized around REST. JSON will be returned in all responses from the API, including errors.

Sandbox Mode

API Endpoint:


https://billplz-staging.herokuapp.com
        

The Billplz Sandbox mirrors the features found on the real production server. While some of the features do not apply to the Sandbox.

You should test your integrations and know they will behave the same on the production server as they do in the Sandbox environment.

API Flow

In Billplz, you will interact with Bill and Collection.

A Collection is a set of Bills. The relationship is, Collection has many Bills. You can choose to create a Collection either from API or within your Billplz's dashboard.

An example of Collection would be something like Tution Fee for June 2015, Donation for Earthquake, Ticket Payment, etc.

A Bill represents the promise made to you by your customer. It's an invoice for your customer. A Bill must belong to a Collection.

To start using the API, you would have to create a Collection. Then the payment flow will kicks in as per below:

1) Customer visits your site.
2) Customer chooses to make payment.
3) Your site creates a Bill via API call.
4) Billplz API returns Bill's URL.
5) Your site redirects the customer to Bill's URL.
6) The customer makes payment via payment option of choice.
7) Billplz sends a server-side update to your site on Bill's status on payment failure or success.
8a) Billplz redirects the customer back to your site if redirect_url is not empty, or
8b) The customer will see Billplz receipt.

Authentication

To test authentication, use this code:


# With shell, you can just pass the correct HTTP Basic Auth credential with each request.
curl https://www.billplz.com/api/v2/bills \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -d collection_id=inbmmepb \
        

If authenticated, you should not see Access denied response.

curl uses the -u flag to pass basic auth credentials (adding a colon after your API key will prevent it from asking you for a password).

A demo test API key has been provided in all the examples on the page, so you can test out any example right away.

You authenticate to the Billplz API by providing your API Secret Keys in the request. You can get your API keys from your account’s settings page.

Authentication to the API occurs via HTTP Basic Auth. Provide your API key as the basic auth username. You do not need to provide a password.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

V2

Collections

Create a Collection

Example request with required arguments only:


# Creates a collection
curl https://www.billplz.com/api/v2/collections \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -d title="My First API Collection"
        

Response:


{
  "id": "inbmmepb",
  "title": "My First API Collection",
  "logo": 
  {
    "thumb_url": null,
    "avatar_url": null
  }
}
        

Example request with optional arguments:


# Creates a collection
curl https://www.billplz.com/api/v2/collections \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -F title="My First API Collection"\
  -F logo=@/Users/Billplz/Documents/uploadPhoto.png
        

Response:


{
  "id": "inbmmepb",
  "title": "My First API Collection",
  "logo":
  {
    "thumb_url": https://sample.net/assets/uploadPhoto.png,
    "avatar_url": https://sample.net/assets/uploadPhoto.png
  }
}
        

Billplz API now support creation of collections, the response will contain the collection’s ID that is needed in Bill API.

HTTP Request

POST https://www.billplz.com/api/v2/collections

Required Arguments

Parameter Description
title The collection title. Will be displayed on bill template. String format.

Optional Arguments

Parameter Description
logo This image will be resized to avatar (40x40) and thumb (180x180) dimensions. Whitelisted formats are jpg, jpeg, gif and png.

Bills

Create a Bill

Example request with required arguments only:


# Creates a bill for RM 2.00
curl https://www.billplz.com/api/v2/bills \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -d collection_id=inbmmepb \
  -d email=api@billplz.com \
  -d name="Michael API" \
  -d amount=200 \
  -d callback_url="http://example.com/webhook/"
        

Response:


{
  "id": "8X0Iyzaw",
  "collection_id": "inbmmepb",
  "paid": false,
  "state": "overdue",
  "amount": 200 ,
  "paid_amount": 0,
  "due_at": "2015-3-9",
  "email" :"api@billplz.com",
  "mobile": null,
  "name": "MICHAEL API",
  "metadata": {},
  "url": "https://www.billplz.com/bills/CGh_CE_0"
}
        

Example request with optional arguments:


# Creates a bill for RM 2.00
curl https://www.billplz.com/api/v2/bills \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -d collection_id=inbmmepb \
  -d email=api@billplz.com \
  -d name="Michael API" \
  -d amount=200 \
  -d callback_url="http://example.com/webhook/" \
  -d due_at="2020-12-31" \
  --data-urlencode mobile="+60112223333" \
  -d metadata[id]=9999 \
  -d metadata[description]="This is to test bill creation" \
  -d deliver=false \
  -d redirect_url="http://example.com/redirect/"
        

Response:


{
  "id": "W_79pJDk",
  "collection_id": "inbmmepb",
  "paid": false,
  "state": "due",
  "amount": 200,
  "paid_amount": 0,
  "due_at": "2020-12-31",
  "email": "api@billplz.com",
  "mobile": "+60112223333",
  "name": "MICHAEL API",
  "metadata":
  {
    "id": "9999",
    "description": "This is to test bill creation"
  },
  "url": "https://www.billplz.com/bills/W_79pJDk"
}
        

To create a bill, you would need the collection’s ID. Each bill must be created within a collection. To get your collection ID, visit the collection page on your Billplz account.

The bill's collection will be set to active automatically.

HTTP Request

POST https://www.billplz.com/api/v2/bills

Required Arguments

Parameter Description
collection_id The collection ID. A string.
email The email address of the bill’s recipient. (Email is required if mobile is not present.)
mobile Recipient’s mobile number. Format is +601XXXXXXXX OR 601XXXXXXXX (Mobile is required if email is not present).
name Bill’s recipient name. Useful for identification on recipient part.
amount A positive integer in the smallest currency unit (e.g 100 cents to charge RM 1.00)
callback_url Web hook URL to be called after payment’s transaction completed. It will POST a Bill object.

Optional Arguments

Parameter Description
due_at Due date for the bill. The format YYYY-MM-DD, default value is today.
metadata Key value pair to store extra information about the bill. This will be returned back to client. Potential usage is to store client’s internal ID.
redirect_url URL to redirect the customer after payment completed. It will do a GET to redirect_url together with bill’s status and ID.
deliver Boolean value to set email and SMS (if mobile is present) delivery. Default value is false.

Get a Bill

Example request:


curl https://www.billplz.com/api/v2/bills/W_79pJDk \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81:
        

Example response:


{
  "id": "W_79pJDk",
  "collection_id": "inbmmepb",
  "paid": false,
  "state": "due",
  "amount": 200,
  "paid_amount": 0,
  "due_at": "2020-12-31",
  "email": "api@billplz.com",
  "mobile": "+60112223333",
  "name": "MICHAEL API",
  "metadata":
  {
    "id": "9999",
    "description": "This is to test bill creation"
  },
  "url": "http: //billplz.dev/bills/W_79pJDk"
}
        

At any given time, you can request a bill to check on the status. It will return the bill object.

HTTP Request

GET https://www.billplz.com/api/v2/bills/{BILL_ID}

URL Parameter

Parameter Description
BILL_ID Bill ID returned in Bill object.

Payment Completion

Example Server Side Request from Billplz:


POST /webhook/ HTTP/1.1
Connection: close
Host: 127.0.0.1
Content-Length: 346
Content-Type: application/x-www-form-urlencoded

  id=W_79pJDk
  &collection_id=599
  &paid=true
  &state=paid
  &amount=200
  &paid_amount=0
  &due_at=2020-12-31
  &email=api%40billplz.com
  &mobile=%2B60112223333
  &name=MICHAEL%20API
  &metadata[id]=9999
  &metadata[description]=This%20is%20to%20test%20bill%20creation
  &url=http%3A%2F%2Fbillplz.dev%2Fbills%2FW_79pJDk
  &paid_at=2015-03-09%2016%3A23%3A59%20%2B0800
        

Body formatted for readability.

Server Side Request

Billplz will make a POST request to callback_url with Bill object upon payment completion (failure or success).

HTTP Request

POST {CALLBACK_UR}

Client Side Request

If redirect_url exists, Billplz will redirect the browser to redirect_url

HTTP Request

GET {REDIRECT_URL}?billplz[id]=W_79pJDk

Delete a Bill

Example Request:


curl -X DELETE https://www.billplz.com/api/v2/bills/{BILL_ID} \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81:
        

Example Response:


{}
        

Only due or overdue bill can be deleted. Paid bill can’t be deleted. Deleting a bill is useful in a scenario where there’s a time limitation to payment.

Example usage would be to show a timer for customer to complete payment within 10 minutes with a grace period of 5 minutes. After 15 minutes of bill creation, get bill status and delete if bill is still due.

HTTP Request

DELETE https://www.billplz.com/api/v2/bills/{BILL_ID}

URL Parameter

Parameter Description
BILL_ID Bill ID returned in Bill object.

V3

Collections

Create a Collection

Example request with required arguments only:


# Creates a collection
curl https://www.billplz.com/api/v3/collections \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -d title="My First API Collection"
        

Response:


{
  "id": "inbmmepb",
  "title": "My First API Collection",
  "logo": 
  {
    "thumb_url": null,
    "avatar_url": null
  },
  "split_payment": 
  {
    "email": null,
    "fixed_cut": null,
    "variable_cut": null
  }
}
        

Example request with optional arguments:


# Creates a collection
curl https://www.billplz.com/api/v3/collections \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -F title="My First API Collection"\
  -F logo=@/Users/Billplz/Documents/uploadPhoto.png\
  -F split_payment[email]="verified@account.com" \
  -F split_payment[fixed_cut]=100
        

Response:


{
  "id": "inbmmepb",
  "title": "My First API Collection",
  "logo":
  {
    "thumb_url": https://sample.net/assets/uploadPhoto.png,
    "avatar_url": https://sample.net/assets/uploadPhoto.png
  },
  "split_payment": 
  {
    "email": "verified@account.com",
    "fixed_cut": 100,
    "variable_cut": null
  }
}
        

Billplz API now support creation of collection with split payment feature, the response will contain the collection’s ID that is needed in Bill API, split payment info and fields

HTTP Request

POST https://www.billplz.com/api/v3/collections

Required Arguments

Parameter Description
title The collection title. Will be displayed on bill template. String format.

Optional Arguments

Parameter Description
logo This image will be resized to avatar (40x40) and thumb (180x180) dimensions. Whitelisted formats are jpg, jpeg, gif and png.
split_payment[email] The email address of the split payment’s recipient. (The account must be a verified account.)
split_payment[fixed_cut] A positive integer in the smallest currency unit that is going in your account (e.g 100 cents to charge RM 1.00)
This field is required if split_payment[variable_cut] is not present
split_payment[variable_cut] Percentage in positive integer format that is going in your account.
This field is required if split_payment[fixed_cut] is not present

Get a Collection

Example request:


# Get a collection
curl https://www.billplz.com/api/v3/collections/inbmmepb \
-u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: 
        

Example Response:


{
  "id": "inbmmepb",
  "title": "My First API Collection",
  "logo": 
  {
    "thumb_url": null,
    "avatar_url": null
  },
  "split_payment": 
  {
    "email": null,
    "fixed_cut": null,
    "variable_cut": null
  },
  "status": "active"
}
        

Use this API to query your collection record.

HTTP Request

GET https://www.billplz.com/api/v3/collections/{COLLECTION_ID}

Get Collection Index

Example request:


# Get collection index
curl https://www.billplz.com/api/v3/collections \
-u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: 

Response:


{
  "collections":
  [{
    "id": "inbmmepb",
    "title": "My First API Collection",
    "logo": 
    {
      "thumb_url": null,
      "avatar_url": null
    },
    "split_payment": 
    {
      "email": null,
      "fixed_cut": null,
      "variable_cut": null
    },
    "status": "active"
  }],
  "page": 1
}

Example request with optional arguments:


# Get collection index
curl https://www.billplz.com/api/v3/collections?page=2&status=active \
-u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: 

Response:


{
  "collections":
  [{
    "id": "inbmmepb",
    "title": "My First API Collection",
    "logo": 
    {
      "thumb_url": null,
      "avatar_url": null
    },
    "split_payment": 
    {
      "email": null,
      "fixed_cut": null,
      "variable_cut": null
    },
    "status": "active"
  }],
  "page": 2
}

Use this API to retrieve your collections list. To utilise paging, append a page parameter to the URL e.g. ?page=1. If there are 15 records in the response you will need to check if there is any more data by fetching the next page e.g. ?page=2 and continuing this process until no more results are returned.

HTTP Request

GET https://www.billplz.com/api/v3/collections

Optional Arguments

Parameter Description
page Up to 15 collections will be returned in a single API call per specified page. Default to 1 if not present.
status Parameter to filter collection's status, valid value are active and inactive.

Create an Open Collection

Example request with required arguments only:


# Creates an open collection
curl https://www.billplz.com/api/v3/open_collections \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -d title="My First API Open Collection" \
  -d description="Maecenas eu placerat ante. Fusce ut neque justo, et aliquet enim. In hac habitasse platea dictumst." \
  -d amount=299
        

Response:


{
  "id": "0pp87t_6",
  "title": "MY FIRST API OPEN COLLECTION",
  "description": "Maecenas eu placerat ante. Fusce ut neque justo, et aliquet enim. In hac habitasse platea dictumst.",
  "reference_1_label": null,
  "reference_2_label": null,
  "email_link": null,
  "amount": 299,
  "fixed_amount": true,
  "tax": null,
  "fixed_quantity": true,
  "payment_button": "pay",
  "photo":
  {
    "retina_url":  null,
    "avatar_url":  null
  },
  "split_payment": 
  {
    "email": null,
    "fixed_cut": null,
    "variable_cut": null
  },
  "url": "https://www.billplz.com/0pp87t_6"
}
        

Example request with optional arguments:


# Creates a collection
curl https://www.billplz.com/api/v3/open_collections \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -F title="My First API Open Collection" \
  -F description="Maecenas eu placerat ante. Fusce ut neque justo, et aliquet enim. In hac habitasse platea dictumst." \
  -F fixed_amount=false \
  -F fixed_quantity=false \
  -F payment_button="buy" \
  -F reference_1_label="ID No" \
  -F reference_2_label="First Name" \
  -F email_link="http://www.test.com" \
  -F tax=1 \
  -F photo=@/Users/Billplz/Documents/uploadPhoto.png \
  -F split_payment[email]="verified@account.com" \
  -F split_payment[variable_cut]=20
        

Response:


{
  "id": "0pp87t_6",
  "title": "MY FIRST API OPEN COLLECTION",
  "description": "Maecenas eu placerat ante. Fusce ut neque justo, et aliquet enim. In hac habitasse platea dictumst.",
  "reference_1_label": "ID No",
  "reference_2_label": "First Name",
  "email_link": "http://www.test.com",
  "amount": null,
  "fixed_amount": false,
  "tax": 1,
  "fixed_quantity": false,
  "payment_button": "buy",
  "photo":
  {
    "retina_url":  https://sample.net/assets/uploadPhoto.png,
    "avatar_url":  https://sample.net/assets/uploadPhoto.png
  },
  "split_payment": 
  {
    "email": "verified@account.com",
    "fixed_cut": null,
    "variable_cut": 20
  },
  "url": "https://www.billplz.com/0pp87t_6"
}
        

Billplz API now support creation of open collections (Payment Form) with split payment feature, the response will contain the collection’s attributes, including the payment form URL.

HTTP Request

POST https://www.billplz.com/api/v3/open_collections

Required Arguments

Parameter Description
title The collection title. Will be displayed on payment form. String format. (Max of 50 characters)
description The collection description. Will be displayed on payment form. String format. (Max of 200 characters)
amount A positive integer in the smallest currency unit (e.g 100 cents to charge RM 1.00)
Required if fixed_amount is true; Ignored if fixed_amount is false

Optional Arguments

Parameter Description
fixed_amount Boolean value. Set fixed_amount to false for Open Amount. Default value is true
fixed_quantity Boolean value. Set fixed_quantity to false for Open Quantity. Default value is true
payment_button Payment button's text. Available options are "buy" and "pay". Default value is pay
reference_1_label Label #1 to reconcile payments (Max of 20 characters)
Default value is Reference 1
reference_2_label Label #2 to reconcile payments. (Max of 20 characters)
Default value is Reference 2
email_link A URL that email to customer after payment is successful.
tax Tax rate in positive integer format.
photo This image will be resized to retina (Yx960) and avatar (180x180) dimensions. Whitelisted formats are jpg, jpeg, gif and png.
split_payment[email] The email address of the split payment’s recipient. (The account must be a verified account.)
split_payment[fixed_cut] A positive integer in the smallest currency unit that is going in your account (e.g 100 cents to charge RM 1.00)
This field is required if split_payment[variable_cut] is not present
split_payment[variable_cut] Percentage in positive integer format that is going in your account.
This field is required if split_payment[fixed_cut] is not present

Get an Open Collection

Example request:


# Get an open collection
curl https://www.billplz.com/api/v3/open_collections/0pp87t_6 \
-u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: 
        

Example Response:


{
  "id": "0pp87t_6",
  "title": "MY FIRST API OPEN COLLECTION",
  "description": "Maecenas eu placerat ante. Fusce ut neque justo, et aliquet enim. In hac habitasse platea dictumst.",
  "reference_1_label": null,
  "reference_2_label": null,
  "email_link": null,
  "amount": 299,
  "fixed_amount": true,
  "tax": null,
  "fixed_quantity": true,
  "payment_button": "pay",
  "photo":
  {
    "retina_url":  null,
    "avatar_url":  null
  },
  "split_payment": 
  {
    "email": null,
    "fixed_cut": null,
    "variable_cut": null
  },
  "url": "https://www.billplz.com/0pp87t_6",
  "status": "active"
}
        

Use this API to query your open collection record.

HTTP Request

GET https://www.billplz.com/api/v3/open_collections/{COLLECTION_ID}

Get Open Collection Index

Example request:


# Get open collection index
curl https://www.billplz.com/api/v3/open_collections \
-u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: 

Response:


{
  "open_collections":
  [{
    "id": "0pp87t_6",
    "title": "MY FIRST API OPEN COLLECTION",
    "description": "Maecenas eu placerat ante. Fusce ut neque justo, et aliquet enim. In hac habitasse platea dictumst.",
    "reference_1_label": "ID No",
    "reference_2_label": "First Name",
    "email_link": "http://www.test.com",
    "amount": null,
    "fixed_amount": false,
    "tax": 1,
    "fixed_quantity": false,
    "payment_button": "buy",
    "photo":
    {
      "retina_url":  https://sample.net/assets/uploadPhoto.png,
      "avatar_url":  https://sample.net/assets/uploadPhoto.png
    },
    "split_payment": 
    {
      "email": "verified@account.com",
      "fixed_cut": null,
      "variable_cut": 20
    },
    "url": "https://www.billplz.com/0pp87t_6",
    "status": "active"
  }],
  "page": 1
}

Example request with optional arguments:


# Get collection index
curl https://www.billplz.com/api/v3/open_collections?page=2&status=active \
-u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: 

Response:


{
  "open_collections":
  [{
    "id": "0pp87t_6",
    "title": "MY FIRST API OPEN COLLECTION",
    "description": "Maecenas eu placerat ante. Fusce ut neque justo, et aliquet enim. In hac habitasse platea dictumst.",
    "reference_1_label": "ID No",
    "reference_2_label": "First Name",
    "email_link": "http://www.test.com",
    "amount": null,
    "fixed_amount": false,
    "tax": 1,
    "fixed_quantity": false,
    "payment_button": "buy",
    "photo":
    {
      "retina_url":  https://sample.net/assets/uploadPhoto.png,
      "avatar_url":  https://sample.net/assets/uploadPhoto.png
    },
    "split_payment": 
    {
      "email": "verified@account.com",
      "fixed_cut": null,
      "variable_cut": 20
    },
    "url": "https://www.billplz.com/0pp87t_6",
    "status": "active"
  }],
  "page": 2
}

Use this API to retrieve your open collections list. To utilise paging, append a page parameter to the URL e.g. ?page=1. If there are 15 records in the response you will need to check if there is any more data by fetching the next page e.g. ?page=2 and continuing this process until no more results are returned.

HTTP Request

GET https://www.billplz.com/api/v3/open_collections

Optional Arguments

Parameter Description
page Up to 15 open collections will be returned in a single API call per specified page. Default to 1 if not present.
status Parameter to filter open collection's status, valid value are active and inactive.

Deactivate a Collection

Example request:


# Deactivate a collection
curl -X POST \
https://www.billplz.com/api/v3/collections/qag4fe_o6/deactivate \
-u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: 
        

Example Response:


{}
        

The API will respond with error messages if the collection cannot be deactivated for some reasons.

HTTP Request

POST https://www.billplz.com/api/v3/collections/{COLLECTION_ID}/deactivate

Activate a Collection

Example request:


# Activate a collection
curl -X POST \
https://www.billplz.com/api/v3/collections/qag4fe_o6/activate \
-u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: 
        

Example Response:


{}
        

The API will respond with error messages if the collection cannot be activated for some reasons.

HTTP Request

POST https://www.billplz.com/api/v3/collections/{COLLECTION_ID}/activate

Bills

Create a Bill

Example request with required arguments only:


# Creates a bill for RM 2.00
curl https://www.billplz.com/api/v3/bills \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -d collection_id=inbmmepb \
  -d description="Maecenas eu placerat ante." \
  -d email=api@billplz.com \
  -d name="Michael API V3" \
  -d amount=200 \
  -d callback_url="http://example.com/webhook/"
        

Response:


{
  "id": "8X0Iyzaw",
  "collection_id": "inbmmepb",
  "paid": false,
  "state": "overdue",
  "amount": 200 ,
  "paid_amount": 0,
  "due_at": "2015-3-9",
  "email" :"api@billplz.com",
  "mobile": null,
  "name": "MICHAEL API V3",
  "url": "https://www.billplz.com/bills/8X0Iyzaw",
  "reference_1_label": "Reference 1",
  "reference_1": null,
  "reference_2_label": "Reference 2",
  "reference_2": null,
  "redirect_url": null,
  "callback_url": "http://example.com/webhook/",
  "description": "Maecenas eu placerat ante."
}
        

Example request with optional arguments:


# Creates a bill for RM 2.00
curl https://www.billplz.com/api/v3/bills \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -d collection_id=inbmmepb \
  -d email=api@billplz.com \
  -d name="Michael API V3" \
  -d amount=200 \
  -d callback_url="http://example.com/webhook/" \
  -d description="Maecenas eu placerat ante." \
  -d due_at="2020-12-31" \
  --data-urlencode mobile="+60112223333" \
  -d reference_1_label="First Name" \
  -d reference_2_label="Last Name" \
  -d reference_1="Jordan" \
  -d reference_2="Michael" \
  -d deliver=false \
  -d redirect_url="http://example.com/redirect/"
        

Response:


{
  "id": "8X0Iyzaw",
  "collection_id": "inbmmepb",
  "paid": false,
  "state": "due",
  "amount": 200 ,
  "paid_amount": 0,
  "due_at": "2020-12-31",
  "email" :"api@billplz.com",
  "mobile": "+60112223333",
  "name": "MICHAEL API V3",
  "url": "https://www.billplz.com/bills/8X0Iyzaw",
  "reference_1_label": "First Name",
  "reference_1": Jordan,
  "reference_2_label": "Last Name",
  "reference_2": Michael,
  "redirect_url": "http://example.com/redirect/",
  "callback_url": "http://example.com/webhook/",
  "description": "Maecenas eu placerat ante."
}
        

To create a bill, you would need the collection’s ID. Each bill must be created within a collection. To get your collection ID, visit the collection page on your Billplz account.

The bill's collection will be set to active automatically.

HTTP Request

POST https://www.billplz.com/api/v3/bills

Required Arguments

Parameter Description
collection_id The collection ID. A string.
email The email address of the bill’s recipient. (Email is required if mobile is not present.)
mobile Recipient’s mobile number. Format is +601XXXXXXXX OR 601XXXXXXXX (Mobile is required if email is not present).
name Bill’s recipient name. Useful for identification on recipient part.
amount A positive integer in the smallest currency unit (e.g 100 cents to charge RM 1.00)
callback_url Web hook URL to be called after payment’s transaction completed. It will POST a Bill object.
description The bill's description. Will be displayed on bill template. String format. (Max of 200 characters)

Optional Arguments

Parameter Description
due_at Due date for the bill. The format YYYY-MM-DD, default value is today.
redirect_url URL to redirect the customer after payment completed. It will do a GET to redirect_url together with bill’s status and ID.
deliver Boolean value to set email and SMS (if mobile is present) delivery. Default value is false.
reference_1_label Label #1 to reconcile payments (Max of 20 characters)
Default value is Reference 1
reference_1 Value for reference_1_label (Max of 120 characters)
reference_2_label Label #2 to reconcile payments (Max of 20 characters)
Default value is Reference 2
reference_2 Value for reference_2_label (Max of 120 characters)

Get a Bill

Example request:


curl https://www.billplz.com/api/v3/bills/8X0Iyzaw \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81:
        

Example response:


{
  "id": "8X0Iyzaw",
  "collection_id": "inbmmepb",
  "paid": false,
  "state": "due",
  "amount": 200 ,
  "paid_amount": 0,
  "due_at": "2020-12-31",
  "email" :"api@billplz.com",
  "mobile": "+60112223333",
  "name": "MICHAEL API V3",
  "url": "https://www.billplz.com/bills/8X0Iyzaw",
  "reference_1_label": "First Name",
  "reference_1": Jordan,
  "reference_2_label": "Last Name",
  "reference_2": Michael,
  "redirect_url": "http://example.com/redirect/",
  "callback_url": "http://example.com/webhook/",
  "description": "Maecenas eu placerat ante."
}
        

At any given time, you can request a bill to check on the status. It will return the bill object.

HTTP Request

GET https://www.billplz.com/api/v3/bills/{BILL_ID}

URL Parameter

Parameter Description
BILL_ID Bill ID returned in Bill object.

Response Parameter

Parameter Description
State State that representing the bill's status, possible states are due, overdue and paid.
paid Boolean value to tell if a bill has paid. It will return false for due and overdue bill; true for paid bill.

Payment Completion

Example Server Side Request from Billplz:


POST /webhook/ HTTP/1.1
Connection: close
Host: 127.0.0.1
Content-Length: 346
Content-Type: application/x-www-form-urlencoded

  id=W_79pJDk
  &collection_id=599
  &paid=true
  &state=paid
  &amount=200
  &paid_amount=0
  &due_at=2020-12-31
  &email=api%40billplz.com
  &mobile=%2B60112223333
  &name=MICHAEL%20API
  &metadata[id]=9999
  &metadata[description]=This%20is%20to%20test%20bill%20creation
  &url=http%3A%2F%2Fbillplz.dev%2Fbills%2FW_79pJDk
  &paid_at=2015-03-09%2016%3A23%3A59%20%2B0800
        

Body formatted for readability.

Server Side Request

Billplz will make a POST request to callback_url with Bill object upon payment completion (failure or success).

A bill that catched payment failure will either in due or overdue state.

Request will be timeout at 20 seconds.

HTTP Request

POST {CALLBACK_UR}

Client Side Request

If redirect_url exists, Billplz will redirect the browser to redirect_url

HTTP Request

GET {REDIRECT_URL}?billplz[id]=W_79pJDk

Delete a Bill

Example Request:


curl -X DELETE https://www.billplz.com/api/v3/bills/{BILL_ID} \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81:
        

Example Response:


{}
        

Only due or overdue bill can be deleted. Paid bill can’t be deleted. Deleting a bill is useful in a scenario where there’s a time limitation to payment.

Example usage would be to show a timer for customer to complete payment within 10 minutes with a grace period of 5 minutes. After 15 minutes of bill creation, get bill status and delete if bill is still due.

HTTP Request

DELETE https://www.billplz.com/api/v3/bills/{BILL_ID}

URL Parameter

Parameter Description
BILL_ID Bill ID returned in Bill object.

Registration Check

By Bank Account Number

Example request:


curl https://www.billplz.com/api/v3/check/bank_account_number/1234567890 \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81:
        

Example response:


{
  "name": "verified"
}
        

At any given time, you can request to check on a registration status by bank account number.

HTTP Request

GET https://www.billplz.com/api/v3/check/bank_account_number/{BANK_ACCOUNT_NUMBER}

URL Parameter

Parameter Description
BANK_ACCOUNT_NUMBER Bank account number to check.

Response Parameter

Parameter Description
Name State that representing the bank account number's status, possible states are verified, unverified and not found.