8. Billing Configuration

8.1. Billing Profiles
8.1.1. Creating Billing Profiles
8.1.2. Creating Billing Fees
8.1.3. Creating Off-Peak Times
8.2. Prepaid Accounting
8.3. Fraud Detection and Locking
8.3.1. Fraud Lock Levels
8.4. Billing Customizations
8.4.1. Billing Networks
8.4.2. Profile Mapping Schedule
8.4.3. Profile Packages
8.4.4. Vouchers
8.4.5. Top-up
8.4.6. Balance Overviews
8.4.7. Usage Examples
8.5. Billing Data Export
8.5.1. Glossary of Terms
8.5.2. File Name Format
8.5.3. File Format
8.5.4. File Transfer

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

8.1. Billing Profiles

Service billing on the NGCP is based on billing profiles, which may be assigned to customers 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.)

8.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 SettingsBilling and click on Create Billing Profile.

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 customer 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.
  • Prepaid: Enables prepaid accounting for this profile as opposed to normal post-paid mode.
  • 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.

8.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_adminfees_csvelement_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.
important

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.

important

There are several internal services (vsc, conference, voicebox, fax2mail) 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 @fax2mail\.local$, @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.

8.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 SettingsBilling and press the Off-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

8.2. Prepaid Accounting

In a normal post-paid accounting scenario, each customer accumulates debt in their billing account, which at the end of the billing interval is then billed to the customer. A prepaid billing profile reverses this sequence: the customer first has to provide credit to their account balance, and the costs for all calls are then deducted from that account balance. Once the balance reaches zero, no further calls from this customer are accepted, with the exception of free calls. Additionally, if the balance drops to zero while any calls are currently active, NGCP will disconnect those calls as soon as that happens.

With prepaid billing enabled, all details of the billing profile and all details of the billing fees behave as they normally do, including interval free time. If any interval free time is given, the free time will be used before the account’s credit is.

important

For technical reasons, the system can make the distinction between on-peak and off-peak times only at call establishment time. In other words, if the currently active call fee at the moment when the call is established is an off-peak fee, then the same off-peak fee will remain active for the whole length of this call, even if the call actually transitions into an on-peak fee (and vice versa).

important

For technical reasons, prepaid billing can’t charge local endpoint calls to Voicebox, VSC calls or calls to a Conference Room.

The Sipwise NGCP platform offers advanced billing features which are especially designed for pre-paid billing scenarios. For details please visit Billing Customizations Section 8.4, “Billing Customizations” section of the handbook.

8.3. 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 8.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.

8.3.1. Fraud Lock Levels

Fraud lock levels are various protection (and notification) settings that are applied to subscribers of a Customer, if fraud detection is enabled in the currently active billing profile and the Customer’s daily or monthly fraud limit has been exceeded.

The following lock levels are available:

  • none: no account locking will happen
  • foreign calls: only calls within the subscriber’s own domain, and emergency calls, are allowed
  • all outgoing calls: subscribers of the customer cannot place any calls, except calls to free and emergency destinations
  • incoming and outgoing: subscribers of the customer cannot place and receive any calls, except calls to free and emergency destinations
  • global: same restrictions as at incoming and outgoing level, additionally subscribers are not allowed to access the Customer Self Care (CSC) interface
  • ported: only automatic call forwarding, due to number porting, is allowed
important

You can override fraud detection and locking settings of a billing profile on a per-account basis via REST API or the Admin interface.

caution

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.

important

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.

info

It is possible to fetch the list of fraud events and thus get fraud status of Customers by using the REST API and referring to the resource: /api/customerfraudevents.

info

Apart from the daily fraud detection check service, NGCP also provides instant, "hard" locking for prepaid use cases, by means of billing profile packages. See Billing Profile Packages Section 8.4.3, “Profile Packages” for reference.

8.4. Billing Customizations

The standard way of doing the billing — i.e. having fixed billing intervals of a calendar month, starting on the 1st day of month — may not fit all billing profiles and intervals that sip:provider PRO platform operators would like to use.

The sip:provider PRO supports — starting from its mr4.2.1 version — alternate ways of defining billing profiles and intervals which are especially worthy for pre-paid scenarios. New functionality is covered by the following titles:

Subsequent sections will provide an introduction and configuration instructions to these advanced features of sip:provider PRO.

8.4.1. Billing Networks

The idea is to dynamically select billing profiles (including fees) depending on the IP network the caller‘s SIP client is using to connect. The caller‘s IP is populated in a call‘s CDR, and effectively processed by:

  • the rating engine component („rate-o-mat“) and the
  • prepaid interception module (libswrate).

The billing profile for rating a call is identified by matching the source IP against network ranges linked to the customer contract‘s billing mappings records. This feature is sometimes also referred to as roaming.

A Billing Network is defined as a series of network blocks where each network block consists of a single IP address or an IP subnet. Blocks of a particular billing network can be defined by either IPv4, or IPv6 addresses but not mixed.

Creation of Billing Network

Figure 62. Creation of Billing Network


The new /api/billingnetworks/ REST API resource allows to manage billing networks. The example billing network that is shown in the figure above may be defined through the API with this JSON structure:

{ "blocks" : [ { "ip" : "10.0.1.0", // subnet: 10.0.1.0 .. 10.0.1.255
                 "mask" : 24
               },
               { "ip" : "10.0.2.2" // single ip
               }
             ],
  "description" : "Some text",
  "name" : "Demo Billing Net 1", //unique per reseller
  "reseller_id" : 1
}

Input validation of the network blocks is automatically performed by sip:provider PRO during their definition in a way that it prevents specifying overlapping blocks by means of Interval Trees; billing networks themselves may overlap though.

Overlapping Block Prevention

Figure 63. Overlapping Block Prevention


