NAV

Introduction

API Endpoint:


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

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. The API will accept both application/x-www-form-urlencoded and application/json.

Premium Plan has been discontinued on 24 September 2018. All API features are available to all eligible* accounts.

*Personal accounts are not eligible to collect payment.

Sandbox Mode

API Endpoint:


https://billplz-staging.herokuapp.com/api/v3/
        

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:

Normal completion flow,

  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**at best effort (Payment Completion) to your site upon payment failure or success. (Basic Callback URL / X Signature Callback URL depending on your configuration)
    [your backend server should capture the transaction update at this point] refer to API#X Signature Callback Url
  8. Billplz redirects (Payment Completion) the customer back to your site if redirect_url is not empty (Basic Redirect URL / X Signature Redirect URL depending on your configuration)
    [your server should capture the transaction update at this point and give your user an instant reflection on the page loaded] refer to API#X Signature Redirect Url
    or,
    The customer will see Billplz receipt if redirect_url is not present.

Completion flow without redirect_url,

  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**at best effort (Payment Completion) to your site upon payment failure or success. (Basic Callback URL / X Signature Callback URL depending on your configuration)
    [your backend server should capture the transaction update at this point] refer to API#X Signature Callback Url
    Billplz does not redirects (Payment Completion) the customer back to your site, redirect_url (due to many possibilities, app hang, browser closed, disconnected, etc)

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/v3/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).

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.

Integration

Xero

Billplz now integrates with Xero!

Xero is a popular online accounting solution for your business. Through a seamless integration, Billplz gives you ability to collect your payments in real time.

Any payments accepted in Billplz will be added and synched to your Xero account seamlessly.

Checkout our step-by-step guideline on how to integrate Billplz with Xero here.

Limitations & Requirements

Subject Explanation
Billplz Collection ID This is your Billplz collection's ID to create and group bills.
Xero Accounts For Payments Handling payments for invoices requires a chart of account which has payments enabled. We have follow the best approach to filter your chart of accounts, by account "Type" is "BANK" and also "CurrencyCode" is "MYR". If you do not have one, please go ahead and create.
Supported Currency Billplz only support "MYR" for now, the system will return status code of 422 with "do not support currency" message if your Xero invoice is not in "MYR". So, please make sure your currency is in the right format.
Billplz Identifier aka Email Billplz requires a valid email to create a bill. The system will generate a default value of "team@billplz.com" if your Xero invoice is missing email.
Billplz Total Billplz requires total to create a bill, the system will return status code of 422 with "invalid total" message if your Xero invoice is missing total.

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: \
  -F 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,
    "split_header": false
  }
}
        

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 \
  -F split_payment[split_header]=true
        

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,
    "split_header": true
  }
}
        

Billplz API now support creation of collection with split rule feature, the response will contain the collection’s ID that is needed in Bill API, split rule 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 rule'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
split_payment[split_header] Boolean value. All bill and receipt templates will show split rule recipient's infographic if this was set to true.

Response Parameter

Parameter Description
id ID that represents a collection
title The collection's title in string format.
logo[thumb_url] The thumb dimension's (180x180) URL.
logo[avatar_url] The avatar dimension's (40x40) URL.
split_payment[email] The 1st recipient's email. It only returns the 1st recipient eventhough there is multiple recipients being set. If you wish to have 2 recipients, please refer to API#get-fpx-banks.
split_payment[fixed_cut] The 1st recipient's fixed cut in smallest and positive currency unit.
split_payment[variable_cut] The 1st recipient's percentage cut in positive integer format.
split_payment[split_header] Boolean value. All bill and receipt templates will show split rule recipient's infographic if this was set to true.

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,
    "split_header": false
  },
  "status": "active"
}
        

Use this API to query your collection record.

HTTP Request

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

Response Parameter

Parameter Description
id ID that represents a collection
title The collection's title in string format.
logo[thumb_url] The thumb dimension's (180x180) URL.
logo[avatar_url] The avatar dimension's (40x40) URL.
split_payment[email] The 1st recipient's email. It only returns the 1st recipient eventhough there is multiple recipients being set. If you wish to have 2 recipients, please refer to API#get-fpx-banks.
split_payment[fixed_cut] The 1st recipient's fixed cut in smallest and positive currency unit.
split_payment[variable_cut] The 1st recipient's percentage cut in positive integer format.
split_payment[split_header] Boolean value. All bill and receipt templates will show split rule recipient's infographic if this was set to true.
status Collection's status, it is either active and inactive.

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,
      "split_header": false
    },
    "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,
      "split_header": false
    },
    "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,
    "split_header": false
  },
  "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 \
  -F split_payment[split_header]=true
        

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,
    "split_header": true
  },
  "url": "https://www.billplz.com/0pp87t_6"
}
        

Billplz API now support creation of open collections (Payment Form) with split rule 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 rule'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
split_payment[split_header] Boolean value. All bill and receipt templates will show split rule recipient's infographic if this was set to true.

Response Parameter

Parameter Description
id The collection ID.
title The collection's title.
description The collection description.
reference_1_label Label #1 to reconcile payments.
reference_2_label Label #2 to reconcile payments.
email_link A URL that email to customer after payment is successful.
amount The collection's fixed amount to create bill in the smallest currency unit.
fixed_amount Boolean value. It returns to false if Open Amount.
tax Tax rate in positive integer format.
fixed_quantity Boolean value. It returns false if Open Quantity.
payment_button Payment button's text.
photo[retina_url] The retina dimension's (Yx960) URL.
photo[avatar_url] The avatar dimension's (180x180) URL.
split_payment[email] The 1st recipient's email. It only returns the 1st recipient eventhough there is multiple recipients being set. If you wish to have 2 recipients, please refer to API#get-fpx-banks.
split_payment[fixed_cut] The 1st recipient's fixed cut in smallest and positive currency unit.
split_payment[variable_cut] The 1st recipient's percentage cut in positive integer format.
split_payment[split_header] Boolean value. All bill and receipt templates will show split rule recipient's infographic if this was set to true.
url URL to the collection.

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,
    "split_header": false
  },
  "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}

Response Parameter

