NAME
Business::CCProcessor - Pass transaction off to secure processor
VERSION
This document describes Business::CCProcessor version 0.05
SYNOPSIS
use Business::CCProcessor;
use CGI::FormBuilder; # this is optional
my $cc = Business::CCProcessor->new();
my %data = (
'processor_settings' => \%processor_settings,
'credit_card_owner' => \%credit_card_owner,
);
See below for details about how those two hash references
ought to be structured.
You may then create a button to include in a web page, like this:
my $html_button = $cc->button_factory(\%data);
or use any one of the following three methods to get a
hash of fields, you can use if you want some additional
control over how the button is rendered.
my $fields = $cc->verisign(\%data);
my $fields = $cc->dia(\%data);
my $fields = $cc->paypal(\%data);
The data in the $fields hashref can then be used to
construct a web form submission button which will take
a browser to the credit card forms for these providers.
You might consider using CGI::FormBuilder, CGI, CGI::Simple
or even hand rolled html fed to print statements, to then
render the form with that data.DESCRIPTION
At present this module and its methods are trivially simple in what they do, offering as its one service, the ability to hide how to munge your web form's data into a post call to a supported credit card processor.
Business::CCProcessor will permit a script to collect non-financial data locally and then using an http POST call, hand that data off to a secure credit card processor which then collects the credit card parameters, and processes the transaction between the credit card owners account and the script owners account. This is a poor man's variant on Business::OnlinePayment for clients who cannot afford the video camera watched locked cages around their dedicated server, to collect credit card payments from their buyers or donors, in a real-time interaction with the credit card owner.
This module is for you if you need to accept online credit card payments for your organization or services but are not prepared to invest in an ssl certificate, a dedicated IP address, a dedicated server and the monitored restricted access to your server which the privacy of your customers or donors requires.
Initially this module offers five public methods: a constructor, a button_factory and methods for munging data for three (so far) credit card processors, but additional methods to handle additional credit card processors who permit this sort of interaction should be straight forward to add.
Each of the credit card processor methods takes a reference to a hash of values which you will have to create before calling the method. This data is generally of the form:
my %data = (
'processor_settings' => \%processor_settings,
'credit_card_owner' => \%credit_card_owner,
);The second part of the hash is fairly consistent across the methods, with some methods offering additional options for passing data than others, but generally, this hash looks like this:
%credit_card_owner = (
'fname' => '',
'lname' => '',
'addr1' => '',
'addr2' => '',
'city' => '',
'state' => '',
'postal_code' => '',
'comments' => '',
'comments1' => '',
'phone' => '',
'email' => '',
'employer' => '',
'occupation' => '',
'amount' => '',
'notes' => '',
'button_label' => '',
);The %processor_settings hash's structure is dependent on which credit card processor method you are using.
As this module develops, I anticipate also providing for a mode, to permit this module to be switched from 'commercial', to 'non-profit', to 'electoral_campaign' mode, to account for variances in how what data is collected for each of these types of users.
my $cc = Business::CCProcessor->new();
This method creates an object permitting access to the other methods provided by this module.
The three public methods listed below each take a reference to a hash of data collected, cleaned and validated from a preceeding web form interaction and returns a hash of fields which can be used to construct a submission button which will POST that data to a web accessible credit card processor.
my $html_button = $cc->button_factory(\%data);
By including the name of your credit card processor in the %data hash, as $data->{'processor_settings'}->{'processor'}, you can use the ->button_factory() method to access the magic of CGI::FormBuilder, and have returned to you a snippet of html code defining a Proceed_to_CC_Processor form button, ready for inclusion in a web page. The button will have encoded as hidden values, the data given to the method in its invocation, and that data should be handed off to the credit card processor, at least that data the processor is designed to handle.
If you need any more control than that over the final form of your web form, you can use these following methods, which are invoked by the ->button_factory() method when doing its work.
my %fields = $cc->verisign(\%data);
This method returns the fields necessary to process a payment with Verisign.
The %data hash must include the following:
%processor_settings = (
'processor' => 'verisign',
'action' => '' # <-- url of web form posted to
'login' => '' # <-- account id
'description' => '' # <-- description of transaction
'button_label' => '' # <-- what to call the button
);my %fields = $cc->dia(\%data);
This method returns the fields necessary to process a payment with Democracy In Action.
The %data hash must include the following:
%processor_settings = (
'processor' => 'dia',
'action' => '' # <-- url of web form posted to
'button_label' => '' #<-- what to call the button
);my %fields = $cc->paypal(\%data);
This method returns the fields necessary to process a payment with Paypal.
The %data hash must include the following:
%processor_settings = (
'processor' => 'paypal',
'action' => '' # <-- url of web form posted to
'business' => '' # <-- email address registered with paypal
'item_name' => '' # <-- description of transaction
'return_url' => '' # <-- url on your site to return to
'cancel_return_url' => '' # <-- url on your site to error out to
'currency_code' => '' # <-- EUR, USD, CAD etc.
'button_label' => '' #<-- what to call the button
);INTERFACE
DIAGNOSTICS
Error message here, perhaps with %s placeholders-
[Description of error here]
Another error message here-
[Description of error here]
[Et cetera, et cetera]
CONFIGURATION AND ENVIRONMENT
Business::CCProcessor requires no configuration files or environment variables.
DEPENDENCIES
None at the moment, though a future version will reguire CGI::FormBuilder for some additional methods.
INCOMPATIBILITIES
None reported.
BUGS AND LIMITATIONS
Apparently, some credit card processors require that their clients register the domain and path of the scripts which may refer a user and browser to them. Paypal did not reject connections coming from my own development sandbox. But both DiA and VeriSign seem to refuse to do business with the machine under my desk, when I used keys for accounts who's forms are hosted at real url's.
If the Verisgn account is setup to screen posts to its forms by referring url, it is possible to configure a new url by logging in to the VeriSign account, and following the following links:
Account Information ->
PayflowLink Info ->
Accepted URLs (look at bottom of configuration page)No bugs have been reported, but I'm sure this is riddled with them.
By no means should this module be mistaken for any sort of informed distillation of the wisdom available in the API's for the services these methods interface with. This is more an attempt to hide some of the ugly details from myself for some code I found myself rewriting on a regular basis.
At this early stage of development, I am simply working to write an interface which can be substituted into multiple copies of similiar code I am hosting in various scripts, which I'd like to refactor and simplify. If it serves your needs, great. If not, perhaps over time, this can evolve into a more generally useful tool to serve a broader audience.
At this point, this is a "works-for-me" kind of project and your input, questions, bug reports, patches and tests to create a more robust, stable and useful tool are certainly welcome.
I welcome bug reports and feature requests at both: http://www.campaignfoundations.com/project/issues as well as through the cpan hosted channels at: bug-business-ccprocessor@rt.cpan.org, or through the web interface at http://rt.cpan.org.
SEE ALSO
Business::OnlinePayment allows a script to accept credit card data from an end user or other source and process a transaction of funds between the account represented by the credit card data and the account owned by the merchant which deploys the script. Its a fine tool for a client who can afford the security it requires to appropriately handle credit card data.
AUTHOR
Hugh Esco <hesco@campaignfoundations.com>
LICENCE AND COPYRIGHT
Copyright (c) 2007, Hugh Esco <hesco@campaignfoundations.com>. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the terms of the Gnu Public License. See gpl.
DISCLAIMER OF WARRANTY
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.