CitrusDB 2.4 Manual

CitrusDB 2.4 Manual

Table of Contents

1 Introduction2 Chapter 1: Installation

2.1 Installing the Main Internal Application2.2 Installing the Public System for Customer Self-Service2.3 Upgrading CitrusDB

3 Chapter 2: Setup3.1 Login3.2 Organization Configuration3.3 Settings3.4 Users3.5 Groups3.6 Billing Types3.7 Holidays3.8 Services

3.8.1 Adding Your Services3.9 Linking Services with Setup Fees, and Bundled Services3.10 Taxes and Fees

3.10.1 Linking taxes3.11 Field Assets3.12 Searches3.13 Attribute/Option URL Links3.14 Setup Finished

4 Chapter 3: Customer Service4.1 Searching for Customers4.2 Customer Records4.3 Billing Records4.4 Editing Billing Records4.5 Invoice Maintenance4.6 Individual Billing Record Refund Report4.7 Prorate Services4.8 Service Records

4.8.1 Example Billing Combinations4.8.2 Edit Service Records4.8.3 Service History

4.9 Customer Notes4.9.1 View notes sent to you4.9.2 Editing a customer support note

4.10 Billing Status4.11 Billing History4.12 Payment History4.13 Billing Details

CitrusDB 2.4 Manual http://www.citrusdb.org/documentation.html

1 of 48 Wednesday 24 April 2013 05:47 AM

4.14 Re-Running Declined Credit Cards4.15 Welcome Letters

5 Chapter 4: Billing and Payments5.1 Billing Tools

5.1.1 Credit card batches5.1.2 Invoice printing5.1.3 E-Invoice emailing5.1.4 Entering Payments5.1.5 Processing Refund5.1.6 Importing New Accounts5.1.7 Importing Service Usage5.1.8 Importing Credit Card Changes

5.2 Reports5.2.1 Customer Summary5.2.2 Revenue Report5.2.3 Refund Report5.2.4 Past Due Report5.2.5 Payment Status Report5.2.6 Service Report5.2.7 Source Report5.2.8 Exempt Report5.2.9 Print Notices5.2.10 Service Growth

6 Chapter 5: Server Administration and Integration6.1 Backups6.2 Custom Modules6.3 Account Activation and Deactivation6.4 Credit Card Batch Exports Format6.5 Credit Card Batch Imports Format6.6 New Accounts Data Format6.7 Service Usage Data6.8 Credit Card Change Format6.9 Automation

6.9.1 Automatic Credit Card Billing6.9.2 Automatic Invoice Printing6.9.3 Automatic Invoice Emailing

7 Chapter 6: Data Security Implementation Guide7.1 CitrusDB Configuration7.2 Physical Data Center7.3 Passwords7.4 Encrypting and Decrypting card data

7.4.1 Encrypting existing card data7.4.2 Changing encryption keys for card data

7.5 Purge old cardholder data7.5.1 Remove Exported Batch files7.5.2 Remove Canceled Customer Records

7.6 Logging of user activity7.7 Keeping Up-to-Date



8 Online Resources9 Appendix A: GPG Commands

9.1 Creating A Key9.2 Listing Public Keys9.3 Listing Private Keys9.4 Export Public Key9.5 Export Private Key9.6 Importing Public Key9.7 Import Private Key9.8 Delete a Public Key9.9 Delete a Private Key9.10 Encrypt Data with Ascii Armor9.11 Decrypt Data9.12 Edit a Key9.13 Key Signing9.14 Key Trust9.15 Revoke a key9.16 Command Options

10 Appendix B: OpenSSL Certificate

1 Introduction

CitrusDB is an open source customer service and billing database. It can be used bycustomer service personnel to provide sales and support to customers, and by billingstaff 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 greaterMySQL 4.x or greaterAn SSL Certificate for the domain where it will be installed (Can be self signed)A GPG Key Pair if you are storing credit card dataA Web Browser with Cookies and Javascript

2 Chapter 1: Installation

Before you install CitrusDB you should check whether a web server with the PHPmodule, 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 file toyour server that contains the following code:

<?php phpinfo(); ?>



View your uploaded file in a web browser by going to your site, eg:www.yourname.com/file.php This will show you what version of PHP you are runningand a lot of information about your PHP installation. Further down the screen therewill be a section about your MySQL installation that will confirm whether MySQL issupported by your PHP installation. If the file you uploaded does not load, give anerror, or does not show anything about MySQL, your server is not configuredcorrectly. You will need to fix this before you continue.

There are many methods to install a web server, MySQL and PHP on your server. OnLinux you will usually be able to find a package available for your distro that you caninstall via a package manager like synaptic, apt-get, or yum. Mac OS X already hasApache installed by default, all you'll need to do is enable PHP and install MySQL oryou can use a pre-built package like XAMPP. If you are using Windows you can try thepre-built packages like XAMPP that include all the pieces you need for Apache,MySQL, and PHP. Microsoft also maintains PHP packages available for windowsservers.

After you have installed your server software you can begin installing CitrusDB. Themain internal application is the largest part of CitrusDB. It is built for use bycustomer service representatives to handle customer service queries and sales, billingstaff to send bills and process payments, and by administrators to activate newservices, deactivate services, and monitor customer service operations.

If you are simply trying out CitrusDB it can be installed on any server you like. Whenusing CitrusDB with real production data it should be installed on a private LAN or ona well protected web server with limited access by using firewalls and SSL, or othercomparable security measures to protect your customer data and limit access to onlyyou and your staff. Follow the steps below to begin your installation.

2.1 Installing the Main Internal Application

Un-tar and un-gzip the citrus file wherever you want the CitrusDB program to belocated on your web server.Create a MySQL database called "citrus" using the citrus.sql file. You can do thisusing a utility like phpMyAdmin or the command line like the one shown here:

mysqladmin create citrus mysql citrus < /path/to/citrusdb/citrus.sql

Create a MySQL database user with access to the citrus database you justcreated.Edit the configuration file: /citrusdb/include/config.inc.phpChange the database host, to your server name, often this will be the localhost itis all on one server. Enter your database username and password that you justcreated before.

$sys_dbhost='localhost'; $sys_dbuser='username';



$sys_dbpasswd='password';

Change the path to citrus variable to the filesystem path of your installation:

On a unix installation it may be something like these depending on where youinstalled your citrus files:

$path_to_citrus='/home/username/citrusdb';

or

$path_to_citrus='/var/www/citrusdb';

On a windows installation it may be something like:

$path_to_citrus='C:\apache\htdocs\citrusdb';

Change the hidden hash var to your own secret hashphrase. You will never needto 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 file. This localization fileholds 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 prefixes for your site. You should use the samename for both the regular url and ssl url with the only difference being http orhttps for the protocol. This will ensure the session cookie assigned during ssllogin is available to the regular http url as well. You may use a self-signedcertificate for this function as long as all the users of the database have that SSLcertificate installed into their browsers. The CitrusDB project is an affiliate ofCerts4Less where you can get an SSL certificate signed by a number ofcertificate authorities at different 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 probablya good idea to generate a gpg keypair just for citrusdb to use. This public keycan then be used on the order side to store credit card numbers before they areimported as well as storing cards entered directly into citrusdb.

To generate a keypair run the command: gpg –gen-key



I recommend using the shortest recommended key length of 1024 bits since thiskey will be used over and over again, using the shorter key length will makedecryption faster. This is a trade off of speed vs. strength. One could also use gpgwith the symmetric encryption option or any other encryption system that canoutput an OpenPGP ascii armor message format. Symmetric encryption could besignificantly faster, however it will require protection of the passphrase that isused when encrypting the card data.

The example shown below stores the gpg key as the www-data user in theirhome directory. This home directory was created for the user that the web serveris running as. This is the easiest way to make sure that the web server runningcitrusdb has access to the keys that it will use to encrypt and decrypt the carddata. If the web server where you run citrusdb is inside your network anddedicated to your internal use this should not be an issue. If you are unable to dothis, then you will need to modify the permissions of your .gnupg folder and thekeyrings inside of it to be readable by everyone. This is less desireable as it mayexpose them to other users of that system as well as cause permission problemsin 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 batchexports or when re-keying the data. The decrypt command must include the–passphrase-fd 0 command because the passphrase will be passed to gpg bycitrus'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 enteredbefore creating a batch file.

$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 theldap variables. Set the ldapenable variable to TRUE and the other variables tocorrespond to your LDAP configuration. You should make sure you haveconfigured your ldap server to work with ssl so that the data passed between theweb server and the ldap server is not able to be intercepted by using the ldapsprotocol.You will need to have the user configured inside of the citrus user utilities toallow them to login with LDAP, but you can manage their password using yourLDAP system.

$ldap_enable = FALSE;



$ldap_host = 'ldaps://localhost'; $ldap_dn = 'ou=webapps,dc=localhost'; $ldap_protocol_version = 3; $ldap_uid_field = 'uid';

If you have an xmpp or jabber server for ticket notifications you can setup thosexmpp account variables to allow citrus to send ticket notifications via xmppinstant messages.

$xmpp_server = "";$xmpp_user = "";$xmpp_password = "";$xmpp_domain = "";