Parameter Description
id The collection ID.
title The collection's title.
description The collection description.
reference_1_label Label #1 to reconcile payments.
reference_2_label Label #2 to reconcile payments.
email_link A URL that email to customer after payment is successful.
amount The collection's fixed amount to create bill in the smallest currency unit.
fixed_amount Boolean value. It returns to false if Open Amount.
tax Tax rate in positive integer format.
fixed_quantity Boolean value. It returns false if Open Quantity.
payment_button Payment button's text.
photo[retina_url] The retina dimension's (Yx960) URL.
photo[avatar_url] The avatar dimension's (180x180) URL.
split_payment[email] The 1st recipient's email. It only returns the 1st recipient eventhough there is multiple recipients being set. If you wish to have 2 recipients, please refer to API#get-fpx-banks.
split_payment[fixed_cut] The 1st recipient's fixed cut in smallest and positive currency unit.
split_payment[variable_cut] The 1st recipient's percentage cut in positive integer format.
split_payment[split_header] Boolean value. All bill and receipt templates will show split rule recipient's infographic if this was set to true.
url URL to the collection.
status Collection's status, it is either active and inactive.

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,
      "split_header": false
    },
    "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,
      "split_header": false
    },
    "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": "due",
  "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. Be sure that all mobile numbers include country code, area code and number without spaces or dashes. (e.g., +60122345678 or 60122345678). Use Google libphonenumber library to help. Mobile is required if email is not present.
name Bill’s recipient name. Useful for identification on recipient part. (Max of 255 characters)
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, paid and hidden.
paid Boolean value to tell if a bill has paid. It will return false for due bills; true for paid bills.

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 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.

Transactions

Get Transaction Index

Example request:


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

Example response:


{
  "bill_id": "inbmmepb",
  "transactions":
  [{
    "id": "60793D4707CD",
    "status": "completed",
    "completed_at": "2017-02-23T12:49:23.612+08:00",
    "payment_channel": "FPX"
  },{
    "id": "28F3D3194138",
    "status": "failed",
    "completed_at": ,
    "payment_channel": "FPX"
  }],
  "page": 1
}

Example request with optional arguments:


# Get transaction index
curl https://www.billplz.com/api/v3/bills/inbmmepb/transactions?page=1&status=completed \
-u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: 

Example response:


{
  "bill_id": "inbmmepb",
  "transactions":
  [{
    "id": "60793D4707CD",
    "status": "completed",
    "completed_at": "2017-02-23T12:49:23.612+08:00",
    "payment_channel": "FPX"
  }],
  "page": 1
}

Use this API to retrieve your bill's transactions. 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/bills/{BILL_ID}/transactions

URL Parameter

Parameter Description
page Up to 15 transactions will be returned in a single API call per specified page. Default to 1 if not present.
status Parameter to filter transaction's status.
Valid values are pending, completed and failed.

Response Parameter

Parameter Description
bill_id ID that represent the bill.
id ID that represent the transaction.
status Status that representing the transaction's status, possible statuses are pending, completed and failed.
completed_at Datetime format when the transaction is completed. ISO 8601 format is used.
payment_channel Payment channel that the transaction is made.
Possible values are FPX, CIMB, BOOST, 2C2P and PAYPAL.

Payment Methods

Get Payment Method Index

Example request:


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

Example response:


{
  "payment_methods":
  [{
    "code": "paypal",
    "name": "PAYPAL",
    "active": true
  },{
    "code": "fpx",
    "name": "Online Banking",
    "active": false
  }]
}

The get payment methods index API allows to retrieve all available payment methods that you can enable / disable to a collection.

HTTP Request

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

URL Parameter

Parameter Description
COLLECTION_ID ID that represents the collection where the payment methods belong to.

Response Parameter

Parameter Description
code Unique payment method's specific code, in string value.
name Payment method's general name, in string value.
active The API will return payment method's status for a collection, in boolean value. It returns true if this payment method has enabled for the collection.

Update Payment Methods

Example request:


# Update payment methods
curl -X PUT -d payment_methods[][code]='fpx' -d payment_methods[][code]='paypal' https://www.billplz.com/api/v3/collections/0idsxnh5/payment_methods \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81:
        

Example response:


{
  "payment_methods":
  [{
    "code": "paypal",
    "name": "PAYPAL",
    "active": true
  },{
    "code": "fpx",
    "name": "Online Banking",
    "active": true
  }]
}

Pass the payment method's code to the API to update your collection's payment methods.

Invalid payment method code will be ignored.

HTTP Request

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

URL Parameter

Parameter Description
COLLECTION_ID ID that represents the collection where the payment methods belong to.
payment_methods Array that contains all codes in hash format.
code in hash represents the unique payment method's code that you would like to enable.
Do not pass the code if you would like to disable a payment method.
Ex, "payment_methods"=>[{"code"=>"fpx"}] would enable fpx (Online Banking) and disable paypal (PAYPAL).

Response Parameter

Parameter Description
code Unique payment method's specific code, in string value.
name Payment method's general name, in string value.
active Payment method current's status for the collection, in boolean value. It is true if this payment method has enabled for the collection.

Bank Account Direct Verification

Get Bank Account Index

Example request:


# Get bank account index
curl 'https://www.billplz.com/api/v3/bank_verification_services?account_numbers\[\]=1234567890&account_numbers\[\]=2234567890&account_numbers\[\]=3234567890' \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81:
        

Example response:


{
  "bank_verification_services":
  [{
    "name": "sara",
    "id_no": "820909101001",
    "acc_no": "1234567890",
    "code": "MBBEMYKL",
    "organization": false,
    "authorization_date": "2015-12-03",
    "status": "pending",
    "processed_at": null,
    "rejected_desc": null
  },{
    "name": "dila",
    "id_no": "820909101002",
    "acc_no": "2234567890",
    "code": "MBBEMYKL",
    "organization": true,
    "authorization_date": "2015-12-03",
    "status": "verified",
    "processed_at": "2015-12-05",
    "rejected_desc": null
  }]
}

Query Billplz Bank Account Direct Verification Service by passing list of account numbers arguement. This API will only return latest, matched bank accounts.

HTTP Request

GET https://www.billplz.com/api/v3/bank_verification_services?account_numbers=[]

URL Parameter

Parameter Description
account_numbers Up to 10 bank accounts found will be returned in a single API call. In array format.

Response Parameter

