CommuniGate Pro
Version 5.2
Miscellaneous
 
 
Billing

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

Interfaces

The CommuniGate Pro Billing subsystem is available for:

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 non-negative number: the amount to reserve.
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 reseve an amount larger than the current Balance value are rejected.
Results:
reserve
a string: the reservation name (the same as the reserve parameter, if it was specified).
amount
a number: the current reservation value.
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 current Balance value.
charge
This operation substracts 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.
reference, description
same as for the credit operation.
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).
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.
CommuniGate® Pro Guide. Copyright © 1998-2009, Stalker Software, Inc.