OnlinePayment.pm

   1 package Business::OnlinePayment;
   2
   3 use strict;
   4 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK $AUTOLOAD);
   5
   6 require 5.004;
   7 require Exporter;
   8
   9 @ISA = qw(Exporter AutoLoader);
  10 @EXPORT = qw();
  11 @EXPORT_OK = qw();
  12
  13 $VERSION = do { my @r=(q$Revision: 1.1 $=~/\d+/g);sprintf "%d."."%02d"x$#r,@r};
  14
  15 use Carp();
  16
  17 my %fields = (
  18     is_success       => undef,
  19     result_code      => undef,
  20     test_transaction => undef,
  21     require_avs      => undef,
  22     transaction_type => undef,
  23     error_message    => undef,
  24     authorization    => undef,
  25     server           => undef,
  26     port             => undef,
  27     path             => undef,
  28     server_response  => undef,
  29 );
  30
  31
  32 sub new {
  33     my($class,$processor,%data) = @_;
  34
  35     Carp::croak("unspecified processor") unless $processor;
  36
  37     my $subclass = "${class}::$processor";
  38     if(!defined(&$subclass)) {
  39         eval "use $subclass";
  40         Carp::croak("unknown processor $processor ($@)") if $@;
  41     }
  42
  43     my $self = bless {processor => $processor}, $subclass;
  44     $self->build_subs(keys %fields);
  45
  46     if($self->can("set_defaults")) {
  47         $self->set_defaults();
  48     }
  49
  50     foreach(keys %data) {
  51         my $key = lc($_);
  52         my $value = $data{$_};
  53         $key =~ s/^\-//;
  54         $self->build_subs($key);
  55         $self->$key($value);
  56     }
  57
  58     return $self;
  59 }
  60
  61 sub content {
  62     my($self,%params) = @_;
  63
  64     if(%params) {
  65         if($params{'type'}) { $self->transaction_type($params{'type'}); }
  66         %{$self->{'_content'}} = %params;
  67     }
  68     return %{$self->{'_content'}};
  69 }
  70
  71 sub required_fields {
  72     my($self,@fields) = @_;
  73
  74     my %content = $self->content();
  75     foreach(@fields) {
  76         Carp::croak("missing required field $_") unless exists $content{$_};
  77     }
  78 }
  79
  80 sub get_fields {
  81     my($self,@fields) = @_;
  82
  83     my %content = $self->content();
  84     my %new = ();
  85     foreach(@fields) { $new{$_} = $content{$_}; }
  86     return %new;
  87 }
  88
  89 sub remap_fields {
  90     my($self,%map) = @_;
  91
  92     my %content = $self->content();
  93     foreach(%map) {
  94         $content{$map{$_}} = $content{$_};
  95     }
  96     $self->content(%content);
  97 }
  98
  99 sub submit {
 100     my($self) = @_;
 101
 102     Carp::croak("Processor subclass did not override submit function");
 103 }
 104
 105 sub dump_contents {
 106     my($self) = @_;
 107
 108     my %content = $self->content();
 109     my $dump = "";
 110     foreach(keys %content) {
 111         $dump .= "$_ = $content{$_}\n";
 112     }
 113     return $dump;
 114 }
 115
 116 # didnt use AUTOLOAD because Net::SSLeay::AUTOLOAD passes right to
 117 # AutoLoader::AUTOLOAD, instead of passing up the chain
 118 sub build_subs {
 119     my $self = shift;
 120     foreach(@_) {
 121         eval "sub $_ { my \$self = shift; if(\@_) { \$self->{$_} = shift; } return \$self->{$_}; }";
 122     }
 123 }
 124
 125 1;
 126
 127 __END__
 128
 129 =head1 NAME
 130
 131 Business::OnlinePayment - Perl extension for online payment processing
 132
 133 =head1 SYNOPSIS
 134
 135   use Business::OnlinePayment;
 136
 137   my $transaction = new Business::OnlinePayment($processor, %processor_info);
 138   $transaction->content(
 139                         type       => 'Visa',
 140                         amount     => '49.95',
 141                         cardnumber => '1234123412341238',
 142                         expiration => '0100',
 143                         name       => 'John Q Doe',
 144                        );
 145   $transaction->submit();
 146
 147   if($transaction->is_success()) {
 148     print "Card processed successfully: ".$transaction->authorization()."\n";
 149   } else {
 150     print "Card was rejected: ".$transaction->error_message()."\n";
 151   }
 152
 153 =head1 DESCRIPTION
 154
 155 Business::OnlinePayment is a generic module for processing payments through
 156 online credit card processors, electronic cash systems, etc.
 157
 158 =head1 METHODS AND FUNCTIONS
 159
 160 =head2 new($processor, %processor_options);
 161
 162 Create a new Business::OnlinePayment object, $processor is required, and defines the online processor to use.  If necessary, processor options can be specified, currently supported options are 'Server', 'Port', and 'Path', which specify how to find the online processor (https://server:port/path), but individual processor modules should supply reasonable defaults for this information, override the defaults only if absolutely necessary (especially path), as the processor module was probably written with a specific target script in mind.
 163
 164 =head2 content(%content);
 165
 166 The information necessary for the transaction, this tends to vary a little depending on the processor, so we have chosen to use a system which defines specific fields in the frontend which get mapped to the correct fields in the backend.  The currently defined fields are:
 167
 168 =over 4
 169
 170 =item * type
 171
 172 Transaction type, supported types are:
 173 Visa, MasterCard, American Express, Discover, Check (not all processors support all these transaction types).
 174
 175 =item * login
 176
 177 Your login name to use for authentication to the online processor.
 178
 179 =item * password
 180
 181 Your password to use for authentication to the online processor.
 182
 183 =item * action
 184
 185 What to do with the transaction (currently available are: Normal Authorization, Authorization Only, Credit, Post Authorization)
 186
 187 =item * description
 188
 189 A description of the transaction (used by some processors to send information to the client, normally not a required field).
 190
 191 =item * amount
 192
 193 The amount of the transaction, most processors dont want dollar signs and the like, just a floating point number.
 194
 195 =item * invoice_number
 196
 197 An invoice number, for your use and not normally required, many processors require this field to be a numeric only field.
 198
 199 =item * customer_id
 200
 201 A customer identifier, again not normally required.
 202
 203 =item * name
 204
 205 The customers name, your processor may not require this.
 206
 207 =item * address
 208
 209 The customers address (your processor may not require this unless you are requiring AVS Verification).
 210
 211 =item * city
 212
 213 The customers city (your processor may not require this unless you are requiring AVS Verification).
 214
 215 =item * state
 216
 217 The customers state (your processor may not require this unless you are requiring AVS Verification).
 218
 219 =item * zip
 220
 221 The customers zip code (your processor may not require this unless you are requiring AVS Verification).
 222
 223 =item * country
 224
 225 Customer's country.
 226
 227 =item * phone
 228
 229 Customer's phone number.
 230
 231 =item * fax
 232
 233 Customer's fax number.
 234
 235 =item * email
 236
 237 Customer's email address.
 238
 239 =item * card_number
 240
 241 Credit card number (obviously not required for non-credit card transactions).
 242
 243 =item * exp_date
 244
 245 Credit card expiration (obviously not required for non-credit card transactions).
 246
 247 =item * account_number
 248
 249 Bank account number for electronic checks or electronic funds transfer.
 250
 251 =item * routing_code
 252
 253 Bank's routing code for electronic checks or electronic funds transfer.
 254
 255 =item * bank_name
 256
 257 Bank's name for electronic checks or electronic funds transfer.
 258
 259 =back
 260
 261 =head2 submit();
 262
 263 Submit the transaction to the processor for completion
 264
 265 =head2 is_success();
 266
 267 Returns true if the transaction was submitted successfully, false if it failed (or undef if it has not been submitted yet).
 268
 269 =head2 result_code();
 270
 271 Returns the precise result code that the processor returned, these are normally one letter codes that don't mean much unless you understand the protocol they speak, you probably don't need this, but it's there just in case.
 272
 273 =head2 test_transaction();
 274
 275 Most processors provide a test mode, where submitted transactions will not actually be charged or added to your batch, calling this function with a true argument will turn that mode on if the processor supports it, or generate a fatal error if the processor does not support a test mode (which is probably better than accidentally making real charges).
 276
 277 =head2 require_avs();
 278
 279 Providing a true argument to this module will turn on address verification (if the processor supports it).
 280
 281 =head2 transaction_type();
 282
 283 Retrieve the transaction type (the 'type' argument to contents();).  Generally only used internally, but provided in case it is useful.
 284
 285 =head2 error_message();
 286
 287 If the transaction has been submitted but was not accepted, this function will return the provided error message (if any) that the processor returned.
 288
 289 =head2 authorization();
 290
 291 If the transaction has been submitted and accepted, this function will provide you with the authorization code that the processor returned.
 292
 293 =head2 server();
 294
 295 Retrieve or change the processor submission server address (CHANGE AT YOUR OWN RISK).
 296
 297 =head2 port();
 298
 299 Retrieve or change the processor submission port (CHANGE AT YOUR OWN RISK).
 300
 301 =head2 path();
 302
 303 Retrieve or change the processor submission path (CHANGE AT YOUR OWN RISK).
 304
 305 =head1 AUTHOR
 306
 307 Jason Kohles, email@jasonkohles.com
 308
 309 =head1 DISCLAIMER
 310
 311 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
 312 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
 313 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 314
 315
 316 =head1 SEE ALSO
 317
 318 For verification of credit card checksums, see L<Business::CreditCard>.
 319
 320 =cut