Parameter Description
name Bank account holder's name, in string value.
id_no Bank account's IC Number/SSM Registration Number, in string value.
acc_no Bank account number, in string value.
code Bank Code that represents bank, in string value.
organization Boolean value that tell if the bank account is registered as organization.
authorization_date Request date for authorization, in format YYYY-MM-DD. Example, 2012-12-30
status Status that representing the authorization status, possible statuses are pending, verified and rejected.
processed_at Date format when the authorization is performed. In format YYYY-MM-DD. Example, 2012-12-30 It returns null if authorization has not been made.
reject_desc Reason why the authorization was rejected, in string value.

Get a Bank Account

Example request:


# Get a bank account
curl https://www.billplz.com/api/v3/bank_verification_services/1234567890 \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81:
        

Example response:


{
  "name": "sara",
  "id_no": "820909101001",
  "acc_no": "1234567890",
  "code": "MBBEMYKL",
  "organization": false,
  "authorization_date": "2015-12-03",
  "status": "pending",
  "processed_at": null,
  "rejected_desc": null
}

Query Billplz Bank Account Direct Verification Service by passing single account number arguement. This API will only return latest, single matched bank account.

HTTP Request

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

URL Parameter

Parameter Description
BANK_ACCOUNT_NUMBER Bank account number to query.

Response Parameter

Parameter Description
name Bank account holder's name, in string value.
id_no Bank account's IC Number/SSM Registration Number, in string value.
acc_no Bank account number, in string value.
code Bank Code that represents bank, in string value.
organization Boolean value that tell if the bank account is registered as organization.
authorization_date Request date for authorization, in format YYYY-MM-DD. Example, 2012-12-30
status Status that representing the authorization status, possible statuses are pending, verified and rejected.
processed_at Date format when the authorization is performed. In format YYYY-MM-DD. Example, 2012-12-30 It returns null if authorization has not been made.
reject_desc Reason why the authorization was rejected, in string value.

Create a Bank Account

Example request:


# Create a bank account
curl https://www.billplz.com/api/v3/bank_verification_services \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -d name="Insan Jaya" \
  -d id_no="91234567890" \
  -d acc_no="999988887777" \
  -d code="MBBEMYKL" \
  -d organization=true
        

Example response:


{
  "name": "Insan Jaya",
  "id_no": "91234567890",
  "acc_no": "999988887777",
  "code": "MBBEMYKL",
  "organization": true,
  "authorization_date": "2017-07-03",
  "status": "pending",
  "processed_at": null,
  "rejected_desc": null
}

Request Bank Account Direct Verification Service by creating bank records thru this API.

HTTP Request

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

URL Parameter

Parameter Description
name Bank account holder's name, in string value.
id_no Bank account's IC Number/SSM Registration Number, in string value.
acc_no Bank account number, in string value.
code Bank Code that represents bank, in string value and case sensitive.
Please refer to the Bank Code table below.
organization Boolean value that tell if the bank account is registered as organization. Default to false if this parameter is missing.

Response Parameter

Parameter Description
name Bank account holder's name, in string value.
id_no Bank account's IC Number/SSM Registration Number, in string value.
acc_no Bank account number, in string value.
code Bank Code that represents bank, in string value.
organization Boolean value that tell if the bank account is registered as organization.
authorization_date Request date for authorization, in format YYYY-MM-DD. Example, 2012-12-30
status Status that representing the authorization status, possible statuses are pending, verified and rejected.
processed_at Date format when the authorization is performed. In format YYYY-MM-DD. Example, 2012-12-30 It returns null if authorization has not been made.
reject_desc Reason why the authorization was rejected, in string value.

Bank Code Table

Bank Code
Affin Bank BerhadPHBMMYKL
AGROBANK / BANK PERTANIAN MALAYSIA BERHADBPMBMYKL
Alliance Bank Malaysia BerhadMFBBMYKL
AL RAJHI BANKING & INVESTMENT CORPORATION (MALAYSIA) BERHADRJHIMYKL
AmBank (M) BerhadARBKMYKL
Bank Islam Malaysia BerhadBIMBMYKL
Bank Kerjasama Rakyat Malaysia BerhadBKRMMYKL
Bank Muamalat (Malaysia) BerhadBMMBMYKL
Bank Simpanan Nasional BerhadBSNAMYK1
CIMB Bank BerhadCIBBMYKL
Citibank BerhadCITIMYKL
Hong Leong Bank BerhadHLBBMYKL
HSBC Bank Malaysia BerhadHBMBMYKL
Maybank / Malayan Banking BerhadMBBEMYKL
OCBC Bank (Malaysia) BerhadOCBCMYKL
Public Bank BerhadPBBEMYKL
RHB Bank BerhadRHBBMYKL
Standard Chartered Bank (Malaysia) BerhadSCBLMYKX
United Overseas Bank (Malaysia) BerhadUOVBMYKL

Bank Direct Feature

Bypass Billplz bill page

In order to bypass Billplz bill page, and direct payers straight from bill URL to bank gateway:

  1. Create bills thru Billplz API with present of reference_1_label and reference_1.
    • Always set reference_1_label as “Bank Code”
    • Always set a bank code to reference_1. Please refer to section API#get-fpx-banks below for more details on how to set the bank code.
  2. Always append parameter, auto_submit=true to the bill's url return from API#create-a-bill.
    Example, https://www.billplz.com/bills/abcdef
    Become,
    https://www.billplz.com/bills/abcdef?auto_submit=true

The page will not auto redirected to bank if reference_1 and reference_1_label are invalid.

