PerfectBiller Documentation

Prerequisite

Before you proceed, you must create an account with PerfectBiller and a Merchant Id will be assigned to you.
It is visible on the Menu section of your PerfectBiller Dashboard.
If you already have an account, Click Here to Login to dashboard. Otherwise Click Here to Create an account
For the purpose of development and testing, you can use PB-DEMO as merchant Id. If that is the case, You will not need real payment details to run your tests, you can use any of the test accounts/Cards povideded
Here for demo

HTML Implementation

HTML Implementation

There are basically two methods of implementing PerfectBiller Payment on HTML Page
  1. Off Page Implementation
  2. On-Page Implementation

Off-Page Implementation

This Implementation mode will redirect your client to PerfectBiller Payment Page when he triggers the payment action, and after the payment will be returned to your specified pages as specified in the success/failure urls in your payment setup, depending on the payment confirmation status.

On-Page Implementation

This payment mode will not take your client away from your page, but will load the PerfectBiller Payment module on your page, allowing your client to complete the transaction without being redirected to PerfectBiller Payment page.

HTML SETUP

HTML SETUP

Implementing PerfectBiller payment Plugin on HTML page is very much simple, Just copy and paste the sample codes into the section of your HTML page where you want to include the payment button.
For advanced programmers, See JavaScript Implementation
Remember: For sandbox / development, use PB-DEMO as the merchant ID You can go live by changing the Merchant ID to the live merchant ID, which can be found on your PerfectBiller Dashboard

HTML OFF-Page Setup

Requiremed Aspect(s):
1. HTML Codes Only:
This is the simplest form of HTML implementation (No JavaScript required), you only need to copy and paste the following codes, then change the necessary parameters.
NB: This mode will take your client to the PerfectBiller Payment page to complete the transaction.

Please refer to Parameter Description for all usable element names that forms part of your code.

<form id='pbform' method='POST' action='https://perfectbiller.com/pay/'>
    <input type='hidden' name='merchant_id' value='PB-DEMO' />
    <input type='hidden' name='merchant_ref' value='ABCD-1234' />
    <input type='hidden' name='memo' value='Payment for Lora e-stores' />
<input type='hidden' name='item_1' value='Casual women shoe' /> <input type='hidden' name='description_1' value='Casual Comfort women fashion flat shoes-black' /> <input type='hidden' name='price_1' value='3200' />
<input type='hidden' name='item_2' value='Coconut & Hibiscus Oil' /> <input type='hidden' name='description_2' value='Coconut & Hibiscus Curl Enhancing Smoothie120z' /> <input type='hidden' name='price_2' value='4050' />
<input type='hidden' name='item_3' value='Mini Desc Fan' /> <input type='hidden' name='description_3' value='Mini Air Conditional Portable desk fan with Fragrance' /> <input type='hidden' name='price_3' value='5600' />
<input type='hidden' name='customer_name' value='Akunne Umah'/> <input type='hidden' name='customer_email' value='Customer email'/> <input type='hidden' name='customer_phone' value= 'Customer phone '/>
<!--Callback Options --> <input type='hidden' name='success_url' value= 'http://www.mywebsite.com/paymentsuccess'/> <input type='hidden' name='failure_url' value= 'http://www.mywebsite.com/paymentfailure'/> <input type='hidden' name='notify_url' value= 'http://www.mywebsite.com/paymentnotify'/>
<!--Optional Parameters --> <input type='hidden' name='address' value='123 Street Avenue, Nigeria'/> <input type='hidden' name='city' value='Customer City'/> <input type='hidden' name='state' value='Customer State'/> <input type='hidden' name='zipcode' value='Customer Zip/Post Code'/> <input type='image' src='https://perfectbiller.com/buttons/buy_blue.png' alt='Submit' /> </form>

HTML ON-Page Integration

To be able to accept payment directly on your page, we require that your website is SSL Secured, otherwise we suggest that you use Off-Page implementation method.
Required Aspects:
1. HTML Setup Code: This is the part of the setup that defines your merchant details, charge details and clients details, just like the off-page method
2.Success & Failure Callback (JavaScript): You will need to create a custom JavaScript function that will be executed after the payment, we already created two functions successcallback() and failurecallback(), you can copy and paste or modify to suit your desire.
successcallback() will execute if the payment is successfull while failurecallback() will execute if for any reason, the payment failed.
3. Import PerfectBiller JS Library (JavaScript): You must import and initiate the PerfectBiller JS Library into your page before the ON-PAGE setup can work correctly.

Having described all we need for this mode of payment, we will take the steps one after the other

1.HTML Setup Code.