A shipment tracking website URL like the one for US Postal, FedEx, or UPS canbe entered if you want to use the field asset tracking number field when shippingfield assets to customers.

$tracking_url = "http://trkcnfrm1.smi.usps.com/PTSInternetWeb/InterLabelInquiry.do?or

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 thecustomer's account status and create a file that can be used to activate anddeactivate 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 finished the main installation of CitrusDB. It's a good idea to login andchange your admin password first. If you are not going to install the customeraccount manager can skip to Chapter 2 - Setup, to continue to setup of the internalCitrusDB application.

2.2 Installing the Public System for Customer Self-Service

CitrusDB also includes an online customer component for customers to viewinformation about their own account, request changes, and make updates. The onlinecustomer account manager is stored in the /online folder of the CitrusDB download. Itis a simple interface for customers to login using their customer number andpassword of their choice.

The online folder is meant to be installed on a separate web server. If you have afirewall, you'll want to configure it to allow access to the database server from thisweb server, so that the online component can query the customer information. It isalso recommended to make a new login name and password for use by the onlinecustomer component that has more restrictions than your normal database user fromthe main system. This new database login name should restrict the access to yourcitrus database to SELECT only, allowing INSERT for only the customer_history tableand SELECT, INSERT, UPDATE, and DELETE for the session2 table.



The online customer system is configured similarly to the main system by editing theconfig.inc.php file inside the citrusdb/online/include folder. There are some additionalvariables to configure for the online customer system.

The $payment_url variable should be set to whatever online form or payment systemyou have such as authorize.net, paypal, your own custom form etc.

The $notify_user variable holds a username from the internal system that will benotified of new requests that customers make online.

2.3 Upgrading CitrusDB

When a there is a new installation or critical security update, you will want to be ableto upgrade your installation to the latest release. To update from an older version to anewer one:

Backup the php files by copying them to another location and backup your citrusdatabase by using a utility like mysqldump.

mysqldump –user <username> –password <passwd> db_name > backup.sql

After you have backed up your current installation, replace the old citrusdb fileswith the new ones from the package you downloadedEdit the config.inc.php in /citrusdb/include with the database and pathinformation from your old config file.To update your database schema from the old to the new, open the update.phpfile in your web browser (www.example.com/citrusdb/update.php) and click theUpdate button.Your database has now been updated, and you are ready to use your new versionof CitrusDB.If you are upgrading from version 1.x to 2.x you will need to make sure you havesetup the new gpg commands in the config file and then run the encryptcardsscript to encrypt the cards in the database.

3 Chapter 2: Setup

3.1 Login

After you have installed CitrusDB the first thing you should do is login with thedefault username (admin) and password (test) and then go update the password tosomething new. To update the password, click on the Tools icon, and then click onChange 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 loginwith the correct username and password after 5 tries in the last 24 hours. If thishappens, your IP address must be removed from the login_failures table by thedatabase administrator.



3.2 Organization Configuration

The Organization Configuration section holds information about the company ororganization using CitrusDB. This should be the first thing you configure when settingup CitrusDB. The information is used in many places for invoices, billing, andcustomer messages.

The Billed By field holds the organization's brand name. If you have more than oneorganization brand name you can add multiple organization brands using the Add linkto create more than one organization listing. This is used to create bills underdifferent brand names and different credit card batches for those brands. If yourorganization does not need multiple brands you can simply edit the defaultconfiguration.

Enter the organization's name that will appear on the bill in the Billed By field. Thenthe street, city, state, zip, phone, and email information. The billing phone and billingemail will appear on the printed and emailed invoices.

Credit Card Export Variable Order is the order of the variables that are exported inthe credit card batch file for processing by your credit card processing system. Youcan export a number of different variables. All the available variables are listed at thebottom of the organization screen. Please note that you need to put the $ in front ofthe variable name so that they are evaluated correctly. CitrusDB will insert the words"CREDIT" or "CHARGE" in quotes at the beginning of the variables, depending onwhat kind of credit card transaction this is. The recommended export format usescomma and quote delimited items. You must keep the commas between the items andquotes around them to make sure other systems can import the information correctly.

"$mybilling_id","$invoice_number,"$billing_ccnum","$billing_ccexp","$abstotal"...

Export File Prefix is is appended to the beginning of all credit card batch filesexported by citrus. If you have multiple organizations exporting from the same citrussystem, you can use this file prefix name to identify which exported batches belong towhich organization.

Past Due Days are the number of days an account is past due before the status isupdated by the statusupdate script to one of the three different past due status types:Past Due, Turned Off, or Canceled. Past Due accounts will be noted as past due andwill be notified in email by the statusupdate script about their status. A Turned Offstatus will cause the account to send a disable message to the account activationsystem, which can then disable access to the account. An account in a Turned Offstatus should be disabled and non-working. The Canceled status is for accounts thathave been through the first two phases of being past due and have not yet paid forservices. Canceled will send a delete message to the account activation system. Theaccount should be removed from your systems, and if you have a collectionsdepartment or processing system, can be forwarded to them for past due amountrecovery.



Carrier Dependent Past Due Days are for third party services that have specialrequirements when they are turned off. They act the same as normal Past Due Dayshowever they have a Shutoff Notice period in between being Past Due and havingtheir service being Turned Off. This shutoff notice is to notify the customer that theirservice will be turned off and also to notify the billing group that the service is injeopardy of being shutoff. The billing group will receive notifications when this serviceis to be turned off or canceled, since they will need to be able to contact the thirdparty service carrier to handle type of cancel request.

The next fields are the four different kinds of invoice notes that are printed at thebottom of the invoices according to the account status. The Default Invoice Note isprinted on an account in good standing, usually this is a note thanking them for usingyour services. The Past Due Invoice Note is printed on invoices while an account is inthe Past Due status. The Turned Off Invoice Note is printed on invoices while anaccount is in the Turned Off status. The Collections Invoice Note is printed oninvoices for accounts in the collections status. These messages can be overridden byentering a custom message in the Notes field on the customer's billing record.

The declined subject and message field hold the data used in the email that is sent tocustomers when their credit card has been declined. Here you should enter amessage that will prompt them to contact you and get their billing information up todate.

The last field is an invoice footer field that holds text that will be placed at the bottomof every invoice.

After you have setup the organization information you are ready to save your changesand 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 CitrusSoftware Version. The database version is the version of the SQL Schema that isbeing used. The software version indicates the version of the software applicationfiles. These two versions should be the same. If they are different it may mean thatyou have not run the update script to update your database to the correct version orthat you are running a Pre-release version of CitrusDB.

The Path to Credit Card File should be set to a file path on the server to a folder thatis outside the path of the web server and other network processes. When credit cardand account activation data is created it will be saved to a new file inside this folder.You can then write scripts that will automatically process new files left in that folder,or download those files to process them manually. You should make a new folder tostore this data in, for example, on a Unix system you can set this to something like

/var/billing



and on a Windows system it can be set to a path such as

C:\billing

This will keep this data outside of the web server path, but will still allow it to beaccessed by 3rd party scripts running on the server that can process this dataautomatically.

The Default Group is used by the support notes and privileges system to allownotifications to certain users. Normally leaving this as the default of "users" isrecommended.

The Billing Group is a group that you will need to create if you are using the carrierdependent services functions or if you are using the Field Asset feature. The statusupdate script will send the billing group notes if a carrier dependent service is in abad billing status, like past due, turned off, or canceled with fees owed. The fieldasset feature will send a note to billing whenever a device is returned so that thebilling group knows the customer has returned a device and can take measuresnecessary to adjust their bill.

The Shipping Group is a group that you will need to create if you are going to use theShip Field Asset feature. Ship Field Assets lets you associate a field asset like a CPEor other device with that customer's service. The shipping group will get a note whena field asset is setup to be shipped.

The carrier dependent cancel url is for third party carrier dependent services. Thiscan link to an internal web form or other form when a carrier dependent service iscanceled 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 accountscreated after this time will not be billed until the next billing day. This is used toprevent new accounts from being given the current billing date after the batch hasalready been processed for the day. This time field is in 24 hour time format.

The Weekend indicators allow the billing system to automatically skip certain dayswhen assigning new billing dates to new customers. This is especially usefull forbilling around weekends, so that a new customer's billing date does not fall on aweekend. You can choose what days of the week you want to assign as weekendshere.

3.4 Users

The Users Tool will allow you to add CitrusDB database users. This is used to addyour staff personnel that will be using the database to access customer informationand billing. The user tool will show you a list of current users. In the defaultinstallation there will be two users present. An admin user that has all privileges toedit everything about the database, and an online user that is used to demonstratethe online customer account manager's message notification. If you have not yet done



so, you should change the password for both the Admin user and Online Request userto something new.

To add a new user click Add New Database User. You will then be presented with aform to fill 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 toadd new users, edit billing types, add new services, and add new modules. TheManager privilege will allow access to the credit card import/export features,invoices, payments, reports, and account activation. All other users should have Noselected for both Admin and Manager privileges.

You can edit existing users by clicking the Edit link next to their name. This will allowyou to change their tool privileges, their username, and their password. You can alsodelete a user by clicking the Delete link next to their name. When you delete a user orchange their username, any notes they have made will stay in the database undertheir old username. You will also need to update any groups they are a part of toinclude their new username.