This is the standard payment flow,

  1. Merchant creates bill thru API
  2. Merchant redirects payer to bill URL returned from #1
  3. Payer lands at Billplz page to select bank
  4. Payer redirected to selected bank to pay
  5. Payer redirected to redirect_url / receipt page (refer to API#flow)

This is the flow for valid Bank Direct payment,

  1. Merchant creates bill thru API with bank code
  2. Merchant redirects payer to bill URL returned from #1 with extra parameter, auto_submit=true
  3. Payer lands at bank to pay
  4. Payer redirected to redirect_url / receipt page (refer to API#flow)

This is the flow for invalid Bank Direct payment,

  1. Merchant creates bill thru API with invalid / inactive bank
  2. Merchant redirects payer to bill URL returned from #1 with extra parameter, auto_submit=true
  3. Payer lands at Billplz page to select bank
  4. Payer redirected to selected bank to pay
  5. Payer redirected to redirect_url / receipt page (refer to API#flow)

Get FPX banks

Example request:


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

Example response:


{
  "banks":
  [{
    "name": "MBU0227",
    "active": true
    },{
    "name": "OCBC0229",
    "active": false
    },{
    "name": "MB2U0227",
    "active": true
  }]
}
        

Use this API to get a list of bank codes that need for setting reference_1 in API#bypass-billplz-bill-page.

HTTP Request

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

Response Parameter

Parameter Description
Name This is the bank code that need to set to reference_1. Case sensitive.
active True or false boolean that represents bank's availability. If an inactive bank was set to reference_1, the payment process will show Billplz page for payer to choose another bank from the list.

FPX Bank Abbreviations

Bank Code Bank Name
ABMB0212 Alliance Bank
ABB0233 Affin Bank
AMBB0209 AmBank
BCBB0235 CIMB Clicks
BIMB0340 Bank Islam
BKRM0602 Bank Rakyat
BMMB0341 Bank Muamalat
BSN0601 BSN
CIT0217 Citibank Berhad
HLB0224 Hong Leong Bank
HSBC0223 HSBC Bank
KFH0346 Kuwait Finance House
MB2U0227 Maybank2u
MBB0227 Maybank2E
MBB0228 Maybank2E
OCBC0229 OCBC Bank
PBB0233 Public Bank
RHB0218 RHB Now
SCB0216 Standard Chartered
UOB0226 UOB Bank
TEST0001* Test 0001
TEST0002* Test 0002
TEST0003* Test 0003
TEST0004* Test 0004
TEST0021* Test 0021
TEST0022* Test 0022
TEST0023* Test 0023

Records marked with *, only applicable in staging environment.

V4

Collections

Create a Collection

Example request with required arguments only:


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

Response:


{
  "id": "inbmmepb",
  "title": "My First V4 API Collection",
  "logo": 
  {
    "thumb_url": null,
    "avatar_url": null
  },
  "split_header": false,
  "split_payments": []
}
        

Example request with optional arguments:


# Creates a collection
curl https://www.billplz.com/api/v4/collections \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -F title="My First V4 API Collection"\
  -F logo=@/Users/Billplz/Documents/uploadPhoto.png\
  -F split_payments[][email]="verified@account.com" \
  -F split_payments[][fixed_cut]=100 \
  -F split_payments[][variable_cut]=2\
  -F split_payments[][stack_order]=0\
  -F split_payments[][email]="verified2@account.com" \
  -F split_payments[][fixed_cut]=200 \
  -F split_payments[][variable_cut]=3\
  -F split_payments[][stack_order]=1
        

Response:


{
  "id": "inbmmepb",
  "title": "My First V4 API Collection",
  "logo":
  {
    "thumb_url": https://sample.net/assets/uploadPhoto.png,
    "avatar_url": https://sample.net/assets/uploadPhoto.png
  },
  "split_header": false,
  "split_payments": [
    {
      "email": "verified@account.com",
      "fixed_cut": 100,
      "variable_cut": 2,
      "stack_order": 0
    },
    {
      "email": "verified2@account.com",
      "fixed_cut": 200,
      "variable_cut": 3,
      "stack_order": 1
    }
   ]
}
        

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

HTTP Request

POST https://www.billplz.com/api/v4/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_payments[][email] The email address of the split rule's recipient. (The account must be a verified account.)
split_payments[][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_payments[][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
split_payments[][stack_order] Integer format that defines the sequence of the split rule recipients.
This field is required and must be in correct order starts from 0 and increment by 1 subsequently if you want to set a split rule.
This input is crucial to determine a precise recipient's order.
split_header Boolean value. All bill and receipt templates will show split rule recipient's infographic if this was set to true.

Response Parameter

Parameter Description
id ID that represents a collection
title The collection's title in string format.
logo[thumb_url] The thumb dimension's (180x180) URL.
logo[avatar_url] The avatar dimension's (40x40) URL.
split_header Boolean value. All bill and receipt templates will show split rule recipient's infographic if this was set to true.
split_payments Array that contains all split rule recipients in hash format.
email in hash represents the recipient's email.
fixed_cut in hash represents the recipient's fixed cut in smallest and positive currency unit.
variable_cut is the recipient's percentage cut in positive integer format.
stack_order is the order of the recipient defined in split rules.

Get a Collection

Example request:


# Get a collection
curl https://www.billplz.com/api/v4/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_header": false,
  "split_payments": [
    {
      "email": "verified@account.com",
      "fixed_cut": 100,
      "variable_cut": 2,
      "stack_order": 0
    },
    {
      "email": "verified2@account.com",
      "fixed_cut": 200,
      "variable_cut": 3,
      "stack_order": 1
    }
   ],
  "status": "active"
}
        

Use this API to query your collection record.

HTTP Request

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

Response Parameter

Parameter Description
id ID that represents a collection
title The collection's title in string format.
logo[thumb_url] The thumb dimension's (180x180) URL.
logo[avatar_url] The avatar dimension's (40x40) URL.
split_header Boolean value. All bill and receipt templates will show split rule recipient's infographic if this was set to true.
split_payments Array that contains all split rule recipients in hash format.
email in hash represents the recipient's email.
fixed_cut in hash represents the recipient's fixed cut in smallest and positive currency unit.
variable_cut is the recipient's percentage cut in positive integer format.
stack_order is the order of the recipient defined in split rules.
status Collection's status, it is either active and inactive.

Get Collection Index

Example request:


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

Response:


{
  "collections":
  [{
    "id": "inbmmepb",
    "title": "My First API Collection",
    "logo": 
    {
      "thumb_url": null,
      "avatar_url": null
    },
    "split_header": false,
    "split_payments": [],
    "status": "active"
  }],
  "page": 1
}

Example request with optional arguments:


# Get collection index
curl https://www.billplz.com/api/v4/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_header": false,
    "split_payments": [],
    "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/v4/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/v4/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_header": false,
  "split_payments": [],
  "url": "https://www.billplz.com/0pp87t_6"
}
        

Example request with optional arguments:


# Creates a collection
curl https://www.billplz.com/api/v4/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_header=true \
  -F split_payments[][email]="verified@account.com" \
  -F split_payments[][variable_cut]=20 \
  -F split_payments[][stack_order]=0
        

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_header": true,
  "split_payments": [
    {
      "email": "verified@account.com",
      "fixed_cut": null,
      "variable_cut": 20,
      "stack_order": 0
    }
  ],
  "url": "https://www.billplz.com/0pp87t_6"
}
        

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

HTTP Request

POST https://www.billplz.com/api/v4/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_payments[][email] The email address of the split rule's recipient. (The account must be a verified account.)
split_payments[][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_payments[][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
split_payments[][stack_order] Integer format that defines the sequence of the split rule recipients.
This field is required and must be in correct order starts from 0 and increment by 1 subsequently if you want to set a split rule.
This input is crucial to determine a precise recipient's order.
split_header Boolean value. All bill and receipt templates will show split rule recipient's infographic if this was set to true.

Response Parameter

Parameter Description
id The collection ID.
title The collection's title.
description The collection description.
reference_1_label Label #1 to reconcile payments.
reference_2_label Label #2 to reconcile payments.
email_link A URL that email to customer after payment is successful.
amount The collection's fixed amount to create bill in the smallest currency unit.
fixed_amount Boolean value. It returns to false if Open Amount.
tax Tax rate in positive integer format.
fixed_quantity Boolean value. It returns false if Open Quantity.
payment_button Payment button's text.
photo[retina_url] The retina dimension's (Yx960) URL.
photo[avatar_url] The avatar dimension's (180x180) URL.
split_header Boolean value. All bill and receipt templates will show split rule recipient's infographic if this was set to true.
split_payments Array that contains all split rule recipients in hash format.
email in hash represents the recipient's email.
fixed_cut in hash represents the recipient's fixed cut in smallest and positive currency unit.
variable_cut is the recipient's percentage cut in positive integer format.
stack_order is the order of the recipient defined in split rules.
url URL to the collection.

Get an Open Collection

Example request:


# Get an open collection
curl https://www.billplz.com/api/v4/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_header": false,
  "split_payments": [],
  "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/v4/open_collections/{COLLECTION_ID}

Response Parameter

Parameter Description
id The collection ID.
title The collection's title.
description The collection description.
reference_1_label Label #1 to reconcile payments.
reference_2_label Label #2 to reconcile payments.
email_link A URL that email to customer after payment is successful.
amount The collection's fixed amount to create bill in the smallest currency unit.
fixed_amount Boolean value. It returns to false if Open Amount.
tax Tax rate in positive integer format.
fixed_quantity Boolean value. It returns false if Open Quantity.
payment_button Payment button's text.
photo[retina_url] The retina dimension's (Yx960) URL.
photo[avatar_url] The avatar dimension's (180x180) URL.
split_header Boolean value. All bill and receipt templates will show split rule recipient's infographic if this was set to true.
split_payments Array that contains all split rule recipients in hash format.
email in hash represents the recipient's email.
fixed_cut in hash represents the recipient's fixed cut in smallest and positive currency unit.
variable_cut is the recipient's percentage cut in positive integer format.
stack_order is the order of the recipient defined in split rules.
url URL to the collection.
status Collection's status, it is either active and inactive.

Get Open Collection Index

Example request:


# Get open collection index
curl https://www.billplz.com/api/v4/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_header": false,
    "split_payments": [
      {
        "email": "verified@account.com",
        "fixed_cut": null,
        "variable_cut": 20,
        "stack_order": 0
      }
    ],
    "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/v4/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_header": false,
    "split_payments": [
      {
        "email": "verified@account.com",
        "fixed_cut": null,
        "variable_cut": 20,
        "stack_order": 0
      }
    ],
    "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/v4/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.

MPI Flow

Mass Payment allows you to make payment to any account bank registered in Malaysia. Since Bank doesn't provide way to programatically make payment to bank account, you can achieve that by using our Mass Payment Instruction (MPI) API.

Mass Payment implements the same collection concept as per API Flow. You will have collection that consists of multiple (MPI).

Before proceeding further, you need to ensure that you have enough payment limit to perform Mass Payment Instruction (MPI). To increase payment limit, navigate to Mass Payments tab and you will notice the Payment Limit at the top.

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

1) Get bank information from the recipient.
2) Execute Create a MPI API.
3) If failed, perform one-time bank account registration using Create a Bank Account;
3) Then, execute Create a MPI API again after three working days.
4) The payment will be settled to the receipient in one (1) working day except Thursday and public holidays.

