User Guide

This chapter aims to help using the software. We will try to describe interactions between entities and the different features available through the web interface.

Entities interaction in the callingcard platform

The graph above illustrates how the main entities interact together.

  • Call is initiated on the Asterisk PBX platform
  • Authentication is perform through various ways : Cardnumber, CallerID, SIP/IAX Friends with Accountcode
  • The 3D cube's purpose is to make this graph a little bit more appealing.
  • Cards have different properties but the main is the tariffgroup to which it is linked. The TariffGroup? will determine how the billing will be processed.
  • TariffGroup? can have 1 or more ratecards. Ratecards contain all the information about one or more destinations (and the rates to those destinations) to which you would like to provide a termination.
  • The main rule for the TariffGroup? is how it will decide which rates to use if there are multiple rates to a destination (they will each need to be on seperate ratecards). LCR/LCD properties can be defined and then the rate engine will be able to determine which termination would be the most appropriate.

Create customer/card

Cards are the main element of the Calling Card software, and may contain all the info about the customers (name, email, phone, ..) Simply put a card is a customer in your system.

Card properties

Let's try to make an non-exhaustive list of the card properties.

  • cardnumber : this is the pin number of the card 😀
  • cardalias : this is an alias of the card, it should be a number and this will be use by the user to connect as username into the customer web interface. It will be also use to call sip/iax friends. (This is similar to a account number)
  • webui pass : password of the user to connect on the customer web UI.
  • credit : this is the amount of money left on this card. it can be negative in PostPay? use.
  • language : the preferred language of the card holder
  • tariffgroup : TariffGroup? to apply on this card
  • activated : determine if this card is active or not.
  • simultaneous access : Define if more that one call can be accept at the same time on this card
  • currency: the currency that will use to pay the balance and provide billing information to the customers
  • runservice : set if the recurring service should apply to this card
  • card type : define the billing method (Prepaid or Postpaid) to apply to this card.
  • credit limit : when postpaid method is selected. A credit limit needs to be specified.
  • first use date : Date when the first call has been make on this card
  • enable expire : Define how you want to enable the expiration of the card (date, amount of days since first use, amount of days since creation).
  • expiration date: Define the date for the expiration, it works only if "enable expire" is set to "date expire"
  • expiration days : Define the numbers of days for the expiration if if "enable expire" is set to "amount of days since first use" or "amount of days since creation"
  • the following is information about the card holder : last name, first name, email, adresse, city, state/province, country, zip/postal code, phonenumber, faxnumber
  • inuse : when a caller is calling on a card, the system sets an increment flag to know that this card is currently being used. If the system stops abnormally, it can happen that some customers won't be able to use their cardnumber again. In that case, reset the flag to 0.
  • callerid : this option specifies the CallerID list attached to this card, several callerId's can be specified.

CallerID Authentication

The CallerID Authentication is well-know in the callingcard business. This allow to a third party to use your service without having to authenticate each time.

Most of common integration would follow the next schema :

  • link one or more callerID's to the Card
  • enable the callerId authentication in the AGI application. edit the a2billing.conf, "cid_enable=YES"
  • if the callerID is not recognized by the system, we can still proceed to the cardnumber authentication but for this we need to set the appropriate option : "cid_askpincode_ifnot_callerid=YES" (see a2billing.conf)

we also have the possibility of creating a card each time a new callerID is found. if you want to activate this we would advise you to look at the following options in a2billing.conf : cid_auto_create_card ; cid_auto_create_card_typepaid ; cid_auto_create_card_credit ; cid_auto_create_card_credit_limit ; cid_auto_create_card_tariffgroup


Billing Engine



Trunk and Provider

The most basic entity is the trunk. If you are familiar with Asterisk, it is the string that you give in the Dial application. it can be IAX2, SIP, ZAP, or any other, according to the dial application format in Asterisk. if you arent familiar with Asterisk you are probably lost here.

For ease of use, a trunk can be associated with a provider, Or as Areski would say: "A provider is the company/person that provides you the termination. Providers will be used to classify the trunk and to help with reporting. "

