2. Home
  4. Libraries for webmasters
  6. Scripts in user’s browser

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,
    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,
    Example request:

    billon.noApp();

  • billon-user.js -the script automatically finds the login of a user logged in on the same device.
    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.

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

    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).     
    connection: new billon.agent("http://billon.me:1400/payment"),
    paymentDialogAddress: "https://billon.info/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 specific proxy service
    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 controller 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 service that handles the payment
    listen

    an object with parameters:

    • ‘Address’ with the name of controller parameter 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 quety will be sent, in miliseconds
    		 empty object an object listening for incoming data from a service 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 hiperlink) ‘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://billon.info/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-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. 

    Example request:

    billon.loadingBar({
    lang: "pl",
    // The address defined as billon.agent should point to billonAgent and a controller which controls the payment (in this example it's PaymentController).     
    connection: new billon.agent("http://billon.me:1400/payment"),
    loadingBarAddress: "https://billon.info/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 proxy service
    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 controller 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 service that handles the payment
    listen

    an object with parameters:

    • ‘Address’ with the name of controller parameter 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://billon.info/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.

    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)
   lang: 'en', // language 'en' or 'pl', 'en' by default
   plateButtonAddress: "https://billon.info/lib/screen/plate-button/index.html", // in the case of not showing buttons, 
                                                                                      // skip in the case of the lack of problems
   plateDialogAddress: "https://billon.info/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 controller parameter where method 'tariff' is being called
      DisplayedCurrency: ' £', // displayed currency, ISO 4217 currency code set with module 'billon' by default
      CentSign: 'p' // sign of currency for the hundredth part of the basic monetary unit displayed for the price lower than this unit, 
                    // sign set in parameter 'DisplayedCurrency'
                    // or ISO 4217 currency code set with module 'billon' in case of lack of this parameter is used by default
   },
   series: {
      request: {
         Address: 'initiate', // name of controller parameter 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 controller parameter 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 controller parameter 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', // 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 proxy service
    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 controller parameter in the parameter ‘Address’, an optional display currency in the parameter ‘DisplayedCurrency‘ and the optional symbol for the hundredth part of the basic monetary unit in the parameter ‘CentSign‘

    		   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 of payment series start,
    • method ‘Data‘: 
      Data: function (user)
{
   return {
	user: user
   };
}

    and optional method ‘ListenResponse’ with response of 24/7 application and user’s object as arguments

    		   an object communicating with controller during operation that starts a series of payments with the name of controller parameter where the series is started and with the function that supports incoming statuses of 24/7 application
    paymentRequest

    object with parameters:

    • ‘Address’ with name of controller parameter of payment initiation,
    • function ‘Data”, which takes no arguments and returns object with the data transmitted to the controller
    		   an object communicating with controller during operation that initiates payment with the name of controller method 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 of listening to payment,
    • function ‘Data’: 
      Data: function (requestResponse)
{
   return {
	taskId: requestResponse.taskId
   };
}
    		  communication object with parameter name of controller of service listening to payment or payment series start with name of parameter of controller
    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 (‘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 reponse 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 suplements 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://billon.info/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://billon.info/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
Was this article helpful to you? Yes No

How can we help?