Billing for FusionPBX Manual

This manual will guide you on every detail about installing and using the Billing for FusionPBX native application.  If you want to have a quick setup, you may read the quick guide and later return here.

Content

Current version 1.5.0.

  1. Billing for FusionPBX installation
  2. Billing for FusionPBX configuration
  3. Maintenance Tasks
  4. Default Settings
  5. LUA and FreeSWITCH Variables

Assumptions: The reader is familiar with Linux and FusionPBX. This manual also assumes you already have LCR installed.

Billing for FusionPBX Installation

Before you start Billing for FusionPBX installation, you must satisfy the next requirements:

  • You need to have FusionPBX 4.4 or better installed with MySQL, MariaDB or PostgreSQL as database data storage.  If you don't know how to do this, OKay offers Linux consultant services.
  • You need to have the PHPShadow extension installed. If you already have the LCR for FusionPBX working, you already have this.
  • You need to have LCR for FusionPBX installed. The Billing for FusionPBX uses the LCR software.
  • You need to have SSH access and to be able to write in /app directory where FusionPBX is installed.
  • You need to have access to FusionPBX as a superadmin.
  • You need to download and get a Billing for FusionPBX license.
  • Optionally, you may need to install mod_niblebill. The billing software uses this module to hang calls up when you run out of credit. If this is not important for you, you may skip it. The installation procedure depends on how you installed FreeSWITCH: source, DEB's or RPM's.

NOTE: If you are upgrading from any version to 1.5.0, crontabs have been moved to the resources/tools/ directory. You have to adjust your crontabs.

When you satisfy these requisites, please follow the next steps:

RPM Installation

This method only applies if you are using the RPM's from the OKay's repository. The installation method is very similar to the LCR one. If you haven't installed the LCR, the RPM dependency engine will install it for you. However, please read the LCR Manual to understand some LCR specific tasks.

  1. Type yum install fusionpbx-billing
  2. Go to Advanced->Upgrade menu, select Schema and Menu Defaults
    fusionpbx upgrade
  3. Go to Advanced->Group Manager and review the Billing permissions, you should have it at least for the superadmin.
  4. Log out and log in again into FusionPBX.
  5. Configure the Enhanced XML CDR Importer. You will need now to replace the standard CDR Importer that comes with FusionPBX and use the Enhanced CDR XML Importer. This depends on how you are using it.
    1. if you are importing after the call ends, you will need to modify the /etc/freeswitch/autoload_configs/xml_cdr.conf.xml file and change the following tag.
      from: <param name="url" value="http://127.0.0.1/fusionpbx/app/xml_cdr/v_xml_cdr_import.php"/>
      to: <param name="url" value="http://127.0.0.1/fusionpbx/app/enhanced-cdr-importer/xml_cdr_import.php"/>
      Make sure the path matches. After that, just reload the mod_xml_cdr module.
    2. if you are using the crontab approach, you will need to find the given crontab and just change the script to call.

Source Installation 

  1. Go to app directory where FusionPBX is installed, for example: cd /var/www/html/fusionpbx/app. If you are using the default FusionPBX installation script, it is very likely the path is /var/www/fusionpbx/app.
  2. Copy Billing for FusionPBX in the server (by FTP or SCP), you can place it in /tmp directory
  3. Inside the app/ directory, execute the command tar -jxvf /tmp/billing-crypted.tar.bz2
  4. Go into /var/www/html/app/billing directory and execute echo -n key > any_name.key command, where the key is your license number. Since version 1.0.1 license name can have any name with .key extension.
  5. Go to Advanced->Upgrade menu, select Schema and Menu Defaults
    fusionpbx upgrade
  6. If you are planning to cut the call when it runs out of credit, copy niblebill.conf.xml into autoload_configs directory (for example: /etc/freeswitch/autoload_configs/).cp niblebill.conf.xml /etc/freeswitch/autoload_configs/. Edit niblebill.conf.xml file and change the DSN values with yours. You can get the DSN value from the /etc/fusionpbx/config.lua file. Please make note that by default, FusionPBX doesn't install mod_nibblebill. You will need to manage yourself to get that installed.
  7. Log into FusionPBX as superadmin and go to System->Modules menu, enable and start the Niblebill module.
  8. Go to Advanced->Group Manager and review the LCR permissions, you should have it at least for the superadmin.
  9. Logout and login again into FusionPBX
  10. Install the fusionpbx-enhanced-xml-importer.

