DESCRIPTION ----------- SIP prepaid functionality is achieved by: 1. An external call control module (not provided by CDRTool) that maintains call status and terminates calls by sending BYEs to both SIP end-points. The call control module communicates with both the SIP Proxy and CDRTool using an API described below. 2. CDRTool rating engine - provides session locking, calculates maximum session time based on user balance and destination using the same algorithm as the postpaid engine and debits the subscriber balance. See doc/PrepaidEngine.pdf for a detailed call flow. Prepaid API ----------- CDRTool prepaid engine is used to compute session times based on user credit and destination rates and debit the balance when the call has ended. The prepaid engine is accessible over a TCP socket. Call control module sends commands based on the syntax described below, to the CDRTool prepaid engine that handles the prepaid accounts. A command is a line of text containing a keyword, which is the command itself followed by a number of parameters separated by space. The command ends with an enter in unix style: '\n' For each such request there will be a reply on one or more lines, containing information that depends on the command that was sent. A reply ends when a double end of line (\n) is received: \n\n (this is needed because there are commands that require multiline responses). How the information contained in a reply is to be interpreted depends on the command itself and is described below. 1. Asking for the call time limit ------------------------------ To request the maximum time for a session, the following request must be sent to CDRTool rating engine on one line: MaxSessionTime From=sip:123@example.com To=sip:0031650222@example.com Duration=7200 Gateway=81.20.68.10 ENUMtl=tld.com Lock=1\n Duration is a limit imposed to the time allowed, in case you want to limit the call time to a maximum duration. This will be a top limit for the call's time, even if the user could talk more than that based on his current balance. The SIP proxy may limit all calls to 7200 seconds for example. Lock specifies if the account is to be locked or not (i.e. don't allow the same user make multiple calls at the same time). This is used because sometimes we only need to peek at the time but not actually start a call and lock the user. When the call starts the account should always be locked. To may actually be sip:number@domain;param=value so you must extract the username part which is the number From is a sip URI which can be "full name" ENUMtld parameter is optional but if present discounts based on ENUM can be applied (see RATING.txt for more information on ENUM discounts). Call control expects a reply like below: value\n\n value is the numeric time in seconds, or one of the keywords Locked or None (None meaning it's not a prepaid account and it doesn't have any limitation, or it's a free destination, like a 0800... number). There is no empty line before value (response starts with value on the first line and then it has 2 enters unix style as described). To field must be the canonical destination SIP URI after all possible lookups in the SIP Proxy. 2. Debiting the balance when the conversation ends ----------------------------------------------- To debit money from the user account when the conversation ends, the Call control module must send the following command on one line: DebitBalance From=sip:123@example.com To=sip:0031650222@example.com Gateway=81.20.68.10 Duration=59\n Same notes about the From and To fields as above apply. and expects in return: value\n\n where value is one of: OK (success), Failed (failure), NotPrepaid (account is not prepaid - this case is not considered a failure) There are cases where we call DebitBalance with a 0 duration. This is valid and should unlock the account but leave the credit untouched. Prepaid calls in progress ------------------------- To see the calls in progress go to Rating -> Prepaid -> Search with Lock = 1 If the connection between the SIP Proxy call control module and CDRTool rating engine is broken it is possible to have prepaid accounts that remained locked because no DebitBalance command has been received. To unlock these accounts find them in Rating -> Prepaid section and set Lock to 0. Third party tools ----------------- FreeRADIUS-CDRTool by Dan-Cristian Bogos FreeRADIUS module providing connectivity to CDRTool prepaid engine. Provides prepaid authentication for calls proxied by OpenSER and returns to OpenSER MaxCallDuration and user Credit. Can be easily extended to support other SIP or H323 devices. http://sourceforge.net/projects/frad-cdrtool Notes ----- The balance is debited correctly regardless of the moment of CDR normalization. Renormalization of calls do not recalculate balance. By default only one call at a time can be performed using a prepaid account. You may enable multiple parallel calls using the same prepaid call if you accept the idea that the balance might become negative. For this set in global.inc $RatingEngine['prepaid_lock'] to false.