Billing

The CommuniGate Pro Server can act as a Billing platform.

Each Account can have one or several Balances. CommuniGate Pro modules and components can post charges and credits to these balances, make refunds, etc.

The current amount is maintained for each Balance, along with active reservations.

The log of all transactions is kept in the Account data files. The Log format provides for easy backup and restore operations, and for Balance recovery after hardware failures.

The "default" or "generic" Balance uses an empty string as its name.

Monetary values (funds) are presented as 64-bit signed integer values.

Reservations

The Balance reservations are used when some billed activity takes time and/or a billing activity takes place in several steps.

The application first "reserves" a certain monetary amount, sufficient to pay for some initial stage of the billed activity. For example, it can be an amount needed to pay for the first minute of a call, or to play the first level of a game.
If the selected Balance does not have sufficient funds, the reservation request is rejected.
Otherwise, a reservation (with an application-supplied or server-generated name) is created inside the Balance. The total funds available in the Balance are decreased by the reserved amount, but not charge record is created in the transaction log.

As the payment amount of the billed activity approaches the reserved amount, the application "extends" the created reservation by some additional amount. If the Balance does have enough "free funds" (i.e. funds not reserved with other reservations), the reservation amount is extended.

The application can release the created reservation. The reservation is removed from the Balance, and the reserved amount is returned to the Balance "free funds". For example, this function can be used when a phone call was not connected, as the reserved funds must be released without recording any charge transaction.

Finally, the application charges the Balance, specifying the reservation. The charge amount should not exceed the amount reserved.
The transaction log record is created, and the charged amount is subtracted from the Balance and from the reservation reserved amount. Optionally, the reservation can be released, and the remaining funds returned to the Balance "free funds".

When a reservation is created or extended, the application can specify the reservation expiration time. The reservation is released automatically after the specified time. This feature can be used if the application can disconnect or quit without explicitly releasing its reservations.
When creating or extending a reservation, the application can specify the amount that should be charged if the reservation is timed-out and it is released automatically. For example, when a game application extends the reservation to cover the next game level, it can specify the amount that should be already be paid for the current game. If the application quits or disconnects without explicitly charging the Balance reservation, the reservation will be released automatically, but the specified amount will be changed first.

Interfaces

The CommuniGate Pro Billing subsystem is available for:

CG/PL server-side applications (PBX Tasks, WebUser applets, etc.)
XIMSS client applications.
ParlayX client applications.
CLI client applications.

Operations

The following Billing operations are available:

list
This operation lists all Balances available for this Account.
- Parameters:
  none
- Results:
  - balance
    an array of available Balance names.
credit
This operation adds funds to a Balance.
- Parameters:
  - balance
    a string: the Balance name. If the Balance with this name does not exist, it is created.
  - amount
    a non-negative number: the credited amount.
  - reference
    a string: arbitrary data used for references, dispute resolutions, etc.
  - description
    an object (usually a string or an array of strings): arbitrary data describing the transaction.
- Results:
  - amount
    a number: the current Balance value.
remove
This operation removes a Balance.
Note
The Balance history is not removed. If the current Balance value is not zero, a record is added to the Balance history, changing the Balance value to zero.
- Parameters:
  - balance
    a string: the Balance name. The Balance with this name is removed.
- Results:
  - amount
    a number: the removed Balance value.
reserve
This operation reserves funds from a Balance. The reserved amount cannot be used for other charges. The reservation can be released explicitly, returning funds to the Balance, or it can expire after the specified period of time.
- Parameters:
  - balance
    a string: the Balance name. This Balance must already exist.
  - amount
    a number: the amount to reserve. If the reservation already exists, this value is used to increase the reserved amount.
  - reserve
    a string, optional: if this parameter exists, it should specify the existing reservation. The amount will be added to this reserve. If this parameter is absent, a new reservation is created.
  - expires
    a timestamp, optional: if this parameter exists, it specifies when this reservation should expire.
  - overdraft
    optional: if this parameter exists, it is possible to reserve an amount larger than the current Balance value. If this parameter does not exist, attempts to reserve an amount larger than the current Balance value are rejected.
  - charge
    a number: the amount to charge if this reservation expires and it is automatically released.
  - reference, description
    these strings can be specified if the charge parameter is specified. They have the same meaning as the credit operation parameters, and they are used if this reservation is automatically charged when it expires.
