Release

Search

Appendices

Link copied to clipboard

APPENDIX A. Prepaid billing features

Link copied to clipboard

Tricky vs. honest charges

Link copied to clipboard

Should surcharges affect the time announced to the user? For example, if an account has a $10 balance, and the price per minute is 0.10 but there is a 0.20 connection fee (or 5% post-call surcharge), should the customer hear: “You have 100 minutes”? Should he be allowed call for 100 minutes, or less? PortaBilling allows calculation of two call durations during call authorization:

  • The call duration to be announced to the customer (h323-credit-time). This is a default parameter, and historically has been used to limit the maximum call duration as well.
  • The actual call duration (when the call should be disconnected – h323-ivr-in DURATION).

So the difference between the “honest” and “tricky” charge is that the former affects both values for call duration, while the latter only affects the “actual” call duration. So, in our example above ($10 balance, rate 0.10/min):

  • If the fixed charge 0.20 is honest, then the customer will hear, “You have 98 minutes,” and then be disconnected after 98 minutes.
  • If the fixed charge 0.20 is tricky, then the customer will hear, “You have 100 minutes,” but will still be disconnected after 98 minutes.
You are free to use either honest or tricky charges, depending on how your business model is set up. Please note that it is your responsibility to make a proper disclaimer to customers when using tricky charges.


In order to implement this functionality, your gateway/IVR should be able to work with two call duration values.

Random charges

Link copied to clipboard

When using the tricky charges described above, one problem is that customers may still discover that they are being charged over and above the per-minute rate by comparing the amount deducted from their account to the estimated charges. PortaBilling allows you to make this detection much more difficult, by applying special charges only randomly. As a result, special charges will apply not to all calls, but rather only to some of them, which makes it virtually impossible to “reverse-engineer” your system of charges.

In creating a rating formula, you may assign a probability to each surcharge (fixed or relative). This parameter defines the chance of this surcharge being applied, e.g., a probability of 25% percent means that there is a one in four chance of its being applied when calculating the total charged amount for a call, such that, in the final analysis, this surcharge will, on average, be applied to every fourth call. Another example is the random charges configuration shown below:

Rating sequence Figure 0-1

Figure 0‑1

Since every random charge is evaluated independently, this formula will produce the following result (an average calculated based on a large number of calls):

  • in 60% of calls, no surcharges will be applied at all
  • in 5% of calls, both the fixed surcharge and relative surcharges will be applied
  • in 15% of calls, the post-call surcharge will be applied
  • in 20% of calls, the fixed surcharge will be applied

Random disconnects

Link copied to clipboard

Since fees such as the connect or disconnect fee are applied once per call, it is obvious that you will earn more profits on many short calls than on a few long ones. Also, you may not wish to allow your customers to make too long calls, as this occupies incoming phone ports on your gateway. So your goal is to disconnect some calls so that customers will have to redial. If the disconnect occurs at a certain moment in time (e.g., the 20th minute of a conversation), it will be very easy for the end user to notice. Therefore, the disconnect should be made to appear as if it had happened naturally, that is, randomly.

The random disconnect element in the PortaBilling rating formula allows you to specify a certain probability according to which calls will be disconnected at a random moment of time during a certain period (for instance, between the 10th and 20th minute). The interval during which the disconnect should occur is called dispersion.

Let’s take a look at the example below:

Rating sequence Figure 0-2

Figure 0‑2

There are two call disconnect elements. The first one specifies, with a probability of 20%, that the call should be disconnected within 5 minutes (300 seconds) after this element is entered into the formula, i.e., the disconnect will happen sometime between the 10th and 15th minute of the call. The second element specifies that the call will always be disconnected (100% probability) 15 minutes (900 seconds) before this element is entered into the rating formula (i.e., the dispersion parameter is negative); so the disconnect will occur sometime between the 25th and 40th minute of the call. Thus, when this formula is applied in the actual tariff, the result will be that there are no calls longer than 40 minutes, i.e., every call will be cut off at some random instant between the 25th and 40th minute, while some calls will even be disconnected earlier (between the 10th and 15th minute).

Call duration

Link copied to clipboard

This feature is similar to the “relative surcharge” discussed earlier, but works in a different way. The main disadvantage of post-call surcharges is that the time charged does not correspond to the officially-quoted price per minute.