Copy the HTML codes and modify the necessary Parameters
<form id='pbform' method='POST' >
    <input type='hidden' name='merchant_id' value='PB-DEMO' />
    <input type='hidden' name='merchant_ref' value='ABCD-1234' />
    <input type='hidden' name='memo' value='Payment for Lora e-stores' />
<input type='hidden' name='item_1' value='Casual women shoe' /> <input type='hidden' name='description_1' value='Casual Comfort women fashion flat shoes-black' /> <input type='hidden' name='price_1' value='3200' />
<input type='hidden' name='item_2' value='Coconut & Hibiscus Oil' /> <input type='hidden' name='description_2' value='Coconut & Hibiscus Curl Enhancing Smoothie120z' /> <input type='hidden' name='price_2' value='4050' />
<input type='hidden' name='item_3' value='Mini Desc Fan' /> <input type='hidden' name='description_3' value='Mini Air Conditional Portable desk fan with Fragrance' /> <input type='hidden' name='price_3' value='5600' />
<input type='hidden' name='customer_name' value='Akunne Umah'/> <input type='hidden' name='customer_email' value='Customer email'/> <input type='hidden' name='customer_phone' value= 'Customer phone '/>
<!--Callback Options --> <input type='hidden' name='success_url' value= 'http://www.mywebsite.com/paymentsuccess'/> <input type='hidden' name='failure_url' value= 'http://www.mywebsite.com/paymentfailure'/> <input type='hidden' name='notify_url' value= 'http://www.mywebsite.com/paymentnotify'/>
<!--Optional Parameters --> <input type='hidden' name='address' value='123 Street Avenue, Nigeria'/> <input type='hidden' name='city' value='Customer City'/> <input type='hidden' name='state' value='Customer State'/> <input type='hidden' name='zipcode' value='Customer Zip/Post Code'/> <input type='image' src='https://perfectbiller.com/buttons/buy_blue.png' alt='Submit' /> </form>

2. Success and Failure Callback functions

We already created a sample code for you to copy and paste, then modify to suit your needs
   <script>
        function successcallback(tx_id){
            alert("Transaction Successfull: "+tx_id);
            window.location.href="http://mywebsite.com/paymentconfirm?tx_id="+tx_id;
        }
        function failurecallback(tx_id){
            alert("Transaction Failed: "+tx_id);
            window.location.href="http://mywebsite.com/transactionfailed?tx_id="+tx_id;
        }
    </script>

3. Import PerfectBiller Library and Initialize

Copy and paste the code to import PerfectBiller JavaScript library
<script src="//perfectbiller.com/pay/perfectbiller.js"></script>
<script>
    PB.init({
        form: 'pbform', //id attribute of your payment form
        onsuccess: successcallback,
        onfailed: failurecallback,
   });
</script>

JavaScript Implementation

Javascript Implementation

Most developers might might prefer Implementing the PerfectBiller Payment using Javascript codes.
The above HTML examples can also be replicated using only Javascript.
Just Copy the following codes and change the necessary parameters.
NB: Please make reference to Parameters Description Section to understand the parameters required on your PerfectBiller Setup.
To switch between OFF-PAGE and ON-PAGE implementation, just change the value for the mode to onpage or offpage. If this value is not set, it sets to onpage by default.
<script src="//perfectbiller.com/pay/perfectbiller.js"></script>

<script>
    closedFunction=function() {
        alert('window closed');
    }

     successFunction=function(transaction_id) {
        alert('Transaction was successful, Ref: '+transaction_id)
    }

     failedFunction=function(transaction_id) {
         alert('Transaction was not successful, Ref: '+transaction_id)
    }
</script>

 <script>
    function paynow(item,price){
       PB.Pay({
            mode: 'offpage', //can use onpage or offpage
            merchant_id: 'PB-DEMO',
            total: price,
            notify_url:'http://www.mywebsite.com/notify',
            cur: 'NGN',
            customer_email: 'email@domain.com',
            customer_phone: "2348012345678",
            merchant_ref:  "ABCD-1234",
            memo:'Payment for '+item,
            store_id:1,
            items: [
                    {
                        name: "Fancy Beautiful handbag",
                        description: "zena handbag 78S",
                        price: 1800
                    },
                    {
                        name: "Donzim Shoes",
                        description: "Italian male shoe",
                        price: 5000
                    },

                ],
           closed:closedFunction,
           onsuccess:successFunction,
           onfailed:failedFunction
       });
    }

 </script>

 <button type="button" onclick="paynow('ez-stores',51800)"> Pay With PerfectBiller </button>

                            

Parameters Description

Parameters Description