3.5 Groups

The Groups tool is used to assign users to different groups for notification andpermission purposes. By default all the users who are added to the database are putin the "users" group. This should probably not be changed, since it affects access tomany pieces of the system. You can add as many other groups as necessary. Forinstance, if you have a group of people who perform shipping duties, you might makea shipping group and assign them to this group. When a particular piece of equipmentis needed you can send a note to the shipping group, which will notify all theindividuals in that group about your message. When someone in the group marks themessage finished, it will dissapear from view of all the people in the group.

This is also where you will add the billing group you specified in the settings tool ifyou are using the carrier dependent service functions.

3.6 Billing Types

The Edit Billing Types tool will allow you to edit what billing types are available in thecustomer's billing record. CitrusDB comes with a number of billing types alreadycreated, so you may not need to create more. In fact, it may be better to delete thosethat you do not need, so they don't get in the way. There are 6 methods of billing:

creditcard: For billing via a credit card batch export.einvoice: For emailing invoices. The invoice is in pdf format, and will be sent tothe email address indicated on the billing record.invoice: For printed invoices.prepaycc: For prepayments done with a creditcard. A prepaid account will nothave it's payment dates updated until payment is made, it will not go into a PastDue status, it will become Not Renewed, and should be turned off if leftun-renewed.



prepay: For prepayments done via checks, cash, or electronic funds transfer. Aprepaid 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 beturned off if left un-renewed.free: For free accounts. These accounts will never be billed and will never bepast due. The free billing type can be used for items like demo accounts ortemporary free items.

If you need to add new billing types, they can be added using the form at the bottomof the Edit Billing Types tool window. You will need to provide the name of the newbilling type. This will show up in the list in the billing record. The frequency of thebilling type. This frequency is used to determine how often (in months) that billingtype is processed. For example a Monthly billing type would use a frequency of 1, aYearly 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 willwant to make sure that none of your current billing records are using that billingtype, otherwise they may not get billed properly.

3.7 Holidays

CitrusDB has a table in the database called "holiday". This table consists of just onedate field called "holiday_date" that holds dates that are billing holidays when billingis not preformed. If a new customer's billing date should fall on one of these days itwill be moved up a day until it does not fall on a holiday. You should determine whatholidays there are during the year that are not already covered by the weekendssetting when billing will not be performed and add those dates to the table. This tablecan only be edited by using a database editor such as phpMyAdmin or SQL insertqueries.

3.8 Services

CitrusDB comes with a default example service, credit, and prorate services. To makeCitrusDB work for your organization you will have to add your services using the EditServices tool. CitrusDB can support many different kinds of services, one timeservices and fees, recurring services, taxes and fees, linked or bundled services, andservices with measured usage or hourly cost.

Open the Edit Services tool to see all your current services. Click Add New Service tobegin 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. Thiswould only change if you have more than one brand organization inside of your



citrusdb installation.

The Description field holds the service name that will appear in the service listing andon invoices.

Price holds the unit price of the service. For example if you have a service that is 9.95per month, enter 9.95, if you have a service that is 39.95 per year, enter 39.95, aservice that is 70.00 per hour, enter 70.00.

The Frequency indicates the service's monthly billing cycle. A service that is billedmonthly would have a frequency of 1 (for every month), a service that is billed yearlywould have a frequency of 12 (for every 12 months), a service that is only billed onetime would have the special frequency of 0 (zero) for a one time service. One timeservices are automatically removed from the customer's service record listing and putinto the service history after they are billed.

The Options/Attributes Table field holds the name of the table that holds theattributes for that service. When you make a service, you can also name a table in thedatabase that holds the attributes that are associated with that service, such aslocation, equipment, usernames, special contact info, anything that may be associatedwith that service itself. This options table name is not required, so if your service hasno attributes you can leave this blank, however if you add an attributes table at alater time the services that were already added will not be associated with the newattributes.

The attributes tables allow CitrusDB to support any kind of service at all, so it is notlimited to one industry. If you are making a new attributes table, choose a table nameand enter it in the Options/Attributes Table field. After you have added the service, goto the Options/Attributes Table link at the top and click Create next to the table namein the listing. This will create an empty table with the correct fields to link it with yournew service. You can then add any attribute fields you want after the first tworelationship fields, using SQL alter table commands or a tool like phpMyAdmin.

Most of the attribute fields will be shown as simple text fields, however if you want tomake a menu of choices, or a Yes/No choice, you can use an enum field type that willshow all the items in the enum within a drop down selection on the web page. You canalso add text or blob fields that will be shown as textarea entry fields.

The Category field is a case sensitive name of a category to group the service underwhen choosing services to add to the customer's service record. This can be left blankif you only have a few services, but when you have many services it will be helpful toorganize them into categories so you can jump to the type of service you are lookingfor.

Selling Active is on by default. It indicates whether this service is currently beingsold. If set to Yes, it will show up in the list of services that can be added to anaccount. If set to No, it will not show up in the list of services that can be added to anaccount, however it can still be billed to customers who still have the service. Thiscan be used to deactivate services that were only available for a limited time and are



still being billed, but are no longer available for new sales.

The Hide Online field is set to No by default. This indicates whether you want to showor hide this service in the customer account manager and in the default view whenadding services. You will probably will want to hide services such as setup fees, installfees, and sometimes bundled services. The services are hidden to regular internalCitrusDB users, and are only visible to manager and admin users using the Show Alllink when adding services to a customer.

The Activate Notify field holds the username or group name of the CitrusDB user whowill 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 aboutservices being added to an account if further manual processing is required.

The Shutoff Notify field holds the username or group name of the CitrusDB user whowill be sent a support ticket note when this service is removed from an account. Thiscan be used to notify order coordinators or a service activation department aboutservices being removed from an account if further manual processing is required.

The Modification Notify field holds the username or group name of the CitrusDB userwho will be sent a support ticket for services are are to be enabled, that werepreviously disabled, but not totally shutoff.

The Support Notify field holds the username or group name of the CitrusDB user whowill be entered by default in new support tickets that are opened for this service.

Activation String is used to hold the field names that are passed to the statusupdatetool with this service. For example, when you add a new Internet account service youwill probably want to provide the username and password from the options_table tothe account activation system. To do that enter the string “username,password” in theActivation String field. The field names must be entered in matching case and becomma seperated with no spaces or other characters between the field name.

The Usage Label is used to label the Measured Usage field when adding measuredusage services. For example if you have a service that is 70.00 per hour, you wouldput “hours” in this field, or if you have a service that is 5.00 per gigabytes, you wouldput “gigabytes” in this field.

Carrier Dependent services are those that are provided by a third party that needs aseperate notification of service activation and deactivation that is not part of yourown account activation system. A Carrier Dependent service has additional stepswhen they are being deactivated that will send a shutoff notice to the customer tomake sure they are aware the service is being shutoff. It will also send simultaneousnotifications to the default billing group that is indicated in the Settings so that groupcan take care of communication to the third party carrier about what to do with a pastdue, turned off, or canceled service.

A carrier dependent service that owes money when their account is canceled will bemarked as the status cancelwfee instead of canceled so that the billing group can find



those customers and go after them for the money they owe. This is usually necessarysince as a provider you will owe money for those services to the third party that wasproviding them and will have more incentive to collect on those charges rather thanjust cancel that service and be done with their account.

After you have filled in all the relevant service information you can click the Addbutton to add your new service to the database. You can now assign this service toyour customers.

If you have many many services to add it may be easier to make a spreadsheet withall their attributes and import them into the master_services table directly using SQLinsert queries or a database editor such as phpMyAdmin.

3.9 Linking Services with Setup Fees, and Bundled Services

Setup Fees and Bundled services are added like any other service using the Add NewService function. After you have added the setup fee or bundle service, choose theLink Services item to connect them to the service it goes with. For example, you maymake a link From a Monthly Service Account to a Service Account Setup Fee. Nowwhenever a Monthly Service Account is added, the Setup Fee is automatically addedto the service record also.

3.10 Taxes and Fees

CitrusDB comes with some default tax rates for certain locations. This data may beincorrect or out of date, please consult your local tax code to make sure you arebilling for the correct tax amounts.

To add a new tax rate click the Taxes link in the Service Editor. and then click on TaxRates. At the bottom of the Tax Rates screen is a form to add new Tax Rates. TheDescription holds the name of the tax, for example “Massachusetts Sales Tax”. TheRate holds the percentage of the tax, for a 5% tax enter “0.05”. The If-Field holds thename of the field in the customer record that is checked to see if this tax applies tothe customer. For example, if the tax is based on what state a customer is in, enter“state”. The field names are the names according to the SQL database names formatching customer table columns, and will usually be in all lower case. The last fieldis the If Value, if this tax is for customers who are only in the state of Massachusetts,enter “MA” in the Value field. You can leave the If Field and If Value fields blank if thetax is applied regardless of the customer attributes.

You can remove tax rates by clicking on the Delete link. Make sure you do not haveany services associated with that tax rate before removing it, or you may not bill themcorrectly.

3.10.1 Linking taxes