For instance, if you are using 30-second rounding, a 0.10/min rate and a 10% post-call surcharge, and the customer makes a call for 4 minutes and 52 seconds, he will be charged 10*(30/60)*0.10 + 10% = 0.55. However, on the CDR this will be represented as “charged time: 5:00 minutes, charged amount: 0.55” - which might lead to a dispute, since you have quoted the customer a rate of 0.10/min.

The add duration feature allows you to increase the call duration before any other charges are applied, so it will look as if the call was actually made for the longer duration. Thus, taking the example above, what will happen if we replace the relative surcharge with an add duration of 10%? First of all, the call duration will increase by 10%, becoming 5:21. Then this call will be rated using 30-second intervals, i.e., it will be rated 11*(30/60)*0.10 = 0.55, and the CDR will read: “charged time: 5:30 minutes, charged amount: 0.55” - therefore it will be perfectly in line with your quoted rates.

A flexible add duration ratio is possible, since calls can be split into any number of segments and the duration of each segment increased according to a different ratio. For instance, the first 5 minutes could be “stretched” by 20%, the following 5 minutes increased by 10%, and the next 10 minutes increased by 5%, with the remaining call duration unchanged. This allows you to avoid the problem of a 20% increase applied to the entire duration of a long call, which is easily noticeable.

Call duration

This produces the following results:

  • A call 4 minutes in duration will be charged as 4:00 + 4:00*20% = 4:48
  • A call 6 minutes in duration will be charged as 6:00 + 5:00*20% + 1:00*10% = 6:00 + 1:00 + 0:06 = 7:06
  • A call 12 minutes in duration will be charged as 12:00 + 5:00*20% + 5:00*10% + 2:00*5% = 12:00 + 1:00 + 0:30 + 0:06 = 13:36
  • A call 30 minutes in duration will be charged as 30:00 + 5:00*20% + 5:00*10% + 10:00*5% = 30:00 + 1:00 + 0:30 + 0:30 = 32:00
  • A call 45 minutes in duration will be charged as 45:00 + 5:00*20% + 5:00*10% + 10:00*5% = 45:00 + 1:00 + 0:30 + 0:30 = 47:00

As you can see, the increase mainly affects short calls (or the initial portion of long calls), but does not increase drastically with the total call duration.

Using “billing tricks”

Link copied to clipboard
Please note that you are responsible for finding out which call rating features are allowed in your business and providing your customers with the required disclaimer.

APPENDIX B. PortaOne calling card application special features

Link copied to clipboard

Here is a list of features not available in Cisco’s standard calling card application (app_debitcard.2.0.2.8 a.tcl), including information on how they can be configured in the PortaOne IVR.

Credit account support

Link copied to clipboard

PortaOne’s IVR application can work with both debit and credit accounts. For credit accounts, the amount of available funds, computed by PortaBilling as (credit_limit – balance), is played. So for an account with a credit limit of $100 and a balance of $75, the amount of available funds is $25. If both an account and a customer have been assigned a credit limit, then the available funds for the account and customer will be computed according to this same formula, with the smaller amount returned to the IVR.

ANI authentication

Link copied to clipboard

PortaOne’s IVR application can perform authentication using the ANI number of an incoming call leg. If authentication is successful, the IVR does not ask for a PIN, and starts with the balance announcement.

Configuration syntax:

call application voice <app-name> ani-authentication <yes|no>

Example:

call application voice porta ani-authentication yes

Normally, if ANI authentication fails the IVR will prompt the user to enter a PIN number. However, this may be disabled so that the script is then used to provide ANI-only service.

Configuration syntax:

call application voice <app-name> card-authentication <yes|no>

Example:

call application voice porta card-authentication no

Number translation and abbreviated dialing expansion

Link copied to clipboard

As a part of the authorization process, the IVR application receives a translated destination number from PortaBilling and then initiates an outgoing call to this number (instead of the one originally dialed by the customer). This permits the following:

  • Applying various number translation schemes on the billing side, e.g., the same access number and the same IVR application can be used for customers with different dialing habits. Customer A may dial the phone number as 0114202123456, while customer B dials it as 004202123456. PortaBilling will apply the respective customer’s translation rules and return the normalized number 4202123456. This significantly simplifies configuration of outgoing dial-peers on your Cisco gateway, since outgoing calls are always in the same format.
  • Translating short dialed numbers (e.g., 101) into complete phone numbers according to a list of dialing abbreviations defined for the customer.

