‎Destinations, rates, and tariffs

Destinations, rates, and tariffs are the essential parameters that define how a certain event must be billed. It is very important to find a correct set of billing parameters and rules (rates) for each event, and this is done by matching a service identifier with the rates available in the rate plan (tariff). The service identifier specifies exactly how the service is used. For example, the service identifier for voice calls would be the destination number (Called-Station-Id, or CLD, or DNIS). For SMS messages, it would be a combination of a mobile country code (MCC) and a mobile network code (MNC), while for services such as a pay-per-view movie it could be the movie category (“New Release,” “International” or “Classic”). Since rating telephony numbers is the most complex case, that will be the primary focus of this chapter.

Destinations are a list of all possible phone number prefixes to be used in your system. You generally need a new phone prefix when you have a new service area for calls that are to be treated differently than others.

For example, if you start providing calls to the Czech Republic, you should add destination 420 and specify it as the Czech Republic. Later, if you plan to charge calls to Prague differently than calls to the rest of the Czech Republic, you might need to add another destination with the phone number prefix 4202. All such destinations must be entered into the system before you can use these prefixes. This prevents errors and helps improve data quality. It is recommended that all of your phone number prefixes be defined in the E.164 format (i.e. <country code><area code><user’s local number> without the ‘+’ prefix).

For SMS delivery, however, you operate with mobile country codes (MCC) and mobile network codes (MNC) for phone numbers. Therefore, to charge users for an SMS to the Czech Republic via Vodafone, you would define the phone number prefix 42077 as the 230-03 code pair and add destination E.212-230-03 for the Czech Republic – Vodafone network in PortaBilling. The format that defines phone numbers as a combination of MCC/MNC codes is called E.212 format.

It is virtually impossible to have an “ultimate” destination list that would contain all the prefixes for the whole world. First of all, it would be quite difficult to gather and maintain such information, and second, and more importantly, having “all possible” prefixes would not offer any real benefits, and would only make rate maintenance more difficult.

For instance, if vendor A provides you with a rate of 0.10/min for calls to 420 (Czech Republic) and a 0.18 rate for calls to 420602 and 420603, you must create three prefixes: 420, 420602, and 420603. If you also create the prefix 4205 (Czech Republic, Brno) it will only take up space in the database since it will never actually be used.

Therefore, we recommend that you follow a “required minimum” approach: only create those destinations for which you need specific rates for your carriers or customers.

For service types other than those based on phone numbers, you may create symbolic destinations such as WIFI, NETACCESS, or MOVIE-BLOCKBUSTER.

Sometimes you will have several prefixes for the same target destination, e.g., 420601, 420602, and 420603 for mobile numbers in the Czech Republic. All of these prefixes can be defined as the single destination group “CZ Mobile”, so when you enter the new rate for this destination group it will, in effect, create rates for each individual prefix.

It happens quite often that different partners will assign a different meaning to the same destination groups. For instance, your partner A says that “CZ Mobile” is 420601, 420602, and 420604, but your partner B also considers prefix 420603 to be part of “CZ Mobile”. So you will need to have two versions of “CZ Mobile” – one for partner A and one for partner B. In this situation, you will create two separate destination group sets (“A” and “B”), as well as different destination groups inside those sets.

You can imagine each destination group set as a binder, with every page in that binder describing a certain destination group.

Destination group sets can be of two types:

• Regular destination group set (default type) – includes only the destination groups created by the administrator and destinations added to these destination groups. The administrator picks destinations from the general destination list and assigns them to one or more destination groups within the destination group set. The “regular” type is used for configuring tariffs, bundle promotions, and volume discount plans.
• Complete destination group set – comes with a Default destination group that includes all PortaBilling destinations (if a new destination is added to PortaBilling, it appears in the Default group automatically). The administrator creates the destination groups they need, picks destinations from the Default group, and moves them to one of the created destination groups. The destinations that were not picked by the administrator still belong to the Default group. Thus, a complete destination group set always includes all the destinations. The “complete” type is used for configuring fraud traffic profiles, service pools, and volume discount plans.

