9. Billing Configuration

This chapter describes the steps necessary to rate calls and export rated CDRs (call detail records) to external systems.

9.1. Billing Data Import

Service billing on the NGCP is based on billing profiles, which may be assigned to VoIP accounts and SIP peerings. The design focuses on a simple, yet flexible approach, to support arbitrary dial-plans without introducing administrative overhead for the system administrators. The billing profiles may define a base fee and free time or free money per billing interval. Unused free time or money automatically expires at the end of the billing interval.

Each profile may have call destinations (usually based on E.164 number prefix matching) with configurable fees attached. Call destination fees each support individual intervals and rates, with a different duration and/or rate for the first interval. (e.g.: charge the first minute when the call is opened, then every 30 seconds, or make it independent of the duration at all) It is also possible to specify different durations and/or rates for peak and off-peak hours. Peak time may be specified based on weekdays, with additional support for manually managed dates based on calendar days. The call destinations can finally be grouped for an overview on user’s invoices by specifying a zone in two detail levels. (E.g.: national landline, national mobile, foreign 1, foreign 2, etc.)

9.1.1. Creating Billing Profiles

The first step when setting up billing data is to create a billing profile, which will be the container for all other billing related data. Go to Settings→Billing and click on Create Billing Profile.

The fields Reseller, Handle and Name are mandatory.

Reseller: The reseller this billing profile belongs to.
Handle: A unique, permanently fixed string which is used to attach the billing profile to a VoIP account or SIP peering contract.
Name: A free form string used to identify the billing profile in the Admin Panel. This may be changed at any time.
Interval charge: A base fee for the billing interval, specifying a monetary amount (represented as a floating point number) in whatever currency you want to use.
Interval free time: If you want to include free calling time in your billing profile, you may specify the number of seconds that are available every billing interval. See Creating Billing Fees below on how to select destinations which may be called using the free time.
Interval free cash: Same as for interval free time above, but specifies a monetary amount which may be spent on outgoing calls. This may be used for example to implement a minimum turnover for a contract, by setting the interval charge and interval free cash to the same values.
Fraud monthly limit: The monthly fraud detection limit (in Cent) for accounts with this billing profile. If the call fees of an account reach this limit within a billing interval, an action can be triggered.
Fraud monthly lock: a choice of none, foreign, outgoing, incoming, global. Specifies a lock level which will be used to lock the account and his subscribers when fraud monthly limit is exceeded.
Fraud monthly notify: An email address or comma-separated list of email addresses that will receive notifications when fraud monthly limit is exceeded.
Fraud daily limit: The fraud detection limit (in Cent) for accounts with this billing profile. If the call fees of an account reach this limit within a calendar day, an action can be triggered.
Fraud daily lock: a choice of none, foreign, outgoing, incoming, global. Specifies a lock level which will be used to lock the account and his subscribers when fraud daily limit is exceeded.
Fraud daily notify: An email address or comma-separated list of email addresses that will receive notifications when fraud daily limit is exceeded.
Currency: The currency symbol for your currency. Any UTF-8 character may be used and will be printed in web interfaces.
VAT rate: The percentage of value added tax for all fees in the billing profile. Currently for informational purpose only and not used further.
VAT included: Whether VAT is included in the fees entered in web forms or uploaded to the platform. Currently for informational purpose only and not used further.

9.1.2. Creating Billing Fees

Each Billing Profile holds multiple Billing Fees.

To set up billing fees, click on the Fees button of the billing profile you want to configure. Billing fees may be uploaded using a configurable CSV file format, or entered directly via the web interface by clicking Create Fee Entry. To configure the CSV field order for the file upload, rearrange the entries in the www_admin→fees_csv→element_order array in /etc/ngcp-config/config.yml and execute the command ngcpcfg apply changed fees element order. The following is an example of working CSV file to upload (pay attention to double quotes):

".","^1",out,"EU","ZONE EU",5.37,60,5.37,60,5.37,60,5.37,60,0,0
"^01.+$","^02145.+$",out,"AT","ZONE Test",0.06250,1,0.06250,1,0.01755,1,0.01733,1,0

For input via the web interface, just fill in the text fields accordingly.