Multi-currency support

Link copied to clipboard

The default Cisco application will always play only one currency, e.g., that is associated with the specific language. You can change the TTS module configuration so that “dollars” will be played for English and “crowns” for Czech, but you cannot allow customers with balances in dollars and pounds to access the same gateway and work with the English IVR, as some of them are bound to hear the wrong currency name.

PortaOne’s IVR application, in tandem with PortaOne TTS modules, can dynamically switch the currency announced based on the currency code (h323-currency) for a particular account supplied by the billing. This allows you to use the same access number for products in different currencies.

Configuration syntax:

call application voice <app-name> multi-currency <yes|no>

(the default setting is no)

Example:

call application voice porta multi-currency yes

Balance announcement suppression

Link copied to clipboard

This allows you to disable announcement of an account’s current balance, and instead proceed to prompt for the destination number.

Configuration syntax:

call application voice <app-name> balance-suppression <yes|no>

Example:

call application voice porta balance-suppression yes

Time announcement suppression

Link copied to clipboard

This allows you to disable announcement of the maximum allowed call duration, and instead just start connecting the call.

Configuration syntax:

call application voice <app-name> time-suppression <yes|no>

Example:

call application voice porta time-suppression yes

Last number redial

Link copied to clipboard

The customer may redial the last number by simply pressing the star key (*) when beginning to enter the destination number.

Once you have already entered some digits of the destination number, the star key may be used to reset the current entry and start entering the phone number from the beginning.

Configuration syntax:

call application voice <app-name> redial-enable <yes|no>

Example:

call application voice porta redial-enable yes

Disallow calls when balance is too low

Link copied to clipboard

If an account’s current balance is lower than the service availability threshold specified in the product configuration, the IVR may disable outgoing calls. There are two ways to block outgoing calls:

  • Play an announcement and disconnect the incoming call leg.
  • Allow the user to dial the destination number, but do not actually initiate the outgoing call, giving just a fast busy signal instead.

Configuration syntax:

call application voice <app-name> check-low-balance <disconnect|nocalls|no>

Example:

call application voice porta check-low-balance nocalls

APPENDIX C. Cisco gateway configuration guidelines

Link copied to clipboard

Obtain the debitcard script

Link copied to clipboard

The default Cisco debitcard application is provided free of charge to all users who have a valid Cisco support contract (CCO). Obtain the latest version of the script (2.0.2.8a). Please note that this script does not support any billing tricks, such as:

  • Announced and real call duration
  • Different rates based on the access number
  • Special rates for the account’s first call

PortaOne’s “Prepaid Card Calling” script with prompts is distributed free of charge and can be found in the following folder:

/home/porta-ivr/tcl/prepaid_card_calling

Basic router configuration

Link copied to clipboard

The latest telephony IOS and DSP firmware is highly recommended. Some of the features (e.g., ability to assign routing plans to prepaid card customers) will only function in IOS 12.4 or later. It is also recommended that the hostname be the same as h323-id.

hostname <h323_id>
ip domain name <default domain>
VSA h323-gw-id=“hostname.domain”

NTP

Link copied to clipboard
It is very important to have reliable time services. Also make sure that the time zone abbreviation is one of the standard ones supported by PortaBilling.
ntp server <name/IP>
…….
ntp server <name/IP>
ntp master 5
clock timezone <your time zone> 1
clock summer-time <your summer time zone> recurring <your rules>

AAA

Link copied to clipboard
aaa new-model
aaa authentication login h323 group radius
aaa authorization exec h323 group radius
aaa accounting connection h323 stop-only group radius

VoIP interface

Link copied to clipboard
interface <your interface to the world>
h323-gateway voip interface
h323-gateway voip h323-id <h323_id>
If you want to use a virtual interface then add the line:
h323-gateway voip bind srcaddr <IP>

Outgoing SIP server

Link copied to clipboard
sip-ua
 aaa username proxy-auth
 sip-server dns:<hostname-of-your-PortaSIP-server>

Enable gateway functionality

Link copied to clipboard
gateway

Enable gateway accounting

Link copied to clipboard

For older IOS versions:

gw-accounting h323 vsa 