A complete destination group set includes all destinations available in PortaBilling: every destination belongs either to the Default group or to a destination group created by the administrator. Complete destination group sets are useful to make sure that all destinations available in PortaBilling are covered, e.g., to monitor international traffic and detect fraud calls.

Let’s consider an example when a complete destination group set is used to configure a fraud traffic profile. A service provider sells VoIP services to customers in the US and Canada and allows them to make calls to the US, Canada, and Europe. The service provider wants to prevent potential fraud traffic to other destinations. To receive alerts when “unusual” traffic is detected, the administrator configures a fraud traffic profile:

1. Creates a complete destination group set “World”, and destination groups “US&Canada” and “Europe” within this destination group set. The destinations that are usually not used are left in the “Default” destination group.
2. Creates the “Business customers” fraud traffic profile and configures service usage monitoring for the “Default” destination group. The administrator sets the expected total volume of voice traffic, to be sent by the customers to destinations other than US/Canada/Europe, to 5 minutes per hour.
3. Assigns the fraud traffic profile to the customer class.

If the total volume of traffic to destinations from “Default” destination group exceeds the 5 minutes threshold, it could be a potential fraud. In this case, the administrator receives an alert notification and takes the necessary measures to minimize potential losses.

Complete destination group sets also allow creating destination groups with subgroups (except Default group).

Complete destination group sets are used for configuring fraud traffic profiles, service pools, and volume discount plans.

A rate is a combination of billing parameters for a specific destination. For example, you can specify that calls to 420 are charged $0.09/min during peak time and $0.07/min during an off-peak time, while calls to 420609 should not be allowed at all.

To easily manage the process of routine rate changes, each rate in PortaBilling is assigned an exact time when it comes into effect (the Effective From attribute). This allows making an automated rate change in the future, so that a new rate can be entered today, but used only after midnight on January 1st. When an existing rate is edited, this does not replace the actual rate, but simply creates a new rate effective from this moment, so that the PortaBilling administrator can always browse the history of rate modifications.

Since it is important to have a clear overview of the history of rate changes, when a rate is not required anymore it cannot just be deleted from the system. For instance, you used to provide a special rate for the destination 442 London, UK, but as of March 1st, there is just one rate for all of the United Kingdom. If a customer calls with a question about his bill for February, you should still be able to see why calls to London were rated in a particular way.

Therefore, rates that are no longer used are not “deleted”, but rather marked as “discontinued”. This has the same effect on call rating as if the rate was not there anymore. However, the administrator can still see all the history on the web interface, including the date when the rate became discontinued.

A tariff is a complete set of rates for a specific account, customer, or vendor. Thus, it should include every possible destination allowed by their service plan (e.g., in the case of a telephony service, every destination to which you want to let them call).

It may be that the tariff will contain some prefixes that are part of more generic ones (for example, you will have a rate for the 420 prefix and for the 4202 prefix). In this case, the longest prefix match takes priority.

What happens if a destination is not included in the tariff, and the customer tries to call there? There are two possibilities:

• If outgoing calls are authorized via PortaBilling (for example, by a Switching Server or by the prepaid card’s IVR) the customer will not be authorized to call this destination.
• If the gateway or switch which processes the call does not perform authorization in PortaBilling before allowing the call to pass through, the customer will actually be able to make the call, but PortaBilling will not be able to bill it properly, since the required information is missing. An email alert will be sent and a special CDR will be written into the database, so you will still have an overview of this call. It is highly recommended that you always use authorization of calls via PortaBilling.

The charged amount for service usage always rounds upward in an individual xDR. For example, if we configure to round up the charged amount to two decimals, then 1.204, 1.205, and 1.206 all round up to 1.21.

You can choose the number of decimals to round up the charged amount in the Rounding precision option on the General info panel.