The table below lists all the usable parameters on the HTML and JavaScript implementation methods.
Take note of parameters marked as required
Field Expected Value
merchant_id (required)

You can get your merchant Id from your Perfect Biller Dashboard

For the purpose of development testing, you can use PB-DEMO as merchant Id until you wish to go live

cur (optional)

If provided, your client will be requrired to make payment in specified currency, provided the currency is enabled on your account dashboard.

merchant_ref (optional)

This identifier is recommened but yet remains optional.

This value is provided as identifier from the merchant's side. Any value provided here, will be returned with the confirmation results. It is used by the merchant to store any data he wishes to retrieve later with the transaction details. For example, username of your client on your website.

memo (optional)

This is the transaction summary or description

item_x

The name of the product(item) being purchased.

(x) is a value starting from 1.

If there are more than 1 products, you can have item_1, item_2, item_3...

As shown in the Sample HTML Forms. Each item_x has a corresponding description_x and price_x

description_x

The short description of the product being purchased.

(x) is a value starting from 1.

If there are more than 1 products(item), you can have multiple description to match each product(item)s specified description_1, description_2, description_3...

As shown in the Sample HTML Form below. Each item_x has a corresponding description_x and price_x

price_x

The price of the product(item)s being purchased. x corresponds to the number in item_x and description_x.

(x) is a value starting from 1.

If there are more than 1 products(item), you can have multiple prices to match each product(item)s and description(s) specified e.g price_1, price_2, price_3...

As shown in the Sample HTML Form below. Each item_x has a corresponding item_x, description_x and price_x

total (optional)

Total of all the prices_x (price_1 + price_2 + price_3...)

This optional field serves as a check for the submitted form. If included, this will be used instead of the sum of all the prices.

notify_url (optional)

Each time a transaction is completed on PerfectBiller, we send a payload containing the transaction details to your notification url, otherwise known as the Webhook. see Webhook/Notification Url for detailed implementation process.

success_url (optional)

Your client will be redirected to this page if the payment is successfull.

failure_url (optional)

If this parameter is set, your client will be automatically redirected to this url if your his transaction fails.

Checkout Buttons

Feel free to download our Buttons (Compressed Zip: 457KB) which you can use on your payment/checkout pages.

Depending on your website theme, you can decide to choose from any of our variations: blue,green,orange,pink,purple,black

blue green orange pink purple black
https://perfectbiller.com/buttons/buy_blue.png
https://perfectbiller.com/buttons/buy_green.png
https://perfectbiller.com/buttons/buy_orange.png
https://perfectbiller.com/buttons/buy_pink.png
https://perfectbiller.com/buttons/buy_purple.png
https://perfectbiller.com/buttons/buy_black.png
https://perfectbiller.com/buttons/checkout_blue.png
https://perfectbiller.com/buttons/checkout_green.png
https://perfectbiller.com/buttons/checkout_orange.png
https://perfectbiller.com/buttons/checkout_pink.png
https://perfectbiller.com/buttons/checkout_purple.png
https://perfectbiller.com/buttons/checkout_black.png
https://perfectbiller.com/buttons/pay_blue.png
https://perfectbiller.com/buttons/pay_green.png
https://perfectbiller.com/buttons/pay_orange.png
https://perfectbiller.com/buttons/pay_pink.png
https://perfectbiller.com/buttons/pay_purple.png
https://perfectbiller.com/buttons/pay_black.png
https://perfectbiller.com/buttons/donate_blue.png
https://perfectbiller.com/buttons/donate_green.png
https://perfectbiller.com/buttons/donate_orange.png
https://perfectbiller.com/buttons/donate_pink.png
https://perfectbiller.com/buttons/donate_purple.png
https://perfectbiller.com/buttons/donate_black.png
https://perfectbiller.com/buttons/renew_blue.png
https://perfectbiller.com/buttons/renew_green.png
https://perfectbiller.com/buttons/renew_orange.png
https://perfectbiller.com/buttons/renew_pink.png
https://perfectbiller.com/buttons/renew_purple.png
https://perfectbiller.com/buttons/renew_black.png
https://perfectbiller.com/buttons/subscribe_blue.png
https://perfectbiller.com/buttons/subscribe_green.png
https://perfectbiller.com/buttons/subscribe_orange.png
https://perfectbiller.com/buttons/subscribe_pink.png
https://perfectbiller.com/buttons/subscribe_purple.png
https://perfectbiller.com/buttons/subscribe_black.png

WebHook / Notification URL

What is WebHook / Notification URL

When a transaction is completed, PerfectBiller Sends a Payload of data containing the transaction details to the url you provide.
This comes as a necessity when you want your server to automatically process payment and give value to your clients without human intervention.