Create Billing Fee

In both cases, the following information may be specified independently for every destination:

Zone: A zone for a group of destinations. May be used to group destinations for simplified display, e.g. on invoices. (e.g. foreign zone 1)
Source: The source pattern. This is a POSIX regular expression matching the complete source URI (e.g. ^.*@sip\.example\.org$ or ^someone@sip\.sipwise\.com$ or just . to match everything). If you leave this field empty, the default pattern . matching everything will be set implicitly. Internally, this pattern will be matched against the <source_cli>@<source_domain> fields of the CDR.
Destination: The destination pattern. This is a POSIX regular expression matching the complete destination URI (e.g. someone@sip\.example\.org or ^43). This field must be set.
Direction: Outbound for standard origination fees (applies to callers placing a call and getting billed for that) or Inbound for termination fees (applies to callees if you want to charge them for receiving various calls, e.g. for 800-numbers). If in doubt, use Outbound. If you upload fees via CSV files, use out or in, respectively.


	The {source, destination, direction} combination needs to be unique for a billing profile. The system will return an error if such a set is specified twice, both for the file upload and the input via the web interface.

There are several internal services (vsc, conference, voicebox) which will need a specific destination entry with a domain-based destination. If you don’t want to charge the same (or nothing) for those services, add a fee for destination \.local$ there. If you want to charge different amounts for those services, break it down into separate fee entries for @vsc\.local$, @conference\.local$ and @voicebox\.local$ with the according fees. NOT CREATING EITHER THE CATCH-ALL FEE OR THE SEPARATE FEES FOR THE .local DOMAIN WILL BREAK YOUR RATING PROCESS!

Onpeak init rate: The rate for the first rating interval in cent (of whatever currency, represented as a floating point number) per second. Applicable to calls during onpeak hours.
Onpeak init interval: The duration of the first billing interval, in seconds. Applicable to calls during onpeak hours.
Onpeak follow rate: The rate for subsequent rating intervals in cent (of whatever currency, represented as a floating point number) per second. Applicable to calls during onpeak hours. Defaults to onpeak init rate.
Onpeak follow interval: The duration of subsequent billing intervals, in seconds. Applicable to calls during onpeak hours. Defaults to onpeak init interval.
Offpeak init rate: The rate for the first rating interval in cent (of whatever currency, represented as a floating point number) per second. Applicable to calls during off-peak hours. Defaults to onpeak init rate.
Offpeak init interval: The duration of the first billing interval, in seconds. Applicable to calls during off-peak hours. Defaults to onpeak init interval.
Offpeak follow rate: The rate for subsequent rating intervals in cent (of whatever currency, represented as a floating point number) per second. Applicable to calls during off-peak hours. Defaults to offpeak init rate if that one is specified, or to onpeak follow rate otherwise.
Offpeak follow interval: The duration of subsequent billing intervals, in seconds. Applicable to calls during off-peak hours. Defaults to offpeak init interval if that one is specified, or to onpeak follow interval otherwise.
Use free time: Specifies whether free time minutes may be used when calling this destination. May be specified in the file upload as 0, n[o], f[alse] and 1, y[es], t[rue] respectively.

9.1.3. Creating Off-Peak Times

To be able to differentiate between on-peak and off-peak calls, the platform stores off-peak times for every billing profile based on weekdays and/or calendar days. To edit the settings for a billing profile, go to Settings→Billing and press the Peaktimes button on the billing profile you want to configure.

To set off-peak times for a weekday, click on Edit next to the according weekday. You will be presented with two input fields which both receive a timestamp in the form of hh:mm:ss specifying a time of day for the start and end of the off-peak period. If any of the fields is left empty, the system will automatically insert 00:00:00 (start field) or 23:59:59 (end field). Click on Add to store the setting in the database. You may create more than one off-peak period per weekday. To delete a range, just click Delete next to the entry. Click the close icon when done.

Create Weekday Offpeak

To specify off-peak ranges based on calendar dates, click on Create Special Off-Peak Date. Enter a date in the form of YYYY-MM-DD hh:mm:ss into the Start Date/Time input field and End Date/Time input field to define a range for the off-peak period.

