Professional Documents
Culture Documents
4 Manual
http://www.citrusdb.org/documentation.html
1 of 48
http://www.citrusdb.org/documentation.html
4.14 Re-Running Declined Credit Cards 4.15 Welcome Letters 5 Chapter 4: Billing and Payments 5.1 Billing Tools 5.1.1 Credit card batches 5.1.2 Invoice printing 5.1.3 E-Invoice emailing 5.1.4 Entering Payments 5.1.5 Processing Refund 5.1.6 Importing New Accounts 5.1.7 Importing Service Usage 5.1.8 Importing Credit Card Changes 5.2 Reports 5.2.1 Customer Summary 5.2.2 Revenue Report 5.2.3 Refund Report 5.2.4 Past Due Report 5.2.5 Payment Status Report 5.2.6 Service Report 5.2.7 Source Report 5.2.8 Exempt Report 5.2.9 Print Notices 5.2.10 Service Growth 6 Chapter 5: Server Administration and Integration 6.1 Backups 6.2 Custom Modules 6.3 Account Activation and Deactivation 6.4 Credit Card Batch Exports Format 6.5 Credit Card Batch Imports Format 6.6 New Accounts Data Format 6.7 Service Usage Data 6.8 Credit Card Change Format 6.9 Automation 6.9.1 Automatic Credit Card Billing 6.9.2 Automatic Invoice Printing 6.9.3 Automatic Invoice Emailing 7 Chapter 6: Data Security Implementation Guide 7.1 CitrusDB Conguration 7.2 Physical Data Center 7.3 Passwords 7.4 Encrypting and Decrypting card data 7.4.1 Encrypting existing card data 7.4.2 Changing encryption keys for card data 7.5 Purge old cardholder data 7.5.1 Remove Exported Batch les 7.5.2 Remove Canceled Customer Records 7.6 Logging of user activity 7.7 Keeping Up-to-Date
2 of 48 Wednesday 24 April 2013 05:47 AM
http://www.citrusdb.org/documentation.html
8 Online Resources 9 Appendix A: GPG Commands 9.1 Creating A Key 9.2 Listing Public Keys 9.3 Listing Private Keys 9.4 Export Public Key 9.5 Export Private Key 9.6 Importing Public Key 9.7 Import Private Key 9.8 Delete a Public Key 9.9 Delete a Private Key 9.10 Encrypt Data with Ascii Armor 9.11 Decrypt Data 9.12 Edit a Key 9.13 Key Signing 9.14 Key Trust 9.15 Revoke a key 9.16 Command Options 10 Appendix B: OpenSSL Certicate
1 Introduction
CitrusDB is an open source customer service and billing database. It can be used by customer service personnel to provide sales and support to customers, and by billing sta to bill customers for their services via invoices and credit card batches. Customers may access the Online customer account manager to view their services, billing history, and make service and support requests online. Requirements: PHP 5.2 or greater MySQL 4.x or greater An SSL Certicate for the domain where it will be installed (Can be self signed) A GPG Key Pair if you are storing credit card data A Web Browser with Cookies and Javascript
2 Chapter 1: Installation
Before you install CitrusDB you should check whether a web server with the PHP module, and MySQL database are installed on your server. To check whether MySQL, and PHP are installed in your server correctly you can upload a simple PHP le to your server that contains the following code:
<?php phpinfo(); ?>
3 of 48
http://www.citrusdb.org/documentation.html
View your uploaded le in a web browser by going to your site, eg: www.yourname.com/le.php This will show you what version of PHP you are running and a lot of information about your PHP installation. Further down the screen there will be a section about your MySQL installation that will conrm whether MySQL is supported by your PHP installation. If the le you uploaded does not load, give an error, or does not show anything about MySQL, your server is not congured correctly. You will need to x this before you continue. There are many methods to install a web server, MySQL and PHP on your server. On Linux you will usually be able to nd a package available for your distro that you can install via a package manager like synaptic, apt-get, or yum. Mac OS X already has Apache installed by default, all you'll need to do is enable PHP and install MySQL or you can use a pre-built package like XAMPP . If you are using Windows you can try the pre-built packages like XAMPP that include all the pieces you need for Apache, MySQL, and PHP . Microsoft also maintains PHP packages available for windows servers. After you have installed your server software you can begin installing CitrusDB. The main internal application is the largest part of CitrusDB. It is built for use by customer service representatives to handle customer service queries and sales, billing sta to send bills and process payments, and by administrators to activate new services, deactivate services, and monitor customer service operations. If you are simply trying out CitrusDB it can be installed on any server you like. When using CitrusDB with real production data it should be installed on a private LAN or on a well protected web server with limited access by using rewalls and SSL, or other comparable security measures to protect your customer data and limit access to only you and your sta. Follow the steps below to begin your installation.
Create a MySQL database user with access to the citrus database you just created. Edit the conguration le: /citrusdb/include/cong.inc.php Change the database host, to your server name, often this will be the localhost it is all on one server. Enter your database username and password that you just created before.
$sys_dbhost='localhost'; $sys_dbuser='username';
4 of 48
http://www.citrusdb.org/documentation.html
$sys_dbpasswd='password';
Change the path to citrus variable to the lesystem path of your installation: On a unix installation it may be something like these depending on where you installed your citrus les:
$path_to_citrus='/home/username/citrusdb'; or $path_to_citrus='/var/www/citrusdb';
Change the hidden hash var to your own secret hashphrase. You will never need to remember this hashphrase so you can make it as complicated as you want.
$hidden_hash_var='youmustchangethis';
Edit the $lang variable to point to your local language le. This localization le holds the values for all the text in CitrusDB as well as the currency symbol used. Please note that CitrusDB can only work with one currency.
$lang = './include/local/us-english.inc.php';
Set the regular url and ssl url prexes for your site. You should use the same name for both the regular url and ssl url with the only dierence being http or https for the protocol. This will ensure the session cookie assigned during ssl login is available to the regular http url as well. You may use a self-signed certicate for this function as long as all the users of the database have that SSL certicate installed into their browsers. The CitrusDB project is an aliate of Certs4Less where you can get an SSL certicate signed by a number of certicate authorities at dierent levels of authentication.
$url_prefix = "http://server.example.com/citrusdb/"; $ssl_url_prefix = "https://server.example.com/citrusdb/";
Set the gpg command that will be used for encryption of stored credit card data. In order to use gpg you must generate a public and private keypair. It is probably a good idea to generate a gpg keypair just for citrusdb to use. This public key can then be used on the order side to store credit card numbers before they are imported as well as storing cards entered directly into citrusdb. To generate a keypair run the command: gpg gen-key
5 of 48
http://www.citrusdb.org/documentation.html
I recommend using the shortest recommended key length of 1024 bits since this key will be used over and over again, using the shorter key length will make decryption faster. This is a trade o of speed vs. strength. One could also use gpg with the symmetric encryption option or any other encryption system that can output an OpenPGP ascii armor message format. Symmetric encryption could be signicantly faster, however it will require protection of the passphrase that is used when encrypting the card data. The example shown below stores the gpg key as the www-data user in their home directory. This home directory was created for the user that the web server is running as. This is the easiest way to make sure that the web server running citrusdb has access to the keys that it will use to encrypt and decrypt the card data. If the web server where you run citrusdb is inside your network and dedicated to your internal use this should not be an issue. If you are unable to do this, then you will need to modify the permissions of your .gnupg folder and the keyrings inside of it to be readable by everyone. This is less desireable as it may expose them to other users of that system as well as cause permission problems in the future if you edit keys.
$gpg_command = "/usr/bin/gpg --homedir /home/www-data/.gnupg --armor --batch -e -r 'CitrusDB'";
Set the gpg decrypt command that is used when decrypting the cards for batch exports or when re-keying the data. The decrypt command must include the passphrase-fd 0 command because the passphrase will be passed to gpg by citrus's decryption function.
$gpg_decrypt = "/usr/bin/gpg --homedir /home/www-data/.gnupg --passphrase-fd 0 --yes --no-tty --skip-verify --decrypt";
Set the gpg sign command will be used by citrus to verify the passphrase entered before creating a batch le.
$gpg_sign = "/usr/bin/gpg --homedir /home/www-data/.gnupg --passphrase-fd 0 --yes --no-tty --clearsign -u 'CitrusDB'";
If you would like to use an LDAP server to authenticate users you can setup the ldap variables. Set the ldapenable variable to TRUE and the other variables to correspond to your LDAP conguration. You should make sure you have congured your ldap server to work with ssl so that the data passed between the web server and the ldap server is not able to be intercepted by using the ldaps protocol. You will need to have the user congured inside of the citrus user utilities to allow them to login with LDAP , but you can manage their password using your LDAP system.
$ldap_enable = FALSE;
6 of 48
http://www.citrusdb.org/documentation.html
If you have an xmpp or jabber server for ticket notications you can setup those xmpp account variables to allow citrus to send ticket notications via xmpp instant messages.
$xmpp_server = ""; $xmpp_user = ""; $xmpp_password = ""; $xmpp_domain = "";
A shipment tracking website URL like the one for US Postal, FedEx, or UPS can be entered if you want to use the eld asset tracking number eld when shipping eld assets to customers.
$tracking_url = "http://trkcnfrm1.smi.usps.com/PTSInternetWeb/InterLabelInquiry.do?
add a cron job to run the statusupdate script (available in the citrusdb folder) every night or after billing is done for the day. This script will update the customer's account status and create a le that can be used to activate and deactivate customer services automatically. Go to your web site address /citrusdb/index.php, you can log in with username "admin", password "test" to start. You have now nished the main installation of CitrusDB. It's a good idea to login and change your admin password rst. If you are not going to install the customer account manager can skip to Chapter 2 - Setup, to continue to setup of the internal CitrusDB application.
7 of 48
http://www.citrusdb.org/documentation.html
The online customer system is congured similarly to the main system by editing the cong.inc.php le inside the citrusdb/online/include folder. There are some additional variables to congure for the online customer system. The $payment_url variable should be set to whatever online form or payment system you have such as authorize.net, paypal, your own custom form etc. The $notify_user variable holds a username from the internal system that will be notied of new requests that customers make online.
After you have backed up your current installation, replace the old citrusdb les with the new ones from the package you downloaded Edit the cong.inc.php in /citrusdb/include with the database and path information from your old cong le. To update your database schema from the old to the new, open the update.php le in your web browser (www.example.com/citrusdb/update.php) and click the Update button. Your database has now been updated, and you are ready to use your new version of CitrusDB. If you are upgrading from version 1.x to 2.x you will need to make sure you have setup the new gpg commands in the cong le and then run the encryptcards script to encrypt the cards in the database.
3 Chapter 2: Setup
3.1 Login
After you have installed CitrusDB the rst thing you should do is login with the default username (admin) and password (test) and then go update the password to something new. To update the password, click on the Tools icon, and then click on Change Password. Enter a new password for the default admin user. The login system will stop your login attempts from your IP address if you fail to login with the correct username and password after 5 tries in the last 24 hours. If this happens, your IP address must be removed from the login_failures table by the database administrator.
8 of 48
http://www.citrusdb.org/documentation.html
Export File Prex is is appended to the beginning of all credit card batch les exported by citrus. If you have multiple organizations exporting from the same citrus system, you can use this le prex name to identify which exported batches belong to which organization. Past Due Days are the number of days an account is past due before the status is updated by the statusupdate script to one of the three dierent past due status types: Past Due, Turned O, or Canceled. Past Due accounts will be noted as past due and will be notied in email by the statusupdate script about their status. A Turned O status will cause the account to send a disable message to the account activation system, which can then disable access to the account. An account in a Turned O status should be disabled and non-working. The Canceled status is for accounts that have been through the rst two phases of being past due and have not yet paid for services. Canceled will send a delete message to the account activation system. The account should be removed from your systems, and if you have a collections department or processing system, can be forwarded to them for past due amount recovery.
9 of 48
http://www.citrusdb.org/documentation.html
Carrier Dependent Past Due Days are for third party services that have special requirements when they are turned o. They act the same as normal Past Due Days however they have a Shuto Notice period in between being Past Due and having their service being Turned O. This shuto notice is to notify the customer that their service will be turned o and also to notify the billing group that the service is in jeopardy of being shuto. The billing group will receive notications when this service is to be turned o or canceled, since they will need to be able to contact the third party service carrier to handle type of cancel request. The next elds are the four dierent kinds of invoice notes that are printed at the bottom of the invoices according to the account status. The Default Invoice Note is printed on an account in good standing, usually this is a note thanking them for using your services. The Past Due Invoice Note is printed on invoices while an account is in the Past Due status. The Turned O Invoice Note is printed on invoices while an account is in the Turned O status. The Collections Invoice Note is printed on invoices for accounts in the collections status. These messages can be overridden by entering a custom message in the Notes eld on the customer's billing record. The declined subject and message eld hold the data used in the email that is sent to customers when their credit card has been declined. Here you should enter a message that will prompt them to contact you and get their billing information up to date. The last eld is an invoice footer eld that holds text that will be placed at the bottom of every invoice. After you have setup the organization information you are ready to save your changes and continue setting up your CitrusDB system.
3.3 Settings
The settings tool holds system wide settings for citrus. At the top of the Settings screen you will see a Citrus Database Version and Citrus Software Version. The database version is the version of the SQL Schema that is being used. The software version indicates the version of the software application les. These two versions should be the same. If they are dierent it may mean that you have not run the update script to update your database to the correct version or that you are running a Pre-release version of CitrusDB. The Path to Credit Card File should be set to a le path on the server to a folder that is outside the path of the web server and other network processes. When credit card and account activation data is created it will be saved to a new le inside this folder. You can then write scripts that will automatically process new les left in that folder, or download those les to process them manually. You should make a new folder to store this data in, for example, on a Unix system you can set this to something like
/var/billing
10 of 48
http://www.citrusdb.org/documentation.html
This will keep this data outside of the web server path, but will still allow it to be accessed by 3rd party scripts running on the server that can process this data automatically. The Default Group is used by the support notes and privileges system to allow notications to certain users. Normally leaving this as the default of "users" is recommended. The Billing Group is a group that you will need to create if you are using the carrier dependent services functions or if you are using the Field Asset feature. The status update script will send the billing group notes if a carrier dependent service is in a bad billing status, like past due, turned o, or canceled with fees owed. The eld asset feature will send a note to billing whenever a device is returned so that the billing group knows the customer has returned a device and can take measures necessary to adjust their bill. The Shipping Group is a group that you will need to create if you are going to use the Ship Field Asset feature. Ship Field Assets lets you associate a eld asset like a CPE or other device with that customer's service. The shipping group will get a note when a eld asset is setup to be shipped. The carrier dependent cancel url is for third party carrier dependent services. This can link to an internal web form or other form when a carrier dependent service is canceled to notify the third party carrier that this service is to be canceled. The Billing Date Rollover time should be set to the time of day when new accounts created after this time will not be billed until the next billing day. This is used to prevent new accounts from being given the current billing date after the batch has already been processed for the day. This time eld is in 24 hour time format. The Weekend indicators allow the billing system to automatically skip certain days when assigning new billing dates to new customers. This is especially usefull for billing around weekends, so that a new customer's billing date does not fall on a weekend. You can choose what days of the week you want to assign as weekends here.
3.4 Users
The Users Tool will allow you to add CitrusDB database users. This is used to add your sta personnel that will be using the database to access customer information and billing. The user tool will show you a list of current users. In the default installation there will be two users present. An admin user that has all privileges to edit everything about the database, and an online user that is used to demonstrate the online customer account manager's message notication. If you have not yet done
11 of 48
http://www.citrusdb.org/documentation.html
so, you should change the password for both the Admin user and Online Request user to something new. To add a new user click Add New Database User. You will then be presented with a form to ll out, including the user's real name, their username, and their password. You will also choose their tool privileges here. Admin privileges will allow access to add new users, edit billing types, add new services, and add new modules. The Manager privilege will allow access to the credit card import/export features, invoices, payments, reports, and account activation. All other users should have No selected for both Admin and Manager privileges. You can edit existing users by clicking the Edit link next to their name. This will allow you to change their tool privileges, their username, and their password. You can also delete a user by clicking the Delete link next to their name. When you delete a user or change their username, any notes they have made will stay in the database under their old username. You will also need to update any groups they are a part of to include their new username.
3.5 Groups
The Groups tool is used to assign users to dierent groups for notication and permission purposes. By default all the users who are added to the database are put in the "users" group. This should probably not be changed, since it aects access to many pieces of the system. You can add as many other groups as necessary. For instance, if you have a group of people who perform shipping duties, you might make a shipping group and assign them to this group. When a particular piece of equipment is needed you can send a note to the shipping group, which will notify all the individuals in that group about your message. When someone in the group marks the message nished, it will dissapear from view of all the people in the group. This is also where you will add the billing group you specied in the settings tool if you are using the carrier dependent service functions.
12 of 48
http://www.citrusdb.org/documentation.html
prepay: For prepayments done via checks, cash, or electronic funds transfer. A prepaid account will not have it's payment dates updated until payment is made, it will not go into a Past Due status, it will become Not Renewed, and should be turned o if left un-renewed. free: For free accounts. These accounts will never be billed and will never be past due. The free billing type can be used for items like demo accounts or temporary free items. If you need to add new billing types, they can be added using the form at the bottom of the Edit Billing Types tool window. You will need to provide the name of the new billing type. This will show up in the list in the billing record. The frequency of the billing type. This frequency is used to determine how often (in months) that billing type is processed. For example a Monthly billing type would use a frequency of 1, a Yearly billing type would use a frequency of 12 (for the 12 months between bills). There is also a special case frequency of 0 (zero) for a free or one time billing type. Lastly, select what billing method this new billing type will use, creditcard, prepay, invoice, einvoice, etc. You can remove billing types from the database, however before doing so you will want to make sure that none of your current billing records are using that billing type, otherwise they may not get billed properly.
3.7 Holidays
CitrusDB has a table in the database called "holiday". This table consists of just one date eld called "holiday_date" that holds dates that are billing holidays when billing is not preformed. If a new customer's billing date should fall on one of these days it will be moved up a day until it does not fall on a holiday. You should determine what holidays there are during the year that are not already covered by the weekends setting when billing will not be performed and add those dates to the table. This table can only be edited by using a database editor such as phpMyAdmin or SQL insert queries.
3.8 Services
CitrusDB comes with a default example service, credit, and prorate services. To make CitrusDB work for your organization you will have to add your services using the Edit Services tool. CitrusDB can support many dierent kinds of services, one time services and fees, recurring services, taxes and fees, linked or bundled services, and services with measured usage or hourly cost. Open the Edit Services tool to see all your current services. Click Add New Service to begin adding the services that you provide. 3.8.1 Adding Your Services The Billed By menu lets you choose which organization this service is billed by. This would only change if you have more than one brand organization inside of your
13 of 48 Wednesday 24 April 2013 05:47 AM
http://www.citrusdb.org/documentation.html
citrusdb installation. The Description eld holds the service name that will appear in the service listing and on invoices. Price holds the unit price of the service. For example if you have a service that is 9.95 per month, enter 9.95, if you have a service that is 39.95 per year, enter 39.95, a service that is 70.00 per hour, enter 70.00. The Frequency indicates the service's monthly billing cycle. A service that is billed monthly would have a frequency of 1 (for every month), a service that is billed yearly would have a frequency of 12 (for every 12 months), a service that is only billed one time would have the special frequency of 0 (zero) for a one time service. One time services are automatically removed from the customer's service record listing and put into the service history after they are billed. The Options/Attributes Table eld holds the name of the table that holds the attributes for that service. When you make a service, you can also name a table in the database that holds the attributes that are associated with that service, such as location, equipment, usernames, special contact info, anything that may be associated with that service itself. This options table name is not required, so if your service has no attributes you can leave this blank, however if you add an attributes table at a later time the services that were already added will not be associated with the new attributes. The attributes tables allow CitrusDB to support any kind of service at all, so it is not limited to one industry. If you are making a new attributes table, choose a table name and enter it in the Options/Attributes Table eld. After you have added the service, go to the Options/Attributes Table link at the top and click Create next to the table name in the listing. This will create an empty table with the correct elds to link it with your new service. You can then add any attribute elds you want after the rst two relationship elds, using SQL alter table commands or a tool like phpMyAdmin. Most of the attribute elds will be shown as simple text elds, however if you want to make a menu of choices, or a Yes/No choice, you can use an enum eld type that will show all the items in the enum within a drop down selection on the web page. You can also add text or blob elds that will be shown as textarea entry elds. The Category eld is a case sensitive name of a category to group the service under when choosing services to add to the customer's service record. This can be left blank if you only have a few services, but when you have many services it will be helpful to organize them into categories so you can jump to the type of service you are looking for. Selling Active is on by default. It indicates whether this service is currently being sold. If set to Yes, it will show up in the list of services that can be added to an account. If set to No, it will not show up in the list of services that can be added to an account, however it can still be billed to customers who still have the service. This can be used to deactivate services that were only available for a limited time and are
14 of 48
http://www.citrusdb.org/documentation.html
still being billed, but are no longer available for new sales. The Hide Online eld is set to No by default. This indicates whether you want to show or hide this service in the customer account manager and in the default view when adding services. You will probably will want to hide services such as setup fees, install fees, and sometimes bundled services. The services are hidden to regular internal CitrusDB users, and are only visible to manager and admin users using the Show All link when adding services to a customer. The Activate Notify eld holds the username or group name of the CitrusDB user who will be sent a support ticket note when this kind of service is added to an account. This can be used to notify order coordinators or a service activation department about services being added to an account if further manual processing is required. The Shuto Notify eld holds the username or group name of the CitrusDB user who will be sent a support ticket note when this service is removed from an account. This can be used to notify order coordinators or a service activation department about services being removed from an account if further manual processing is required. The Modication Notify eld holds the username or group name of the CitrusDB user who will be sent a support ticket for services are are to be enabled, that were previously disabled, but not totally shuto. The Support Notify eld holds the username or group name of the CitrusDB user who will be entered by default in new support tickets that are opened for this service. Activation String is used to hold the eld names that are passed to the statusupdate tool with this service. For example, when you add a new Internet account service you will probably want to provide the username and password from the options_table to the account activation system. To do that enter the string username,password in the Activation String eld. The eld names must be entered in matching case and be comma seperated with no spaces or other characters between the eld name. The Usage Label is used to label the Measured Usage eld when adding measured usage services. For example if you have a service that is 70.00 per hour, you would put hours in this eld, or if you have a service that is 5.00 per gigabytes, you would put gigabytes in this eld. Carrier Dependent services are those that are provided by a third party that needs a seperate notication of service activation and deactivation that is not part of your own account activation system. A Carrier Dependent service has additional steps when they are being deactivated that will send a shuto notice to the customer to make sure they are aware the service is being shuto. It will also send simultaneous notications to the default billing group that is indicated in the Settings so that group can take care of communication to the third party carrier about what to do with a past due, turned o, or canceled service. A carrier dependent service that owes money when their account is canceled will be marked as the status cancelwfee instead of canceled so that the billing group can nd
15 of 48
http://www.citrusdb.org/documentation.html
those customers and go after them for the money they owe. This is usually necessary since as a provider you will owe money for those services to the third party that was providing them and will have more incentive to collect on those charges rather than just cancel that service and be done with their account. After you have lled in all the relevant service information you can click the Add button to add your new service to the database. You can now assign this service to your customers. If you have many many services to add it may be easier to make a spreadsheet with all their attributes and import them into the master_services table directly using SQL insert queries or a database editor such as phpMyAdmin.
16 of 48
http://www.citrusdb.org/documentation.html
service with a tax. The tax will be added to customers with that service if the customer record meets the If Field/Value checks, and if the customer is not tax exempt for that tax type.
3.12 Searches
CitrusDB comes with a number of searches pre-installed in the searches table. Search elds are edited in each module's search.php le and show up on the search page. You will probably want to create search queries for your new service attributes, so you can nd services by the specic attributes that have been specied in their options/attributes table. You can add new searches by adding a new row to the searches table. For example in the query eld:
SELECT * FROM customer WHERE phone LIKE '%%s1%%'
This will allow you to search the customer table for a phone number. The %%s1%% will be replaced with the information lled out in the search form. Then link to the search row id using a small input form in the corresponding module search.php page. In this case you would edit the /modules/customer/search.php le and add new html for a form:
<form ACTION="index.php?load=dosearch&type=fs" METHOD="POST">
17 of 48
http://www.citrusdb.org/documentation.html
Find Phone Number: <input type=text name=s1> <input type=hidden name=id value=4> <-- "4" is the id of the row in the searches table --> <input type=submit name=submit value="search" class=smallbutton> <form>
You can search with multiple eld inputs by naming each eld s1, s2, s3, s4, or s5.
the %s1% is a place holder where the value of the attribute will be put into the URL.
http://www.citrusdb.org/documentation.html
When you have a new customer to add to the database click the New icon at the top of the screen. This will prompt you to ll in some standard customer information, such as their name, address, and phone number. After you have lled in their information, click the Add button. This will make a new customer record, and take you to the customer record where you can begin adding their new service and billing records by clicking on the service and billing tabs on the left. Adding new service and billing records is detailed below. After you have added service and billing records for the customer, that record is considered complete and ready for billing and service provisioning. To edit the customer's record click the Edit Customer link at the top of the customer record screen. This will allow you to edit the information about the customer, such as their address, phone number, or email address. When you edit the customer record, this does not automaticaly aect their billing record. After you have saved your changes to the customer record you will be promted to update the billing record with the matching information. Click Yes if the customer's billing information should match. Otherwise you will need to edit the billing record seperately. If a customer wishes to cancel their services and will no longer have any customer relationship with your organization, you can cancel a customer using the Cancel link at the top of the customer record. You will then be asked if you are sure you want to cancel this customer. When you cancel a customer it will deactivate all the services on their account and the account will no longer generate new bills for services. If you want to un-cancel the customer's record you can click the Uncancel customer link that will show up on a canceled customer record. Add their services back onto the account, and edit their billing so that it begins billing them as before.
19 of 48
http://www.citrusdb.org/documentation.html
information will be copied from the customer information so that billing can be processed. If you didn't copy the customer information into the billing record when editing the customer record, you'll need to start by lling in the customer's billing contact information. This will hold the address that an invoice is mailed to, the email address an e-invoice is emailed to, and the address that a credit card is veried against. You will also choose the billing type here. There are many billing types to choose from. Depending on what kind of services the customer has, it may restrict what billing types are compatible with that service. A service cannot have a billing type that has a billing cycle frequency that is smaller than the service frequency. For example, if the customer has a service on their record that is a Quarterly Subscription Service that is billed every 3 months, they must have a billing type that is also billed every 3 months or a greater multiple of 3 months, such as yearly (which will multiply that service cost * 4 when billed yearly). This is one of the reasons you may need to add alternate billing types to an account, if the customer has services that are billed at many dierent intervals. When you add a new billing record the next billing date is lled in with today's date, or if it is a holiday or after the billing rollover time setup by the server administrator, the next available billing date. A From date of today, and a To date that is automatically set according to the length of the billing cycle specied by the chosen billing type. The payment due date is also entered as today's date on a new billing record. A payment due date of today may be ne when billing is done by daily credit card batches, however if the service is invoiced or billed dierently, this date may need to be edited. The payment due date is very important to get right if you are using the statusupdate script to automatically update customer status information. That script relies on the payment due date to determine what status the account should be in, whether to turn it o or back on etc. When accounts are billed by credit card, invoice, or einvoice, the billing dates are moved forward automatically according to the billing type's cycle. Accounts with a prepaid billing type will have their billing dates automatically moved forward after the currently due payment has been made.
http://www.citrusdb.org/documentation.html
The Refund Report link available on each billing record allows you to indicate which services to refund on that billing record. Credit card billing type refunds will be added to the refund batch run from the refund batch tool. Invoice or E-Invoiced billing type refunds will need to be processed manually. It will show you a list of all services billed to that billing record and allow you to indicate a refund amount for those services that have already been paid for.
21 of 48
http://www.citrusdb.org/documentation.html
button. You will then be returned to the list of services on the account, and will see the new service listed there. The service will be added with the default billing type. If there are other services linked with the one you added, or if the service has taxes associated with it, those will be shown also. If the service has others linked to it, those will also have been added to the record, such as setup fees or bundled services. If you add a service that requires a dierent billing frequency, you will get a message that says Fix Billing Frequency. If you have not setup the customer's billing record yet, you can ignore this message for now. This error will appear if their billing type has a billing cycle that is less than the service frequency. For example, you will receive this error when the account has a billing type with a monthly cycle such as a monthly credit card bill, but a service that should be billed yearly, such as a yearly Internet service subscription. If the customer has alternate billing types that should be used for that service, click the Edit button and choose the alternate billing ID from the menu to assign this service to that billing record. You may want to add a dierent, but comparable service that is billed monthly so they can keep their billing simple, or make a new alternate billing type and assign this service to that new billing type. 4.8.1 Example Billing Combinations Some example service and billing type combinations: One bill Bill 1 Yearly Service and a Monthly Services assigned to one Yearly Billing type for both means that the monthly service rate will be multiplied by 12 to give the total amount for the one yearly bill. Two bills: Bill 1 Yearly Service assigned to a Yearly Billing type for just the yearly service Bill 2 Monthly Services assigned to a Monthly Billing for just the monthly service Two bills: Bill 1 Yearly Services assigned to a yearly billing type for just the yearly service Bill 2 Quarterly Services and Monthly Services assigned to a quarterly billing type, the monthly service will be multiplied by 3 to give it's total amount for the quarter. 4.8.2 Edit Service Records After you have added a service you can edit it by going back to the service record and click Edit. This will bring you to the attributes for that service as well as allow you to enter usage and alternate billing id choices. The service can also be changed to another service that shares the same attributes. When a service is changed, the old service is moved to the history and a new service is created with the same attribute information. A notication will also be sent to the modify notication user indicated in the service settings.
22 of 48
http://www.citrusdb.org/documentation.html
4.8.3 Service History In the service record screen you can also view a history of services that have been assigned to this account in the past. Click the History link at the top to view this listing. This will show you services that have been removed, as well as one time services, such as setup and install fees. One time services are automatically moved to the service history after they have been billed.
23 of 48
http://www.citrusdb.org/documentation.html
Declined 2X: a credit card account whose two most recent charges were declined Pending: an account with no next billing date, this usually means the account is pending an account change. Past Due: an account that has amounts past due, but not yet turned o or sent to collections status. Turned o: an account that has been put in the Turned O status, due to being past due with no payment made for a specic amount of days. Collections: an account that has been put in the Collections status by the billing group, due to being turned o with no payment for a specic amount of days. Canceled: an account that has been canceled, this is indicated by a cancel date on the customer record Cancel w/Fee: an account that has been canceled, but still has amounts past due.
24 of 48
http://www.citrusdb.org/documentation.html
25 of 48
http://www.citrusdb.org/documentation.html
into CitrusDB for crediting to accounts. To import the batch go to the Tools and select the Import Credit Cards icon. This will prompt you to browse your hard drive for the batch results le from your credit card processing system. The format for each line of this le is
"trxcode","ccnum","ccexpire","amount","billingid","Y/N","avs"
trxcode: this is the transaction code associated with this unique transaction ccnum: this it the credit card number, it should probably come back with most of it starred out, eg, 4*********111 ccexpire: this is the expiration date of the card that was run amount: this is the amount the card was run for billingid: this is the billing id that identies the customer billing record that was run. This is required to connect it to the right customer. Y/N: this is the letter Y or N that should indicate whether the card was authorized with a Y or declined with an N avs: this is the status of the AVS processing that will show whether the address matched or not. The server administrator may need to make a script that converts the results from the bank into the format that CitrusDB imports. Upon importing this le, account records will have their billing status updated accordingly and an email message will be mailed to those customers who have had their credit card declined. You can specify what the message says by editing the Declined Subject and Declined Message elds in the Organization settings. 5.1.2 Invoice printing Invoice printing can be done daily, or if you have used the prorate service item and edited their next billing date to prorate a customer's billing record, you can print invoices on the days you have chosen. Click on Tools and select the Print New Invoices icon. This tool can print batches of invoices based on their Next Billing Date, or individual invoices based on their Billing ID number, or Account Number. After you enter this information it will then provide you with a summary of what it found and prompt you to print the invoices. Then it will render the invoice page as a PDF le that can be opened with a PDF reader. You can then print the PDF from within the PDF application. It may also be a good idea to save this pdf to your hard drive to make an archive of all the invoices you have ever printed for auditing purposes. Invoices are formatted to be put into #10 windowed envelopes and have the recipient's address show through the window. 5.1.3 E-Invoice emailing E-Invoice emailing can be done daily, or if you have used the prorate service item and edited their next billing date to prorate a customer's billing record, you can email
26 of 48
http://www.citrusdb.org/documentation.html
invoices on the days you have chosen. Click on Tools and select the Email New Invoices icon. This tool can email batches of invoices based on their Next Billing Date, or individual invoices based on their Billing ID number, or Account Number. After you enter this information it will then provide you with a summary of what it found and prompt you to email the invoices. The invoice will be sent as a pdf le attached to email to the billing_email specied in their billing record. The web server that is running CitrusDB server must be properly congured to send email. This tool is a prime candidate to be automated by running a modied copy of it using the php command line program in a CRON job. 5.1.4 Entering Payments When there is a cash or check payment, or an electronic funds transfer (eft) is made, you can use the Enter Payments tool to enter the payments made to the account. You can apply a payment in three dierent ways. By Account Number, which will apply the payment to the oldest fees still due on that account's default billing record. By Billing ID, which will apply the payment to the oldest fees still due for services under that billing id. By Invoice Number, which will apply the payment to the oldest fees still due on that one invoice. You must also enter the payment amount, and the payment type, and if necessary the check number. If an over-payment is made, the payment utility will tell you that there is an amount left over. You can then apply this amount as necessary to the account, either by applying that payment to a dierent invoice, billing id, or making a credit in the account service record. 5.1.5 Processing Refund The refund tool is used to create a credit card batch for refunds that have been marked on customer records. Any refunds that have not been processed yet will be processed by clicking the Yes button and a credit card batch le will be created to upload to your credit card processor for processing. You can then import the results from the refund batch and it will show a credit in the payments on those accounts. 5.1.6 Importing New Accounts If you have an online order form for new customers, you can import their information into CitrusDB using the Import New Accounts tool. Your server administrator will tell you the steps necessary to get the data to import into this new accounts tool. This tool is a prime candidate to be automated by running a modied copy of it using the php command line program in a CRON job. 5.1.7 Importing Service Usage Some services have a usage associated with them. The server administrator will need to make a script that imports the usage directly into new services for each customer.
27 of 48
http://www.citrusdb.org/documentation.html
See your server administrator for the steps necessary. 5.1.8 Importing Credit Card Changes If you have a form on your website for customers to update their credit card information, you can use this tool to import their new information into their default billing record. Click the Tools icon and select the Credit Card Changes icon. This tool is used to import credit card changes that have been sent in via external methods such as online forms or order systems, usually done after a card has declined and a notice has been sent to the customer.
5.2 Reports
5.2.1 Customer Summary The Customer Summary tool will produce a report that shows the total number of paying customers you have for each service type that has not been removed. The total number of Paid Subscriptions, which counts the total number of non-free recurring services that customers have. The Total Number of Customers is the total number of customers that have not been canceled. Tht Total paying customers is the the same as the Total Number of Customers minus the customers that have a free billing type. 5.2.2 Revenue Report This report shows the total amount of revenue for services that were billed during the date period shown. It also shows the tax revenue during that period, the credit service types given during that period, and the refunds processed during that period. If payment has not yet been made to a service billed during the date period, it will not show up as revenue during the period until it has been paid. 5.2.3 Refund Report The refund report tool will show you the credit card information, amount refunded, and the account the refund was given to for refunds that were processed during a given time period. 5.2.4 Past Due Report The past due report will show customers with some type of unpaid status. It will allow you to nd Past Due, Turned O, and accounts in the Collections or Cancel with Fee status. You can use this report to determine which customers need to be contacted about their billing issues. 5.2.5 Payment Status Report This report shows you customer payment information. For example, here you can nd
28 of 48 Wednesday 24 April 2013 05:47 AM
http://www.citrusdb.org/documentation.html
out if they have had had their credit card declined in the past few days. You will be prompted for what days from the previous week you want to nd declined cards for. It will then produce a report of the credit card declines from that day. You can use this report to contact customers about their billing issues. 5.2.6 Service Report The service report will show you total customers for a chosen service. It will show you total numbers of who has active service and total number of deactivated services, and what status they have had. It will also show you a break down of reasons that were chosen when accounts with that service were canceled. 5.2.7 Source Report This report will show totals for the customer source chosen when the customer was activated. This will let you see where customers have said they heard about your services. 5.2.8 Exempt Report The exempt report will show a list of customers who have been marked as past due exempt, bad debt, or have tax exempt status for certain tax rates. 5.2.9 Print Notices This tool can print pdf notices that have been created by the nightly statusupdate script. 5.2.10 Service Growth A simple graph that compares the number of services in that category that were stared and ended in a month for a chosen year. For services that were changed from one type to another they will have one start and one end, so the old one shows up as an ended service and the new one shows up as a started service.
6.1 Backups
Having up to date backups are very important for a billing system, since your whole business will rely on it for their day-to-day work. You should implement a backup
29 of 48
http://www.citrusdb.org/documentation.html
policy that takes into account your uptime requirements. Backups can be performed nightly or as needed using the standard MySQL backup utility mysqldump:
mysqldump user <username> password <passwd> db_name > backup.sql
This command can be added to a nightly cron script on a Unix server, or a windows batch script.
Goodbye.";
Goodbye.";
30 of 48
http://www.citrusdb.org/documentation.html
} else permission_error(); } else if ($create) { if ($pallow_create) { include('create.php'); } else permission_error(); } else if ($delete) { if ($pallow_remove) { include('delete.php'); } else permission_error(); } else if ($pallow_view) { // // YOUR DEFAULT CODE GOES HERE // } else permission_error();
create.php this will be used to create a new record for that module function. for example, with the services module, this would create a new service for that customer, called with create=on edit.php this will be used to edit a record for that module function. for example, with the billing module, this would edit the billing for the specied billing id, called with edit=on, often called with an id value to specify a billing_id, or user_service_id etc. delete.php this will be used to delete a record for that modules function. for example, with the services module, this would remove the service from that customer, called with delete=on search.php this will be included in the main search page. it will not be called through the index.php le it will either be empty if your modules doesn't need search ability, or have form html for searching the data that your module deals with example of search.php:
<form ACTION="index.php?load=dosearch&type=fs" METHOD="POST"> Company Name: <input type=text name=s1> <input type=hidden name=id value=2> <!-- the id of this search in the searches table --> <input type=submit name=submit value="Search" class=smallbutton> </form>
After you have created your module, you'll need to install it into the system. Copy your module folder into the modules folder of CitrusDB. Open the Edit Modules tool and click Add Module. This will ask you for the Common Name of the module, this is the name you want it to be called in the Tab on the left that users will see. The Module Name is the name of the folder that the module is stored in, this eld is case sensitive. The Sort Order eld is a number that determines what order the tabs are sorted in.
31 of 48
http://www.citrusdb.org/documentation.html
There is a script included in the citrusdb folder named statusupdate. This script can be run nightly in a unix cron job or windows task scheduler. It will create a le in the path you specied in the general conguration (the same path as credit card data) with a list of accounts to ADD, DELETE, ENABLE and DISABLE today. The statusupdate script will also email messages to customers and make a pdf le for printed messages to be mailed by the billing adminstrator regarding their past due accounts. These messages can be edited in the language les using the $l_notice_text_ variables. This le can be used in conjunction with other cron jobs or scripts that check for new account les and process them automatically. You may want to make a shell script that calls the statusupdate script and then calls your own account activation script that works on the le created by statusupdate. It will print an ADD line for new services added today. A DELETE line for services that have a removal date of today. An ENABLE entry for services that should be turned back on today that were previously disabled. A DISABLE line for services that should be shut o today such as accounts with declined credit cards or past due. It prints them in a standard text format that could be processed by an activation script at a later time. Example:
"ACTION","category","Customer Name","Service Description","field1",...
The ACTION will hold the value ADD, DELETE, ENABLE, or DISABLE to indicate what should be done to the account The category eld holds the category you assigned to that service. This will allow your custom activation script to check this eld and do things to specic categories of service, without having to parse the whole service description. This is the customer's name, often entered into the data with their account This is the description of the service being added from the database The last elds are holding data from whatever elds have been specied for that service in the Activation String eld in the service editor. It will print them all for that service, so it will be a variable number of elds. You will probably want to specify the same elds for each category of service so you will know what elds you are looking at when you read the category name earlier in the line.
32 of 48
http://www.citrusdb.org/documentation.html
The rst eld in the rst line of a card record will be the words CHARGE or CREDIT to indicate whether the transaction is a charge or a credit, after the rst eld you can use any of the following variables: $user: this is the database user that ran the export tool $batchid: this is the id of the batch, there is a unique batch id for each export created $mybilling_id: this is the billing record id that is being billed $invoice_number: this is the invoice number for this bill, it is unique to this one bill $billing_name: this is the name in the billing record $billing_company: the company in the billing record $billing_street: the street on the billing record $billing_city: the city on the billing record $billing_state: the state on the billing record $billing_zip: the zip code on the billing record $billing_acctnum: the customer's account number $billing_ccnum: the customer's credit card number $billing_ccexp: the customer's credit card expirationdate $billing_fromdate: the billing from date on the billing record $billing_todate: the billing to date on the billing record $billing_payment_due_date: the payment due date on the billing record $mydate: the date in Y-m-d date format (eg: 2007-04-19) $abstotal: the absolute value of total, if the bill total is negative it will not be exported with the credit card batch. The refund tool must be used to refund an account's credit card.
trx code: the unique transaction code assigned to this one transaction by the bank or by you cc number: holds the credit card number, should probably be imported in a format with most of the information hidden like
4***********1111
cc expire: the expiration date of the card that was run. amount: the amount of the transaction the billing id that connects this transaction to a citrusdb billing record. The uppercase letter "Y" or "N" that indicates whether the transaction was
33 of 48 Wednesday 24 April 2013 05:47 AM
http://www.citrusdb.org/documentation.html
successfully approved (Y) or declined (N). You can place other text after the Y or N if you want to indicate other transaction codes or things like whether the transaction was live or in a batch. avs: this eld can hold address verication result codes if those are available to you. You may need to create a script that converts your bank output into the format above that CitrusDB will import. The only required data are the transaction code, billing id, and approved or declined, the other elds can be left blank if they are unavailable. Upon importing this le accounts will have their billing status updated accordingly.
The rst line of the import record is the customer data, the second line is the billing data. The credit card number here should be masked with ****'s in it so that one cannot view it. The real card number will be stored in the encrypted PGP text below. The third section of lines are for services to add to the account upon import. The nal lines are for the PGP ascii armored credit card data so that you can encrypt the data with your public key before importing it into the database, preferably directly in the order system that is saving these new customers. If the customer does not use a credit card you will need to include the BEGIN PGP MESSAGE and END PGP MESSAGE lines with nothing in between them. This denotes the end of that customer record. (normally each line is on one line and does not have spaces between
34 of 48 Wednesday 24 April 2013 05:47 AM
http://www.citrusdb.org/documentation.html
lines, but is printed this way to show up in the instructions correctly.) Field denitions:
source, name, company, street, city, state, country, zip, phone, alt_phone, fax, contact_email, tax_exempt_id, secret_question, secret_answer, account_manager_password, organization_id Name, Company, Street, City, State, Country, Zip, Phone, Fax, Email, Billing Type ID, Masked Creditcard Number, Creditcard Expiration Service ID, (any fields that make up the services options_table) in this case, Username, Password, OS, Street, Device -----BEGIN PGP MESSAGE----aSC14RMoRD3tAaSC14RMoRD3tAaSC14RMoRD3tAaSC14RMoRD3tA aSC14RMoRD3tAaSC14RMoRD3tAaSC14RMoRD3tAaSC14RMoRD3tA aSC14RMoRD3tAaSC14RMoRD3tAaSC14RMoRD3tAaSC14RMoRD3tA aSC14RMoRD3tAaSC14RMoRD3tAaSC14RMoRD3tAaSC14RMoRD3tA -----END PGP MESSAGE-----
35 of 48
http://www.citrusdb.org/documentation.html
$mydate = date("Y-m-d H:i:s"); // get the default billing id for the customer's record $query = "SELECT * FROM customer WHERE account_number = $account_number"; $DB->SetFetchMode(ADODB_FETCH_ASSOC); $result = $DB->Execute($query) or die ("$l_queryfailed"); $myresult = $result->fields; $default_billing_id = $myresult['default_billing_id']; // insert the new service into the user_services table $query = "INSERT into user_services (account_number, master_service_id, billing_id, start_datetime, salesperson, usage_multiple) VALUES ('$account_number', '$serviceid', '$default_billing_id', '$mydate', '$user', '$usage')"; $result = $DB->Execute($query) or die ("$l_queryfailed");
If there is an options table that you want to put attributes into you'll also need to insert that information:
// use the mysql_insert_id command to get the ID of the row the // user_services insert you just did was set to. $myinsertid = $DB->Insert_ID(); $query = "INSERT into options_table_name (user_services,field1,field2,field3...) VALUES ($myinsertid,$field1, $field2, $field3...)"; $result = $DB->Execute($query) or die ("$l_queryfailed");
This code will usually be put inside a loop that is reading the input le that stores the usage data and inputs it into the database.
36 of 48
http://www.citrusdb.org/documentation.html
name: the customer's name street: the customer's street address city: the customer's city state: the customer's state zip: the customer's zip code ccnumber: the customer's new credit card number in masked form with ****'s ccexpire: the customer's new card expiration date PGP MESSAGE BLOCK will hold the card number encrypted with the public key This will update the credit card number on all billing id's assigned to that customer. You'll need to create a form cgi that saves data in this format and download this le from your web server's periodically. You'll probably want to download and empty this le every day to check if new updates have been made. This will update the credit card number on all billing id's assigned to that customer.
6.9 Automation
Most of the pieces of CitrusDB, such as invoicing, e-invoicing, importing new accounts, exporting credit cards, importing credit cards, and activating accounts, can be automatically run at specic times. It relies on the server's cron scheduling services on unix servers to run the commands at a specied time, or on a windows server you could do something similar with the Task Scheduler. There is one part of citrusdb that should be run every day and take advantage of a cron or task schedule. That is the statusupdate script. This must be run every day to update the billing status of accounts and also creates a le that contains account information that can be used to process account changes, new accounts, and removed accounts. PHP has a command line interpreter that can be used to execute the citrusdb les. On a unix server this can be used much like the perl or shell interpreter is used, so you can put the path to your php executable like:
#!/usr/local/bin/php
at the top of the script you want to run. On windows servers you would run it with a command that is something like:
C:\path\to\php\php.exe <filename.php>
To run a CitrusDB script from the command line you'll need to make a copy of the script to edit, in this case the einvoice.php le which is inside of the tools/modules /billing folder. It may be best to move it up a few levels to the citrusdb folder itself so your include path's are easier to gure out. With the new copy, you'll need to edit it to include the stu from the includes les, just like it's included in the index.php le normally, so you'll need to put these near the top of the script:
37 of 48
http://www.citrusdb.org/documentation.html
Then you'll need to write some php code in the new script to generate the input you want, such as today's date in the billing_date that is being processed, since the form isn't being accessed by the web, all the input and output needs to be handled there. You can also remove some things from your new script like the code that prints the form interface and since this is all going to be accessed by the computer with pre-programmed input. 6.9.1 Automatic Credit Card Billing You can automatically bill a credit card batch every day by using the Export Credit Card tool, or modify the exportcc.php to be used as a php command line script. Replace the YYYY-MM-DD with the date you want to bill. This will cause CitrusDB to save the credit card batch into a le named exportXX.csv, where XX is the batch number. Your script can read this le and send it to your credit card processor in the format they require. After the credit cards are run you will get a results le from your credit card processor. You can import this manually using the Import Credit Card Batch tool, or you can make a script that will input the results automatically by inserting data into your MySQL database. Here is some example PHP code using the ADODB layer that CitrusDB uses. In order to import this data you will need to know the customer's transaction code, amount they were billed, their billing id, and the response code from the credit card company. This code would usually run in a loop while it reads the results le and does the necessary processing.
// determine if they are a prepaycc or creditcard type // if they are prepaycc then update the billing dates $query = "SELECT b.id b_id, b.billing_type b_billing_type, b.next_billing_date b_next_billing_date, b.from_date b_from_date, b.to_date b_to_date, t.frequency t_frequency, t.id t_id, t.method t_method FROM billing b LEFT JOIN billing_types t ON b.billing_type = t.id WHERE b.id = '$billing_id'"; $typeresult = $DB->Execute($query) or die ("$l_queryfailed"); $mytyperesult = $typeresult->fields; $billingmethod = $mytyperesult['t_method']; $mybillingdate = $mytyperesult['b_next_billing_date']; $myfromdate = $mytyperesult['b_from_date'];
38 of 48
http://www.citrusdb.org/documentation.html
$mytodate = $mytyperesult['b_to_date']; $mybillingfreq = $mytyperesult['t_frequency']; if ($response_id == 'N') { // declined or credit (first letter of response code is an 'N') $query = "INSERT INTO payment_history (creation_date, transaction_code, billing_id, creditcard_number,creditcard_expire, response_code, billing_amount, status, payment_type, avs_response) VALUES(CURRENT_DATE,'$transaction_code','$billing_id', '$cardnumber','$cardexp','$response_code','$amount', 'declined','$billingmethod','$avs_response')"; $result = $DB->Execute($query) or die ("query failed"); } else { // authorized (first letter of response code is a 'Y') $query = "INSERT INTO payment_history (creation_date, transaction_code, billing_id, creditcard_number, creditcard_expire, response_code, billing_amount, status, payment_type,avs_response) VALUES(CURRENT_DATE,'$transaction_code','$billing_id', '$cardnumber','$cardexp','$response_code','$amount', 'authorized','$billingmethod','$avs_response')"; $result = $DB->Execute($query) or die ("query failed"); // update the next_billing_date, to_date, // from_date, and payment_due_date for prepay/prepaycc if ($billingmethod == 'prepaycc' OR $billingmethod == 'prepay') { // to get the to_date, double the frequency $doublefreq = $mybillingfreq * 2; // insert the new dates $query = "UPDATE billing SET next_billing_date = DATE_ADD('$mybillingdate', INTERVAL '$mybillingfreq' MONTH), from_date = DATE_ADD('$myfromdate', INTERVAL '$mybillingfreq' MONTH), to_date = DATE_ADD('$myfromdate', INTERVAL '$doublefreq' MONTH), payment_due_date = DATE_ADD('$myfromdate', INTERVAL '$mybillingfreq' MONTH) WHERE id = '$billing_id'"; $updateresult = $DB->Execute($query) or die ("query failed"); } // update the billing_details for things that still // need to be paid up $query = "SELECT * FROM billing_details WHERE paid_amount < billed_amount AND billing_id = $billing_id";
39 of 48
http://www.citrusdb.org/documentation.html
$DB->SetFetchMode(ADODB_FETCH_ASSOC); $result = $DB->Execute($query) or die ("query failed"); while (($myresult = $result->FetchRow()) and ($amount > 0)) { $id = $myresult['id']; $paid_amount = $myresult['paid_amount']; $billed_amount = $myresult['billed_amount']; // calculate owed $owed = $billed_amount - $paid_amount; if ($amount >= $owed) { $amount = $amount - $owed; $fillamount = $owed + $paid_amount; $query = "UPDATE billing_details SET paid_amount = '$fillamount' WHERE id = $id"; $greaterthanresult = $DB->Execute($query) or die ("query failed"); } else { // amount is less than owed $available = $amount; $amount = 0; $fillamount = $available + $paid_amount; $query = "UPDATE billing_details SET paid_amount = '$fillamount' WHERE id = $id"; $lessthanresult = $DB->Execute($query) or die ("query failed"); } //end if } // end while } // end if
6.9.2 Automatic Invoice Printing The Invoice Printing tool can be run daily, you can modify the invoice.php to be used as a php command line script. This will cause CitrusDB to output a PDF le back to the browser for all the invoices for the data specied in YYYY-MM-DD format. Your script can then get this le and send it to a printer or save it to a hard drive for printing later. 6.9.3 Automatic Invoice Emailing The Invoice Emailing tool can be run daily, or you can modify the einvoice.php to be used as a php command line script. This will cause CitrusDB to begin emailing invoices to the customers who have billing on YYYY-MM-DD.
http://www.citrusdb.org/documentation.html
stores credit card data and is not currently subject to PA-DSS certication. While CitrusDB itself is not required to be certied since it does not connect directly with a merchant bank, it must still be be installed and implemented in a way that meets the information security requirements that each merchant is subject to prevent attacks and comply with credit card regulations and local privacy laws. The PCI Data Security Standards are a good starting point when implementing security for any billing system. The standards outline the following requirements: Build and Maintain a Secure Network: Update passwords regularly and maintain a rewall. Protect Cardholder Data: Protect stored cardholder data, encrypt the transmission of cardholder data on public networks like the Internet. Maintain a Vulnerability Management Program: Use anti-virus software, and maintain secure system and applications by keeping them up-to-date. Implement Strong Access Control Measures: Require unique ID and passwords for those with computer access to cardholder data. Restrict access to only those who need it. Regularly Monitor and Test Networks: Track access to the network, and regularly test the security systems. Maintain an Information Security Policy: Develop a security policy that your sta follow when dealing with this information. This is a simple overview of these security standards. You can nd the complete documentation online at https://www.pcisecuritystandards.org/
41 of 48
http://www.citrusdb.org/documentation.html
should be set to the path to the folder you wish to store imported and exported credit card data inside. The path should be outside of your web server's le path, and if possible outside of PHP's include path to keep it away from http queries.
7.3 Passwords
Passwords to access the server, database, and web interface should be strong to help prevent password guessing. Strong passwords avoid the use of dictionary words or all numbers, they include upper and lower case letters, numbers, and punctuation symbols. Longer passwords are stronger than short ones, even just a few letters can make it signicantly harder to brute force. Passwords in CitrusDB are stored in a salted bcrypt or md5 hash to make them harder to recover from the database. If a user forgets their password the administrator will need to set a new one using the User editing tool. If the administrator forgets their password, they will need direct access to the database via SQL queries or a utility like phpMyAdmin to put a new password on their user record. You will need to hash your password using the phpass framework before you paste it into the database record.
42 of 48
http://www.citrusdb.org/documentation.html
To change they key you will need to rst decrypt all the card data in the database. This will need to be done when the database is not being accessed by any users or other processes. Run the decryptcards command from the main citrusdb folder. This will go through and decyrpt all the cards in the database using the gpg decrypt command from your cong le. The decryptcards command takes the passphrase input on the command line, so you may want to run this command from the console in single user mode if you want to ensure nobody else may log in while doing this. This can take a long time depending on how fast the server is and how much card data there is. After you have decrypted the card data you can create your new gpg key and setup the gpg encryption command to use this new key. Then run the encryptcards script to encrypt all the cards in the database with the new key.
43 of 48
http://www.citrusdb.org/documentation.html
This table keeps track of the following: The Date and Time of the activity The CitrusDB user who generated the request if they are logged in IP Address the request came from The account number of the record the activity occured on The type of activity, login, logout, view, edit, create, delete, undelete, export, import, cancel, or uncancel The type of record, either the tools dashboard screen, customer record, billing record, service record, or creditcard record The record id number if the activity occured on an specic record The result of the request, either a success which most queries will be, or a failure, such as a login failure. This table of data should be exported out of the database by a seperate log watching script as often as necessary to satisfy your reporting needs.
8 Online Resources
Thank you for reading the CitrusDB Usage Manual. I hope this will allow you to take CitrusDB and use it with your organization to meet your billing and customer service needs. For additional information please join our mailing lists and visit the website. citrusdb-announce mailing list: https://lists.sourceforge.net/lists/listinfo/citrusdb-announce This mailing list is for announcements of new versions and critical updates to CitrusDB. All users of CitrusDB are encouraged to subscribe to this list to make sure they have the latest updates. citrusdb-users mailing list: https://lists.sourceforge.net/lists/listinfo/citrusdb-users This mailing list is where users can discuss issues with other users and nd solutions. Home Page: http://www.citrusdb.org
44 of 48
http://www.citrusdb.org/documentation.html
This is the home page for CitrusDB, this will connect you to all the information about CitrusDB . The latest release is always available for download on the home page. Bug reports and development: http://www.launchpad.net/citrusdb The launchpad site hosts the bug report list, source code in bzr version control, and has some blueprints that show future ideas for citrusdb.
45 of 48
http://www.citrusdb.org/documentation.html
disks) during the prime generation; this gives the random number generator a better chance to gain enough entropy. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++. gpg: key 3F9D1764 marked as ultimately trusted public and secret key created and signed.
http://www.citrusdb.org/documentation.html
gpg edit-key
http://www.citrusdb.org/documentation.html
This allows the user to factor in their own preferred algorithms when algorithms are chosen via recipient key preferences. The most highly ranked cipher in this list is also used for the symmetric encryption command. -no-tty This will tell gpg not to expect any TTY input -skip-verify This will tell gpg to skip the verication of signatures. It can make gpg faster when one does not need to verify signatures.
This will create the 2048bit RSA private key. You can add -des3 to this command if you want to password protect the key, however that will require you enter the password whenever the web server starts up.
openssl req -new -key webserver.key -out webserver.csr
This command will create a certicate signing request from the private key. If you are going to send the key to a certicate authority (CA) like Certs4Less for signing then you can send the csr le to the CA instead of self-signing it. If you want to run your web server with a self-signed certicate then you will need to run the signkey command below. If you are using a self-signed certicate your web browser may warn you to conrm and accept the certicate. If you know the self-signed certicate is legitimate this oers the same encryption as any other certicate, however the browser is being cautious since it does not have an authority record for self-signed certicates.
openssl x509 -req -days 365 -in webserver.csr -signkey webserver.key -out webserver.crt
This command will sign request and create a certicate le. After you have a signed certicate you will need to install that certicate into your web server. Author: Paul Yasi <pyasi@citrusdb.org> Date: 2011-01-06 09:20:03 EST HTML generated by org-mode 6.21b in emacs 23
48 of 48