Handling Notification URL

The Payload sent to the webhook is a JSON Post data. Depending on the programing language used on your server, you can know how best to interprete the data. The examples on this documentation is for a PHP Server, but the procedures remain the same for other programing languages.

Procedures of Handling Payload On you WebHook

  1. Receive Data Via Post: The sample transaction data is shown below, but for security reasons, it is of Paramount Importance that you verify the transaction data using the PerfectBiller transaction verify before giving value to your client. A hacker can send a fake payload to your and if not verified your system will give value to the client without receiving the actual payment.
  2. Verifying Your Payment: We will guide you on how to use the PerfectBiller transaction verify to authenticate payload before giving value to your client.
    Before you proceed, do take note of the two references that forms part of the parameters received from the payload.
    a. merchant_ref : This is the transaction reference as provided by the merchant (You), it is the unique identifier from your own system for a particular transaction. It can be your system generated transaction id, your clients, email, username or any reference you will use to identify your client on your database. Make reference to Parameters Description
    b. transaction_ref : This is the transaction reference generated by PerfectBiller for each transaction. It is used as key to verify transaction on transaction verify

1. Sample Transaction Payload

{
    merchant_ref : 'ABCD-1234',
    customer_email : 'michael.o@yahoo.com',
    customer_phone : '2348034567890',
    total : '12400.00',
    cur : 'NGN',
    status : 'Approved',
    transaction_ref : 'PB-1559445533',
}

Verifying Transactions Using Transaction Reference

2. Verifying Transaction Using Transaction Reference

You can always verify any transaction using the Transaction Reference by making a call to our transaction verification url. https://www.perfectbiller.com/tx_verify.
NB: You need to send a post data containing two parameters.
  • txn_reference: Which is the transaction reference returned after making the payment
  • secret_key: You need to login to your PerfectBiller dashboard to obtain an API Secret Key.
    From the dashboard menu, click on My Account > API Keystore > New API Key.
    For any transaction Performed with PB-DEMO as Merchant Id, You can verify with PB-DEMO-SECRET as your secret key.

Sample Response

When you make a request using the right parameters, you get a response that looks like this

{
    status: "success",
    resp: "Approved",
    successful_verifications : 1,
    transaction_ref: "PB-1559445533",
    transaction_datetime: "2019-06-02 04:21:14",
    transaction_details: {
        merchant_id: "PB-DEMO",
        total: "6800",
        cur: "NGN",
        notify_url:"http://www.mywebsite.com/notify",
        customer_email: "email@domain.com",
        customer_phone: "2348012345678",
        merchant_ref:  "ABCD-1234",
        ip: "192.168.54.2",
        memo:"Payment for Oz-Stores",
        items: [
                {
                    name: "Fancy Beautiful handbag",
                    description: "zena handbag 78S",
                    price: "1800"
                },
                {
                    name: "Donzim Shoes",
                    description: "Italian male shoe",
                    price: "5000"
                },
            ],
    }

}
Take note of the successful_verifications the value is a count of number of successful verifications for each transfaction_ref.
You can use this to control machine error or human error, such that your client will not be given value more than once.

Example 1

A PHP Example for verifying transaction Using Transaction Reference and Secret Key

For a full sample code for creating a notification_url/webhook on php, see example 2

<?php
//let us create a custom function that accepts the transaction reference and secret key
//then returns the full transaction details
//Please Note, you have to login to your Perfect Biller dashboard to obtain your secret key,
//but for the purpose of development test, you can use PB-DEMO-SECRET as secret key.

function VerifyTransactionRef($txref,$secret_key){
    $postfields = array('txn_reference'=> $txref, 'secret_key' => $secret_key);
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL,"https://perfectbiller.com/tx_verify");
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postfields));  //Post Fields
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $request = curl_exec ($ch);
    if(curl_error($ch)){
      return "Error connecting to verification Api";
    }
    curl_close ($ch);
    $result = json_decode($request, true);
    return $result;
}

//The next step is to make a call to the VerifyTransactionRef function.
$response = VerifyTransactionRef('PB-1559445533','PB-DEMO-SECRET');

if(isset($response['status']) && ($response['status'] == 'success') && isset($response['resp']) && ($response['resp'] == 'Approved')){
    if(@$response['successful_verifications'] > 1){
        echo 'This transaction has been verified before';
        exit();
    }else{
        //at this point, you have verified the transaction and every other detail
        //is stored in the array, $response['transaction_details'].

        //perform other verifications such as users email, phone ,etc
        //give the value to the user.
    }

}else{
		echo json_encode($response);
	}

Example 2: Webhook /Notification URL Sample on PHP