Create Special Offpeak

9.1.4. Fraud Detection and Locking

The NGCP supports a fraud detection feature, which is designed to detect accounts causing unusually high customer costs, and then to perform one of several actions upon those accounts. This feature can be enabled and configured through two sets of billing profile options described in Section 9.1.1, “Creating Billing Profiles”, namely the monthly (fraud monthly limit, fraud monthly lock and fraud monthly notify) and daily limits (fraud daily limit, fraud daily lock and fraud daily notify). Either monthly/daily limits or both of them can be active at the same time.

Monthly fraud limit check runs once a day, shortly after midnight local time and daily fraud limit check runs every 30min. A background script (managed by cron daemon) automatically checks all accounts which are linked to a billing profile enabled for fraud detection, and selects those which have caused a higher cost than the fraud monthly limit configured in the billing profile, within the currently active billing interval (e.g. in the current month), or a higher cost than the fraud daily limit configured in the billing profile, within the calendar day. It then proceeds to perform at least one of the following actions on those accounts:

If fraud lock is set to anything other than none, it will lock the account accordingly (e.g. if fraud lock is set to outgoing, the account will be locked for all outgoing calls).
If anything is listed in fraud notify, an email will be sent to the email addresses configured. The email will contain information about which account is affected, which subscribers within that account are affected, the current account balance and the configured fraud limit, and also whether or not the account was locked in accordance with the fraud lock setting. It should be noted that this email is meant for the administrators or accountants etc., and not for the customer.


	You can override these settings on a per-account basis via REST API or the Admin interface.


	Accounts that were automatically locked by the fraud detection feature will not be automatically unlocked when the next billing interval starts. This has to be done manually through the administration panel or through the provisioning interface.

If fraud detection is configured to only send an email and not lock the affected accounts, it will continue to do so for over-limit accounts every day. The accounts must either be locked in order to stop the emails (only currently active accounts are considered when the script looks for over-limit accounts) or some other action to resolve the conflict must be taken, such as disabling fraud detection for those accounts.

9.2. Billing Data Export

Regular billing data export is done using CSV (comma separated values) files which may be downloaded from the platform using the cdrexport user which has been created during the installation.

There are two types of exports. One is CDR (Call Detail Records) used to charge for calls made by subscribers, and the other is EDR (Event Detail Records) used to charge for provisioning events like enabling certain features.

9.2.1. File Name Format

In order to be able to easily identify billing files, the file names are constructed by the following fixed-length fields:

<prefix><separator><version><separator><timestamp><separator><sequence number><suffix>

The definition of the specific fields is as follows:

Table 4. CDR/EDR export file name format

File name element	Length	Description
`<prefix>`	7	A fixed string. Always `sipwise`.
`<separator>`	1	A fixed character. Always `_`.
`<version>`	3	The format version, a three digit number. Currently `007`.
`<timestamp>`	14	The file creation timestamp in the format `YYYYMMDDhhmmss`.
`<sequence number>`	10	A unique 10-digit zero-padded sequence number for quick identification.
`<suffix>`	4	A fixed string. Always `.cdr` or `.edr`.

A valid example filename for a CDR billing file created at 2012-03-10 14:30:00 and being the 42nd file exported by the system, is:

sipwise_007_20130310143000_0000000042.cdr

9.2.2. File Format

Each billing file consists of three parts: one header line, zero to 5000 body lines and one trailer line.

9.2.2.1. File Header Format

The billing file header is one single line, which is constructed by the following fields:

<version>,<number of records>

The definition of the specific fields is as follows:

Table 5. CDR/EDR export file header line format

Body Element	Length	Type	Description
`<version>`	3	zero-padded uint	The format version. Currently `007`.
`<number of records>`	4	zero-padded uint	The number of body lines contained in the file.

A valid example for a Header is:

007,0738

9.2.2.2. File Body Format for Call Detail Records (CDR)

The body of a CDR consists of a minimum of zero and a maximum of 5000 lines. Each line holds one call detail record in CSV format and is constructed by the following fields, all of them enclosed in single quotes:

Table 6. CDR export file body line format