License Installation

Go into / your Billing directory (usually /var/www/html/fusionpbx/app/billing or the right directory where you installed) and execute echo -n key > any_name.key command, where the key is your license number. Since version 1.0.1 license name can have any name with .key extension. You don't need to do this if you hold an IP license; IP licenses can be obtained only if you donate to convert the project into open-source.

FusionPBX Patch or Default Settings

You may want to apply the patch xml_cdr_inc.php.diff. From the FusionPBX root directory, type: patch -p0 < app/billing/resources/patches/xml_cdr_inc.php.diff. If you are not able to do this or you don't want to alter your installation you can always set up the following default settings:

  • Category: CDR
  • Sub-Category: field
  • Type: array
  • Value: call_sell_local_currency and local_currency (two entries).

The default settings approach is preferred.

Billing for FusionPBX Configuration

To configure Billing for FusionPBX, you need to understand the following concepts:

Profile
A Profile is used to define who to charge. Each profile is identified by a unique label that is linked directly to the accountcode variable.
Billing Cycle
A Billing Cycle defines the billing day. Static charges will take place this day.
Billing Type
A billing type may be pre or postpaid.
Amount
The specific amount, on post-paid profiles, establishes the maximum credit a profile may have (negative number). This value is zero for pre-paid profiles. You must define billing currency, the system will use external services to do the rating.
LCR profile/Pricing List
A tag that defines what pricing list to use. By changing this label, you may have more than one pricing list.
Refered
Referal fields let you reward your users just because they recommend your service.

Billing Profile Configuration

  1. Go to Apps->Billing menu and add a profile
  2. Fill in the next information
    fusionpbx add new billing
    Select FROM and TO depending on who shall send the billing to who. Data will be taken according to information in the Contacts application; you can go to App -> Contacts menu to fill in the information.
    In most cases, using billing per tenant (domain) is enough, but there are specific cases where an alternate code is required, especially if you need more than one billing profile per tenant; in this case, select the by-code option. The value entered in the Criteria Value field needs to be in place on all other FusionPBX items. This value is the one you will need to match with the accountcode variable to know who to charge.
    Select the billing day cycle, to make things simple it is only allowed from 1 to 28.
    The Amount field is read-only, you must select the currency for billing. Once the currency is set, you won't be able to change it.
    Delay days field is not used.
    Balance is a read-only field.
    LCR profile/Pricing list field will tell the profile what pricing list to use. By default, it is 'default'.
    Referal fields are sued to reward your users because of recommendations.

    New billing releases may have more options.

Remember to fill the accountcode field with the correct value when creating items in FusionPBX. Accountcode by itself is just a variable, depending on your call flow you may configure it at:

  • extensions,
  • variable dialplans.

If you don't know where to start, a good place is by configuring all the extensions with the proper accountcode value.

Dialplan Configuration

The Billing for FusionPBX software needs to have the cdr_billing variable set (any value). This is the way where you can decide what calls to bill or not. The best place to set this variable is in the "variable" dialplan (go to Dialplan -> Dialplan Manager menu option).

Currency Rate Configuration

Insert at least this record in the database:

INSERT INTO v_rate_conversions (rate_conversion_uuid, from_iso4217, to_iso4217, rate, rate_epoch) VALUES ('55e5796b-3aba-4b0a-aab2-299994c755a4', 'USD', 'USD', 1, 0);

