1. Home
  2. Libraries for webmasters
  3. Server-side scripts in PHP

Server-side scripts in PHP

If you need a payment module in PHP, contact with us. The module requires version no. 5.3 of PHP. The module requires extension JSON to support standard payments using Billon JavaScript scripts and communication with the ‘billon.me’ service and extension SOAP to support direct communication with 24/7 application. Communication with the ‘billon.me’ service requires enabled accessing URL object like files or extension cURL. Separate files or controller actions to initiate and listen for payments will be needed to handle payments. Both files or actions have to include file or function that should begin with an import of the Billon library and creation of a payment object at the beginning:

require_once "billon/index.php"; // location of a script 'index.php' of the Billon payment module
$myShop = new \billon\Shop();

Next, call the configuration functions for the newly created payment object, which receive ‘requestData’ as a parameter (it is an object sent for the user’s browser via the POST method) and then return correctly formatted data to the object as a callback, in this file or function.

Configuration methods

Configuration methods return a reference to their object. An example of a product purchase payment service (payment for product):

require_once "billon/index.php"; // location of a script 'index.php' of the Billon payment module
$myShop = new \billon\Shop();
$myShop->user(function($requestData, $cb)
{
    $cb($requestData->user);
)->products(function ($requestData, $cb)
{
	$cb($requestData->itemsId);
}
)->product(function ($requestData, $itemId, $cb)
{
	if (itemId == 16)
        { // the number of thousandth parts of the basic monetary unit
                $cb(2000); // eg. 2 pounds
        }
        else if (itemId == 17) 
        {
                $cb([ // 'array(...)' instead of '[...]' in PHP 5.3
                                "amount_gross": 1.2 // eg. 1.2 pounds
                ]);
        }
        else if ($itemId == 18) 
	{
		$cb([
				"item_id"=> "18",
				"item_name"=>  "eBook",
				"quantity"=>  1,
				"unit_type"=>  "pcs",
				"unit_price_net"=> 0.24,
				"amount_net"=>  0.24,
				"amount_discount_net"=>  0,
				"vat"=>  [
					"percent"=>  23,
					"amount"=>  0.06
				],
				"amount_gross"=>  0.3
		]);
	}
	else if ($itemId == 30)
	{
		$cb([
				"item_id"=>  "30",
				"item_name"=>  "Access code",
				"quantity"=>  1,
				"unit_type"=>  "pcs",
				"unit_price_net"=>  0.81,
				"amount_net"=>  0.81,
				"amount_discount_net"=>  0,
				"vat"=>  [
				       "percent"=>  23,
				       "amount"=>  0.19
				],
				"amount_gross"=>  1
		]);
	}
)->productBillon(function ($requestData, $item, $cb) 
{ // not required method
	$cb($item);
}
)->productDelivery(function ($requestData, $items, $cb)
{ // not required method
	$cb([
		"delivery_id"=> "",
		"delivery_description"=> "",
		"delivery_kind"=> "",
		"delivery_price_net"=> "0",
		"vat"=> [
			"percent"=> "0",
			"amount"=> "0"
		],
		"delivery_price_gross"=> "0",
		"estimated_delivery_date"=> "0"
	]);
}
)->currency(function ($requestData, $cb)
{
	$cb('GBP');
}
)->paymentTitle(function ($requestData, $items, $delivery, $cb) {
	$cb('Payment title');
}
)->app24(function ($requestData, $items, $delivery, $cb) 
{    $cb("eyJhkGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c3VyIjp7ImlkIjoyNSwic2FsdCI6IjEyZWVkMzQwLTM2NGUtMThNjgyN1hNDM5zA1MiOjEh0OTCJpYXQiDk0NjF9Q1M.zeWXG7Nyr3PFVhb4HRgLi5rh8fLZx41VHySHWUStIzc"); // API key of the user of the service 'billon.me'
    /*$cb([
       Name: "billonpayments4",
       Address: "http://213.189.38.34:20891"
    ]);*/ // direct communication with the application 24/7
})->merchant(function ($requestData, $items, $delivery, $cb) { // not required method
	$cb(array("company" => array("name" => "Default", "NIP" => "", "REGON" => "", "KRS" => ""), "person" => array("first_name" => "Default", "last_name" => "", "PESEL" => ""), "address" => array("street" => "Default", "city" => "Default", "zip" => "00-000", "country" => ""), "fax" => "", "www" => "", "email" => ""));
}
)->documentParse(function ($requestData, $document, $cb) {
	$cb(false); // not required method
}
)->onFinishedPayment(function ($items, $delivery_option, $document, $requestData) 
{ // not required method
	file_put_contents('log.txt', serialize([$items, $delivery_option, $document, $requestData]));
})->onRequestSend(function ($requestName, $parameters, $requestResponse, $error)
{ // the event of sending SOAP request, not required method
});

A specific type of payment used to purchase the product is the plate payments. Example of a service of a donation (payment for amount):

require_once "billon/index.php"; //lokalizacja skryptu "index.php" modułu płatności Billon
$myShop = new \billon\Shop();
$myShop->currency(function ($requestData, $cb) use ($pluginParams)
{
    $cb('PLN');
}
)->paymentTitle(function ($requestData, $items, $delivery, $cb) use ($title)
{
    $cb('Donate');
}
)->app24(function ($requestData, $items, $delivery, $cb) use ($token)
{
$cb("eyJhkGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c3VyIjp7ImlkIjoyNSwic2FsdCI6IjEyZWVkMzQwLTM2NGUtMThNjgyN1hNDM5zA1MiOjEh0OTCJpYXQiDk0NjF9Q1M.zeWXG7Nyr3PFVhb4HRgLi5rh8fLZx41VHySHWUStIzc"); // API key użytkownika serwisu "billon.me"
    /*$cb([
       Name: "billonpayments4",
       Address: "http://213.189.38.34:20891"
    ]);*/ // komunikacja bezpośrednio z aplikacją 24/7
}
)->merchant(function ($requestData, $items, $delivery, $cb)
{ // not required method
    $cb(array("company" => array("name" => "Default", "NIP" => "", "REGON" => "", "KRS" => ""), "person" => array("first_name" => "Default", "last_name" => "", "PESEL" => ""), "address" => array("street" => "Default", "city" => "Default", "zip" => "00-000", "country" => ""), "fax" => "", "www" => "", "email" => ""));
}
)->documentParse(function ($requestData, $document, $cb)
{ // not required method
    $cb(false);
}
)->onFinishedPayment(function ($items, $delivery_option, $document, $requestData)
{
});

1. user

In the function serving as a parameter of the ‘user’ method, the function ‘cb’ should be called with the array ‘peerLocation’ as parameter. The array should be the user’s location, automatically checked by ‘billon-user.js’ if there is Billon running on the user’s device. If not, it is an array with one value with a key: ‘userName’. The method does not apply to donations made using the method ‘donateInitiation’ where user`s ‘peerLocation’ object is retrieved from the parameter ‘user’ of JSON structure that is the parameter of the request of the controller from the webpage. The donation amount expressed in the number of thousandth parts of the basic monetary unit is passed in a similar way through the parameter ‘amount’ which is the parameter of the request. Example request:

$myShop->user(function ($requestData, $cb)
{
  /* Example value of variable $requestData->user:
  {
    "userName": "test", // Wymagane
    ... // Other optional parameters for faster user searching.
  }
  */
  $cb($requestData->user);
});

2. products

This method should pass an array of product ids. The method does not apply to the donations. The method is not required in version no. 2.4 of the module. Example request:

$myShop->products(function ($requestData, $cb) 
{
  /* Example value of variable $requestData->itemsId:
  [
    1,
    2,
    3
  ]
  */
  $cb($requestData->itemsId);
});

3. product

The function serving as a parameter of the ‘product’ method should have the parameter ‘id’ of a product or a price expressed in a number of the thousandth parts of the basic monetary unit. and should pass an object with product data. The data will be available in the user’s browser to display information about the product which is being purchased. A simple product or price shall be set using this method in the case of not using the method ‘products’. Example request:

$myShop->product(function ($requestData, $itemId, $cb)
{
	if (itemId == 16)
        { // the number of thousandth part of the basic monetary unit
                $cb(2000); // eg. 2 pounds
        }
        else if (itemId == 17) 
        {
                $cb([ // 'array(...)' instead of '[...]' in PHP 5.3
                                "amount_gross": 1.2 // 1.2 pounds
                ]);
        }
        else if ($itemId == 18) 
	{
		$cb([ 
				"item_id"=> "18",
				"item_name"=>  "eBook",
				"quantity"=>  1,
				"unit_type"=>  "pcs",
				"unit_price_net"=> 0.24,
				"amount_net"=>  0.24,
				"amount_discount_net"=>  0,
				"vat"=>  [
					"percent"=>  23,
					"amount"=>  0.06
				],
				"amount_gross"=>  0.3
		]);
	}
	else if ($itemId == 30)
	{
		$cb([
				"item_id"=>  "30",
				"item_name"=>  "Access code",
				"quantity"=>  1,
				"unit_type"=>  "pcs",
				"unit_price_net"=>  0.81,
				"amount_net"=>  0.81,
				"amount_discount_net"=>  0,
				"vat"=>  [
				"percent"=>  23,
				"amount"=>  0.19
				],
				"amount_gross"=>  1
		]);
	}
);

4. productBillon

The method ‘productBillon’ is different from the previous method in that it requires the parameters to be formatted in a way that complies with Billon API. Example request:

$myShop->productBillon(function ($requestData, $item, $cb) 
{ // not required method
  $cb($item);
});

5. productDelivery

In this method there should be a delivery method specified by the customer. Method not required. It does not apply to payments for online products or donations. Example request:

$myShop->productDelivery(function ($requestData, $items, $cb) 
{ // The structure of the object delivery options below.
	$cb([
		"delivery_id"=> "",
		"delivery_description"=> "",
		"delivery_kind"=> "",
		"delivery_price_net"=> "0",
		"vat"=> [
			"percent"=> "0",
			"amount"=> "0"
		],
		"delivery_price_gross"=> "0",
		"estimated_delivery_date"=> "0"
	]);
}
);

6. currency

In this method you can specify the currency, using ISO 4217 format. This method is optional. The default currency is ‘PLN’. Example request:

    $myShop->currency(function ($requestData, $cb)
    {
       $cb('EUR');
    });

7. paymentTitle

Method used for setting payment title. Example request:

$myShop->paymentTitle(function ($requestData, $items, delivery, $cb) 
{
  $cb("Code");
});

8. app24

This method specifies the address of a 24/7 service which handles payments. API key of the user of the service ‘billon.me’, which can be copied from a settings page, or the object with username with which the application 24/7 is signed in and address on which the application 24/7 listens for incoming requests can be given. You can include your loadbalancing functionality here. Example request:

$myShop->app24(function ($requestData, $items, $delivery, $cb) {
$cb("eyJhkGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c3VyIjp7ImlkIjoyNSwic2FsdCI6IjEyZWVkMzQwLTM2NGUtMThNjgyN1hNDM5zA1MiOjEh0OTCJpYXQiDk0NjF9Q1M.zeWXG7Nyr3PFVhb4HRgLi5rh8fLZx41VHySHWUStIzc"); // API key of the user of the service 'billon.me'
    /*$cb([
       Name: "billonpayments4",
       Address: "http://213.189.38.34:20891"
    ]);*/ // an array that contains the name and the IP address (and port) of the application 24/7 - direct communication with the application 24/7
});

9. merchant

This methods shows your data in the user’s app. The data has to be formatted according to Billon API standards. The method is optional. Example request:

$myShop->app24(function ($requestData, $items, $delivery, $cb) {
    $cb(array("company" => array("name" => "Default", "NIP" => "", "REGON" => "", "KRS" => ""), "person" => array("first_name" => "Default", "last_name" => "", "PESEL" => ""), "address" => array("street" => "Default", "city" => "Default", "zip" => "00-000", "country" => ""), "fax" => "", "www" => "", "email" => ""));
});

10. documentParse

This method is used for non-standard parsing of the payment document. The method is optional.

$myShop->documentParse(function ($requestData, $document, $cb)
{   
  // If the method "$cb" is being called with the parameter "false", the document will not be parsed..   
  $cb(false);   
});

11. merchantBrandName

$myShop->merchantBrandName(function ($requestData, $cb)
{
  $cb('Name of brand'); 
});

12. plates

Using this method, you can set the price of plates. These prices apply at the time of the call of methods ‘platePaymentSeriesStart’ and ‘platesList’ in Sails.js controller. Example of use with previously set values:

This method sets the name of the brand, which is by default the domain of the page on which payment is made:

$myShop->plates(function($requestData, $cb)
{
   $cb($alpha * 1000, $beta * 1000, $gamma * 1000, $delta * 1000, $epsilon * 1000); // pomnożenie cen do liczby tysięcznych części podstawowej jednostki monetarnej

}); // method ‘$cb’ can be called with fewer arguments, number 0 also removes a plate from the tariff

13. maxTotalAmount

This method is used to set the maximum amount of the plate payments in series. The method is applicable at the time of the call of method ‘platePaymentSeriesStart’ in Sails.js controller. The sum is expressed in the number of thousandths of a basic monetary unit:

$myShop->maxTotalAmount(function($requestData, $cb)
{
   $cb(10000); // np. 10 zł
});

14. duration

Using this method, you need to set the duration of the series the plate payments in seconds. The method is applicable at the time of the call of method ‘platePaymentSeriesStart’ in Sails.js controller. Example:

$myShop->duration(function($requestData, $cb)
{
   $cb(3600);
});

15. maxPaymentsInSeries

This method can be called with an argument being a function that calls a function of its second argument with the maximum number of payments in a series of the plate payments. The method is applicable at the time of the call of method ‘platePaymentSeriesStart’ in Sails.js controller. Example:

$myShop->maxPaymentsInSeries(function($requestData, $cb)
{
   $cb(10);
});

16. platePayment

This method is used to define the payment as plate one. The argument of this method is a function that calls a function of its first argument with two arguments: an identifier of series and the type of plate (PLATE_ALPHA, PLATE_BETA, PLATE_GAMMA, PLATE_DELTA or PLATE_EPSILON). An example of using the values set the script in the browser:

$myShop->platePayment(function($requestData, $cb)
{
   $cb(requestData->seriesId, requestData->type);
});

Note: If the number of plates is less than five, a type of a plate can be changed by client-side script „billon-plates.js”.

17. onReceivedPlatePaymentSeriesStatus

This method is used to handle the status returned by 24/7 application during the operation of acceptance of the plate payments series. The method is applicable at the time of the call of method ‘platePaymentSeriesStart’ in Sails.js controller.

$myShop->onReceivedPlatePaymentSeriesStatus(function ($response)
{ 
   $response; // wiadomość zwrócona przez aplikację 24/7
   $response->status; // zwracany status
});

18. onAcceptedPlatePaymentSeries

This method is used to handle the status returned by 24/7 application during the operation of acceptance of the plate payments series. The method is applicable at the time of the call of method ‘platePaymentSeriesStart’ in Sails.js controller.

$myShop->onAcceptedPlatePaymentSeries(function ($paymentData)
{
   // event handler of acceptance of payments series here
});

19. onFinishedPayment

The most important method for Billon integration on your website. It specifies what happens when the operation is successfully completed. You can, for example, display a ”success” screen and / or send a confirmation email to your customer. Example request:

$myShop->onFinishedPayment(function ($items, $delivery, $purchaseDocument, $requestData) 
{
   if (property_exists($purchaseDocument->additionalInfo, 'actual_amount'))
   {
      $document->additionalInfo->actual_amount; // actual amount paid by user expressed in the number of the thousandth parts of the basic monetary unit
   }
   if (property_exists($purchaseDocument, 'taskId'))
   {
      $purchaseDocument->taskId; // the task identifier
   }
});

20. onRequestSend

This method handles the event of sending SOAP request to 24/7 app and receiving or not receiving a response. The method can be useful to create logs of SOAP communication or perform some operation in case of a failure of the payment. Example request:

$myShop->onRequestSend(function ($requestName, $parameters, $requestResponse, $error) { 
   $requestName; // name of the SOAP message 
   $parameters; // parameters of the SOAP message 
   $requestResponse; // 27/7 application response 
   $error; // errors when sending SOAP request (the errors from 24/7 app are being passed by the argument '$requestResponse') 
});

Communicating with a WWW user

A method ‘paymentInitiation’ or ‘donateInitiation’ of the payment object should be called in the file or action that initiate payment:

/**
 * PHP payment module configuration
 * (declaring and setting of the payment object).
 */
require_once "processing.inc.php";

$myShop->paymentInitiation();
//$myShop->donateInitiation(); // in the case of a donation

A method ‘paymentInitiation’ should be called in the file or action that listen to the payment:

/**
 * PHP payment module configuration
 * (declaring and setting of the payment object).
 */
require_once "processing.inc.php";

$taskId = @json_decode(file_get_contents("php://input"))->taskId;
$myShop->paymentStatus($taskId ? $taskId : $_GET['taskId'], function($response) use (&$cart)
{ // $cart - additional optional variable to determine eg. API key
    $responseString = json_encode($response);
    echo $responseString;
});

You can use scripts for browsers ‘billon-<module>.js to communicate with the files or actions that initiate or listen to the payment using HTTP POST request.

Was this article helpful to you? Yes No

How can we help?