For newer IOS versions (12.2T or 12.3):

gw-accounting aaa
  acct-template callhistory-detail
VSA does not work for all platforms.

Radius

Link copied to clipboard
Ports 1645 / 1646 are the traditional Radius ports used by many vendors without obtaining an official IANA assignment. The official assignment is now ports 1812 / 1813, and users are encouraged to migrate to these new ports when possible.

Cisco notes:

  • “radius-server” commands will be available only after issuing “aaa new-model” command
  • UDP port for RADIUS accounting server - default is 1646 (see note above)
  • UDP port for RADIUS authentication server - default is 1645 (see note above)

Keep in mind:

  • Default ports for Cisco are 1645/1646
  • Defaults in /etc/ services are 1812/1813
radius-server host <name/IP>
auth-port 1812 acct-port 1813

radius-server key <key>

radius-server vsa send
accounting

radius-server vsa send
authentication

voice-card

Link copied to clipboard

controller

Link copied to clipboard

voice-port

Link copied to clipboard

Depends on your hardware configuration.

call application voice & dial-peers

Link copied to clipboard
call application voice russian http://…../app_porta_debitcard.tcl
call application voice russian pin-len 0
call application voice russian language 1 en
call application voice russian language 2 ru
call application voice russian set-location ru 0 http://…./tcl/prompts/ru/
call application voice russian set-location en 0 http://…./tcl/prompts/en/
call application voice czech http://…../app_porta_debitcard.tcl
call application voice czech pin-len 0
call application voice czech language 1 en
call application voice czech language 2 cz
call application voice czech set-location cz 0 http://……/tcl/prompts/cz/
call application voice czech set-location en 0 http://……/tcl/prompts/en/
!
dial-peer voice 201 pots
 application czech
 incoming called-number 201
 port 0:D
!
dial-peer voice 202 pots
 application russian
 incoming called-number 202
 port 0:D
!
dial-peer voice 60 voip
 destination-pattern .T
 session protocol sipv2
 session target sip-server
!

APPENDIX D. Quintum configuration guidelines

Link copied to clipboard

To configure RADIUS on the Quintum Tenor (first generation), execute the following commands:

# config
config# radius

To set the authentication port:

config radius# authenticationport p 1812

To set the accounting port:

config radius# accountingport p 1813

To set the IP address (replace the IP address with that of the PB-100 master server):

config radius# host p 192.168.100.211

You must set accounting type to 2 (one accounting record per call leg):

config radius# accountingtype 2

For more information on these commands, please refer to Section IV: Command Line Reference in the Tenor user manual.

To configure RADIUS on the Quintum CMS gateway, execute the following commands in admin mode:

# config
config# ri 1

To set the authentication port:

config-RadiusInfo-1# set pap 1812

To set the accounting port:

config-RadiusInfo-1# set pacp 1813

To set the IP address (replace the IP address with that of the PB-100 master server):

config-RadiusInfo-1# set psipa 192.168.100.211

Set accounting type to 2 (one accounting record per call leg):

config-RadiusInfo-1# set at 2
Do not configure a RADIUS routing server unless you have one, or else the RADIUS records will not be delivered to PortaBilling.

For more information on these commands, please refer to the Tenor CMS Command Line Interface reference guide.

To configure RADIUS on the new generation of Quintum gateways (AX/DX series), execute the following commands in admin mode:

# Ethernet:
EthernetInterface
set IPAddress {IP}
set SubnetMask {NetMask}
StaticIPRouteDir
add 0.0.0.0 NetMask 0.0.0.0 Gateway {RouterIP}
#TimeServer:
TimeServer
set UTCOffset {Hours}
set PrimaryServerIPAddr 192.43.244.18
set SecondaryServerIPAddr 131.188.3.222
#Radius:
RadiusInfo UserServer
set PrimaryServerIPAddr {RadiusIP}
set SharedSecret {SecretKey}
set AccountingType 2
#Unit:
SIte
set Country 1
GateWay
set OutgoingIPRouting 1
DialPlan
set LongDistancePrefix
set CarrierPrefixPattern
set INTernationaLPrefix[1]
set MAXDNlength 20
set MINDNlength 10
SLot SL2
set Online[1] 1
PUBlicNumberingPlan
set CountryCode
set AreaCode
HuntLDNDirectory pub1
add {AccountID}