MPI Collections

Create a MPI Collection

Example request with required arguments only:


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

Response:


{
  "id": "4po8no8h",
  "title": "My First API MPI Collection",
  "mass_payment_instructions_count": "0",
  "paid_amount": "0",
  "status": "active"
}
        

New Mass Payment Instruction Collection (MPI Collection) used to group all your Mass Payment Instructions (MPI) to make mass payment transfers.

HTTP Request

POST https://www.billplz.com/api/v4/mass_payment_instruction_collections

Required Arguments

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

Response Parameter

Parameter Description
id ID that represents a collection
title The collection's title in string format.
mass_payment_instructions_count The number of mass payment instruction belongs to this collection.
paid_amount Total paid amount for mass payment instructions in this collection.
A positive integer in the smallest currency unit (e.g 100 cents to charge RM 1.00).
status Collection's status, it is either active and inactive.

Get a MPI Collection

Example request with required arguments only:


# Get a MPI collection
curl https://www.billplz.com/api/v4/mass_payment_instruction_collections/4po8no8h \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: 
        

Response:


{
  "id": "4po8no8h",
  "title": "My First API MPI Collection",
  "mass_payment_instructions_count": "0",
  "paid_amount": "0",
  "status": "active"
}
        

Use this API to query your Mass Payment Instruction Collection record.

HTTP Request

GET https://www.billplz.com/api/v4/mass_payment_instruction_collections/{MASS_PAYMENT_INSTRUCTION_COLLECTION_ID}

Required Arguments

Parameter Description
MASS_PAYMENT_INSTRUCTION_COLLECTION_ID Collection ID returned in MPI Collection object.

Response Parameter

Parameter Description
id ID that represents a collection
title The collection's title in string format.
mass_payment_instructions_count The number of mass payment instruction belongs to this collection.
paid_amount Total paid amount for mass payment instructions in this collection.
A positive integer in the smallest currency unit (e.g 100 cents to charge RM 1.00).
status Collection's status, it is either active and inactive.