If your default currency is different than the USD, you will need to do the same equivalent SQL query. This query won't be necessary for future releases.

After that, sign up for a currency rate API key at https://www.currencyconverterapi.com/ and configure the following default setting:

  • Category: Billing
  • Sub-Category: currency_converter_api
  • Type: text

Run the following command for the first time from the FusionPBX root directory: php app/billing/billing_crontab_currency_rate.php. If you are planning to have customers or carriers that use a mix of currencies, for the sake of speed, it is a good idea to set this crontab at least every 24 hours. This is totally optional, the software will query the API as needed.

Deals

Deals will allow you to give specials. Read our deals document to understand how it works.

Auto Top-Ups and Low Balance Alerts

(It will be soon here)

Maintenance Tasks

Crontab Configuration

The following files can be edited and place into a crontab:

  1. billing_crontab_pyramid.php
  2. billing_crontab_lowbalance_email.php
  3. billing_crontab_auto_topup.php
  4. billing_crontab_lowbalance_email.php

Follow this crontab example:

* * * * * cd /var/www/html/fusionpbx && php app/billing/billing_crontab_auto_topup.php

Configure the crontab frequency as your need it. It is important to call the scripts from within the FusionPBX directory.

Billing Logic Change

Sometimes, you may need to change billing logic (only in specific cases). You can edit the file resources/functions/ratings.php

Billing for FusionPBX Update

You may follow the installation procedure for any update.

Default Settings

Category Sub Category Type Values Default Value
billing earning_rate numeric
  • float value. 1.0 means no earning, 1.10 means 10% profit.
 1.1
billing payment_amount array
  • float or integers of the fixed options to accept a payment. Use this to force always payments of the same amounts. The payments are specified in the local currency, if the local currency is less than the minimum payment, it won't be shown.
  
billing minimum_payment numeric
  • a float indicating the minimum payment the software will accept. If the currency of the customer is other, it will be converted first.
 0
billing minimum_payment_currency text
  • the currency of the minimum payment.
 USD
billing offline_enabled
paypal_enabled
stripe_enabled		 boolean
  • false: disables the PLUGIN for payments.
  • true: enables the PLUGIN for payments.
 true
billing offline_debug
paypal_debug
stripe_debug		 boolean
  • false
  • true
 false
billing offline_message_LANGUAGE
paypal_message_LANGUAGE
stripe_message_LANGUAGE		 text
  • A text to display in the payment plugin. Change LANGUAGE for the language code such as en, es, fr.
 en
billing offline_postpaid_capable
paypal_postpaid_capable
stripe_postpaid_capable		 boolean
  • false: disable this plugin for postpaid customers.
  • true: enable this plugin for postpaid customers.
 false
billing offline_prepaid_capable
paypal_prepaid_capable
stripe_prepaid_capable		 boolean
  • false: disable this plugin for prepaid customers.
  • true: enable this plugin for prepaid customers.
 false
billing

offline_percentage_comission
paypal_percentage_comission
stripe_percentage_comission

  numeric
  • float number of the percentage fee to take of before applying the balance. PayPal fee goes from 2.9%, then the value would be 2.9. 
 0
billing offline_fixed_comission_currency
paypal_fixed_comission_currency
stripe_fixed_comission_currency​		 text
  • The currency used to discount the fixed fee.
 Billing default currency, or USD
billing offline_fixed_comission
paypal_fixed_comission
stripe_fixed_comission		 numeric
  • The fixed fee to take before applying the balance. PayPal's fixed fee is 0.30 USD, then the value would be 0.30.
 0
billing offline_default_charge
paypal_default_charge​
stripe_default_charge​		 numeric
  • a float number that is prefilled when a customer is going to pay.
 0
billing offline_minimum_payment
paypal_minimum_payment​
stripe_minimum_payment​		 numeric
  • a float to specify a minimum payment per plugin.
 Global minimum payment or 0