8.4.2. Profile Mapping Schedule

Using the default settings related to billing when creating a new Reseller or Customer on the administrative web panel results in applying the standard billing profile mapping schedule: the same billing profile is always used.

8.4.2.1. Definition of Profile Mapping Schedules

The idea of billing profile mapping schedule is to extend the billing mappings logic to utilize it as a schedule for billing profiles (and associated fees) for the Customer or Reseller contract. So far, billing mapping records provided only a history showing which profile was in effect at a given time in the past, which is for example required for delayed rating of calls.

Now it is also possible to define in advance, when specific billing profiles should become active in the future, e.g. to plan campaigns or special offers.

Billing profile mappings represent a schedule of overlapping time intervals with Billing Profiles and Billing Networks, which are assigned to (customer) contracts when creating or editing them.

Mapping intervals can be of type:

  • open: no start time + no end time
  • half-open:

    • left-open: no start time + definite end time
    • right-open: definite start time + no end time
  • closed: definite start time + definite end time
8.4.2.2. Schedule Example
Profile Mapping Schedule Example

Figure 64. Profile Mapping Schedule Example


Applying the profile mapping schedule shown in the above figure will result in billing profiles being active as provided in the table below.

Table 11. Active Billing Profiles

Time

Web Panel shows

Rating

Caller IP in Network 1

Caller IP in Network 2

Caller IP in other network

May 30

Profile 1

Profile 1

Profile 1

Profile 1

June 1

Profile 4

Profile 3

Profile 4

Profile 1

June 2

Profile 2

Profile 2

Profile 4

Profile 1

June 5

Profile 5

Profile 3

Profile 4

Profile 5


8.4.2.3. Configuration of Schedules

A Customer’s default billing profile mapping can be changed to scheduled mappings when editing its properties, at the parameter "Set billing profiles", selecting: schedule (billing mapping intervals)

Profile Mapping Schedule Creation

Figure 65. Profile Mapping Schedule Creation


tip

Assigning a Billing Network to a billing profile mapping is optional. Without selecting the network, the Billing Profile will be applied to all calls.

The profile mapping schedule assigned to a Customer is also listed among Customer’s properties. See Settings → Customers → Details → Billing Profile Schedule.

Profile Mapping Schedule List

Figure 66. Profile Mapping Schedule List


info

Profile mappings that started in the past, like the default one, are displayed with a strike-through font in order to indicate that those can not be modified.

The currently active mapping is depicted by a checked box.

8.4.2.4. REST API for Profile Mapping Schedules

The /api/customers/ API resource was extended to provide three different modes of defining profile mappings:

  1. billing_profiles field: explicitly declare profile mappings in form of (billing profile, billing network, start time, stop time) tuples
  2. billing_profile_id field (legacy API spec): a single profile mapping interval is appended (billing profile, no network / any caller IP respectively, starting now)
  3. profile_package_id field: profile mappings starting now are appended by using lists of (billing profile, billing network) tuples from the given profile package

With regards to Resellers, the /api/contracts/ API resource was enhanced as well, but supports method 1. and 2. only, and without billing networks.

Mapping Intervals

Intervals can be of open, half-open (left-open, right-open) or closed type. When specifying profile mappings discretely, allowed interval types are restricted, depending on create/update situation:

Table 12. Allowed Mapping Intervals

Interval Type Start Stop POST (create) PUT / PATCH (update)

open

undefined

undefined

1..*

0

left-open

undefined

defined

0

0

right-open

> now()

undefined

*

*

closed

> now()

> start

*

*


Example Profile Mapping

An example JSON structure for definition of profile mapping schedules shown in Billing Profile Schedule List Figure 66, “Profile Mapping Schedule List” :

{ ...,
  "billing_profile_definition" : "profiles", // i.e. use 'billing_profiles' field
  "billing_profiles" : [ { "network_id" : "236",
                           "profile_id" : "236",
                           "start" : "2016-11-01 00:00:00",
                           "stop" : "2016-12-31 00:00:00"
                         }, // closed future interval, with network
                         { "network_id" : null,
                           "profile_id" : "237",
                           "start" : "2017-01-01 00:00:00",
                           "stop" : "2017-12-31 00:00:00"
                         } ], // closed future interval, without network
  "contact_id" : 141,
  ...
}

8.4.3. Profile Packages

By introducing billing profile packages, general billing parameters can be defined for a customer contract:

  • Balance interval duration (regular/constant or aligned to top-up events)
  • The first interval‘s start date
  • The cash-balance carry-over/discard behaviour upon interval transitions
  • Subscriber lock levels and profile sets to get applied upon:

    • top-up
    • balance threshold underrun
  • Initial balance and billing profiles

Profile Packages are fundamental for pre-paid billing scenarios, since in such a billing scheme the traditional, fixed monthly periods prove to be insufficient to cover the business needs of the NGCP platform operator. As an example: pre-paid subscribers typically have their "billing periods" between account balance top-ups.

8.4.3.1. Elements of Profile Packages

A Profile Package consists of various elements that will be discussed in subsequent sections of the sip:provider PRO handbook. In order to set the parameters of a profile package one must navigate to: Settings → Profile Packages → Create Profile Package, or alternatively, in order to update an existing profile package: select the package and press Edit button.

Basic Balance Intervals Setup

  • Interval duration (n hours, days, weeks, months)
  • Interval start mode:

    • 1st of month (1st): billing interval is 1 calendar month; this is the default for each Customer created on Sipwise NGCP platform

      Interval Start Mode: 1st

      Figure 67. Interval Start Mode: 1st


    • upon customer creation (create): (the initial) billing interval starts when the Customer is created

      Interval Start Mode: create

      Figure 68. Interval Start Mode: create


    • upon topup (topup_interval): interval starts at first topup event and its length is defined by interval duration parameter of the profile package

      Interval Start Mode: topup_interval

      Figure 69. Interval Start Mode: topup_interval


    • intervals from topup to topup (topup): interval starts at any topup event and its length is defined by interval duration parameter of the profile package; intervals can overlap in this case

      Interval Start Mode: topup

      Figure 70. Interval Start Mode: topup


  • Initial balance: the initial value of account balance (e.g. every new customer gets 5 Euros as a starting bonus)