After you have added your applicable tax rates you need to link those taxes to theservices that are being taxed. Click on the Taxed Services item. Here you can link a



service with a tax. The tax will be added to customers with that service if thecustomer record meets the If Field/Value checks, and if the customer is not taxexempt for that tax type.

3.11 Field Assets

Field assets refer to devices out in the field like customer premises equipment (CPE)or other devices you want to track that are associated with a service.

To add Field Assets to a service first you must setup what Field Assets types areavailable for each category of service. Open the edit services tool and click on EditField Asset Types. Here you can enter the device description, choose the status ofcurrent for devices that you are currently shipping to your customers. If you havedevices in the field but do not ship them to customers anymore you can change thedevice to the old status using this same edit screen. You can enter the weight of thedevice here which is not used yet, but may be used some day to calculate a shippingfee. Finally choose what service category that this device belongs to.

Now that you have added your Field Assets when you edit a customers' service youwill see a choice called Ship Field Asset under the service attributes. If you want totrack a field asset shipment you can then choose the type of field asset you areshipping and then enter the device details and shipping information. This will nowassociate this device with that service record and will show you that device on theservice edit screen.

If one returns the field asset device you can edit the customer's service record andclick on Return Device and enter information about why the device has beenreturned.

3.12 Searches

CitrusDB comes with a number of searches pre-installed in the searches table. Searchfields are edited in each module's search.php file and show up on the search page.You will probably want to create search queries for your new service attributes, soyou can find services by the specific attributes that have been specified in theiroptions/attributes table. You can add new searches by adding a new row to thesearches table. For example in the query field:

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 filled out in the search form. Then link to thesearch 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 file and add new htmlfor a form:

<form ACTION="index.php?load=dosearch&type=fs" METHOD="POST">



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 field inputs by naming each field s1, s2, s3, s4, or s5.

3.13 Attribute/Option URL Links

You can add a link to the right of the service attribute field that will allow users toquery a web address with that service attribute. This can be used for things likechecking the finger results on a Unix server or checking other account status througha website. The URL Options Links are stored in a table called options_urls. You canadd new links or edit existing ones using SQL queries or a utility like phpMyAdmin.The URL link is matched by the name of the attributes table field, so any attributestable with a matching name will get a link next to it. For example if you have ausername field and you want people to be able to run a finger.cgi on any attributetable field with a name of username you would make a new entry into the options_urltable with the fieldname of username and a url such as

http://www.example.com/finger.cgi?%s1%

the %s1% is a place holder where the value of the attribute will be put into the URL.

3.14 Setup Finished

You have now completed the setup of CitrusDB to work with your organization. Youcan now begin adding customers and billing them for services!

4 Chapter 3: Customer Service

CitrusDB helps make customer service easier by putting all the customer information,billing records, service information, and payments in one easy to access location.

4.1 Searching for Customers

After CitrusDB has been setup and customers have been entered into the database,the most common thing one will do when first dealing with a customer is search fortheir record in the database. To search for a customer record, click the Search icon atthe top of the screen. This will show you the available searches you can perform. Youcan find customers by their account number, their name, their company, and manyother bits of customer information. Additional searches can be added by the serveradministrator by editing the searches table and search.php files, detailed in chaptertwo.

4.2 Customer Records



When you have a new customer to add to the database click the New icon at the topof the screen. This will prompt you to fill in some standard customer information,such as their name, address, and phone number. After you have filled in theirinformation, click the Add button. This will make a new customer record, and takeyou to the customer record where you can begin adding their new service and billingrecords by clicking on the service and billing tabs on the left. Adding new service andbilling records is detailed below. After you have added service and billing records forthe customer, that record is considered complete and ready for billing and serviceprovisioning.

To edit the customer's record click the Edit Customer link at the top of the customerrecord screen. This will allow you to edit the information about the customer, such astheir address, phone number, or email address. When you edit the customer record,this does not automaticaly affect their billing record. After you have saved yourchanges to the customer record you will be promted to update the billing record withthe matching information. Click Yes if the customer's billing information shouldmatch. Otherwise you will need to edit the billing record seperately.

If a customer wishes to cancel their services and will no longer have any customerrelationship with your organization, you can cancel a customer using the Cancel linkat the top of the customer record. You will then be asked if you are sure you want tocancel this customer. When you cancel a customer it will deactivate all the services ontheir account and the account will no longer generate new bills for services. If youwant to un-cancel the customer's record you can click the Uncancel customer linkthat will show up on a canceled customer record. Add their services back onto theaccount, and edit their billing so that it begins billing them as before.

4.3 Billing Records

After you have added a customer record you'll want to edit their billing record. Clickthe Billing tab on the left side. If this is a new customer, the billing record will havecopied the customer address from the custsomer record, but will have empty billingmethod and may have ivalid billing dates. If the customer's contact information willnot match their billing contact information, you must edit the record to add theirbilling address information to the billing record. You are then ready to edit their restof their billing record.

Most customers will have just one default billing record. Alternate billing records canbe associated with services when those services require billing that differs from thecustomer's default. To edit the default billing record click the Edit Default Billing linkat the top. If you need to edit an alternate billing record, click the alternate billingrecord's ID number in the alternate billing list. This will bring up the billing recordeditor.

4.4 Editing Billing Records

In the billing record editor you can update their billing address, phone, email andbilling type. When you add a new customer billing record much of the address



information will be copied from the customer information so that billing can beprocessed. If you didn't copy the customer information into the billing record whenediting the customer record, you'll need to start by filling in the customer's billingcontact information. This will hold the address that an invoice is mailed to, the emailaddress an e-invoice is emailed to, and the address that a credit card is verifiedagainst.

You will also choose the billing type here. There are many billing types to choosefrom. Depending on what kind of services the customer has, it may restrict whatbilling types are compatible with that service. A service cannot have a billing typethat has a billing cycle frequency that is smaller than the service frequency. Forexample, if the customer has a service on their record that is a Quarterly SubscriptionService that is billed every 3 months, they must have a billing type that is also billedevery 3 months or a greater multiple of 3 months, such as yearly (which will multiplythat service cost * 4 when billed yearly). This is one of the reasons you may need toadd alternate billing types to an account, if the customer has services that are billedat many different intervals.

When you add a new billing record the next billing date is filled 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 isautomatically set according to the length of the billing cycle specified by the chosenbilling type. The payment due date is also entered as today's date on a new billingrecord. A payment due date of today may be fine when billing is done by daily creditcard batches, however if the service is invoiced or billed differently, this date mayneed to be edited. The payment due date is very important to get right if you areusing the statusupdate script to automatically update customer status information.That script relies on the payment due date to determine what status the accountshould be in, whether to turn it off or back on etc.

When accounts are billed by credit card, invoice, or einvoice, the billing dates aremoved forward automatically according to the billing type's cycle. Accounts with aprepaid billing type will have their billing dates automatically moved forward afterthe currently due payment has been made.

4.5 Invoice Maintenance

The Invoice Maintenance link is available for each billing record. This allows you toview all the invoices or bills ever generated for this account. Here you can reprint theinvoice in pdf or html format, or re-email the invoice to the customer by clicking theemail link. Invoices that have not been associated with payments yet may be removedby clicking the Remove link. When an invoice is removed, the billing history record,and details of the items on that invoice is also removed. Invoices will usually only beremoved when a billing issue requires making a new replacement invoice. You mayalso use the Enter Payment link to open a payment screen with the invoiceinformation already filled in.

4.6 Individual Billing Record Refund Report



The Refund Report link available on each billing record allows you to indicate whichservices to refund on that billing record. Credit card billing type refunds will beadded to the refund batch run from the refund batch tool. Invoice or E-Invoicedbilling type refunds will need to be processed manually. It will show you a list of allservices billed to that billing record and allow you to indicate a refund amount forthose services that have already been paid for.

4.7 Prorate Services

If billing is not performed daily, the next billing date field may need to be edited toconform to your billing cycles, and prorate service types will need to be added to theaccount to make up the difference in price.

Most installations of citrusdb include a pre-made Prorate service. This service may behidden from view of regular users, an admin or manager may need to add the Proratetype using Show All. If you do not have a pre-made Prorate service you will need toadd one. A Prorate service is simply a service with a frequency of zero, a Price rate of1, and a Usage Label of whatever currency you are using.

First add the service they are getting to their account and then add a onetime prorateservice to the customer's account. When adding the prorate service set the MeasuredUsage Multiple to the amount you want to prorate the account for to get it into theright billing cycle. You need to do a little math here on your own. For example, if youadd a 19.95 service, in a 30 day month each day is 0.665 cents. If you want to billthem on July 1st, and today is June 8th, then there are 22 days of prorated service,which is 14.63. So put 14.63 in the Multiple field. Their first bill will then equal 34.58with the service item plus the prorate item.

In the billing section for that customer you would set their next billing date to be July1st, set the from date to July 1st also, and then it will fill in the to date equal towhatever number of months the billing type covers starting July 1st, so if you had amonthly invoice service the to date would be August 1st. This will make the billingdates at the top of the invoice not exactly match the prorate time period since there isa prorate item in there and they really started service on the 8th. In the proratedescription one could put the date of the prorate period.

4.8 Service Records

