| Version 5.4
Introduction
Installation
SysAdmin
Network
Objects
Storage
E-mail
Real-Time
Access
Services
Directory
Clusters
Applications
Miscellaneous
Licensing
WebMail
Pronto!
PBX
E-Mail | Billing
# Billing Reservations Interfaces Operations 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 not 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 together 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

CommuniGate® Pro Guide. Copyright © 1998-2012, Stalker Software, Inc.