NOTE:When defining your trunk configuration, you can take asterisk trunk configuration. You have to insert the same name you use to define the trunk in asterisk. If you are defining a SIP trunk and the carrier needs authentication, remember to add the following configuration in sip.conf (or where you have defined the trunk, maybe sip_additional.conf if you are using AMP/FreePBX):

username=123456 ;Username to authenticate against your SIP provider type=peer secret=111111 ;Password to authenticate against your SIP provider ;IP/FQDN of your SIP provider fromuser=123456 ;Again, your username ;Provider's domain (or whatever it requires) authuser=123456 ;Once again, your username


as you can see from the HIGHLY interactive diagram above, rate is the next most basic entity in the billing engine. primarily, with every trunk theres a rate associated. You can also specify the buying rate, i.e. : "your purchase cost that you need to pay to your voip-provider to let your platform call this destination..." Then we have a selling rate, which is how to bill the user. Progressive rate aims to bill the customer at various rates according the duration of the call. For instance you can define that you can to bill the customer 0.33dollars for the first 2 minutes and then you want to bill him 0.45dollars for the rest of the call.

Now you also have to assign it to a ratecard and a dial prefix.


A ratecard is set of rates (rates are defined according to a dialing prefix, for instance 44 : UK). For each ratecard you will be able to create as many rates you want. A ratecard can have a "starting date" and an "expiration date", you can also define a trunk by default and if no trunk is defined for a trunk, the ratecard default trunk will be used[[BR]]


Tariffgroup is a set of ratecards hooked up together. The calling card system will choose the appropriate rates according to the Tariffgroup settings (LCR or LCD).

LCR : Least Cost Routing - search the best termination with the cheaper cost for you (buying rate)

LCD : Least Cost Dialing - search the best termination with the cheaper cost for end-user (selling rate)

Import Ratecard

This module will allow you to import ratecard from a csv file ! You will have to define the ratecard name, the trunk to use and the different fields that you want to specify from your csv files. Finally select the csv files and click on the "Import Ratecard" button.

SIP/IAX Friends

With this callingcard platform we can also define Asterisk user (SIP/IAX Friends), in other words we can pre-configure a SIP client, an ATA phone or even a gateways.

We will not go in details with all the parameters that define a SIP/IAX friends, we will refer a well-documented pages of the WIKI :

  • SIP configuration :
  • IAX configuration :

As you probably discover, when you browse the card you have 2 particulars button at your disposal : SIP & IAX. When you click on one of them, you will see that an instance in SIP/IAX Friends has been created and 2 red buttons will appears asking you to generate the configuration files. If your system as been well configured you should have an include of the a2billing sip/iax files into your sip/iax.conf files, this will allow us to generate after each changes the specific a2billing sip/iax files and reload asterisk at your convenience to add/update or remove some Asterisk friend/user.

Standard process should be:

  1. Create Card
  2. Create a SIP/IAX Friend
  3. Adapte SIP/IAX configuration according to your user
  4. Reload Asterisk (it can be perform from the web interface)
  5. Provide information to your user
  6. Make card recharge & notify payment
  7. Reporting tools
  8. Cdr report
  9. Calls compare
  10. Monthly traffic
  11. Daily load
  12. Invoice
  13. Edit/Add administrator (& define ACL)

Here you define the different roles for different administrators. There is an ACL admin which has limited access to the buttons on the right. for example, i will create an admin incharge of creating trunks, another for setting rates on that trunk and so on and not all administrators need all of the options so might as well restrict them from poking around.

The permissions can be granted for:

  • Customers
  • Billing
  • Ratecard
  • Trunk
  • Call report
  • Cront service (oh i have to document this one too)
  • Administrator
  • File manager
  • Signup
  • DID

Then there is a daddy administrator, which has all the options, and can create acl administrators. If you know something about administrators you will get an idea and that is enough. If you dont know anything about administrators then... pity. Customer web interface