The service record tab will show you a list of the current services that are on theaccount. To add new services to an account click Add Service on the Services tab.This will bring you to a list of all the services available for sale. Scroll down the list, orchoose the service category to jump to a category of services to choose from. Clickthe Add button to begin adding the service.

When you are adding a service, it will then bring up the service editor which willallow you to fill in fields for any service attributes and the measured usage amount, ifthe service is billed via measured usage, such as per hour, per minute, or permegabyte. After you have filled in any attribute information necessary, click the Add



button. You will then be returned to the list of services on the account, and will seethe new service listed there. The service will be added with the default billing type. Ifthere are other services linked with the one you added, or if the service has taxesassociated with it, those will be shown also. If the service has others linked to it, thosewill also have been added to the record, such as setup fees or bundled services.

If you add a service that requires a different billing frequency, you will get a messagethat says “Fix Billing Frequency”. If you have not setup the customer's billing recordyet, you can ignore this message for now. This error will appear if their billing typehas a billing cycle that is less than the service frequency. For example, you willreceive this error when the account has a billing type with a monthly cycle such as amonthly credit card bill, but a service that should be billed yearly, such as a yearlyInternet service subscription. If the customer has alternate billing types that shouldbe used for that service, click the Edit button and choose the alternate billing ID fromthe menu to assign this service to that billing record. You may want to add a different,but comparable service that is billed monthly so they can keep their billing simple, ormake 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 billBill 1 Yearly Service and a Monthly Services assigned to one Yearly Billingtype for both means that the monthly service rate will be multiplied by 12 togive the total amount for the one yearly bill.

Two bills:Bill 1 Yearly Service assigned to a Yearly Billing type for just the yearlyserviceBill 2 Monthly Services assigned to a Monthly Billing for just the monthlyservice

Two bills:Bill 1 Yearly Services assigned to a yearly billing type for just the yearlyserviceBill 2 Quarterly Services and Monthly Services assigned to a quarterlybilling type, the monthly service will be multiplied by 3 to give it's totalamount 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 andclick Edit. This will bring you to the attributes for that service as well as allow you toenter usage and alternate billing id choices. The service can also be changed toanother service that shares the same attributes. When a service is changed, the oldservice is moved to the history and a new service is created with the same attributeinformation. A notification will also be sent to the modify notification user indicated inthe service settings.



4.8.3 Service History

In the service record screen you can also view a history of services that have beenassigned to this account in the past. Click the History link at the top to view thislisting. This will show you services that have been removed, as well as one timeservices, such as setup and install fees. One time services are automatically moved tothe service history after they have been billed.

4.9 Customer Notes

Customer notes show support tickets that are associated with this customer. They arevisible in the Notes tab at the bottom of the screen. To add a new support note to thiscustomer click the Support module tab on the left and enter the note you want toleave on this record.

You can choose to notify a certain CitrusDB user, a group of users, or nobody at all ifyou just want the note to be on the record, but no action needs to be taken.

4.9.1 View notes sent to you

When someone has sent a message to your attention, or a service has been added thatyou are notified about, you will see the number of new message in the tab underSupport. Click on this tab, or click the Check Notes link in the support tab to viewyour waiting message. You can then perform whatever action is needed to fulfill therequest. You can update the status of the ticket to pending while you are working onit by clicking the Pending link. When you are finished with the request click Finishedand the support note will disappear from your list of new messages.

4.9.2 Editing a customer support note

You can edit a support ticket by clicking on the ticket number in your list of supporttickets. Using the support ticket editor you can add a new message on the ticket, sendthe ticket to someone else by choosing to notify them, or change the status of theticket back to not done or pending.

4.10 Billing Status

Each Customer Record has a Billing Status field that will show the current status ofthe customer. The following status types may be shown depending on the customer'ssituation:

New: account has no billing historyFree: account has a billing type of freeNot Renewed: a prepaid account that has not been renewed before it's bill todate.Authorized: a credit card or invoice account that is paid up to dateDeclined: a credit card account whose most recent charge was declined



Declined 2X: a credit card account whose two most recent charges were declinedPending: an account with no next billing date, this usually means the account ispending an account change.Past Due: an account that has amounts past due, but not yet turned off or sent tocollections status.Turned off: an account that has been put in the Turned Off status, due to beingpast due with no payment made for a specific amount of days.Collections: an account that has been put in the Collections status by the billinggroup, due to being turned off with no payment for a specific amount of days.Canceled: an account that has been canceled, this is indicated by a cancel dateon the customer recordCancel w/Fee: an account that has been canceled, but still has amounts past due.

4.11 Billing History

The Billing history tab is shown at the bottom of each screen. Click this tab to viewthe billing history for that customer. You will see all bills generated for this account,no matter what payment type they are. It will show you the date the bill wasgenerated, what the date range of the bill was, what the new charges on the bill were,and the total charges on the bill. You can click the Invoice Number link to view asnapshot of an invoice for that billing history record.

4.12 Payment History

The Payment History tab is shown at the bottom of each screen. Here you can view allthe payments made to this account, when the payment was made, the payment status,what type of payment it was, the AVS or Address Verification status for credit cardpayments, and how much the payment was for.

4.13 Billing Details

The Billing Details tab is at the bottom of each screen. It will show you the details ofeach item ever billed. It shows the date it was billed, the name of the service, theinvoice number the service was on, the amount the service was billed for, and howmuch of the service has been paid for. You can click the Invoice Number link to view asnapshot of the invoice that service was listed on.

4.14 Re-Running Declined Credit Cards

If a credit card gets declined and the customer wishes to try running the credit cardbilling again, you can click the Rerun link in the Billing record. This will cause thecredit card on the billing record to be billed for any past due amounts on the datespecified in the Rerun Date field. It will not charge the credit card any new servicecharges, only those that are past due. If the next available billing date to rerun thecard matches the customer's Next Billing Date you will get an error that the card willbe run normally on the next billing date. This will bill the customer for their past dueamounts and any recurring service charges.



4.15 Welcome Letters

Welcome letters may be printed by users with manager privileges. To view thewelcome letters go to the Tools section and click on the Welcome Letters icon. Thiswill create a web page on your screen with welcome letters for each new serviceactivated today. Simply print this page from your browser and mail these letters toyour customers to welcome them to their new service. The welcome letter can bechanged by editing the text near the end of your printwelcome.php file in thecitrusdb/tools folder.

5 Chapter 4: Billing and Payments

CitrusDB can handle a large daily billing workload. Daily billing is especiallyimportant for credit card billing, since one will inevitably need to re-bill cards thathave been declined or bill those customers that have ordered service today. If you areonly mailing or emailing invoices, daily billing may not be as important. You can useholidays and the pro-rate service type to move billing into a different billing day cycle,such as the 1st or 15th of each month.

5.1 Billing Tools

5.1.1 Credit card batches

CitrusDB's credit card system is built to export a credit card batch that would beprocessed via upload to a credit card batch processor. Most credit card billingsystems such as authorize.net, paypal, and regular merchant banks have a batchprocessing option. This allows you to upload a text file in a specific format for creditcard processing. The format of this file can be specified by the Credit Card Variableexport order in the General configuration.

Exporting Credit Cards

To export a credit card batch click on the Tools icon and select the Export CreditCards icon. This tool is used to export the credit cards into a batch format. This willprompt you for what date you want bill and the secret passphrase that will decryptthe card data. It will then show you a summary of the services it found to bill andsaves the card data to a file. This file will be stored in the folder you specified usingthe Path To Credit Card File in the general configuration. This can be used inconjunction with cron jobs or scripts that check for new billing files and process themautomatically. The interface also gives you the option to download the file to processit on your local PC. This file can then be formatted and transmitted to your credit cardbilling provider via a batch upload. Your server administrator will be able to informyou of any additional steps necessary.

Importing Credit Cards

After a credit card batch has been processed the results need to be imported back



into CitrusDB for crediting to accounts. To import the batch go to the Tools and selectthe Import Credit Cards icon. This will prompt you to browse your hard drive for thebatch results file from your credit card processing system. The format for each line ofthis file is

"trxcode","ccnum","ccexpire","amount","billingid","Y/N","avs"

trxcode: this is the transaction code associated with this unique transactionccnum: this it the credit card number, it should probably come back with most ofit starred out, eg, 4*********111ccexpire: this is the expiration date of the card that was runamount: this is the amount the card was run forbillingid: this is the billing id that identifies the customer billing record that wasrun. 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 wasauthorized with a Y or declined with an Navs: this is the status of the AVS processing that will show whether the addressmatched or not.

The server administrator may need to make a script that converts the results from thebank into the format that CitrusDB imports. Upon importing this file, account recordswill have their billing status updated accordingly and an email message will be mailedto those customers who have had their credit card declined. You can specify what themessage says by editing the Declined Subject and Declined Message fields in theOrganization settings.

5.1.2 Invoice printing

Invoice printing can be done daily, or if you have used the prorate service item andedited their next billing date to prorate a customer's billing record, you can printinvoices on the days you have chosen. Click on Tools and select the Print NewInvoices 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 youenter this information it will then provide you with a summary of what it found andprompt you to print the invoices. Then it will render the invoice page as a PDF filethat can be opened with a PDF reader. You can then print the PDF from within thePDF application. It may also be a good idea to save this pdf to your hard drive tomake 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 therecipient'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 andedited their next billing date to prorate a customer's billing record, you can email