MPI

Create a MPI

Example request with required arguments only:


# Creates a MPI for RM 20.00
curl https://www.billplz.com/api/v4/mass_payment_instructions \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -d mass_payment_instruction_collection_id="4po8no8h" \
  -d bank_code="MBBEMYKL" \
  -d bank_account_number="820808062202123" \
  -d identity_number="820808062202" \
  -d name="Michael Yap" \
  -d description="Maecenas eu placerat ante." \
  -d total=2000
        

Response:


{
  "id": "afae4bqf",
  "mass_payment_instruction_collection_id": "4po8no8h",
  "bank_code": "MBBEMYKL",
  "bank_account_number": "820808062202123",
  "identity_number": 820808062202 ,
  "name": "Michael Yap",
  "description": "Maecenas eu placerat ante.",
  "email" :"hello@billplz.com",
  "status": "processing",
  "notification": false,
  "recipient_notification": true,
  "total": "2000"
}
        

Example request with optional arguments:


# Creates a MPI for RM 20.00
curl https://www.billplz.com/api/v4/mass_payment_instructions \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: \
  -d mass_payment_instruction_collection_id="4po8no8h" \
  -d bank_code="MBBEMYKL" \
  -d bank_account_number="820808062202123" \
  -d identity_number="820808062202" \
  -d name="Michael Yap" \
  -d description="Maecenas eu placerat ante." \
  -d total=2000 \
  -d email="recipient@email.com" \
  -d notification=true \
  -d recipient_notification=false
        

Response:


{
  "id": "57iofla8",
  "mass_payment_instruction_collection_id": "4po8no8h",
  "bank_code": "MBBEMYKL",
  "bank_account_number": "820808062202123",
  "identity_number": 820808062202 ,
  "name": "Michael Yap",
  "description": "Maecenas eu placerat ante.",
  "email" :"recipient@email.com",
  "status": "processing",
  "notification": true,
  "recipient_notification": false,
  "total": "2000"
}
        

To make a payment transfer to another bank account, simply create a Mass Payment Instruction (MPI).

To create a MPI, you would need the MPI collection’s ID. Each MPI must be created within a MPI Collection.

HTTP Request

POST https://www.billplz.com/api/v4/mass_payment_instructions

Required Arguments

Parameter Description
mass_payment_instruction_collection_id The MPI Collection ID. A string.
bank_code Bank Code that represents bank, in string value. Case sensitive.

Status code of 422 with "Bank account not found" message will be returned if no bank accounts matched.

So, please make sure all bank_code, bank_account_number and identity_number are all correct.

Please refer to API#get-a-bank-account
bank_account_number Bank account number, in string value.

Status code of 422 with "Bank account not found" message will be returned if no bank accounts matched.

So, please make sure all bank_code, bank_account_number and identity_number are all correct.

Please refer to API#get-a-bank-account
identity_number Bank account's IC Number/SSM Registration Number, in string value.

Status code of 422 with "Bank account not found" message will be returned if no bank accounts matched.

So, please make sure all bank_code, bank_account_number and identity_number are all correct.

Please refer to API#get-a-bank-account
name MPI’s recipient name. Useful for identification on recipient part.
description The MPI's description. Will be displayed on bill template. String format. (Max of 200 characters)
total Total amount you would like to transfer to the recipient.
A positive integer in the smallest currency unit (e.g 100 cents to charge RM 1.00)

Optional Arguments