Body Element	Length	Type	Description
`<id>`	1-10	uint	Internal CDR id.
`<update_time>`	19	timestamp	Timestamp of last modification.
`<source_user_id>`	36	string	Internal UUID of calling party subscriber.
`<source_provider_id>`	1-255	string	Internal ID of calling party provider.
`<source_ext_subscriber_id>`	0-255	string	External ID of calling party subscriber.
`<source_subscriber_id>`	1-10	uint	Internal ID of calling party subscriber.
`<source_ext_account_id>`	0-255	string	External ID of calling party VoIP account.
`<source_account_id>`	1-10	uint	Internal ID of calling party VoIP account.
`<source_user>`	1-255	string	SIP username of calling party.
`<source_domain>`	1-255	string	SIP domain of calling party.
`<source_cli>`	1-64	string	CLI of calling party in E.164 format.
`<source_clir>`	1	uint	`1` for calls with CLIR, `0` otherwise.
`<source_ip>`	0-64	string	IP Address of the calling party.
`<destination_user_id>`	1 / 36	string	Internal UUID of called party subscriber or `0` if callee is not local.
`<destination_provider_id>`	1-255	string	Internal ID of called party provider.
`<dest_ext_subscriber_id>`	0-255	string	External ID of called party subscriber.
`<dest_subscriber_id>`	1-10	uint	Internal ID of called party subscriber.
`<dest_ext_account_id>`	0-255	string	External ID of called party VoIP account.
`<destination_account_id>`	1-10	uint	Internal ID of called party VoIP account.
`<destination_user>`	1-255	string	Final SIP username of called party.
`<destination_domain>`	1-255	string	Final SIP domain of called party.
`<destination_user_in>`	1-255	string	Incoming SIP username of called party.
`<destination_domain_in>`	1-255	string	Incoming SIP domain of called party.
`<dialed_digits>`	1-255	string	The user-part of the SIP Request URI as received by the soft-switch.
`<peer_auth_user>`	0-255	string	User to authenticate towards peer.
`<peer_auth_realm>`	0-255	string	Realm to authenticate towards peer.
`<call_type>`	3-4	string	The type of the call - one of: `call`: normal call `cfu`: call forward unconditional `cft`: call forward timeout `cfb`: call forward busy `cfna`: call forward no answer
`<call_status>`	2-7	string	The final call status - one of: `ok`: successful call `busy`: callee busy `noanswer`: no answer from callee `cancel`: cancel from caller `offline` callee offline `timeout`: no reply from callee `other`: unspecified, see `<call_code>` for details
`<call_code>`	3	uint	The final SIP status code.
`<init_time>`	23	timestamp	Timestamp of call initiation (invite received from caller). Seconds include fractional part (3 decimals).
`<start_time>`	23	timestamp	Timestamp of call establishment (final response received from callee). Seconds include fractional part (3 decimals).
`<duration>`	4-11	fixed precision	Length of call (beginning at `start_time`) in seconds with 3 decimals.
`<call_id>`	1-255	string	The SIP call-id.
`<rating_status>`	2-7	string	The internal rating status - one of: `unrated`: not rated `ok`: successfully rated `failed`: error while rating Currently always `ok` or `unrated`, depending on whether rating is enabled or not.
`<rated_at>`	0 / 19	timestamp	Timestamp of rating or empty if not rated.
`<source_carrier_cost>`	4-11	fixed precision	The originating carrier cost or empty if not rated. In cent with two decimals. `Only available in system exports, not for resellers.`
`<source_customer_cost>`	4-11	fixed precision	The originating customer cost or empty if not rated. In cent with two decimals.
`<source_carrier_zone>`	0-127	string	The originating carrier billing zone or empty if not rated. `Only available in system exports, not for resellers.`
`<source_customer_zone>`	0-127	string	The originating customer billing zone or empty if not rated.
`<source_carrier_destination>`	0-127	string	The originating carrier billing destination or empty if not rated. `Only available in system exports, not for resellers.`
`<source_customer_destination>`	0-127	string	The originating customer billing destination or empty if not rated.
`<source_carrier_free_time>`	1-10	uint	The number of originating free time seconds used on carrier side or empty if not rated. `Only available in system exports, not for resellers.`
`<source_customer_free_time>`	1-10	uint	The number of originating free time seconds used from the customer’s account balance or empty if not rated.
`<destination_carrier_cost>`	4-11	fixed precision	The termination carrier cost or empty if not rated. In cent with two decimals. `Only available in system exports, not for resellers.`
`<destination_customer_cost>`	4-11	fixed precision	The termination customer cost or empty if not rated. In cent with two decimals.
`<destination_carrier_zone>`	0-127	string	The termination carrier billing zone or empty if not rated. `Only available in system exports, not for resellers.`
`<destination_customer_zone>`	0-127	string	The termination customer billing zone or empty if not rated.
`<destination_carrier_destination>`	0-127	string	The termination carrier billing destination or empty if not rated. `Only available in system exports, not for resellers.`
`<destination_customer_destination>`	0-127	string	The termination customer billing destination or empty if not rated.
`<destination_carrier_free_time>`	1-10	uint	The number of termination free time seconds used on carrier side or empty if not rated. `Only available in system exports, not for resellers.`
`<destination_customer_free_time>`	1-10	uint	The number of termination free time seconds used from the customer’s account balance or empty if not rated.
`<source_reseller_cost>`	4-11	fixed precision	The originating reseller cost or empty if not rated. In cent with two decimals. `Only available in system exports, not for resellers.`
`<source_reseller_zone>`	0-127	string	The originating reseller billing zone or empty if not rated. `Only available in system exports, not for resellers.`
`<source_reseller_destination>`	0-127	string	The originating reseller billing destination or empty if not rated. `Only available in system exports, not for resellers.`
`<source_reseller_free_time>`	1-10	uint	The number of originating free time seconds used from the reseller’s account balance or empty if not rated. `Only available in system exports, not for resellers.`
`<destination_reseller_cost>`	4-11	fixed precision	The termination reseller cost or empty if not rated. In cent with two decimals. `Only available in system exports, not for resellers.`
`<destination_reseller_zone>`	0-127	string	The termination reseller billing zone or empty if not rated. `Only available in system exports, not for resellers.`
`<destination_reseller_destination>`	0-127	string	The termination reseller billing destination or empty if not rated. `Only available in system exports, not for resellers.`
`<destination_reseller_free_time>`	1-10	uint	The number of termination free time seconds used from the reseller’s account balance or empty if not rated. `Only available in system exports, not for resellers.`
`<line_terminator>`	1	string	A fixed character. Always `\n` (special char LF - ASCII `0x0A`).