invoices on the days you have chosen.

Click on Tools and select the Email New Invoices icon. This tool can email batches ofinvoices based on their Next Billing Date, or individual invoices based on their BillingID number, or Account Number. After you enter this information it will then provideyou with a summary of what it found and prompt you to email the invoices. Theinvoice will be sent as a pdf file attached to email to the billing_email specified intheir billing record. The web server that is running CitrusDB server must be properlyconfigured to send email. This tool is a prime candidate to be automated by running amodified 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. Youcan apply a payment in three different ways. By Account Number, which will apply thepayment to the oldest fees still due on that account's default billing record. By BillingID, which will apply the payment to the oldest fees still due for services under thatbilling id. By Invoice Number, which will apply the payment to the oldest fees still dueon 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 amountleft over. You can then apply this amount as necessary to the account, either byapplying that payment to a different invoice, billing id, or making a credit in theaccount service record.

5.1.5 Processing Refund

The refund tool is used to create a credit card batch for refunds that have beenmarked on customer records. Any refunds that have not been processed yet will beprocessed by clicking the Yes button and a credit card batch file will be created toupload to your credit card processor for processing. You can then import the resultsfrom 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 informationinto CitrusDB using the Import New Accounts tool. Your server administrator will tellyou the steps necessary to get the data to import into this new accounts tool. This toolis a prime candidate to be automated by running a modified copy of it using the phpcommand line program in a CRON job.

5.1.7 Importing Service Usage

Some services have a usage associated with them. The server administrator will needto make a script that imports the usage directly into new services for each customer.



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 cardinformation, you can use this tool to import their new information into their defaultbilling record. Click the Tools icon and select the Credit Card Changes icon. This toolis used to import credit card changes that have been sent in via external methodssuch as online forms or order systems, usually done after a card has declined and anotice 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 ofpaying customers you have for each service type that has not been removed. The totalnumber of Paid Subscriptions, which counts the total number of non-free recurringservices that customers have. The Total Number of Customers is the total number ofcustomers that have not been canceled. Tht Total paying customers is the the same asthe 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 thedate period shown. It also shows the tax revenue during that period, the creditservice 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 notshow 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 agiven time period.

5.2.4 Past Due Report

The past due report will show customers with some type of unpaid status. It will allowyou to find Past Due, Turned Off, and accounts in the Collections or Cancel with Feestatus. You can use this report to determine which customers need to be contactedabout their billing issues.

5.2.5 Payment Status Report

This report shows you customer payment information. For example, here you can find



out if they have had had their credit card declined in the past few days. You will beprompted for what days from the previous week you want to find declined cards for. Itwill then produce a report of the credit card declines from that day. You can use thisreport 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 youtotal numbers of who has active service and total number of deactivated services, andwhat status they have had. It will also show you a break down of reasons that werechosen 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 wasactivated. This will let you see where customers have said they heard about yourservices.

5.2.8 Exempt Report

The exempt report will show a list of customers who have been marked as past dueexempt, 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 statusupdatescript.

5.2.10 Service Growth

A simple graph that compares the number of services in that category that werestared and ended in a month for a chosen year. For services that were changed fromone type to another they will have one start and one end, so the old one shows up asan ended service and the new one shows up as a started service.

6 Chapter 5: Server Administration and Integration

CitrusDB requires operating system and database administration skills to maintain aninstallation in a production setting. There are a few things that are a uniquerequirement of a billing system that I will cover in this chapter, such as securityrequirements, backing up the data, customization, and automation of billing tasks.

6.1 Backups

Having up to date backups are very important for a billing system, since your wholebusiness will rely on it for their day-to-day work. You should implement a backup



policy that takes into account your uptime requirements. Backups can be performednightly 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 windowsbatch script.

6.2 Custom Modules

All the tabs on the left side, such as the default ones of Customer, Services, Billing,and Support are called modules. You can add new tabs here that hold your owninformation by adding a new custom module with your own php code that doeswhatever you need it to do, such as querying database tables, or storing additionalcustomer information that is unique to your operation. A module is simply a folderinside the modules folder with an index.php file and other files that make up thefunctions of the module. Some modules may or may not need all these functions. Ifthey don't need the function, please make an empty file for that function.

If you are making a new module, it should conform to a few functions to make sureone can use the major functions of any module without knowing all of it's details.

The following files are required, index.php, create.php, edit.php, delete.php, andsearch.php file. When making a new custom module you may want to start with onethat is already there. I recommend copying the Support module and renaming it. TheSupport module is one of the smaller modules and a good starting place to edit it andmake your own modules.

index.php

This is the default file. It has code to include the other files when called with edit=onor similar it will also provide the view of the data by default

example of index.php:

if(constant("INDEX_CITRUS") <> 1){ echo "You must be logged in to run this. Goodbye."; exit; } if (!defined("INDEX_CITRUS")) { echo "You must be logged in to run this. Goodbye."; exit; }

include('include/permissions.inc');

