$Revision: 1.3 $
Apache::Centipaid - mod_perl AuthenHandler
#in httpd.com <directory /document_root/path_path> AuthName centipaid AuthType custom PerlAuthenHandler Apache::Centipaid require valid-user PerlSetVar acct account_name PerlSetVar pass receipt_password PerlSetVar amount 0.01 PerlSetVar duration 1d PerlSetVar access /pay_path PerlSetVar domain your.domain.name PerlSetVar lang en PerlSetVar enforce_ip 0 PerlSetVar https https://pay.centipaid.com PerlSetVar authserver centipaid_receipt_server PerlSetvar authport 2021 PerlSetVar dbtype mysql PerlSetVar dbhost localhost PerlSetVar dbport 3306 PerlSetVar dbname centipaid_rcpt perlSetVar dbuser user perlSetVar dbpass pass </directory>
Perl5.004_04, mod_perl 1.15, IO::Socket, Net::hostent, DBI, DBD, DBD::mysql, CGI::Cookie;
Apache::Centipaid is a mod_perl Authentication handler used in granting access to users wishing to access paid web services, after making payment on centipaid.com which process micropayments using internet stamps.
Centipaid.com offers websites the flexibility to charge small amounts of money, also refered to as micropayment, to users wishing to access to their web services without the complexity of setting up e-commerce enabled site, or to deal with expensive credit card processing options. Users benefit from not having to reveal their identity or credit card information everytime they decide to visit a website. Instead, centipaid allows users to simply pay using a pre-paid internet stamp, by simply uploading the stamp to centipaid's site. The stamps are valid in all sites using centipaid.com payment system.
To access a site, recipts are issued by centipaid and are used to track valid payments. This information is captured and processed by the Apache::Centipaid module. The information is then stored locally to any SQL database installed. The module relies on DBD/DBI interface so as long as the database has a DBD interface installed under Perl, and utilizes SQL to make queries and inserts, then you should be able to maintain and track your receipts.
How does it work? A user visits a website, or a section with a site, that requieres an accecss fee. The webserver will intercept the request, and realize that the user has not made a payment, and hence they are directed to centipaid.com to pay for access. Centipaid will inform the user what they are paying for in a standard language, along with the fee associated with the access, and the duration of the granted access.
If the user agrees to the terms, s/he proceeds to select an electronic stamp from his computer that has enough funds to pay for the access. Centipaid will autheticate the stamp, deduct the access fee, and issue the user a receipt number. The user will see a receipt on his page that re-iterates the terms, amount paid, and internet stamp balance. A link will be also available for the user to click on to be transported back to the page they came from, along with the receipt number. Once the user makes a payment, they are shown the amount paid, the balance left on the card, and a link back to the page they were trying to access. Once they press the link, they are forwarded back to the initial page they tried to access.
At this stage, Apache::Centipaid realizes that a rececipt is being submited as payment. It takes the receipt number and autheticates with centipaid's receipt server to insure that the receipt is a valid one, and that the proper funds have been paid.
If the rececipt is valid, then the information is stored locally. The information stored included the ip of the client (for optional enforcment of payment tied to ip), amount paid, date of transaction, expiry date, and the zone the payment covers. And since centipaid micropayment system is designed to allow users to pay without having to provide username, password or any other payment information other than the recipt number, it makes the process easy to manage and neither the payer or payee have to worry about financial information falling into the wrong hands.
How do we track payments? When a user makes a payment, the Apache::Centipaid module inserts a cookie that contains the receipt number, and it sets the expiry of the cookie based on the payment duration specified in the configuration file. Everytime a user visits protected areas in a site, the cookie is inspected, and if it exists it is matched with the receipt database. if it is found, and the expiry date has not been met, then they are granted access. If the receipt is non existent, or past its expiry date, the user is prompted to make payment again.
Please reffer to centipaid.com for the most updated version of this module, since other methods of tracking payment may be available.
The account number is issued by ceentipaid.com for a given domain name. This number is unique and it determines who gets paid.
The password is used only in socket authetication. It does not grant the owner any special access except to be able to query the receipt server for a given receipt number.
The amount is a real number (float, non-integer) that specifies how much the user must pay to be granted access to the site. For example amount 0.5 will ask the user to pay 50 cents to access the site. The value of amount is in dollar currency.
The duration is in the format of NZ where N is an integer number, and Z is either m, w, d, h where m is month, w is week, d is day, and h is hour. So if duration is 24h, then it means we grant access for 24 hours, and 2d means 2 days, etc..
The access specifies what path to protect, and it should be also included in the <Location path_goes_here></Location> as well. So if we want to protect a whole site then the access is set to "/", while if we want to protect a chat service under /chat then access will be "/chat"
This defines the domain which will be returned to. Altough the information is redundant and we can retrieve it from apache itself, we let the admin to set it to insure that the return href is properly formed.
This deines the language of the payment page displayed to the user. It is set by the site admin using the two letter ISO 639 code for the language. For example ayna.com requieres the payment info to be displayed in arabic on centipaid, CNN.com will need several sections of its site to show payment requests in different languages. Some of the ISO 639 language codes are: English (en), Arabic (ar), japanese (ja), Spanish (es), etc..
This tells the module if the website wants to tie the receipt to a one ip. This may be requiered in certain casees where the site admin decides that access to the site is made only from the ip of the machine that makes the payment, as long as the machine also holds the receipt cookie. The valid values are 0 for "do not restrict to ip", and 1 for "yes do restrict to the ip". If ommited, then the default is 0.
This should contain the payment url assigned to the account number. This defaults to http://pay.centipaid.com
This should contain the receipt server assigned to the account number above
This should contain the port number of receipt server assigned to the account number above
This dhould be the DBD database string. For example MySQL's dbtype should be mysql, while postgreSQL is Pg. Reffer to DBD documentation for the correct string. The module defaults to mysql as the installed database if not defined in the configuration file.
This should the domain name of the database server. The module defaults to localhost if not defined in the configuration file.
This should the port number of the database server. The module defaults to 3306 if not defined in the configuration file, since the default database type is mysql. For PostgreSQL the port is usually 5432.
This should be the name of the database you create to hold the recipt information. The module default to centipaid_rcpt default if not defined in the configuration file.
This should be the username of the user that has access to read/write to the database defined in dbname.
This should be the password of the user that has access to read/write to the database defined in dbname.
MySQL The receipts are stored in a locally accessible database. The MySQL database structure is as follows
==begin
CREATE TABLE rcpt ( rcpt varchar(100) NOT NULL default '', date datetime NOT NULL default '0000-00-00 00:00:00', expire datetime NOT NULL default '0000-00-00 00:00:00', paid double NOT NULL default '0', ip varchar(100) default NULL, zone varchar(50) NOT NULL default '', PRIMARY KEY (rcpt) );
==end
where rcpt stores the recipt number, date and expire contain the date the receipt was issued on the site, and its expiration. Paid contains the amount paid in float format. The IP could be used in cases where the site admin decides to tie a payment to an ip as well as a browser. We do not reommend this, since people use proxy servers, and dynamic IPs. The zone is used for statistical purposes, where the website admin can see what sections are being used most.
Thanks for Liconln Sten & Doug MacEachern for a great book about writing Apache Modules with Perl and C. It made writing this module a breeze :)
Adonis El Fakih, adonis@aynacorp.com
mod_perl(1). DBI(3)
2 POD Errors
The following errors were encountered while parsing the POD:
'=item' outside of any '=over'
You forgot a '=back' before '=head1'
To install Apache::Centipaid, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Apache::Centipaid
CPAN shell
perl -MCPAN -e shell install Apache::Centipaid
For more information on module installation, please visit the detailed CPAN module installation guide.