A valid example of one body line of a rated CDR is (line breaks added for clarity):

'15','2013-03-26 22:09:11','a84508a8-d256-4c80-a84e-820099a827b0','1','','1','',
'2','testuser1','192.168.51.133','4311001','0','192.168.51.1',
'94d85b63-8f4b-43f0-b3b0-221c9e3373f2','1','','3','','4','testuser3',
'192.168.51.133','testuser3','192.168.51.133','testuser3','','','call','ok','200',
'2013-03-25 20:24:50.890','2013-03-25 20:24:51.460','10.880','44449842',
'ok','2013-03-25 20:25:27','0.00','24.00','onnet','testzone','platform internal',
'testzone','0','0','0.00','200.00','','foo','','foo','0','0',
'0.00','','','0','0.00','','','0'

The format of the CDR export files generated for resellers (as opposed to the complete system-wide export) is identical except for a few missing fields. Reseller CDR CSV files don’t contain the fields for carrier or reseller ratings, neither in source nor destination direction. Thus, the reseller CSV files have 16 fewer fields.

9.2.2.3. File Body Format for Event Detail Records (EDR)

The body of a EDR consists of a minimum of zero and a maximum of 5000 lines. Each line holds one call detail record in CSV format and is constructed by the following fields, all of them enclosed in single quotes:

Table 7. EDR export file body line format