There is one special destination: | (pipe). When a rate for this destination is present in the tariff, it will match any dialed phone number. But this will only happen, of course, if there is no other, better match by the actual phone prefix. Such a rate should probably not be used in the customer’s tariff, since it effectively authorizes him to call any phone number in the world. It is very useful, however, in tariffs for internal purposes. For instance, we can use it in the tariff used to produce CDRs for SIP-to-SIP on-net calls, since there the cost is zero regardless of which number is actually dialed. Otherwise, that tariff would have to include all phone prefixes for all possible phone numbers assigned to IP phones.

Also, for some services or billing features, you may need to create other destinations. For example, in order to charge calls between extensions in the same PBX environment according to a pre-defined rate, you will need the destination VOICEONNETRX. Consult the reference manual for a particular feature to find out which additional destinations it may require.

Let’s move from VoIP to a simpler scenario. Imagine you are the owner of an office supply store. You have to manage your inventory and price lists for customers and resellers.

• First of all, you must create a catalog of all the items you intend to sell. This is your internal document containing entries such as “20001 – ball-point pen, blue; 20002 – ball-point pen; black; 50345 – stapler;” and so on. Note that this is just a description of the items, without prices, since the price will depend on the specific vendor/customer.
• You will receive price lists from your suppliers and convert them into data files for every vendor, such as “Office Depot: 20001 – $0.35; 20002 – $0.35; etc.” Note two things: there is no need to include an item description in every file – you can always extract this from the catalog of items you have created above. Also, each data file will contain only some of the items, i.e. those which are provided by this particular supplier.
• The next step is to create similar price lists, but with the prices you will apply to your customers. Of course, you might have several such price lists: e.g., one for retail customers, another for business customers, yet another for resellers, and so on. Every data file will contain all of the items you offer to this category of customers, including prices.

Now let’s come back to the VoIP business:

• The catalog of items corresponds to destinations in PortaBilling. Every destination is similar to an item description in the catalog, i.e. it provides general information (e.g., 420 – Czech Republic proper, 420602 – Czech Republic mobile, and so on).
• The price list (for vendor or customer) is equal to a tariff in PortaBilling. The price list includes all items the customer may purchase and all destinations the customer can make calls to. All tariffs are identical in structure, but some of them will be used to calculate your costs (vendor tariffs), while others will be used to charge your customers.
• A single line item in the price list is equivalent to a rate in PortaBilling. It gives the price per minute and other rating parameters for a specific destination.

Therefore, the standard sequence for setting up your service is as follows:

• Define the destinations you will use in your business. Basically, you will need to define every unique prefix used by your vendors (an easy way to do this is by using PortaBilling default destination set and PortaBilling templates).
• Create a tariff for every vendor using the rate list they supply.
• Create a tariff for every customer/product. Once again, note that each tariff may contain a different set of destinations. For instance, the tariff for your vendor ABC may contain different rates for 420 (0.10/min), 4202 (0.09/min) and 420602 (0.18/min). But you can just list a single rate for your customer in the tariff, i.e. 420 – 0.20/min.

As mentioned before, multiple destination group sets may be defined in the system, with some destination groups (e.g., CZ-Mobile) defined for each of them. So, when you enter a new rate for CZ-Mobile in a specific tariff, which destination group definition should be used? To avoid such ambiguities, you will assign a destination group set for every tariff, which will be used to create new rates (if you do not assign a destination group set to the tariff, then you can only enter rates for individual prefixes). Thus when you attempt to create a new rate for destination group CZ-Mobile, the following sequence of events takes place:

• PortaBilling locates the definition of the CZ-Mobile destination group in the destination group set associated with this tariff.
• For every destination included in this destination group, the new rate is inserted.

In other words, the result is the same as if you had created multiple rate entries manually. Rates that are created using a destination group do not differ in any way from rates created for a single destination. One important consequence of the foregoing is that if you change the destinations included in a destination group, it will not affect the previously created rates. Thus if you had 420602 and 420603 in the CZ-Mobile destination group, and you now add 420737, this will not affect any of the tariffs. In order to have correct billing for the 420737 prefix, you must go to the corresponding tariff and add a new rate for the CZ-Mobile prefix.