Balance Carry Over

  • Carry Over: balance carry over behaviour upon interval transitions:

    • carry-over: always keep balance
    • carry-over only if topped-up timely: keep balance in case of a timely top-up only; where timely means the topup happens within a pre-defined time span before the end of the balance interval
    • discard: discard balance at the end of each interval
  • Timely Duration: duration of the timely period
  • Discard balance after intervals: for how many balance intervals the remaining account balance is kept before its disposal

Underrun Settings

  • Underrun lock threshold: when account balance reaches this amount the subscriber will be locked to a restricted set of services
  • Underrun lock level: this level of services will apply when an account balance underruns

    • don’t change: no change in the available set of services
    • no lock: all services are available
    • foreign: only calls within subscriber’s own domain are allowed
    • outgoing: all outgoing calls are prohibited
    • all calls: all calls (incoming + outgoing) are prohibited
    • global: all calls + access to Customer Self Care web interface are prohibited
    • ported: only automatic call forwarding, due to number porting, is allowed
  • Underrun profile threshold: when account balance reaches this amount the Underrun Billing Profile will be applied

Basic Top-up Settings

  • Top-up lock level: subscriber lock (unlock) levels to apply upon top-up event
  • Service charge: (always) subtract this value from the voucher amount, if topup happens via the usage of a voucher

Profile mappings

A lists of (billing profile, billing network) tuples for appending profile mappings:

  • Initial Billing Profile: when creating or manually changing the customers package (initial_profiles)
  • Underrun Billing Profile: when the balance underuns a cash threshold (underrun_profiles)
  • Top-up Billing Profile: when the customer tops-up using a voucher associated with the package (topup_profiles)
8.4.3.2. Examples

Profile Package Configuration

  1. Definition of basic profile package parameters

    Basic Profile Package Parameters

    Figure 71. Basic Profile Package Parameters


  2. Definition of balance interval and carry-over behaviour

    Balance Interval and Carry-over

    Figure 72. Balance Interval and Carry-over


  3. Definition of balance underrun parameters

    Balance Underrun Parameters

    Figure 73. Balance Underrun Parameters


  4. Definition of top-up settings

    Balance Top-up Settings

    Figure 74. Balance Top-up Settings


  5. Assigning a profile package to a customer

    Assigning Profile Package to Customer

    Figure 75. Assigning Profile Package to Customer


Interval start mode: top-up interval; carry-over: timely

Profile package setup:

  • initial_balance: 1.0 euro
  • balance_interval: 30 "day(s)“
  • interval_start_mode: "topup_interval“
  • carry_over_mode: "timely“
  • timely_duration: 12 "day(s)“
  • underrun_lock_threshold: 0.7 euro
  • underrun_profile_threshold: 5.0 euro
  • underrun_lock_level:…
Example: Top-up Interval and Timely Carry-over

Figure 76. Example: Top-up Interval and Timely Carry-over


Interval start mode: top-up to top-up; carry-over: always

  • initial_balance: 1.0 euro
  • balance_interval: 30 "day(s)“
  • interval_start_mode: "topup“
  • carry_over_mode: "carry-over“
  • notopup_discard_intervals: 1
  • underrun_lock_threshold: 0.7 euro
  • underrun_profile_threshold: 5.0 euro
  • underrun_lock_level:…
Example: Top-up and Always Carry-over

Figure 77. Example: Top-up and Always Carry-over


8.4.3.3. REST API

The new /api/profilepackages/ REST API resource allows to manage billing profile package container entities, that aggregate settings of profile packages.

A sample JSON structure follows:

{
  "reseller_id" : 1,
  "status" : "active",
  "name" : "demo profile package",
  "description" : "package for 10€ ...",
  "balance_interval_start_mode" : "1st",
  "balance_interval_value" : 1,
  "balance_interval_unit" : "month",
  "carry_over_mode" : "carry_over",
  "timely_duration_unit" : null,
  "timely_duration_value" : null,
  "initial_balance" : 0,
  "initial_profiles" : [...], // required default, e.g. same as „topup_profiles“
  "notopup_discard_intervals" : null,
  "underrun_lock_threshold" : 0,
  "underrun_lock_level" : 4,
  "underrun_profile_threshold" : 5,
  "underrun_profiles" : [...],
  "service_charge" : 10,
  "topup_lock_level" : null,
  "topup_profiles" : [ {
                         "network_id" : null, // any network
                         "profile_id" : 29
                       },
                       {
                         "network_id" : 2, // a specific billing network
                         "profile_id" : 30
                       },
                     ],
  ...
}

8.4.4. Vouchers

Vouchers are a typical mean of topping-up an account balance in pre-paid billing scenarios.

The definition of a voucher in the database may succeed via:

  • manual entry of voucher data on the administrative web panel or through the REST API
  • bulk-uploading of vouchers using a CSV (comma separated value) formatted file

In order to manage vouchers the administrator has to navigate to: Settings → Vouchers → Create Billing Voucher or select an existing one and press Edit button.

List of Vouchers

Figure 78. List of Vouchers


8.4.4.1. Properties of Vouchers
  • Code: the unique code of the voucher which assures that a voucher can be used only once; this property is encrypted and displayed on the web panel to authorized users only
  • Amount: the amount of money the voucher represents
  • Valid until: end of validity period