Parameter Description
email The email address of recipient. (it default to sender's email if not present.)
A receipt will be sent to this email once the MPI has been processed.
notification Boolean value. As a sender, you can opt-in for email notification by setting this to true. Sender will receive email once a MPI has been processed. Default value is false.
recipient_notification Boolean value. If this is set to true, recipient of the MPI will receive email notification once the MPI has been processed. Default value is true. Set to false if you do not like the recipient to receive any email notifications.

Response Parameter

Parameter Description
id ID that represents a MPI
mass_payment_instruction_collection_id The MPI collection's title in string format.
bank_code Bank Code that represents bank, in string value. Case sensitive.
bank_account_number Bank account number, in string value.
identity_number Bank account's IC Number/SSM Registration Number, in string value.
name MPI’s recipient name.
description The MPI's description.
email The email address of recipient. (it default to sender's email if not present.)
status MPI status. It is either processing or completed
notification Boolean value. Sender will receive email notification if this is true
recipient_notification Boolean value. Recipient will receive email notification if this is true
total Total amount transfer to the recipient. A positive integer in the smallest currency unit (e.g 100 cents to charge RM 1.00)

Get a MPI

Example request with arguments:


# Get a MPI
curl https://www.billplz.com/api/v4/mass_payment_instructions/afae4bqf \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: 
        

Response:


{
  "id": "afae4bqf",
  "mass_payment_instruction_collection_id": "4po8no8h",
  "bank_code": "MBBEMYKL",
  "bank_account_number": "820808062202123",
  "identity_number": 820808062202 ,
  "name": "Michael Yap",
  "description": "Maecenas eu placerat ante.",
  "email" :"hello@billplz.com",
  "status": "processing",
  "notification": false,
  "recipient_notification": true,
  "total": "2000"
}
        

Use this API to query your Mass Payment Instruction (MPI) record.

HTTP Request

GET https://www.billplz.com/api/v4/mass_payment_instructions/{MASS_PAYMENT_INSTRUCTION_ID}

Required Arguments

Parameter Description
MASS_PAYMENT_INSTRUCTION_ID The MPI ID. A string.

Response Parameter

Parameter Description
id ID that represents a MPI
mass_payment_instruction_collection_id The MPI collection's title in string format.
bank_code Bank Code that represents bank, in string value. Case sensitive.
bank_account_number Bank account number, in string value.
identity_number Bank account's IC Number/SSM Registration Number, in string value.
name MPI’s recipient name.
description The MPI's description.
email The email address of recipient. (it default to sender's email if not present.)
status MPI status. It is either processing or completed
notification Boolean value. Sender will receive email notification if this is true
recipient_notification Boolean value. Recipient will receive email notification if this is true
total Total amount transfer to the recipient. A positive integer in the smallest currency unit (e.g 100 cents to charge RM 1.00)

Webhook Rank

Example request:


# Get a MPI
curl https://www.billplz.com/api/v4/webhook_rank \
  -u 73eb57f0-7d4e-42b9-a544-aeac6e4b0f81: 
        

Response:


{
  "rank": 0.0
}
        

Webhook Rank has been introduced to ensure callback is running at it's best. The higher the ranking, the higher priority for the callback to be executed. Use this API to query your current Account Ranking. 0 indicate highest ranking (default) and 10 lowest ranking.

HTTP Request

GET https://www.billplz.com/api/v4/webhook_rank

Response Parameter

Parameter Description
rank Ranking Number (0.0 - 10.0)

X Signature

X Signature Calculation

The message level security is implemented by using signing and verification of the message.

Step 1 - Construct Source String

Step 2 - Sign The Source String

Payment Completion

Basic Callback Url

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@billplz.com"
  &mobile="+60112223333"
  &name="MICHAEL API"
  &metadata[id]="9999"
  &metadata[description]="This is to test bill creation"
  &url="http://billplz.dev/bills/W_79pJDk"
  &paid_at="2015-03-09 16:23:59 +0800"
        

Body formatted for readability.

callback_url feature does not give your users the same instant bill update experience as of redirect_url feature, however it does guarantee you 100% execution backend to backend update.

callback_url feature integration is compulsory but redirect_url feature is optional.

**you are strongly advised to integrate both redirect_url feature (for better user experience) and callback_url feature (for 100% transaction update)

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 be in due state.

By default, Basic Callback URL feature is enabled.

HTTP Request

POST {CALLBACK_URL}

Post Parameter

Parameter Description
id ID that represents bill.
collection_id ID that represents the collection where the bill belongs to.
paid Boolean value to tell if a bill has paid. It will return false for due bills; true for paid bills.
state State that representing the bill's status, possible states are due and paid.
amount Bill's amount in positive integer, smallest currency unit (e.g 100 cents to charge RM 1.00)
paid_amount Bill's paid amount in positive integer, smallest currency unit (e.g 100 cents to charge RM 1.00)
due_at Due date for the bill, in format YYYY-MM-DD. Example, 2020-12-31
email The email address of the bill's recipient.
mobile Recipient's mobile number, in format +601XXXXXXXX
name Recipient's name.
metadata Deprecated hash value data.
URL URL to the bill page.
paid_at Date time when the bill was paid, in format YYYY-MM-DD HH:MM:SS TimeZone. Example, 2017-02-13 05:43:43 +0800

Callback request will be timeout at 20 seconds.

Billplz server also expecting the end point server responds with status code of 200.

In a case of either the end point server does not able to respond within the limit seconds (20 secs) or does not respond with 200 status code, the callback will consider as failure.

On failure, the job is scheduled again in 15 minutes * N, where N is the number of attempts with maximum of 4. The 5th (last) attempt will be 24 hours after 4th attempt.

Billplz will attempt for maximum of 5 times and the callback will be removed from the system queue permanently after that.

Basic Redirect Url

redirect_url feature is just a front-end redirection to redirect_url specified, it does not guaranteed the execution, due to many factors (user disconnected, browser closed, app hang, etc).

But it is good to have, to provide better user experience (front-end instant bill status update)

callback_url feature integration is compulsory but redirect_url feature is optional.

**you are strongly advised to integrate both redirect_url feature (for better user experience) and callback_url feature (for 100% transaction update)

Client Side Request

If redirect_url exists, Billplz will redirect the browser to redirect_url

By default, Basic Redirect URL feature is enabled.

HTTP Request

GET {REDIRECT_URL}?billplz[id]=W_79pJDk

URL Parameter

Parameter Description
billplz[id] ID that represents bill.

X Signature Callback Url

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@billplz.com"
  &mobile="+60112223333"
  &name="MICHAEL API"
  &url="http://billplz.dev/bills/W_79pJDk"
  &paid_at="2015-03-09 16:23:59 +0800"
  &x_signature="f0ff6c564f98d5403e2b26fbd3d45309c76eb68d8c5bcda0d48b541c3502a396"
        

Body formatted for readability.

callback_url feature does not give you the same instant bill update experience as of redirect_url feature, however it does guarantee you 100% execution backend to backend update.

callback_url feature integration is compulsory but redirect_url feature is optional.

**you are strongly advised to integrate both redirect_url feature (for better user experience) and callback_url feature (for 100% transaction update)

Server Side Request

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

X Signature Callback URL request created through the API by Billplz can be verified by calculating a digital signature - x_signature.

Each callback request includes a x_signature which is generated using HMAC-SHA256 algorithm and shared XSignature Key, along with the data sent in the request.

To verify that the request came from Billplz, compute the HMAC-SHA256 digest according to the X Signature section and compare it to the value in the x_signature parameter. If they match, you can be sure that the callback was sent from Billplz and the data has not been compromised.

A bill that catched payment failure will be in due state.

By default, X Signature Callback URL feature is not activated. If you wish to activate X Signature Callback URL to replace Basic Callback URL, please go to your setting page to turn it on.

HTTP Request

POST {CALLBACK_URL}

Post Parameter

Parameter Description
id ID that represents bill.
collection_id ID that represents the collection where the bill belongs to.
paid Boolean value to tell if a bill has paid. It will return false for due bills; true for paid bills.
state State that representing the bill's status, possible states are due and paid.
amount Bill's amount in positive integer, smallest currency unit (e.g 100 cents to charge RM 1.00)
paid_amount Bill's paid amount in positive integer, smallest currency unit (e.g 100 cents to charge RM 1.00)
due_at Due date for the bill, in format YYYY-MM-DD. Example, 2020-12-31
email The email address of the bill's recipient.
mobile Recipient's mobile number, in format +601XXXXXXXX
name Recipient's name.
URL URL to the bill page.
paid_at Date time when the bill was paid, in format YYYY-MM-DD HH:MM:SS TimeZone. Example, 2015-03-09 16:23:59 +0800
x_signature Digital signature computed with posted data and shared XSignature Key.

Callback request will be timeout at 20 seconds.

Billplz server also expecting the end point server responds with status code of 200.

In a case of either the end point server does not able to respond within the limit seconds (20 secs) or does not respond with 200 status code, the callback will consider as failure.

On failure, the job is scheduled again in 15 minutes * N, where N is the number of attempts with maximum of 4. The 5th (last) attempt will be 24 hours after 4th attempt.

Billplz will attempt for maximum of 5 times and the callback will be removed from the system queue permanently after that.

Sample HTTP request from X Signature callback url feature

POST {CALLBACK_URL}

with POST body,
{:id=>"zq0tm2wc", :collection_id=>"yhx5t1pp", :paid=>true, :state=>"paid", :amount=>100, :paid_amount=>100, :due_at=>"2018-9-27", :email=>"tester@test.com", :mobile=>nil, :name=>"TESTER", :url=>"http://billplz-staging.herokuapp.com/bills/zq0tm2wc", :paid_at=>"2018-09-27 15:15:09 +0800", :x_signature=>"f700880531938f3c16d2b06e195509a381db4ba7f4e771d1aaf93ca468102276"}

#1 Extract all key-value pair parameters except x_signature,

id="zq0tm2wc"

collection_id="yhx5t1pp"

paid="true"

state="paid"

amount="100"

paid_amount="100"

due_at="2018-9-27"

email="tester@test.com"

mobile=""

name="TESTER"

url="http://billplz-staging.herokuapp.com/bills/zq0tm2wc"

paid_at="2018-09-27 15:15:09 +0800"

#2 Construct source string from each key-value pair parameters above, become

idzq0tm2wc

collection_idyhx5t1pp

paidtrue

statepaid

amount100

paid_amount100

due_at2018-9-27

emailtester@test.com

mobile

nameTESTER

urlhttp://billplz-staging.herokuapp.com/bills/zq0tm2wc

paid_at2018-09-27 15:15:09 +0800

#3 Sort in ascending order, case-insensitive.

amount100

collection_idyhx5t1pp

due_at2018-9-27

emailtester@test.com

idzq0tm2wc

mobile

nameTESTER

paid_amount100

paid_at2018-09-27 15:15:09 +0800

paidtrue

statepaid

urlhttp://billplz-staging.herokuapp.com/bills/zq0tm2wc

#4 Combine sorted source strings with "|" (pipe) character in between.

amount100|collection_idyhx5t1pp|due_at2018-9-27|emailtester@test.com|idzq0tm2wc|mobile|nameTESTER|paid_amount100|paid_at2018-09-27 15:15:09 +0800|paidtrue|statepaid|urlhttp://billplz-staging.herokuapp.com/bills/zq0tm2wc

#5 Compute x_signature by signing the final source in #4 using HMAC_SHA256 and the sample XSignature Key,
S-s7b4yWpp9h7rrkNM1i3Z_g

f700880531938f3c16d2b06e195509a381db4ba7f4e771d1aaf93ca468102276

#6 Compare the computed x_signature with the x_signature passed in the request.

If they match, you can be sure that the callback was sent from Billplz and the data has not been compromised,
and you do not need to trigger additional Get a Bill API for primary status validation.

X Signature Redirect Url

redirect_url feature is just a front-end redirection to the redirect_url specified, it does not guaranteed the execution, due to many factors (user disconnected, browser closed, app hang, etc).

But it is good to have, to provide better user experience (front-end instant bill status update)

callback_url feature integration is compulsory but redirect_url feature is optional.

**you are strongly advised to integrate both redirect_url feature (for better user experience) and callback_url feature (for 100% transaction update)

Client Side Request

If redirect_url exists, Billplz will redirect the browser to redirect_url

X Signature Redirect URL request created by Billplz can be verified by calculating a digital signature - x_signature.

Each redirect request includes a x_signature which is generated using HMAC-SHA256 algorithm and shared XSignature Key, along with the parameters passed in the request.

To verify that the request came from Billplz, compute the HMAC-SHA256 digest according to the X Signature section and compare it to the value in the x_signature parameter. If they match, you can be sure that the redirection was sent from Billplz and the data has not been compromised.

By default, X Signature Redirect URL feature is not activated. If you wish to activate X Signature Redirect URL to replace Basic Redirect URL, please go to your setting page to turn it on.

HTTP Request

GET {REDIRECT_URL}?billplz[id]=ifpgaa&billplz[paid]=true&billplz[paid_at]=2017-01-04%2013%3A10%3A45%20%2B0800&billplz[x_signature]=76de0ad8cc23706d694fd81c9027b8e3ae169e0880d75e1e123c5832c82bf707

URL Parameter

Parameter Description
billplz[id] ID that represents bill.
billplz[paid] Boolean value to tell if a bill has paid. It will return false for due bills; true for paid bills.
billplz[paid_at] Date time when the bill was paid, in format YYYY-MM-DD HH:MM:SS TimeZone. Example, 2017-01-04 13:10:45 +0800
billplz[x_signature] Digital signature computed with passing parameters and shared XSignature Key.

Sample HTTP request from X Signature redirect url feature

GET {REDIRECT_URL}?billplz[id]=zq0tm2wc&billplz[paid]=true&billplz[paid_at]=2018-09-27%2015%3A15%3A09%20%2B0800&billplz[x_signature]=4aab095fe5a39b1d534500988f9a0cb085cd1b6d5bbb55dd4e02ea6fa102b47b

#1 Extract all key-value pair parameters except x_signature,

billplz[id]="zq0tm2wc"

billplz[paid]="true"

billplz[paid_at]="2018-09-27 15:15:09 +0800"

#2 Construct source string from each key-value pair parameters above, become

billplzidzq0tm2wc

billplzpaidtrue

billplzpaid_at2018-09-27 15:15:09 +0800

#3 Sort in ascending order, case-insensitive.

billplzidzq0tm2wc

billplzpaid_at2018-09-27 15:15:09 +0800

billplzpaidtrue

#4 Combine all source strings with "|" (pipe) character in between.

billplzidzq0tm2wc|billplzpaid_at2018-09-27 15:15:09 +0800|billplzpaidtrue

#5 Compute x_signature by signing the final source in #4 using HMAC_SHA256 and the sample XSignature Key,
S-s7b4yWpp9h7rrkNM1i3Z_g

4aab095fe5a39b1d534500988f9a0cb085cd1b6d5bbb55dd4e02ea6fa102b47b

#6 Compare parameter x_signature passed in the request with the computed x_signature in #5.

If they match, you can be sure that the redirection was sent from Billplz and the data has not been compromised,
and you do not need to trigger additional Get a Bill API for primary status validation.