- Results:
  - reserve
    a string: the reservation name (the same as the reserve parameter, if it was specified).
  - amount
    a number: the current reservation value.
  - total
    a number: the current Balance "free funds".
release
This operation releases a reservation. The reserved amount is returned to the Balance.
- Parameters:
  - balance
    a string: the Balance name. This Balance must already exist.
  - reserve
    a string: the existing reservation name.
- Results:
  - reserve
    a string: the reservation name (the same as the reserve parameter, if it was specified).
  - amount
    a number: the released reservation value.
  - total
    a number: the current Balance "free funds".
charge
This operation subtracts funds from a Balance or a reservation.
- Parameters:
  - balance
    a string: the Balance name. This Balance must already exist.
  - amount
    a number: the amount to charge.
  - reserve
    a string, optional: if this parameter exists, the charge is applied to the already existing reservation. If this parameter is absent, the charge is applied to the Balance itself.
  - overdraft
    optional, cannot be specified together with the reserve parameter: if this parameter exists, it is possible to charge an amount larger than the current Balance value. If this parameter does not exist, attempts to charge an amount larger than the current Balance value are rejected.
  - release
    optional, cannot be specified without the reserve parameter: if this parameter exists, the reservation is released after the charge is made.
  - reference, description
    same as for the credit operation.
- Results:
  - amount
    a number: the current Balance "free funds" or reservation value.
  - total
    a number: the current Balance "free funds" (only if the reserve parameter is specified).
  - expires
    a timestamp: the reservation expiration time (only if the reserve parameter is specified and the reservation has an expiration time set).
read
This operation reads the current Balance or reservation value.
- Parameters:
  - balance
    a string: the Balance name. This Balance must already exist.
  - reserve
    a string, optional: if this parameter exists, it must specify an existing reservation. The operation reads that reservation value. If this parameter is absent, the operation reads the Balance value.
- Results:
  - amount
    a number: the current Balance or reservation value.
  - expires
    a timestamp: the reservation expiration time (only if the reserve parameter is specified and the reservation has an expiration time set).
history
This operation reads the Balance transaction log.
- Parameters:
  - balance
    a string: the Balance name. This Balance must already exist.
  - timeFrom,timeTill
    timestamps: Balance records from recorded on or after timeFrom but before timeTill (exclusive) are read.
  - limit
    a number: the maximum number of records to display.
    If this number is positive, the newest records are returned first, and the oldest records are discarded if the record number limit is reached.
    If this number is negative, the oldest records are returned first, and the newest records are discarded if the record number limit is reached.
- Results:
  - history
    an array of transaction records. Each record contains the following elements:
    - Date
      a timestamp: the time of transaction.
    - amount
      a number: the transaction amount (positive for credit operations).
    - balance
      a number: the Balance value after this transaction.
    - reference, description
      copies of the credit and charge operation parameters.
calllog
This operation reads the Call Log files.
- Parameters:
  - timeFrom,timeTill
    timestamps: records for calls that took place on or after timeFrom but before timeTill (exclusive) are read.
  - limit
    a number: the maximum number of records to display.
    If this number is positive, the newest records are returned first, and the oldest records are discarded if the record number limit is reached.
    If this number is negative, the oldest records are returned first, and the newest records are discarded if the record number limit is reached.
  - filter
    optional string: if specified, the operation returns only the calls with peers whose addresses or "real names" match the specified string.
- Results:
  - callHistory
    an array of transaction records. Each record contains the following elements:
    - Date
      a timestamp: call start time (GMT).
    - direction
      the "inp" string for incoming calls, the "out" string for outgoing calls.
    - To
      the peer address string.
    - RealName
      (optional) the real name of the peer.
    - Call-ID
      the call Call-ID string.
    - disconnected
      a timestamp: call end time (GMT).
    - connected
      a timestamp: call connected time (GMT). If absent, the call has not been connected.
    - dialogError
      (optional) call completion/failure error code string.
    - dialogApp
      (optional) if a call has been answered by a PBX application, the application program name string.
  - amount
    the total number of found call records

Billing ​

Reservations ​

Interfaces ​

Operations ​

Billing

Reservations

Interfaces

Operations