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.
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.
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
|
