Scripts in user’s browser

To configure your website, you can use our ‘billon-<module>.js’ scripts. Your choice of scripts depends on the functionality you want to include. Below is the list (download all):

billon.js – the base script making POST requests, providing helper functions and being a namespace for other scripts,
Example request:

// Helper function: formatting user login to be compatible with Billon API.
var realUsername = billon.trimUsername("my_app_24.7");
// var realUsername returns "my_app-247".

billon-object.js – Provides neccesary objects to other scripts (compliant with Billon API),
Example request:

// The below script automatically adds all other parameters required by the Billon API, including parameter 'currency' with value 'PLN'.
var peerLocation = new billonAmount({
  amount: 1,
});

billon-agent.js – enables AJAX connection, requires the script ‘billon.js’
Example request:

var billonAgent = new billon.agent("http://billon.me:1400/payment");
billonAgent.call("initiate", function (response) {
  if (response.requestStatus === "SUCCESS") {
    // We have successfully started a payment (but we don't yet know if it's completed)
  }
});

billon-noApp.js – a script displaying an information screen when the user doesn’t have the Billon application running, requires the script ‘billon.js’
Example request:
billon.noApp();

billon-user.js – the script automatically finds the login of a user logged in on the same device. It requires the scripts ‘billon.js’ and ‘billon-object.js’ successively.
Example request:

var field = $("#BillonUserName");
billon.user.get({
  abort: function ()
  {
    // If the field is filled, we will cancel the execution of the user detection.
    if (field.val().length > 0) 
    {
      return true;
    }
    return false;
  }
}, function (err, User)
  {
    user = User;
    if (err)
    {
      return billon.noApp();
    }
    field.val(user.userName);
});

billon-hash.js – includes the billon variable generated from a URL hash in JSON format. Used for example to automatically initiate a payment after clicking a link. It requires the script ‘billon.js’.

billon-paymentDialog.js – the standard payment script, initiates the payment and displays a dialog showing payment progress. The script uses a model of a screen, which receives and reacts to incoming data. It requires the scripts ‘billon.js’, ‘billon-object.js’ and ‘billon-user.js’ successively.

Przykład wywołania:

billon.paymentDialog({
    lang: "en",
    // The address defined as billon.agent should point to billonAgent and a controller which controls the payment (in this example it's PaymentController) or a directory with PHP scripts that support the payment.     
    connection: new billon.agent("http://billon.me:1400/payment"),
    paymentDialogAddress: "https://showroom.billongroup.com/lib/screen/paymentDialog/index.html", // in case of problems with not showing dialog
    skipAnotherUser: true, // optional - omission of the step of of choosing another user than detected
    showSellerFinishedPaymentInfo: false, // optional parameter - the value 'true' recommended in the event of shops
    anotherTry: function () // optional replacement of 'Give it another try' click action
    {
        if (false/*new Date() - startDate > 120000*/)
        {
            window.location.href = 'some-page';
        }
        else
        {
            return false; // invoking the default action
        }
    },
    on: {
        "billon-paymentDialog-remove": function()
        { // optional event, function called after closing the dialogs
            window.location.href += '&close=ok';
        }
    },
    request: {
      address: "initiate",
      data: function (user/*, amount*/) // the second parameter in the event of donation of an amount set by paying
      {
        return {
          itemsId: [1], // example parameter according to which paid product will be determined on the server
          // amount: 1000, - in the case of amount of one monetary unit, eg. 1 £, instead of 'itemsId'
          // amount: amount, - in the event of donations of amount set by paying instead of 'itemsId'
          user: user
        };
      }
    },
    listen: {
      address: "status",
      data: function (requestResponse) 
      {
        return {
          taskId: requestResponse.taskId
        };
      },
      response: function (response)
      { // optional listening to responses of merchant application
        if (response.progressPercent == "100")
        {
	  console.log('Transakcja zakończona');
}
      },
      interval: 1000 // optional time between polls about the payment status in miliseconds, 1000 by default
    }
  });

Parametry argumentu metody „billon.paymentDialog”:

Name	Options	Default value	Description
connection	np. new billon.agent(„http://billon.info:1401/opinie”)		object ‘billon.agent’ created for a controller or directory with PHP scripts
skipAnotherUser	false, true	no value treated as ‘false’	should you let a logged in user choose a different login (except in the case of the donation of an amount chosen by a user)
lang	en, pl	en	language of the dialog
request	an object with the name of parameter or action of the controller or the PHP script name in ‘address” parameter and a ‘data” function, which has one parameter in the case of payment of fixed amount or two ones in the event of the donation of amount cosen by a user and must return an object with parameters: ‘user’ with value of the first function argument, ‘amount’ with the payment amount multiplied by 1000 or with value of the second function argument in the event of donations other parameters you may need for handling payments, eg. ‘itemsId’ with an array of product ids in case of purchase payment	empty object	an object communicating with a controller or a PHP script that handles the payment
listen	an object with parameters: ‘address’ with the name of parameter or action of controller or PHP script listening for incoming data, function ‘data’: data: function (requestResponse) { return { taskId: requestResponse.taskId }; } optional function ‘response”, taking as a parameter a SOAP response for the request ‘getTaskStatus’ optional ‘Interval’ with interval, at which the payment status will be sent, in miliseconds	empty object	an object listening for incoming data from a controller or a PHP script which handles the payment
showSellerFinishedPaymentInfo	false, true	no value treated as ‘false’	whether message ‘Seller has received money!’ instead of ‘Recipient has received money!’ or ‘Pieniądze są już u sprzedawcy!’ instead of ‘Pieniądze są już u odbiorcy!’ is to be displayed after successful payment
anotherTry	function		function which is called when clicking an anchor (a hyperlink) ‘Give it another try’ and replaces default action of the anchor in the event of returning value ‘false’ or replacing this action otherwise (function ‘anotherTry’ replaces default action of another try and returning ‘false’ causes invoking default action)
on	an object with a function ‘billon-paymentDialog-remove’		an object with a function ‘billon-paymentDialog-remove’ called after closing dialog
paymentDialogAddress	np. https://showroom.billongroup.com/lib/screen/paymentDialog/index.html	address of the document ‘screen/paymentDialog/index.html’ in the directory above the directory with Billon scripts	screen model required when there is a problem with displaying the dialog

billon-paymentDialog.bundle.min.js – a minimized script ‘billon-paymentDialog.js’ containing the required scripts ‘billon.js’, ‘billon-agent.js’, ‘billon-object.js’, ‘billon-user. js’, used like the script ‘billon-paymentDialog.js’, but you do not need to include the required scripts, it uses a model of the dialog with the minimized code by default,

billon-loadingBar.js – the payment script, initiates the payment and displays a bar showing payment progress. The script requires a small angular.js application, which can receive and react to incoming data. This is a dedicated screen loadingBar2 (see a sample screen waiting for new data) by default. It requires the scripts ‘billon.js’, ‘billon-object.js’ and ‘billon-user.js’ in succession.

Example request:

billon.loadingBar({
    lang: "pl",
    // The address defined as billon.agent should point to a controller which controls the payment (in this example it's PaymentController) or to directory with PHP scripts that support the payment.     
    connection: new billon.agent("http://billon.me:1400/payment"),
    loadingBarAddress: "https://showroom.billongroup.com/lib/screen/loadingBar2/index.html", // in case of problems with not showing bar
    skipAnotherUser: true, // optional - omission of the step of of choosing another user than detected
    request: {
      address: "initiate",
      data: function (user)
      {
        return {
          itemsId: [1],
          // amount: 1000, - instead of 'itemsId' in case of donations
          user: user,
          colour: 0 // other custom parameter optionally
        };
      }
    },
    listen: {
      address: "status",
      data: function (requestResponse) 
      {
        return {
          taskId: requestResponse.taskId
        };
      },
      response: function (response)
      { // optional listening to responses of merchant application
        if (response.progressPercent == "100")
        {
	  console.log('Transaction finished');
}
      }
    }
  });

Parameters of argument of the method ‘billon.loadingBar’:

Name	Options	Default value	Description
connection	for example new billon.agent(“http://billon.info:1401/opinie”)		object ‘billon.agent’ created for a specific controller or directory with PHP scripts
skipAnotherUser	false, true	no value treated as ‘false’	should you let a logged in user choose a different login
lang	en, pl	en	language of the bar
request	an object with name of parameter or action of controller or PHP script name in ‘address” parameter and a ‘data” function, which must return an object with parameters: ‘user’ with value of function argument, ‘itemsId’ with an array of product ids in case of purchase payment, ‘amount’ the payment amount multiplied by 1000 in case of donation. other parameters you may need for handling payments	empty object	an object communicating with a controller or a PHP script that handles the payment
listen	an object with parameters: ‘address’ with the name of parameter or action of controller or the name of PHP script listening for incoming data, function ‘data’: data: function (requestResponse) { return { taskId: requestResponse.taskId }; } optional function „response”, taking as a parameter a SOAP response for the request ‘getTaskStatus’	empty object	an object listening for incoming data from a service which handles the payment
loadingBarAddress	eg. https://showroom.billongroup.com/lib/screen/loadingBar2/index.html	address of the document ‘screen/loadingBar2/index.html’ in the directory above the directory with Billon scripts	screen model required when there is a problem with displaying the progress bar

billon-plates.js – plate payment processing script. The script uses models of button and dialog, which listen and respond to messages. It requires the scripts ‘billon.js’, ‘billon-object.js’ and ‘billon-user.js’ successively.

Example request:

billon.plates({
   connection: new billon.agent("http://billon.info:1401/plates"), // address pointing to Sails.js controller that supports payment (in this case PlatesController) or directory with PHP scripts that support the payment
   lang: 'en', // language 'en' or 'pl', 'en' by default
   plateButtonAddress: "https://showroom.billongroup.com/lib/screen/plate-button/index.html", // in the case of not showing buttons, 
                                                                                      // skip in the case of the lack of problems
   plateDialogAddress: "https://showroom.billongroup.com/lib/screen/plate-dialog/index.html", // in the case of not showing dialog, 
                                                                                      // skip in the case of the lack of problems
   skipAnotherUser: false, // optional - omission of the step of of choosing another user than detected, the step is not skipped by default
   disableButtonsTitle: false, // optional - default not adding title (tooltip) with the price to the buttons, the titles are being set by default
   tariff: {
      address: 'list', // name of parameter or action of controller or name of PHP script where method 'tariff' is being called
      displayedCurrency: '£', // displayed currency, ISO 4217 currency code set with Billon server payment module by default
                              // if a parameter 'displayedCurrencyBefore' is not set and the amounts greater than or equal to 1 or a parameter 'centSign' is not set, 
                              // they are formatted by default according to ISO 4217 currency code set with the Billon server module and user's locale, 
                              // ISO 4217 currency code set with server payment module is used as sign of currency by default, when 'displayCurrencyBefore' is set
      displayCurrencyBefore: true, // displaying the sign of currency before the number, 
                                    // the sign from the parameter 'displayedCurrency' is appended to the number at the end by default
      centSign: 'p', // sign of currency for the hundredth part of the basic monetary unit displayed for the price lower than this unit, 
                    // the sign is used as for higher prices by default
      displayCentSignBefore: false // displaying the sign of currency set in parameter 'centSign' before number, this sign is appended to the number at the end by default
   },
   series: {
      request: {
         address: 'initiate', // name of parameter or action of controller or name of PHP script where method 'platePaymentSeriesStart' is being called
         data: function (user) 
         {
           return {
             user: user
           };
         }
      },
      listenResponse: function (response, user)
      {
         if (response.status == "SERIES_ACCEPTED" || response.status == "TRANSFERRING" || response.status == "TRANSFERING")
         { // save of identifier of series and Billon username, in this case in Local Storage
            localStorage.setItem("seriesId", response.taskId);
	         localStorage.setItem("user", JSON.stringify(user));
         }
      }
   },
   paymentRequest: {
      address: 'pay', // name of parameter or action of controller or name of PHP script where method 'paymentInitiation' is being called
      data: function()
      { // reading previously saved identifier of series and Billon username, in this case from Local Storage
         try
         {
            return {
               seriesId: localStorage.getItem("seriesId"),
               user: JSON.parse(localStorage.getItem("user"))
            };
         }
         catch (e)
         {
            return {};
         }
      }
   },
   listen: {
      address: "status", // name of parameter or action of controller or name of PHP script where method 'paymentStatus' is being called
      data: function (requestResponse) 
      {
        return {
          taskId: requestResponse.taskId
        };
      }
   },
   buttons: [ // array of buttons
   {
      place: document.getElementById('button-container-1'), // HTML element in which the button is to be placed
      type: 'alpha', // 0 can be given instead of 'alpha' - type of the button
      disableTitle: false, // optional - not setting the title of the button with the price,
                           // the global option 'DisableButtonsTitle' is acted on by default
      requestData: function(type)
      {
         return {
            type: type,
            itemsId: [1] // array of identifiers of products
         }
      },
      listenResponse: function(response)
      { // optional method
         switch (response.status)
         {
            case "FINISHED_OK":
               // event of successfully purchase with the button
               break;
            case "FINISHED_ERR_USER_REJECTED": // a lack of possibility to pay within the stored series
               localStorage.setItem("seriesId", null);
	       localStorage.setItem("user", JSON.stringify(null));
         }
      }
   },
   {
      place: document.getElementById('button-container-2'),
      type: 'beta',
      requestData: function(type)
      {
         return {
            type: type,
            itemsId: [2]
         }
      },
      listenResponse: function(response)
      {
         switch (response.status)
         {
            case "FINISHED_OK":
               // event of successfully purchase with the button
               break;
            case "FINISHED_ERR_USER_REJECTED": // a lack of possibility to pay within the stored series
               localStorage.setItem("seriesId", null);
	       localStorage.setItem("user", JSON.stringify(null));
         }
      }
   },
   {
      place: document.getElementById('button-container-3'),
      type: 'gamma',
      requestData: function(type)
      {
         return {
            type: type,
            itemsId: [3]
         }
      },
      listenResponse: function(response)
      {
         switch (response.status)
         {
            case "FINISHED_OK":
               // event of successfully purchase with the button
               break;
            case "FINISHED_ERR_USER_REJECTED": // a lack of possibility to pay within the stored series
               localStorage.setItem("seriesId", null);
	       localStorage.setItem("user", JSON.stringify(null));
         }
      }
   },
   {
      place: document.getElementById('button-container-4'),
      type: 'delta',
      requestData: function(type)
      {
         return {
            type: type,
            itemsId: [4]
         }
      },
      listenResponse: function(response)
      {
         switch (response.status)
         {
            case "FINISHED_OK":
               // event of successfully purchase with the button
               break;
            case "FINISHED_ERR_USER_REJECTED": // a lack of possibility to pay within the stored series
               localStorage.setItem("seriesId", null);
	       localStorage.setItem("user", JSON.stringify(null));
         }
      }
   },
   {
      place: document.getElementById('button-container-5'),
      type: 'epsilon',
      requestData: function(type)
      {
         return {
            type: type,
            itemsId: [5]
         }
      },
      listenResponse: function(response)
      {
         switch (response.status)
         {
            case "FINISHED_OK":
               // event of successfully purchase with the button
               break;
            case "FINISHED_ERR_USER_REJECTED": // a lack of possibility to pay within the stored series
               localStorage.setItem("seriesId", null);
	       localStorage.setItem("user", JSON.stringify(null));
         }
      }
   }]
});

Parameters of argument of the method ‘billon.plates’:

Name	Options	Default value	Description
connection	eg. new billon.agent(“http://billon.info:1401/opinie”)		object ‘billon.agent’ created for a specific controller or directory with PHP scripts
skipAnotherUser	false, true	no value treated as ‘false’	whether question about choosing another user than detected is to be skipped
disableButtonsTitle	false, true	no value treated as ‘false’	whether setting titles (tooltips, which are visible on hover for example) of the buttons is to be disabled by default, so that the tariff will not be checked when adding buttons
lang	en, pl	en	language of dialog
tariff	object with the name of parameter or action of controller or the PHP script name in the parameter ‘address’, an optional display currency in the parameter ‘displayedCurrency’, the optional symbol for the hundredth part of the basic monetary unit in the parameter ‘centSign’ and boolean variables ‘displayCurrencyBefore’ i ‘displayCentSignBefore’, which determines, whether signs of currency and the hundredth part of the basic monetary unit are to be displayed before number		object with controller parameter that outputs tariff and with displayed signs of the basic monetary unit and its hundredth part
series	object whose parameter is object ‘request’ with parameters: ‘address’ with name of controller parameter, controller action or PHP script of payment series start, method ‘data’: data: function (user) { return { user: user }; } and optional method ‘listenResponse’ with response of Corporate Node and user’s object as arguments		an object communicating with controller or PHP script during operation that starts a series of payments with the name of controller parameter or action or the name of PHP script where the series is started and with the function that supports incoming statuses of Corporate Node
paymentRequest	object with parameters: ‘address’ with name of controller parameter, controller action or PHP script of payment initiation, function ‘data”, which takes no arguments and returns object with the data transmitted to the controller or the PHP script		an object communicating with controller or PHP script during operation that initiates payment with the name of controller method or PHP script that supports the operation initiating plate payment and with method that returns the transmitted data, eg. identifier of series of payments and user’s object
listen	object with parameters: ‘address’ with name of controller parameter, controller action or PHP script of listening to payment, function ‘data’: data: function (requestResponse) { return { taskId: requestResponse.taskId }; }		communication object with parameter name of controller parameter, controller action or PHP script listening to payment or payment series start with name of parameter, action or script
buttons	array of objects with parameters: ‘place’ with JavaScript object with HTML element to which button is to be added, ‘type’ with string of plate type or with number of plate position (plate types in turn: ‘alpha’, ‘beta’, ‘gamma’, ‘delta’ or ‘epsilon’), optional ‘disableTitle’ determining whether not to set the tooltip of the button, method ‘requestData’ that returns object to be sent at the initiation of the payment for given type (eg. ‘PLATE_ALPHA’), optional method ‘listenResponse’ taking response of proxy service as argument for listening to statuses of operation of payment		description of the buttons to start the payment with their location, type, method that returns the data which supplements and replaces the data returned by the method of ‘paymentRequest.Data’, method for a listening to incoming status of proxy service during the operation of payment
plateButtonAddress	eg. https://showroom.billongroup.com/lib/screen/plateButton/index.html	address of document ‘screen/plate-button/index.html’ in the directory above the directory with Billon scripts	screen model required when there is a problem with displaying the buttons
plateDialogAddress	eg. https://showroom.billongroup.com/lib/screen/plateDialog/index.html	address of document ‘screen/plate-dialog/index.html’ in the directory above the directory with Billon scripts	screen model required when there is a problem with displaying the dialog

How can we help?