billing paypal_testmode
stripe_testmode		 boolean
  • false: charges actual money with PayPal.
  • true: uses the PayPal sandbox.
 false
billing paypal_seller_id text
  • PayPal registered email that can receive funds.
  
billing paypal_domain text
  • a domain name that the software will send to let know PayPal where it should push the IPN.
  
billing stripe_publishable_key text
  • your stripe publishable key. It will be used if stripe_test mode is false.
  
billing stripe_secret_key text
  • your stripe secret key. It will be used if stripe_test mode is false.
  
billing stripe_publishable_test_key text
  • your stripe publishable test key. It will be used if stripe_test mode is true.
  
billing stripe_secret_test_key text
  • your stripe secret test key. It will be used if stripe_test mode is true.
  
billing paypal_callback_file
stripe_callback_file		 text
  • an absolute path to the file that has a routine that will be called each time someone makes a payment.
  
billing paypal_callback_function
stripe_callback_function		 text
  • name of the function that is going to be called.
  
billing debug boolean
  • false
  • true
 false
billing https boolean
  • false: uses plain HTTP for internal HTTP calls.
  • true: forces HTTPS for internal HTTPS calls. Turn this on if you are forcing all to use HTTPS.
 false
billing http_project_path boolean  
billing invoice_first_caracters numeric
  • an integer value of how many characters it will use from the contact organization to start numbering your invoice. If you put 4 and the company name is OKay Inc, invoices will be OKAY9999999. This value is used when using the internal invoicing system.
 0
billing invoice_image1
invoice_image2
invoice_image3		 text
  • Paths of the images to attach to the invoice email. Use this if you are using the internal invoicing system.
  
billing invoice_message text
  • text to append in the invoice email. Use this if you are using the internal invoicing system.
  
billing invoice_subject text
  • text of subject on the invoice emails. Use this if you are using the internal invoicing system.
  
billing invoice_cc text
  • email of carbon-copy for the invoice emails. Use this if you are using the internal invoicing system. If you are going to CC to more than one email, use the comma.
  
billing invoice_bcc text
  • email of blinded-Carbon-copy for the invoice emails. Use this if you are using the internal invoicing system. If you are going to BCC to more than one email, use the comma.
  
billing pyramid_message text
  • text to add to the reward email.
  
billing currency text USD
billing extension_price
destination_price
device_price
ivr_menu_price		 numeric
  • a float value of how much to bill per item using the currency specified by the default setting.
 0
billing extensions_for_free
destinations_for_free
devices_for_free
ivr_menu_for_free		 numeric
  • an integer value of how many items per customer will be excluded from being charged.
 0
billing deals_realtime boolean
  • false: don't apply the price correction of any deal in real-time.
  • true: apply the price correction of any deal in real-time. The CDR will have the adjusted price.
 false
billing invoice_only_superadmins var
  • 0: all the contacts in the FROM field of the billing profile will be listed.
  • 1: only super-admin contacts in the FROM field of the billing profile will be listed.

This variable will be fixed in future versions.

 0
billing currency_database_cache_ttl numeric
  • an integer that sets the TTL for the currency cache.
 infinite
billing currency_converter_api text  
billing whmcs_url text
  • full HTTP URL of the WHMCS api.php interface.
  
billing whmcs_identifier text
  • API identifier
  
billing whmcs_secret text
  • API secret
  
billing whmcs_http_user text
  • HTTP authentication user
  
billing whmcs_http_password text
  • HTTP authentication password
  
billing whmcs_billableitem_decimals text
  • an integer indicating the number of decimal places the software will round when placing a charge into the WHMCS.
  
billing whmcs_record_zeroes boolean
  • false: do not send a billable item if the charge of the item is zero.
  • true: send always the charge even if it is a free charge.
 false
