view release on metacpan or  search on metacpan

Centipaid.pm  view on Meta::CPAN

1;

__END__

=head1 NAME

$Revision: 1.3 $

B<Apache::Centipaid> - mod_perl AuthenHandler 


=head1 SYNOPSIS


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


=head1 REQUIRES

Perl5.004_04, mod_perl 1.15, IO::Socket, Net::hostent, DBI, DBD, DBD::mysql, CGI::Cookie;


=head1 DESCRIPTION

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

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

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

Centipaid.pm  view on Meta::CPAN

 for a given domain name.  This number is unique 
 and it determines who gets paid.
 
=item B<pass> receipt_password

 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.

=item B<amount> 0.5

 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.
 
=item B<duration> 1d

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

=item B<access> /pay_path

 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"
 
=item B<domain> your.domain.name

 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.
 
=item B<lang> en

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


=item B<enforce_ip> 0

 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.
    

=item B<Authetication server information>

=item B<https> https://pay.centipaid.com

 This should contain the payment url assigned to the
 account number. This defaults to 
 http://pay.centipaid.com


=item B<authserver> centipaid_receipt_server

 This should contain the receipt server assigned to 
 the account number above
 
=item B<authport> 2021

 This should contain the port number of receipt 
 server assigned to the account number above
    

=item B<Local database Information>


=item B<dbtype> mysql

 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.
 
=item B<dbhost> localhost

 This should the domain name of the database server. 
 The module defaults to localhost if not defined  
 in the configuration file.
 
=item B<dbport> 3306

 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.

=item B<dbname> centipaid_rcpt

 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.
 
=item B<dbuser> user

 This should be the username of the user that has 
 access to read/write to the database defined in 
 dbname.
 
=item B<dbpass> pass

 This should be the password of the user that has 
 access to read/write to the database defined in 
 dbname.

=back

=head1 Database Schema


B<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 B<rcpt> stores the recipt number, B<date> and B<expire> contain the date the
receipt was issued on the site, and its expiration. B<Paid> contains the amount paid
in float format.  The B<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 B<zone> is used for statistical purposes, where
the website admin can see what sections are being used most.



=head1 TODO

=item B<Apache::DBI support> Use Apache::DBI instead of DBI to use persistent connections


=head1 ACKNOWLEDGEMENTS 

Thanks for Liconln Sten & Doug MacEachern for a great book about B<writing
Apache Modules with Perl and C>. It made writing this module a breeze :)

=head1 AUTHOR

Adonis El Fakih, adonis@aynacorp.com

=head1 SEE ALSO

mod_perl(1). DBI(3)

=cut