Voucher's Main Properties

Figure 79. Voucher's Main Properties


Setting following properties of a voucher is optional:

  • Customer: the Customer whom the voucher will be assigned to; subscribers of other customers can not redeem the voucher
  • Package: vouchers may be associated with profile packages; if done so, some changes will be applied to the Customer for whom the voucher is redeemed with the top-up event:

    • applying top-up profile mappings starting with the time of the top-up
    • subtracting the new package‘s service charge from the voucher amount
    • resizing the current balance interval for a gapless transition, if the new package has a different interval start mode (e.g. from "create" to "1st")
    • if a new balance interval starts with the top-up, the carry-over mode of the customer‘s previous package applies
Voucher: Customer and Profile Package

Figure 80. Voucher: Customer and Profile Package


8.4.4.2. REST API

Vouchers can be created and managed using the /api/vouchers/ REST API resource. This resource restricts invasive operations (POST, PUT, PATCH, DELETE) to authorized users.

{
  "amount" : 1000,
  "customer_id" : null, //do not restrict to a specific customer
  "valid_until" : "2017-06-05 23:59:59",
  "package_id" : "571", //switch to profile package
  "reseller_id" : 1,
  "code" : "SILVER_1_1437974823"
}

8.4.5. Top-up

A customer’s administrator or subscriber can perform a top-up to increase the contract‘s cash balance. The NGCP platform supports two means of topping-up the balance:

  1. Top-up Cash: Directly specify the cash amount to add
  2. Top-up Voucher: Specify the code of a voucher, which was set up in advance

The NGCP platform provides 2 interfaces to perform top-ups:

  1. through the REST API: use a CRM or third-party REST-API Broker (which i.e. coordinates with an App-Store purchase process) to finally instruct NGCP to perform a top-up. This is the recommended method.
  2. through the administrative web interface:

    One has to select the Customer, then Details → Contract Balance and finally press Top-up Cash or Top-up Voucher.

8.4.5.1. Top-up Cash

When doing top-up with cash one needs to supply the amount of top-up in the currency of the customer contract. Optionally one can assign a Profile Package to the top-up event which will activate that profile package for the customer.

Balance Top-up with Cash

Figure 81. Balance Top-up with Cash


It is also possible to perform top-up through the REST API: POST /api/topupcash

{
  "subscriber_id" : "73",
  "amount" : 100,
  "package_id" : null,
}
8.4.5.2. Top-up Voucher

Selecting Top-up Voucher option will provide a simple list of available vouchers from which the administrator can choose the voucher. If a Profile Package is assigned to the voucher, that package will be activated for the customer on the top-up event.

Balance Top-up with Voucher

Figure 82. Balance Top-up with Voucher


It is also possible to perform top-up through the REST API: POST /api/topupvouchers

{
  "subscriber_id" : "73",
  "code" : "SILVER_1_1437974390“
  "request_token" : "uuid_from_3rdparty_relay" // optional request identifier
                                               // for lookups in the top-up log
}

8.4.6. Balance Overviews

The actual contract balance and logs of top-up or balance interval change events are a kind of financially important information and that’s why those are provided on the administrative web interface for each customer. One should navigate to: Settings → Customers → select the customer → Details.

The various information details available on the web interface are discussed in subsequent sections of the handbook.

8.4.6.1. Contract Balance

This part of the overviews shows the actual financial state of the customer’s balance and the current profile package and balance interval.

Contract Balance Status

Figure 83. Contract Balance Status


Another functionality assigned to Contract Balance section is the manual top-up. Both top-up with cash and top-up with voucher can be performed from here.

8.4.6.2. Balance Intervals

This table shows the balance intervals that have been in use, including the current interval.

List of Balance Intervals

Figure 84. List of Balance Intervals


Content of the balance intervals table is:

  • From, To: starting and end points of the time interval
  • Cash: the contract’s cash balance value at the end of the interval (former int.), or currently (actual int.)
  • Debit: the total spent amount of money in the actual interval

    info

    While "Cash" shows the remaining amount, "Debit" shows the spent amount. With a post-paid billing scenario only "Debit" field would be populated, with pre-paid both fields will display an amount.

  • No. of Top-ups: how many top-up events happened within the interval
  • No. of Timely Top-ups: how many timely top-up events happened within the interval
  • Underrun detected (Profiles or Lock): the time of last underrun event when either an underrun billing profile, or a subscriber lock was activated
8.4.6.3. Top-up Log

Each successful or failing top-up request has to be logged. The log records represent an audit trail and reflect any data changes in the course of the top-up request.

In case of an error during the top-up operation the error message and any parseable fields of failed top-up attempts is recorded.

Balance Top-up Log

Figure 85. Balance Top-up Log


Content of the top-up log table is:

  • Timestamp: when the top-up happened
  • Subscriber: the ID of the subscriber who performed the top-up
  • Type: cash or voucher
  • Outcome: ok or failed
  • Message: error message, if Outcome="failed"
  • Voucher ID: ID of voucher, if Type="voucher"
  • Amount: the amount by which the balance was modified (after the Service Charge was subtracted from the voucher’s value)
  • Balance before: balance’s value before top-up
  • Balance after: balance’s value after top-up
  • Package before: the name of the Profile Package that was active before top-up
  • Package after: the name of the Profile Package that became active after top-up

The top-up log table can also be queried using the readonly /api/topuplogs REST API resource.

An example of the response:

{
  "_embedded" : {
    "ngcp:topuplogs" : [{
      "_links" : {...},
      "amount" : null,
      "cash_balance_after" : null,
      "cash_balance_before" : null,
      "contract_balance_after_id" : null,
      "contract_balance_before_id" : null,
      "contract_id" : 2565,
      "id" : 373,
      "lock_level_after" : null,
      "lock_level_before" : null,
      "message" : ..., //error reason
      "outcome" : "failed",
      "package_after_id" : null,
      "package_before_id" : null,
      "profile_after_id" : null,
      "profile_before_id" : null,
      "request_token" : "1444956281_6", // = “panel“ for panel UI requests
      "subscriber_id" : 1804,
      "timestamp" : "2015-10-16 02:45:19",
      "type" : "voucher", // "cash" or "voucher"
      "username" : "administrator",
      "voucher_id" : null }]
  },
  "_links" : { ... },
  "total_count" : 1
}

8.4.7. Usage Examples

After getting to know the concepts of customized billing solution on sip:provider PRO platform, it’s worth seeing some practical examples for the usage of those advanced features.

The starting point is the setup of Profile Packages for our fictive customers: A, B and C. There are 4 different packages defined, with corresponding vouchers:

  • Initial:

    • Balance interval: 1 month
    • Timely duration: 1 month
    • Interval start mode: topup_interval
    • Carry-over mode: carry_over_timely
  • Silver:

    • Balance interval: 1 month
    • Timely duration: 1 month
    • Interval start mode: "topup_interval"
    • Carry-over mode: "carry_over_timely"
    • Service charge: 2 EUR
    • Underrun lock level: "no lock"
    • Voucher value: 10 EUR
  • Gold:

    • Balance interval: 1 month
    • Interval start mode: "topup_interval"
    • Carry-over mode: "carry_over"
    • Service charge: 5 EUR
    • Underrun lock level: "no lock"
    • Voucher value: 20 EUR
  • Extension:

    • Balance interval: 1 month
    • Timely duration: 1 month
    • Interval start mode: "topup_interval"
    • Carry-over mode: "carry_over_timely"
    • Service charge: 2 EUR
    • Underrun lock level: "no lock"
    • Voucher value: 2 EUR
8.4.7.1. Customer A — Silver Package
  1. Customer A tops up 10 EUR with a “silver” voucher. 2 EUR are deducted as service charge. Remaining balance is 8 EUR starting on the date of the top- up.
  2. Customer A doesn’t top-up balance within the next month, so remaining balance is set to 0 after one month, and billing profiles and lock levels are set to the balance-underrun definition of the “silver” package.
Usage Example: Silver Package

Figure 86. Usage Example: Silver Package


8.4.7.2. Customer B — Silver and Extension Package
  1. Customer B tops up 10 EUR with the “silver” voucher. 2 EUR are deducted as service charge. Remaining balance is 8 EUR starting on the date of the top-up.
  2. Customer B tops up 2 EUR using an “extension” voucher on the last day. 2 EUR are deducted as service charge and the interval is extended for one month, carrying over his old balance.
  3. Customer B doesn’t top-up balance within the next month, so remaining balance is set to 0 after the month, and billing profiles and lock levels are set to the balance-underrun definition of the “extension” package.
Usage Example: Silver + Extension Package

Figure 87. Usage Example: Silver + Extension Package


8.4.7.3. Customer C — Gold Package

Customer C tops up 20 EUR with the “gold” voucher. 5 EUR are deducted as service charge. Remaining balance is 15 EUR starting on the date of the top-up. Balance is carried over after each month until used up.

Usage Example: Gold Package

Figure 88. Usage Example: Gold Package


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

8.5.1. Glossary of Terms

Billing records contain fields that hold data of various entities that play a role in the phone service offered by Sipwise NGCP. For a better understanding of billing data please refer to the glossary provided here:

  • Account: the customer’s account that is charged for calls of its subscriber(s)
  • Carrier: a SIP peer that sends incoming calls to, or receives outgoing calls from NGCP. A carrier may charge fees for the outgoing calls from NGCP (outbound billing fee), or for the incoming calls to NGCP (inbound billing fee).
  • Contract: the service contract that represents a customer, a reseller or a SIP peer; a contract on NGCP contains the billing profile (billing fees) too
  • Customer: the legal entity that represents any number of subscribers; this entity receives the bills for calls of its subscriber(s)
  • Provider: either the reseller that holds a subscriber who is registered on NGCP, or the SIP peer that handles calls between an external subscriber and NGCP
  • Reseller: the entity who is the direct, administrative service provider of a group of customers and subscribers registered on NGCP; the NGCP operator may also charge a reseller for the calls initiated or received by its subscribers
  • User: the subscriber who either is registered on NGCP, or is an external call party

8.5.2. 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 13. CDR/EDR export file name format

File name elementLengthDescription

<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

8.5.3. File Format

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

8.5.3.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 14. CDR/EDR export file header line format

Body ElementLengthTypeDescription

<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
8.5.3.2. File Body Format for Call Detail Records (CDR)

The body of a CDR consists of a minimum of zero and a default maximum of 5000 lines. The platform operator can configure the maximum number of lines kept in a file by updating the cdrexport.max_rows_per_file parameter in /etc/ngcp-config/config.yml file. Each line holds one call detail record in CSV format and is constructed by a configurable set of fields, all of them enclosed in single quotes.

The following table defines the default set of fields that are inserted into the CDR file, for exports related to system scope. The list of fields is defined in /etc/ngcp-config/config.yml file, cdrexport.admin_export_fields parameter.

Table 15. Default set of system CDR fields

Body ElementLengthTypeDescription

CDR_ID

1-10

uint

Internal CDR ID.

UPDATE_TIME

19

timestamp

Timestamp of last modification, including date and time (with seconds precision).

SOURCE_USER_ID

36

string

Internal UUID of calling party subscriber. Value is 0 if calling party is external.

SOURCE_PROVIDER_ID

0-255

string

Internal ID of the contract of calling party provider (i.e. reseller or peer).

SOURCE_EXTERNAL_SUBSCRIBER_ID