billing whmcs_billableitem_invoiceaction text
  • nextcron: the item will be invoiced when the WHMCS crontab runs.
  • nextinvoice: the item will be appended to the next customer invoice.
  • duedate: the item will be invoiced when the billion cycle ends. This day is defined in the billing profile.
 nextcron
billing ca_verification boolean
  • false: the software won't verify the SSL certificates. Use this if you have an old PHP version with an outdated CA chain or use self-signed certificates.
  • true: verifies the HTTPS connections.
 true
billing short_duration_acceptable_percentage numeric
  • a float indicating the maximum percentage of short-calls before applying a surcharge.
 0
billing short_duration_charge numeric
  • a float indicating a fixed surcharge when a short duration happens. If the currency is different, it will be converted before being billed.
 0
billing short_duration_currency text
  • the currency of the short-duration surcharge.
 the billing default currency or USD
billing short_duration_time numeric
  • an integer indicating the maximum call duration to be considered a short call. All calls between zero and this value are short calls.
 0
billing auto_topup_message text
  • the text to send in an email. If the first character starts with an @, you can specify a route to a file. Use the template that is included.
  
billing low_balance_alert numeric
  • The minimum balance to trigger the low-balance email. Currency is specified in the currency default setting.
 5
billing low_balance_message text
  • the text to send in an email. If the first character starts with an @, you can specify a route to a file. Use the template that is included.
  

LUA and FreeSWITCH Variables

LUA Variable FreeSWITCH Variable Values Default Value
lcr.billing  
  • false
  • true: executes the billing part on the LCR engine. It will add all the needed variables for post-processing.
 false
lcr.billing_dynamic_price lcr_billing_dynamic_price
  • false: use strictly the prices from the selling pricing list.
  • true: calculate the selling price on the fly with a profit margin.
 false
lcr.billing_dynamic_earnings lcr_billing_dynamic_earnings
  • a float indicating the profit margin. If 0.50, it means it will add 50% of the buying price.
 false
lcr.billing_default_list_fallback billing_default_list_fallback
  • false: doesn't look into the default pricing list for a missing rate. The price will be for free.
  • true: looks into the default pricing list if the main pricing list doesn't have the required rate.
 false
  billing_default_list_name
  • name of the default pricing list to fallback.
 'default'
lcr.billing_list_required billing_list_required
  • false: allows a free call if the selling rate is missing from the main and the fallback selling pricing list.
  • true: if the rate is not present in the main pricing list or the fallback, the call is not routed.
 false
lcr.strict_earnings lcr_strict_earnings
  • 'relaxed': allows routing even if there is a loss (selling price is lower than buying price).
  • 'strict': only allows routing when there is a profit (selling price must be greater than buying price).
  • a float: routes only if the profit is greater than the required. If you want only to route if you do a 10% profit, put 0.10.
 'relaxed'
  accountcode
  • the code that links the call to the billing profile
  
  cdr_billing
  • any value: it allows the call to be billed by the Enhanced XML CDR Importer.
  • unset: the call won't be billed.
  
  lcr_user_first_rate
  • an integer with the connection rate
 0
  lcr_user_second_rate
  • an integer with the talking rate
 0
  lcr_user_first_increment
  • an integer with the first increment that applies to lcr_user_first_rate
 0
  lcr_user_second_increment
  • an integer with the talking increment that applies to lcr_user_second_rate
 0
  lcr_user_currency
  • the currency of lcr_user_first_rate and lcr_user_second_rate
 Billing default currency or USD

 

Useful Internal Links

Pay with Credit Card
Sitemap
Login
Download Area
Helpdesk
Blog & News

Elsewhere External Places

Bitbucket
Book a Call or Support
Facebook
GitHub
Google +
Google My Business

About OKay

An IT Company whose mission is generating value with low cost of ownership.

We will offer you Linux based solutions that satisfy your needs. We focus on VoIP & Linux, but we are up for any other challenge you may want to bring.