Billing for FusionPBX with FreeSWITCH

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.

Billing for FusionPBX installation
Billing for FusionPBX configuration
Maintenance Tasks
Default Settings
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.

Type yum install fusionpbx-billing
Go to Advanced->Upgrade menu, select Schema and Menu Defaults
Go to Advanced->Group Manager and review the Billing permissions, you should have it at least for the superadmin.
Log out and log in again into FusionPBX.
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

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.
Copy Billing for FusionPBX in the server (by FTP or SCP), you can place it in /tmp directory
Inside the app/ directory, execute the command tar -jxvf /tmp/billing-crypted.tar.bz2
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.
Go to Advanced->Upgrade menu, select Schema and Menu Defaults
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.
Log into FusionPBX as superadmin and go to System->Modules menu, enable and start the Niblebill module.
Go to Advanced->Group Manager and review the LCR permissions, you should have it at least for the superadmin.
Logout and login again into FusionPBX
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.; 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

Go to Apps->Billing menu and add a profile
Fill in the next information

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:

billing_crontab_pyramid.php
billing_crontab_lowbalance_email.php
billing_crontab_auto_topup.php
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	the HTTP path (directory) on how to reach your FusionPBX. If your URL is https://yourserver.com/fusionpbx/, then the value of this parameter should be fusionpbx.
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	ISO 4217 currency code: https://www.iso.org/iso-4217-currency-codes.html.	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	API key for the currency conversion service. You can get it from https://free.currencyconverterapi.com/free-api-key.
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

1.5.0

Billing retroactive rewritten
Crontab scripts moved to a directory
New email templates
Logic bug fixes
FusionPBX 4.5.35, 5.0 compatibility

1.4.0

New billing_card_* permissions
Auto top-up for Strip plugin
Tag support for auto-pricing script
Low balance email warning
PostgreSQL compatibilities
New DISA Lua Script

1.3.3.1

Fix a bug that prevents deleting a billing profile
Recursive queries fix

1.3.3

Auto-pricing script
Fix a bug that prevents adding new billing profiles when using PostgreSQL
More memory to the HTTP export script
Fix recursive queries
Payment plugins now use more default settings (soon plugin_config.php file will be useless)
Callback support when getting a payment

1.3.2

WHMCS SSL certification can be disabled by using a default setting
Date range bugs were fixed
Billing crontab proxy support (very useful when you have a cluster)

1.3.1

Support to get fixed payment amounts.
Amazon MariaDB 10.2+ support.
CSV support to the HTTP export script.

1.3.0

Minimum payment support per plugin.
Deals support, you can now give first X minutes to a prefix at a flat rate.
Better billing by item.
Fix a bug with the currency API.
Export your selling rates in JSON format.
Force payment in full.
Static items charge logic fixed.

1.2.3

Some bugs when you create a new billing profile were fixed.
New support to charge for short calls.
More default settings to customize WHMCS integration.

1.2.2

Cosmetic fixes.

1.2.1

Database currency rate cache. Use the following default setting category: 'billing', subcategory: 'currency_database_cache_ttl', type: 'numeric' to specify a TTL (in seconds). If you specify a negative number, the cache won't expire. You can manipulate this table to use your own rates.
Multiple fixes when using account code different than the domain.
More WHMCS work to make the integration easier. Billable items can be pushed to be invoiced on the next cron, next invoice or a fixed due date.

1.2.0

Force a customer to pay the balance in full.
Currency conversion API updated, you will need to get your own API key from https://www.currencyconverterapi.com/
Currency API updated to v7
All default settings using dot are now deprecated (still useful), use the lower dash. For example, paypal.debug is now paypal_debug.
More WHCMS fixes.
Disable the payment button after pressing it, it will prevent double charges.
Minimum payments. You can specify a general minimum top-up amount or per payment plugin.

1.1.7

In the retroactive script, you can bill for passed calls.
Cosmetic fixes.

1.1.6

Postpaid Customers now can be forced to pay the balance in full.
The quick profile import tool.
Cosmetic fixes.

1.1.5

Bugfixes.

1.1.4

Bugfixes.
Static billing items are rewritten.
New database fields.
WHMCS support, you can now invoice.

1.1.1

Bugfix that prevents the correct charge of static items when using multi-tenant and mixing billing profiles.
Many speed improvements.
Since Yahoo! Finance has closed its currency converting service, we have switched to curencyconverterapi.com.

1.1.0.1

Bugfix that prevents installation in brand new deployments.

1.1.0

TAXes logic was improved, they are added when you are paying.
The Stripe/Offline payment add-ons are now included.

1.0.8

IDR currency support.
Labelling changes of LCR Profile to be more understandable.
Minor fixes.

1.0.7

New default settings to allow to disable experimental features.
Better support for FusionPBX 4.0.
Fix PayPal IPN issue that prevents balance application under some conditions.
Allow showing the updated balance after paying with PayPal.

1.0.6

Useless fields are now hidden.

1.0.5

More fault tolerable.
More credit for post-paid profiles.
Paypal, Stripe and Offline payments plugins now use Default Settings. File config is supported for compatibility.
The Paypal payment plugin now supports auto top-ups.
HTTPS now can be selected as the default protocol.
Better support for websites with 301/302 answer codes.
Postpaid invoices with CC and BCC support.
Better support for PostgreSQL.

1.0.4

Better Support for FusionPBX 3.7.
New 'default settings' to control pyramid message.
New script to send billing messages to post-paid users.
Recurrent payments for Paypal Support.
nibblebill.conf.xml file fixes.
Commission deduction support for payment gateways, in % or fixed quantity.

Billing

Since 1.3.0, the Billing for FusionPBX has support for deals. A deal is an easy way to overwrite the rate of certain destinations based on some conditions. You will be able to offer deals such as:

The first 60 monthly minutes of outbound calls to the 1613 area code will be for free.

Page 1 of 2

Start
Prev
1
2
Next
End

Useful Internal Links

Elsewhere External Places

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.

To Top