Body Element	Length	Type	Description
`<event_id>`	1-10	uint	Internal EDR id.
`<event_type>`	1-255	string	The type of the event - one of: `start_profile`: A subscriber profile has been newly assigned to a subscriber. `end_profile`: A subscriber profile has been removed from a subscriber. `update_profile`: A subscriber profile has been changed for a subscriber. `start_huntgroup`: A subscriber has been provisioned as group. `end_huntgroup`: A subscriber has been deprovisioned as group. `start_ivr`: A subscriber has a new call-forward to auto-attendant set. `end_ivr`: A subscriber has removed a call-forward to auto-attendant.
`<customer_external_id>`	0-255	string	The external customer ID as provisioned for the subscriber.
`<contact_company>`	0-255	string	The company name of the customer’s contact.
`<subscriber_external_id>`	0-255	string	The external subscriber ID as provisioned for the subscriber.
`<subscriber_number>`	0-255	string	The voip number of the subscriber with the highest ID (DID or primary number).
`<old_status>`	0-255	string	The old status of the event. Depending on the event_type: `start_profile`: Empty. `end_profile`: The profile id of the profile which got removed from the subscriber. `update_profile`: The old profile id which got updated. `start_huntgroup`: Empty. `end_huntgroup`: The profile id of the group which got deprovisioned. `start_ivr`: Empty. `end_ivr`: Empty.
`<new_status>`	0-255	string	The new status of the event. Depending on the event_type: `start_profile`: The profile id which got assigned to the subscriber. `end_profile`: Empty. `update_profile`: The new profile id which got updated. `start_huntgroup`: The current profile id assigned to the group subscriber. `end_huntgroup`: The current profile id assigned to the group subscriber. `start_ivr`: Empty. `end_ivr`: Empty.
`<timestamp>`	0-255	string	The time when the event occured.
`<line_terminator>`	1	string	A fixed character. Always `\n` (special char LF - ASCII `0x0A`).

A valid example of one body line of an EDR is (line breaks added for clarity):

"1","start_profile","sipwise_ext_customer_id_4","Sipwise GmbH",
"sipwise_ext_subscriber_id_44","436667778","","1","2014-06-19 11:34:31"

9.2.2.4. File Trailer Format

The billing file trailer is one single line, which is constructed by the following fields:

<md5 sum>

The <md5 sum> is a 32 character hexadecimal MD5 hash of the Header and Body.

To validate the billing file, one must remove the Trailer before computing the MD5 sum of the file. An example bash script to validate the integrity of the file is given below:

#!/bin/sh

error() { echo $@; exit 1; }
test -n "$1" || error "Usage: $0 <cdr-file>"
test -f "$1" || error "File '$1' not found"

TMPFILE="/tmp/$(basename "$1").$$"
MD5="$(sed -rn '$ s/^([a-z0-9]{32}).*$/\1/i p' "$1")  $TMPFILE"
sed '$d' "$1" > "$TMPFILE"
echo "$MD5" | md5sum -c -
rm -f "$TMPFILE"

Given the script is located in cdr-md5.sh and the CDR-file is sipwise_001_20071110123000_0000000004.cdr, the output of the integrity check for an intact CDR file would be:

$ ./cdr-md5.sh sipwise_001_20071110123000_0000000004.cdr
/tmp/sipwise_001_20071110123000_0000000004.cdr: OK

If the file has been altered during transmission, the output of the integrity check would be:

$ ./cdr-md5.sh sipwise_001_20071110123000_0000000004.cdr
/tmp/sipwise_001_20071110123000_0000000004.cdr: FAILED
md5sum: WARNING: 1 of 1 computed checksum did NOT match

9.2.3. File Transfer

Billing files are created twice per hour at minutes 25 and 55 and are stored in the home directory of the cdrexport user. If the amount of records within the transmission interval exceeds the threshold of 5000 records per file, multiple billing files are created. If no billing records are found for an interval, a billing file without body data is constructed for easy detection of lost billing files on the 3rd party side.

CDR and EDR files are fetched by a 3rd party billing system using SFTP or SCP with either public key or password authentication using the username cdrexport. If public key authentication is chosen, the public key file has to be stored in the file ~/.ssh/authorized_keys2 below the home directory of the cdrexport user. Otherwise, a password has to be set for the user.

The 3rd party billing system is responsible for deleting CDR files after fetching them.


	The `cdrexport` user is kept in a jailed environment on the system, so it has only access to a very limited set of commandline utilities.