0-255

string

External, arbitrary ID of calling party subscriber. (A string value shown as "External ID" property of an NGCP subscriber.)

SOURCE_SUBSCRIBER_ID

1-11

uint

Internal ID of calling party subscriber. Value is 0 if calling party is external.

SOURCE_EXTERNAL_CONTRACT_ID

0-255

string

External, arbitrary ID of calling party customer. (A string value shown as "External ID" property of an NGCP customer/peer.)

SOURCE_ACCOUNT_ID

1-11

uint

Internal ID of calling party customer.

SOURCE_USER

0-255

string

SIP username of calling party.

SOURCE_DOMAIN

0-255

string

SIP domain of calling party.

SOURCE_CLI

0-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

36

string

Internal UUID of called party subscriber. Value is 0 if called party is external.

DESTINATION_PROVIDER_ID

0-255

string

Internal ID of the contract of called party provider (i.e. reseller or peer).

DESTINATION_EXTERNAL_SUBSCRIBER_ID

0-255

string

External, arbitrary ID of called party subscriber. (A string value shown as "External ID" property of an NGCP subscriber.)

DESTINATION_SUBSCRIBER_ID

1-11

uint

Internal ID of called party subscriber. Value is 0 if calling party is external.

DESTINATION_EXTERNAL_CONTRACT_ID

0-255

string

External, arbitrary ID of called party customer. (A string value shown as "External ID" property of an NGCP customer/peer.)

DESTINATION_ACCOUNT_ID

1-11

uint

Internal ID of called party customer.

DESTINATION_USER

0-255

string

Final SIP username of called party.

DESTINATION_DOMAIN

0-255

string

Final SIP domain of called party.

DESTINATION_USER_IN

0-255

string

Incoming SIP username of called party, after applying inbound rewrite rules.

DESTINATION_DOMAIN_IN

0-255

string

Incoming SIP domain of called party, after applying inbound rewrite rules.

DESTINATION_USER_DIALED

0-255

string

The user-part of the SIP Request URI as received by NGCP.

PEER_AUTH_USER

0-255

string

Username used to authenticate towards peer.

PEER_AUTH_REALM

0-255

string

Realm used to authenticate towards peer.

CALL_TYPE

3-4

string

The type of the call - one of:

call: normal call

cfu: call forward unconditional

cfb: call forward busy

cft: call forward timeout

cfna: call forward not available

cfs: call forward for SMS

CALL_STATUS

2-8

string

The final call status - one of:

ok: successful call

busy: called party busy

noanswer: no answer from called party

cancel: cancel from caller

offline called party offline

timeout: no reply from called party

other: unspecified, see CALL_CODE field for details

CALL_CODE

3

string

The final SIP status code.

INIT_TIME

23

timestamp

Timestamp of call initiation (SIP INVITE received from calling party). Includes date, time with milliseconds (3 decimals).

START_TIME

23

timestamp

Timestamp of call establishment (final SIP response received from called party). Includes date, time with milliseconds (3 decimals).

DURATION

4-13

fixed precision (3 decimals)

Length of call (calculated from START_TIME) including milliseconds (3 decimals).

CALL_ID

0-255

string

The SIP Call-ID.

RATING_STATUS

2-7

string

The internal rating status of the CDR - 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

datetime

Time of rating, including date and time (with seconds precision). Empty if CDR is not rated.

SOURCE_CARRIER_COST

7-14

fixed precision (6 decimals)

The originating carrier cost that the carrier (i.e. SIP peer) charges for the calls routed to his network, or empty if CDR is not rated.

PLEASE NOTE: Only available in system exports, not for resellers.

SOURCE_CUSTOMER_COST

7-14

fixed precision (6 decimals)

The originating customer cost, or empty if CDR is not rated.

SOURCE_CARRIER_ZONE

0-127

string

Name of the originating carrier billing zone, or onnet if data is not available.

PLEASE NOTE: Only available in system exports, not for resellers.

SOURCE_CUSTOMER_ZONE

0-127

string

Name of the originating customer billing zone, or empty if CDR is not rated.

SOURCE_CARRIER_DETAIL

0-127

string

Description of the originating carrier billing zone, or platform internal if data is not available.

PLEASE NOTE: Only available in system exports, not for resellers.

SOURCE_CUSTOMER_DETAIL

0-127

string

Description of the originating customer billing zone, or empty if CDR is not rated.

SOURCE_CARRIER_FREE_TIME

1-10

uint

The number of free time seconds used on originating carrier side, or empty if CDR is not rated.

PLEASE NOTE: Only available in system exports, not for resellers.

SOURCE_CUSTOMER_FREE_TIME

1-10

uint

The number of free time seconds used from the originating customer’s account balance, or empty if CDR is not rated.

DESTINATION_CARRIER_COST

7-14

fixed precision (6 decimals)

The terminating carrier cost, or empty if CDR is not rated.

PLEASE NOTE: Only available in system exports, not for resellers.

DESTINATION_CUSTOMER_COST

7-14

fixed precision (6 decimals)

The terminating customer cost, or empty if CDR is not rated.

DESTINATION_CARRIER_ZONE

0-127

string

Name of the terminating carrier billing zone, or onnet if data is not available.

PLEASE NOTE: Only available in system exports, not for resellers.

DESTINATION_CUSTOMER_ZONE

0-127

string

Name of the terminating customer billing zone, or empty if CDR is not rated.

DESTINATION_CARRIER_DETAIL

0-127

string

Description of the terminating carrier billing zone, or empty if CDR is not rated.

PLEASE NOTE: Only available in system exports, not for resellers.

DESTINATION_CUSTOMER_DETAIL

0-127

string

Description of the terminating customer billing zone, or empty if CDR is not rated.

DESTINATION_CARRIER_FREE_TIME

