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