if ($edit) { if ($pallow_modify) { include('edit.php');



} 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. forexample, with the services module, this would create a new service for thatcustomer, called with create=onedit.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 specified billing id,called with edit=on, often called with an id value to specify a billing_id, oruser_service_id etc.delete.php this will be used to delete a record for that modules function. forexample, with the services module, this would remove the service from thatcustomer, called with delete=onsearch.php this will be included in the main search page. it will not be calledthrough the index.php file it will either be empty if your modules doesn't needsearch ability, or have form html for searching the data that your module dealswith

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>  <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. Copyyour module folder into the modules folder of CitrusDB. Open the Edit Modules tooland click Add Module. This will ask you for the Common Name of the module, this isthe name you want it to be called in the Tab on the left that users will see. TheModule Name is the name of the folder that the module is stored in, this field is casesensitive. The Sort Order field is a number that determines what order the tabs aresorted in.

6.3 Account Activation and Deactivation



There is a script included in the citrusdb folder named statusupdate. This script canbe run nightly in a unix cron job or windows task scheduler. It will create a file in thepath you specified in the general configuration (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 file forprinted messages to be mailed by the billing adminstrator regarding their past dueaccounts. These messages can be edited in the language files using the$l_notice_text_ variables.

This file can be used in conjunction with other cron jobs or scripts that check for newaccount files and process them automatically. You may want to make a shell scriptthat calls the statusupdate script and then calls your own account activation scriptthat works on the file created by statusupdate.

It will print an ADD line for new services added today. A DELETE line for services thathave a removal date of today. An ENABLE entry for services that should be turnedback on today that were previously disabled. A DISABLE line for services that shouldbe shut off today such as accounts with declined credit cards or past due. It printsthem in a standard text format that could be processed by an activation script at alater time.

Example:

"ACTION","category","Customer Name","Service Description","field1",...

The ACTION will hold the value ADD, DELETE, ENABLE, or DISABLE to indicatewhat should be done to the accountThe category field holds the category you assigned to that service. This will allowyour custom activation script to check this field and do things to specificcategories of service, without having to parse the whole service description.This is the customer's name, often entered into the data with their accountThis is the description of the service being added from the databaseThe last fields are holding data from whatever fields have been specified for thatservice in the Activation String field in the service editor. It will print them all forthat service, so it will be a variable number of fields. You will probably want tospecify the same fields for each category of service so you will know what fieldsyou are looking at when you read the category name earlier in the line.

6.4 Credit Card Batch Exports Format

The credit card batch format is in a quote and comma separated format that can beedited by changing the Credit Card Export Variable field in the General Configuration.

Each transaction will look something like this example:

"CHARGE","111","4353","4111111111111111","0810","19.95","01234","5 Example St."



The first field in the first line of a card record will be the words CHARGE or CREDITto indicate whether the transaction is a charge or a credit, after the first field you canuse 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 exportcreated$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 onebill$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 beexported with the credit card batch. The refund tool must be used to refund anaccount's credit card.

6.5 Credit Card Batch Imports Format

The results of the credit card batch will need to be imported into CitrusDB. Theformat for this is a comma separated file with the following fields (all on one line):

"trx code","cc number","cc expire","amount","billing id", "approved(Y) or declined(N)", "avs"

trx code: the unique transaction code assigned to this one transaction by thebank or by youcc number: holds the credit card number, should probably be imported in aformat 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 transactionthe billing id that connects this transaction to a citrusdb billing record.The uppercase letter "Y" or "N" that indicates whether the transaction was



successfully approved (Y) or declined (N). You can place other text after the Y orN if you want to indicate other transaction codes or things like whether thetransaction was live or in a batch.avs: this field can hold address verification result codes if those are available toyou.

You may need to create a script that converts your bank output into the format abovethat CitrusDB will import. The only required data are the transaction code, billing id,and approved or declined, the other fields can be left blank if they are unavailable.Upon importing this file accounts will have their billing status updated accordingly.

6.6 New Accounts Data Format

Online order forms can save the order data and you can use Import New Accountstool to import the orders into CitrusDB. The New Accounts tool can also be used whenmigrating to CitrusDB, by importing existing customer records into citrus with alltheir customer, billing, and service information. Here is an example of what each linein order data file should look like (normally each line is on one line and does not haveblank lins between each, it is printed this way to show up in the instructions moreclearly.)

Online, Test User, Test Company, 523 Test Ave., Testcity, CA, USA, 95113, 408-555-5555, 408-555-6666, 408-555-7777, [email protected], , What is your favorite color, red, testpassword, 1 Test User, Test Company, 1 Test Street, Testcity, MA, USA, 01234, 555-555-1234, 555-555-1235, [email protected], 1, 4***********1111, 0406 3, usernm, passwd, Linux, 1 Test Street, Cisco Thing 3, nameuser, wordpass, Windows, 123 Test Street, USB Thing -----BEGIN PGP MESSAGE----- aSC14RMoRD3tAaSC14RMoRD3tAaSC14RMoRD3tAaSC14RMoRD3tA aSC14RMoRD3tAaSC14RMoRD3tAaSC14RMoRD3tAaSC14RMoRD3tA aSC14RMoRD3tAaSC14RMoRD3tAaSC14RMoRD3tAaSC14RMoRD3tA aSC14RMoRD3tAaSC14RMoRD3tAaSC14RMoRD3tAaSC14RMoRD3tA -----END PGP MESSAGE-----

The first line of the import record is the customer data, the second line is the billingdata. The credit card number here should be masked with ****'s in it so that onecannot 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 finallines are for the PGP ascii armored credit card data so that you can encrypt the datawith your public key before importing it into the database, preferably directly in theorder system that is saving these new customers. If the customer does not use acredit card you will need to include the –—BEGIN PGP MESSAGE–— and ——ENDPGP MESSAGE–— lines with nothing in between them. This denotes the end of thatcustomer record. (normally each line is on one line and does not have spaces between



lines, but is printed this way to show up in the instructions correctly.)

Field definitions:

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

6.7 Service Usage Data

You can create bills for service usage manually by adding the service using theservice record for that customer and typing in their measured usage for that service.If you have many many services that have usage tracked automatically, for exampleminutes of a phone call or megabytes transferred you can create a custom importscript to input this usage data in to a new one time service charge for the customerevery month, or whatever period you are billing them by.

To input service usage data you will first need to create some place holder servicesthat have a pricerate that is equal to the service's unit cost. For example, if you have aservice that costs $1.00 per megabyte, you can make a new one time service called“Megabyte Use” with a price of $1.00 and a frequency of 0 (zero) so it is a one timefee. This is a one time service because a new service with that month's usage will beentered every month or billing period. When you add this service to a customer youwould fill in the measured usage field with the number of megabytes they have used,say they used 100 megabytes, then it will multiply their usage by the price and giveyou a total of $100 for that service.

To automate this service usage input you will need to make a script that inputs newservice records into your MySQL database. Adding new services to a customer isdone by making entries into the user_services table. In order to insert thisinformation you'll need know the customer's account number, the id of the servicethat you are adding, and the amount of usage units. PHP code to do this query withthe ADODB layer that CitrusDB uses will look something like this:

// make the creation date YYYY-MM-DD HOUR:MIN:SEC



$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 toinsert 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 file that stores theusage data and inputs it into the database.

6.8 Credit Card Change Format

If you have a form on your website for customers to update their credit cardinformation, you can use this tool to import their new information into their defaultbilling record. Click the Tools icon and select the Credit Card Changes icon. This toolis used to import credit card changes that have been sent in via external methodssuch as online forms or email messages, usually done after a card has declined and anotice has been sent to the customer. The format for this file is:

The format for this file is:

account_number, name, street, city, state,zip,card_number (masked), card_expiration_d-----BEGIN PGP MESSAGE-----ASCiiARM0R3DD4TAASCiiARM0R3DD4TAASCiiARM0R3DD4TA-----END PGP MESSAGE-----

account number: account number for the customer's record



name: the customer's namestreet: the customer's street addresscity: the customer's citystate: the customer's statezip: the customer's zip codeccnumber: the customer's new credit card number in masked form with ****'sccexpire: the customer's new card expiration datePGP 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 filefrom your web server's periodically. You'll probably want to download and empty thisfile every day to check if new updates have been made. This will update the creditcard 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 newaccounts, exporting credit cards, importing credit cards, and activating accounts, canbe automatically run at specific times. It relies on the server's cron schedulingservices on unix servers to run the commands at a specified time, or on a windowsserver 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 acron or task schedule. That is the statusupdate script. This must be run every day toupdate the billing status of accounts and also creates a file that contains accountinformation that can be used to process account changes, new accounts, and removedaccounts.

PHP has a command line interpreter that can be used to execute the citrusdb files. Ona unix server this can be used much like the perl or shell interpreter is used, so youcan 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 acommand 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 thescript to edit, in this case the einvoice.php file 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 soyour include path's are easier to figure out. With the new copy, you'll need to edit it toinclude the stuff from the includes files, just like it's included in the index.php filenormally, so you'll need to put these near the top of the script:



// Includes include('./include/config.inc.php'); include("$lang"); include('./include/database.inc.php'); include('./include/billing.inc.php'); require './include/citrus_base.php';

Then you'll need to write some php code in the new script to generate the input youwant, such as today's date in the billing_date that is being processed, since the formisn'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 theform interface and since this is all going to be accessed by the computer withpre-programmed input.

6.9.1 Automatic Credit Card Billing

You can automatically bill a credit card batch every day by using the Export CreditCard 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 tosave the credit card batch into a file named exportXX.csv, where XX is the batchnumber. Your script can read this file and send it to your credit card processor in theformat they require.

After the credit cards are run you will get a results file from your credit cardprocessor. You can import this manually using the Import Credit Card Batch tool, oryou can make a script that will input the results automatically by inserting data intoyour MySQL database. Here is some example PHP code using the ADODB layer thatCitrusDB uses. In order to import this data you will need to know the customer'stransaction code, amount they were billed, their billing id, and the response codefrom the credit card company. This code would usually run in a loop while it reads theresults file 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'];



$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";



$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 usedas a php command line script.

This will cause CitrusDB to output a PDF file back to the browser for all the invoicesfor the data specified in YYYY-MM-DD format. Your script can then get this file andsend 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 beused as a php command line script.

This will cause CitrusDB to begin emailing invoices to the customers who have billingon YYYY-MM-DD.

7 Chapter 6: Data Security Implementation Guide

CitrusDB is believed to fall under the PA-DSS category of a Back-office system that



stores credit card data and is not currently subject to PA-DSS certification. WhileCitrusDB itself is not required to be certified since it does not connect directly with amerchant bank, it must still be be installed and implemented in a way that meets theinformation security requirements that each merchant is subject to prevent attacksand comply with credit card regulations and local privacy laws.

The PCI Data Security Standards are a good starting point when implementingsecurity for any billing system. The standards outline the following requirements:

Build and Maintain a Secure Network: Update passwords regularly and maintaina firewall.Protect Cardholder Data: Protect stored cardholder data, encrypt thetransmission of cardholder data on public networks like the Internet.Maintain a Vulnerability Management Program: Use anti-virus software, andmaintain secure system and applications by keeping them up-to-date.Implement Strong Access Control Measures: Require unique ID and passwordsfor those with computer access to cardholder data. Restrict access to only thosewho need it.Regularly Monitor and Test Networks: Track access to the network, andregularly test the security systems.Maintain an Information Security Policy: Develop a security policy that your stafffollow when dealing with this information.

This is a simple overview of these security standards. You can find the completedocumentation online at https://www.pcisecuritystandards.org/

7.1 CitrusDB Configuration

Besides the GPG and SSL configuration CitrusDB has a few places where you willwant to pay special attention to your settings to make sure that your security ismaintained. The username and password used in the configuration to open thedatabase should have the minimal permissions necessary to access your citrusdatabase and perform the operations. For the internal main system this means givingthe user access privileges to just the citrus database and the MySQL Data andStructure privileges. For the online public system you must restrict the access muchmore. Make a different database user with access to the citrus database, but this newdatabase login name should restrict the access to your citrus database to SELECTonly, and use table specific privileges that allows only SELECT and INSERT to thecustomer_history table and SELECT, INSERT, UPDATE, and DELETE in the session2table.

In the configuration you should set the $hidden_hash_var to something hard to guess.This passphrase is used to create a unique cookie value for your CitrusDB login. Youshould use a different passphrase for the internal and online public system. You donot need to remember this passphrase, so I encourage you to make it as complicatedas you want.

In the general configuration there is a place for the Path To Credit Card variable. This



should be set to the path to the folder you wish to store imported and exported creditcard data inside. The path should be outside of your web server's file path, and ifpossible outside of PHP's include path to keep it away from http queries.

7.2 Physical Data Center

Your citrusdb server should be installed in your secure data center on a segment ofthe network that is only accessible from your internal LAN. Cardholder data shouldnot be stored on a server connected to the internet.

7.3 Passwords

Passwords to access the server, database, and web interface should be strong to helpprevent password guessing. Strong passwords avoid the use of dictionary words or allnumbers, they include upper and lower case letters, numbers, and punctuationsymbols. Longer passwords are stronger than short ones, even just a few letters canmake it significantly harder to brute force.