1-10

uint

The number of free time seconds used on terminating carrier side, or empty if CDR is not rated.

PLEASE NOTE: Only available in system exports, not for resellers.

DESTINATION_CUSTOMER_FREE_TIME

1-10

uint

The number of free time seconds used from the terminating customer’s account balance, or empty if CDR is not rated.

SOURCE_RESELLER_COST

7-14

fixed precision (6 decimals)

The originating reseller cost, or empty if CDR is not rated.

PLEASE NOTE: Only available in system exports, not for resellers.

SOURCE_RESELLER_ZONE

0-127

string

Name of the originating reseller billing zone, or empty if CDR is not rated.

PLEASE NOTE: Only available in system exports, not for resellers.

SOURCE_RESELLER_DETAIL

0-127

string

Description of the originating reseller billing zone, or empty if CDR is not rated.

PLEASE NOTE: Only available in system exports, not for resellers.

SOURCE_RESELLER_FREE_TIME

1-10

uint

The number of free time seconds used from the originating reseller’s account balance, or empty if CDR is not rated.

PLEASE NOTE: Only available in system exports, not for resellers.

DESTINATION_RESELLER_COST

7-14

fixed precision (6 decimals)

The terminating reseller cost, or empty if CDR is not rated.

PLEASE NOTE: Only available in system exports, not for resellers.

DESTINATION_RESELLER_ZONE

0-127

string

Name of the terminating reseller billing zone, or empty if CDR is not rated.

PLEASE NOTE: Only available in system exports, not for resellers.

DESTINATION_RESELLER_DETAIL

0-127

string

Description of the terminating reseller billing zone, or empty if CDR is not rated.

PLEASE NOTE: Only available in system exports, not for resellers.

DESTINATION_RESELLER_FREE_TIME

1-10

uint

The number of free time seconds used from the terminating reseller’s account balance, or empty if CDR is not rated.

PLEASE NOTE: Only available in system exports, not for resellers.

<line_terminator>

1

string

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.

info

Please check the description of fields in the table above, in order to see which fields are omitted for reseller related CDR exports.

The list of fields for reseller CDR export is defined in /etc/ngcp-config/config.yml file, cdrexport.reseller_export_fields parameter.

8.5.3.3. Extra fields that can be exported to CDRs

Supplementary Data

There are fields in CDR database that contain supplementary data related to subscribers. This data is not used by NGCP for CDR processing but rather provides the system administrator with a possibility to include supplementary information in CDRs.

info

This informational section is meant for problem solving / debugging purpose: The supplementary data listed in following table is stored in provisioning.voip_preferences database table.

Table 16. Supplementary data in CDR fields

Body ElementLengthTypeDescription

SOURCE_GPP0

0-255

string

Supplementary data field 0 of calling party.

SOURCE_GPP1

0-255

string

Supplementary data field 1 of calling party.

SOURCE_GPP2

0-255

string

Supplementary data field 2 of calling party.

SOURCE_GPP3

0-255

string

Supplementary data field 3 of calling party.

SOURCE_GPP4

0-255

string

Supplementary data field 4 of calling party.

SOURCE_GPP5

0-255

string

Supplementary data field 5 of calling party.

SOURCE_GPP6

0-255

string

Supplementary data field 6 of calling party.

SOURCE_GPP7

0-255

string

Supplementary data field 7 of calling party.

SOURCE_GPP8

0-255

string

Supplementary data field 8 of calling party.

SOURCE_GPP9

0-255

string

Supplementary data field 9 of calling party.

DESTINATION_GPP0

0-255

string

Supplementary data field 0 of called party.

DESTINATION_GPP1

0-255

string

Supplementary data field 1 of called party.

DESTINATION_GPP2

0-255

string

Supplementary data field 2 of called party.

DESTINATION_GPP3

0-255

string

Supplementary data field 3 of called party.

DESTINATION_GPP4

0-255

string

Supplementary data field 4 of called party.

DESTINATION_GPP5

0-255

string

Supplementary data field 5 of called party.

DESTINATION_GPP6

0-255

string

Supplementary data field 6 of called party.

DESTINATION_GPP7

0-255

string

Supplementary data field 7 of called party.

DESTINATION_GPP8

0-255

string

Supplementary data field 8 of called party.

DESTINATION_GPP9

0-255

string

Supplementary data field 9 of called party.


Account balance details (prepaid calls)

There are fields in CDR database that show changes in cash or free time balance. In addition to that, a history of billing packages / profiles may also be present, since the NGCP vouchers, that are used to top-up, may also be set up to cause a transition of profile packages. (Which in turn can result in changing the billing profile/applicable fees). Therefore the billing package and profile valid at the time of the CDR are recorded and exposed as fields for CDR export.

tip

Such fields may also be required to integrate sip:provider PRO with legacy billing systems.

info

Please be aware that pre-paid billing functionality is only available in Sipwise sip:provider PRO and sip:carrier products.

The name of CDR data field consists of the elements listed below:

  1. source|destination: decides if the data refers to calling (source) or called (destination) party
  2. carrier|reseller|customer: the account owner, whose billing data is referred
  3. data type:

    1. cash_balance|free_time_balance _ before|after: cash balance or free time balance, before or after the call
    2. profile_package_id|contract_balance_id: internal ID of the active pre-paid billing profile or the account balance

Examples:

  • source_customer_cash_balance_before
  • destination_customer_profile_package_id
important

For calls spanning multiple balance intervals, the latter one will be selected, that is the balance interval where the call ended.

important

There are some limitations in rating pre-paid calls, please visit Pre-paid Billing Section 8.2, “Prepaid Accounting” section for details.

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

