$Revision: 1.2 $
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.
- Account and Access Information
-
- acct account_name
-
The account number is issued by ceentipaid.com
for a given domain name. This number is unique
and it determines who gets paid.
- 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.
- 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.
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..
- 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..
- 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.
- Authetication server
information
-
- https https://pay.centipaid.com
-
This should contain the payment url assigned to the
account number. This defaults to
http://pay.centipaid.com
- 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
- Local database Information
-
- 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.
- 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.
MySQL The receipts are stored in a locally accessible
database. The MySQL database structure is as follows
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) );
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.
- Apache::DBI support Use Apache::DBI instead of
DBI to use persistent connections
-
-
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)
|