Let us take an instance of an e-commerce website site. Each order is identified by the website using an order id. So in this case, the system uses the order id as the merchant_ref.
You can copy and paste this block of codes in your notification_url file
<?php

    $notification_data = $_POST;

    //You can decide to store the notification data to a file a database.
    error_log(json_encode($notification_data));


    function VerifyTransactionRef($txref,$secret_key){
        $postfields = array('txn_reference'=> $txref, 'secret_key' => $secret_key);
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL,"https://www.perfectbiller.com/tx_verify");
        curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postfields));  //Post Fields
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        $request = curl_exec ($ch);
        if(curl_error($ch)){
          return "Error connecting to verification Api";
        }
        curl_close ($ch);
        $result = json_decode($request, true);
        return $result;
    }

    //The next step is to make a call to the VerifyTransactionRef function.
    $transaction_reference = $notification_data['transaction_ref'];
    $secret_key = 'PB-DEMO-SECRET';
    $response = VerifyTransactionRef($transaction_reference,$secret_key);


    if(@$response['status'] == 'success' && @$response['resp'] == 'Approved' ){
        //you have verified the transaction
        //every other transaction information is stored in the array $response.

        //Ensuring this transaction has not been verified before
        if(@$response['successful_verifications'] > 1){
            echo 'This transaction has been verified before';
            exit();
        }else{
           /*
           Optional Block of codes to verify your customer/client
           $response['transaction_details']['customer_email'] matches your client's email,
           $response['transaction_details']['total'] matches your transaction value,
           $response['transaction_details']['cur'] matches your transaction currency,
           $response['transaction_details']['customer_phone'] matches your client's phone,
           $response['transaction_details']['merchant_ref'] matches your client's order id,
         */


         /*
           Block of codes to set your order status to completed,
           log your transaction and notify your customer.
         */
        }

    }else{
		echo json_encode($response);
	}
    exit();

               

Virtual POS/Payment Link

Virtual POS

If dont have a website or dont want to get dirty with codes, we already have a perfect plan for you.
You just need to setup Virtual POS link.
All you need is to provide the necessary information and generate a unique link which you can send to your clients and receive payments directly to your PerfectBiller account. This silmulates a typical POS(Point Of Sale) device and is very easy to use.
Anyway, the limitations on the VPOS system are

  1. You can only receive a maximum of N100,000 in a single transaction
  2. There are no options to specify notification url, success url or failure url. This implies that you have to manually give the client the value for the payment made.
However, for any transaction performed with vPOS, both the payer and the payee receives email and sms notifications containing the transaction details
vPOS

vPOS LINKS

There are basically two methods of generating payment link.

  1. From Your dashboard: You can login to your Perfect Biller Dashboard and generate a payment link, all the necessary parameters that were set are stored in the key token supplied along the payment link.
    Sample payment link.
    https://perfectbiller.com/pos/efizyshop
  2. Parameter Based Link: in case you dont want to generate a payment link from your dashboard, you make a http get request to the Perfect Biller pos link.
    https://perfectbiller.com/pos

Here is an example of parameter based vPOS link
https://perfectbiller.com/pos?merchant_id=PB-DEMO&total=12500&merchant_ref=invoice301&memo=Payment%20for%20bulksms%20subscription

vPOS Parameters Description
Field Expected Value
merchant_id

This is your merchant id, which you can get your from your Perfect Biller Dashboard, this parameter is optional, if not provided, the client will be requested to provide your merchant_id

For the purpose of development testing, you can use PB-DEMO as merchant Id until you wish to go live

merchant_ref

This identifier is recommened but yet remains optional.

This value is provided as identifier from the merchant's side. Any value provided here, will be returned with the confirmation results. It is used by the merchant to store any data he wishes to retrieve later with the transaction details. For example, username of your client on your website.

memo

This is the transaction summary or description

total

This is the price that your client will be charged for the transaction

Test Accounts

Test Cards

For the purpose of development, you can use the card details to silmulate transactions.
But you have to set merchant_id to PB-DEMO

PIN Transaction
5399832615671382
cvv 212
Expiry: 12/22
Pin 1515
otp 12345
3DSecure authentication
4960091889134256
cvv 212
Expiry: 12/22
Pin 1112
otp 12345
Declined Transaction
5061021096405863119
cvv 212
Expiry: 12/21
Pin 12345

Insufficient Funds
4960091815671382
cvv 212
Expiry: 12/21
Pin 1234
otp 12345
Successfull wallet Transaction
email: success@perfectbiller.com
password: success
otp: 12345


Failed wallet Transaction
email: failed@perfectbiller.com
password: failed
otp: 12345