The body of an EDR consists of a minimum of zero and a maximum of 5000 lines. The platform operator can configure the maximum number of lines kept in a file by updating the eventexport.max_rows_per_file parameter in /etc/ngcp-config/config.yml file. Each line holds one call detail record in CSV format and is constructed by the fields as per the subsequent table.

The following table defines the default set of fields that are inserted into the EDR file, for exports related to system scope. The list of fields is defined in /etc/ngcp-config/config.yml file, eventexport.admin_export_fields parameter.

Table 17. Default set of system EDR fields

Body ElementLengthTypeDescription

EVENT_ID

1-11

uint

Internal EDR ID.

TYPE

0-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 PBX / hunting group.

end_huntgroup: A subscriber has been deprovisioned as PBX / hunting group.

start_ivr: A subscriber has a new call-forward to Auto-Attendant.

end_ivr: A subscriber has removed a call-forward to Auto-Attendant.

CONTRACT_EXTERNAL_ID

0-255

string

The external ID of the customer. (A string value shown as "External ID" property of an NGCP customer.)

COMPANY

0-127

string

The company name of the customer’s contact.

SUBSCRIBER_EXTERNAL_ID

0-255

string

The external ID of the subscriber. (A string value shown as "External ID" property of an NGCP subscriber.)

PLEASE NOTE: This field is empty in case of start_huntgroup and end_huntgroup events.

PILOT_PRIMARY_NUMBER

0-64

string

The pilot subscriber’s primary number (HPBX subscribers). PLEASE NOTE: This is not included in default set of EDR fields from NGCP version mr5.0 upwards.

PRIMARY_NUMBER

0-64

string

The VoIP number of the subscriber with the highest ID (DID or primary number).

OLD_PROFILE_NAME

0-255

string

The old status of the event. Depending on the event_type:

start_profile: Empty.

end_profile: The name of the subscriber profile which got removed from the subscriber.

update_profile: The name of the former subscriber profile which got updated.

start_huntgroup: Empty.

end_huntgroup: Empty.

start_ivr: Empty.

end_ivr: Empty.

NEW_PROFILE_NAME

0-255

string

The new status of the event. Depending on the event_type:

start_profile: The name of the subscriber profile which got assigned to the subscriber.

end_profile: Empty.

update_profile: The name of the new subscriber profile which got applied.

start_huntgroup: Empty.

end_huntgroup: Empty.

start_ivr: Empty.

end_ivr: Empty.

TIMESTAMP

23

timestamp

Timestamp of event. Includes date, time with milliseconds (3 decimals).

RESELLER_ID

1-11

uint

Internal ID of the reseller which the event belongs to.

PLEASE NOTE: 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 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","1"

The format of the EDR export files generated for resellers (as opposed to the complete system-wide export) is identical except for a few missing fields.

info

Please check the description of fields in the table above, in order to see which fields are omitted for reseller related EDR exports.

The list of fields for reseller EDR export is defined in /etc/ngcp-config/config.yml file, eventexport.reseller_export_fields parameter.

8.5.3.5. Extra fields that can be exported to EDRs

There are fields in EDR database that contain supplementary data related to subscribers, for example subscriber phone numbers are such data.

Table 18. Supplementary data in EDR fields

Body ElementLengthTypeDescription

SUBSCRIBER_PROFILE_SET_NAME

0-255

string

The subscriber’s profile set name.

PILOT_SUBSCRIBER_PROFILE_SET_NAME

0-255

string

The profile set name of the subscriber’s pilot subscriber.

PILOT_SUBSCRIBER_PROFILE_NAME

0-255

string

The profile name of the subscriber’s pilot subscriber.

FIRST_NON_PRIMARY_ALIAS_USERNAME_BEFORE

0-255

string

The subscriber’s non-primary alias with lowest ID, before number updates during the operation.

FIRST_NON_PRIMARY_ALIAS_USERNAME_AFTER

0-255

string

The subscriber’s non-primary alias with lowest ID, after number updates during the operation.

PILOT_FIRST_NON_PRIMARY_ALIAS_USERNAME_BEFORE

0-255

string

The non-primary alias with lowest ID of the subscriber’s pilot subscriber, before number updates during the operation.

PILOT_FIRST_NON_PRIMARY_ALIAS_USERNAME_AFTER

0-255

string

The non-primary alias with lowest ID of the subscriber’s pilot subscriber, after number updates during the operation.

NON_PRIMARY_ALIAS_USERNAME

0-255

string

The non-primary alias of a subscriber affected by an update_profile, start_profile or end_profile event to track number changes.

PRIMARY_ALIAS_USERNAME_BEFORE

0-255

string

The subscriber’s primary alias, before number updates during the operation.

PRIMARY_ALIAS_USERNAME_AFTER

0-255

string

The subscriber’s primary alias, after number updates during the operation.

PILOT_PRIMARY_ALIAS_USERNAME_BEFORE

0-255

string

The primary alias of the subscriber’s pilot subscriber, before number updates during the operation.

PILOT_PRIMARY_ALIAS_USERNAME_AFTER

0-255

string

The primary alias of the subscriber’s pilot subscriber, after number updates during the operation.

FIRST_NON_PRIMARY_ALIAS_USERNAME_BEFORE_AFTER

0-255

string

Equals FIRST_NON_PRIMARY_ALIAS_USERNAME_BEFORE, if the value is not NULL, otherwise it’s the same as FIRST_NON_PRIMARY_ALIAS_USERNAME_AFTER.

PILOT_FIRST_NON_PRIMARY_ALIAS_USERNAME_BEFORE_AFTER

0-255

string

Equals PILOT_FIRST_NON_PRIMARY_ALIAS_USERNAME_BEFORE, if the value is not NULL, otherwise it’s the same as PILOT_FIRST_NON_PRIMARY_ALIAS_USERNAME_AFTER.


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

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

info

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.