Passwords in CitrusDB are stored in a salted bcrypt or md5 hash to make them harderto recover from the database. If a user forgets their password the administrator willneed to set a new one using the User editing tool. If the administrator forgets theirpassword, they will need direct access to the database via SQL queries or a utility likephpMyAdmin to put a new password on their user record. You will need to hash yourpassword using the phpass framework before you paste it into the database record.

7.4 Encrypting and Decrypting card data

New cards entered into the system are encrypted by the configured GPG command,however if you have a previous version of citrusdb with card data already in it you willneed to encrypt the cards that are already heald in the system.

7.4.1 Encrypting existing card data

To encrypt the card data make sure you have setup a working gpg command in theconfig file. Be sure to have a backup of your database before you run this command. Ifthe gpg command does not work or encrypts the cards using a key you are not able todecrypt then you have lost data. Run the encryptcards script from the main citrusdbfolder. This will begin going through the database looking for unencrypted cards andencrypt them. This can take a long time depending on how fast the server is and howmuch card data there is.

7.4.2 Changing encryption keys for card data

It is a good idea to periodically change the encryption key being used. You may wantto change to a larger key every few years to make sure you are ahead of the curve forcryptanalysis attacks on the smaller key size.



To change they key you will need to first decrypt all the card data in the database.This will need to be done when the database is not being accessed by any users orother processes. Run the decryptcards command from the main citrusdb folder. Thiswill go through and decyrpt all the cards in the database using the gpg decryptcommand from your config file. The decryptcards command takes the passphraseinput on the command line, so you may want to run this command from the console insingle user mode if you want to ensure nobody else may log in while doing this. Thiscan take a long time depending on how fast the server is and how much card datathere is. After you have decrypted the card data you can create your new gpg key andsetup the gpg encryption command to use this new key. Then run the encryptcardsscript to encrypt all the cards in the database with the new key.

7.5 Purge old cardholder data

You will want to pick a time period to keep this data. After that period has passed,then remove that data from your system.

7.5.1 Remove Exported Batch files

These batch files are created by the Export Cards tool and can be removed after theyhave been used. Adding a cron job to get rid of these files nightly is recommended.

7.5.2 Remove Canceled Customer Records

Canceled customer records in the database will not be necessary after a certainnumber of years have passed and that customer data is no longer necessary forbusiness operations and auditing purposes.

You will likely need to make a custom script that can remove this for you since youwill need to be deleting data from multiple tables depending on different criteria. Thefirst criteria would be to find the customer records with a cancel_date that is so oldyou want to remove all their information. Once you have a list of those customers youwill then want to remove their information from a number of tables including billing,billing_details that is related to their billing table id, billing_history also related totheir billing table id, any optional tables you've created containing service attributesthat are related to their user_services id, payment_history related to the billing id ,and user_services which can be related to the accountnumber or billing id. Before yourun your customer script you will want to make sure that you have a backup of thedatabase in case something more than you expected is removed.

7.6 Logging of user activity

You will want to keep logs of the activity that occurs on the server holding citrusdband periodically review those logs.

CitrusDB logs it's activity via the sql database in the activitylog table.



This table keeps track of the following:

The Date and Time of the activityThe CitrusDB user who generated the request if they are logged inIP Address the request came fromThe account number of the record the activity occured onThe type of activity, login, logout, view, edit, create, delete, undelete, export,import, cancel, or uncancelThe type of record, either the tools dashboard screen, customer record, billingrecord, service record, or creditcard recordThe record id number if the activity occured on an specific recordThe result of the request, either a success which most queries will be, or afailure, such as a login failure.

This table of data should be exported out of the database by a seperate log watchingscript as often as necessary to satisfy your reporting needs.

7.7 Keeping Up-to-Date

Keeping your CitrusDB installation up-to-date is also important when there arecritical security fixes. You can sign up for the CitrusDB announce mailing list to bekept up to date on any updates to CitrusDB, including critical security updates. Visithttps://lists.sourceforge.net/lists/listinfo/citrusdb-announce to join for the mailing list.

8 Online Resources

Thank you for reading the CitrusDB Usage Manual. I hope this will allow you to takeCitrusDB and use it with your organization to meet your billing and customer serviceneeds. 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 toCitrusDB. All users of CitrusDB are encouraged to subscribe to this list to makesure 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 findsolutions.

Home Page:

http://www.citrusdb.org



This is the home page for CitrusDB, this will connect you to all the informationabout CitrusDB . The latest release is always available for download on the homepage.

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.

9 Appendix A: GPG Commands

9.1 Creating A Key

gpg --gen-key

Please select what kind of key you want: (1) DSA and Elgamal (default) (2) DSA (sign only) (5) RSA (sign only)Your selection? 1DSA keypair will have 1024 bits.ELG-E keys may be between 1024 and 4096 bits long.What keysize do you want? (2048) 1024

Please specify how long the key should be valid. 0 = key does not expire <n> = key expires in n days <n>w = key expires in n weeks <n>m = key expires in n months <n>y = key expires in n yearsKey is valid for? (0) 0Key does not expire at all

Real name: MyNameEmail address: [email protected]: You selected this USER-ID: "MyName <[email protected]>"

You need a Passphrase to protect your secret key.

enter passphrasere-enter passphrase

We need to generate a lot of random bytes. It is a good idea to performsome other action (type on the keyboard, move the mouse, utilize the



disks) during the prime generation; this gives the random numbergenerator a better chance to gain enough entropy.++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++.gpg: key 3F9D1764 marked as ultimately trustedpublic and secret key created and signed.

9.2 Listing Public Keys

gpg –list-keys

9.3 Listing Private Keys

gpg –list-secret-keys

9.4 Export Public Key

gpg –export -a "User Name" > public.key

9.5 Export Private Key

gpg –export-secret-key -a "User Name" > private.key

9.6 Importing Public Key

gpg –import public.key

9.7 Import Private Key

gpg –allow-secret-key-import –import private.key

9.8 Delete a Public Key

gpg –delete-key "User Name"

9.9 Delete a Private Key

gpg –delete-secret-key "User Name"

9.10 Encrypt Data with Ascii Armor

gpg -e -u "Sender User Name" -r "Recipient User Name" –armor filename

9.11 Decrypt Data

gpg -d filename.gpg

9.12 Edit a Key



gpg –edit-key

9.13 Key Signing

You should only sign keys that you know are authentic.

run: gpg –edit-key "username" at the prompt enter: sign

9.14 Key Trust

Run gpg –edit-key "username" at the prompt enter: trust

1 = I don't know or won't say 2 = I do NOT trust 3 = I trust marginally 4 = I trustfully 5 = I trust ultimately m = back to the main menu

The keys you created for citrus can be set to trusted ultimately.

9.15 Revoke a key

gpg –gen-revoke

9.16 Command Options

-homedir This will specify the path to the .gnupg folder that contains the key files tobe used

-armor This will encode the output in ASCII Armor format.

-batch This will tell gpg that it to run in batch mode.

-no-secmem-warning Some Operating systems may give a warning about securememory. This will supress that warning.

-passphrase-fd 0 This will take a passphrase from stdin instead of interactively.

-passphrase-file filename This will read the passphrase from the file specified insteadof interactively.

-yes answer yes to any prompts

-symmetric use symmetric encryption instead of asymmetric Using a symmetricencryption is usually faster than the regular asymmetric encryption of gpg, however itrequires a way to maintain the security of the passphrase when encrypting the datasince there is no keyfile and the same passphrase is used both for encryption anddecryption.

-personal-cipher-preferences string Set the list of personal cipher preferences tostring. Use gpg

-version to get a list of available algorithms, and use none to set no preference at all.



This allows the user to factor in their own preferred algorithms when algorithms arechosen via recipient key preferences. The most highly ranked cipher in this list is alsoused 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 verification of signatures. It can make gpgfaster when one does not need to verify signatures.

10 Appendix B: OpenSSL Certificate

To create a SSL certificate you will first need to create a private key and thecertificate signing request.

openssl genrsa -out webserver.key 2048

This will create the 2048bit RSA private key. You can add -des3 to this command ifyou want to password protect the key, however that will require you enter thepassword whenever the web server starts up.

openssl req -new -key webserver.key -out webserver.csr

This command will create a certificate signing request from the private key.

If you are going to send the key to a certificate authority (CA) like Certs4Less forsigning then you can send the csr file to the CA instead of self-signing it. If you wantto run your web server with a self-signed certificate then you will need to run thesignkey command below. If you are using a self-signed certificate your web browsermay warn you to confirm and accept the certificate. If you know the self-signedcertificate is legitimate this offers the same encryption as any other certificate,however the browser is being cautious since it does not have an authority record forself-signed certificates.

openssl x509 -req -days 365 -in webserver.csr -signkey webserver.key -out webserver.crt

This command will sign request and create a certificate file.

After you have a signed certificate you will need to install that certificate into yourweb server.

Author: Paul Yasi <[email protected]>

Date: 2011-01-06 09:20:03 EST

HTML generated by org-mode 6.21b in emacs 23

Documents

CitrusDB 2.4 Manual