APPENDIX E. Authorizing and billing customers by the originating phone number (ANI-based billing)

Link copied to clipboard

PortaBilling gives you great flexibility in choosing how you would like to authorize and bill your customers. For ANI-based billing, you only need to do the following:

  1. Create a tariff (or tariffs) and a product.
    If you are providing both prepaid cards and ANI-based billing, take measures to prevent fraud (e.g., someone could dial your IVR and enter their neighbor’s home phone number as the PIN). See the APPENDIX F. Preventing an ANI Number from Being Used as a PIN topic below.
  2. Use the corresponding application on your gateway to handle the call. You can use one of the default Cisco applications (clid_*), create your own, or use PortaOne’s “Advanced Remote Authenticate” script. The only important thing is that ANI (CLI) must be in the User-Name attribute in the AAA requests which go to the billing.
None of the default Cisco applications support call authorization, so the gateway will not consult billing as to whether the customer is allowed to call this particular destination and what is the maximum allowed call duration.

Needless to say, this may lead to abuse of your service; moreover, there are several other drawbacks to the default Cisco applications. In order to avoid all these problems, it is recommended that you use PortaOne’s “Advanced Remote Authenticate” script, or (if you need advanced IVR capabilities such as “announce available balance or number of minutes”) modify the debit card application.

Here is a sample:

aaa new-model
aaa authentication login h323 group radius
aaa authorization exec h323 group radius 
aaa accounting connection h323 stop-only group radius
!
gw-accounting h323 vsa   
!
call application voice ani http://…/portaone.tcl
call application voice ani authenticate-by ani
call application voice ani skip-password yes
call application voice ani authorize yes
!
dial-peer voice 1 pots
 application ani
 incoming called-number .
 port 1:D
!
gateway
!
  1. Create a customer who will own these accounts.
  2. Create accounts with an Account ID identical to the phone number from which the service is to be used.

tips TIP: Check in which format ANI (CLI) numbers are reported by your gateway. For example, the phone number 42021234567 might be reported as “21234567,” “021234567,” or something different. You must use exactly the same format for the Account ID (or change your application so as to convert it to the desired format). Only one extra item is required in the application configuration for PortaOne’s “Advanced Remote Authenticate” – the translate parameter. The following example assumes that phone numbers arrive in the local format, prefixed by 0, e.g., 021234567 instead of 42021234567:

call application voice ani translate "/^0/420/"

APPENDIX F. Preventing an ANI number from being used as a PIN

Link copied to clipboard

The first method is the easiest one: use different gateways or access numbers for PIN-based and ANI services, and configure product rating list accordingly. Thus even if a “hacker” calls your access number 12345 for prepaid cards and attempts to enter his neighbor’s phone number as a PIN, the call will not be authorized, since, although such an account exists, its product only allows usage with the access number 12346.

However, you might need to create an advanced service in which a single access number can be used for both ANI and PIN-based services. When the customer calls in, the system checks his ANI and, if the ANI is OK, it asks for a destination number. Otherwise, it gives the option of entering either a PIN or a phone number + password. In this case, you must prevent account misuse in a different way:

  • ANI accounts should always be created with a non-empty Service password. Prepaid cards should be created with an empty Service password.
  • PortaOne’s “Prepaid Card Calling” script supports this feature by default. A third-party script may require additional modification, so that when the first authentication by ANI is done, the billing will receive User-Name=ANI and a special flag “skip password.” Thus, authentication will be successful if such an account exists, otherwise it will fail and the user will be prompted for a PIN. To activate the “skip password” feature in PortaOne’s “Advanced Remote Authenticate” script, simply include the skip-password yes configuration parameter for this application.
  • When a user enters a PIN, the PIN is provided in the User-Name, and the Password attribute is empty. The system checks for such an account, and since the password is empty for prepaid card VoIP, authentication is successful. If somebody tries to enter an ANI number as the PIN, authentication will fail because the password supplied does not match the one assigned to the account.
  • If given the option “enter your registered phone number”, the user will then enter both his phone number and password (the latter is required to prevent unauthorized usage of his account), and both will be supplied to the billing. Authentication will be successful only if a correct account ID and password are provided.

On this page

Release
What's new
Admin manuals
Handbooks
API
UI help
Search