OnlinePayment.pm

   1 package Business::OnlinePayment;
   2
   3 use strict;
   4 use vars qw($VERSION); # @ISA @EXPORT @EXPORT_OK $AUTOLOAD);
   5 use Carp;
   6
   7 require 5.005;
   8 #require Exporter;
   9
  10 #@ISA = (); #qw(Exporter AutoLoader);
  11 #@EXPORT = qw();
  12 #@EXPORT_OK = qw();
  13
  14 $VERSION = '3.00_04';
  15 sub VERSION { #Argument "3.00_01" isn't numeric in subroutine entry
  16   local($^W)=0;
  17   UNIVERSAL::VERSION(@_);
  18 }
  19
  20 my %fields = (
  21     is_success       => undef,
  22     failure_status   => undef,
  23     result_code      => undef,
  24     test_transaction => undef,
  25     require_avs      => undef,
  26     transaction_type => undef,
  27     error_message    => undef,
  28     authorization    => undef,
  29     server           => undef,
  30     port             => undef,
  31     path             => undef,
  32     server_response  => undef,
  33 );
  34
  35
  36 sub new {
  37     my($class,$processor,%data) = @_;
  38
  39     Carp::croak("unspecified processor") unless $processor;
  40
  41     my $subclass = "${class}::$processor";
  42     if(!defined(&$subclass)) {
  43         eval "use $subclass";
  44         Carp::croak("unknown processor $processor ($@)") if $@;
  45     }
  46
  47     my $self = bless {processor => $processor}, $subclass;
  48     $self->build_subs(keys %fields);
  49
  50     if($self->can("set_defaults")) {
  51         $self->set_defaults();
  52     }
  53
  54     foreach(keys %data) {
  55         my $key = lc($_);
  56         my $value = $data{$_};
  57         $key =~ s/^\-//;
  58         $self->build_subs($key);
  59         $self->$key($value);
  60     }
  61
  62     return $self;
  63 }
  64
  65 sub content {
  66     my($self,%params) = @_;
  67
  68     if(%params) {
  69         if($params{'type'}) { $self->transaction_type($params{'type'}); }
  70         %{$self->{'_content'}} = %params;
  71     }
  72     return %{$self->{'_content'}};
  73 }
  74
  75 sub required_fields {
  76     my($self,@fields) = @_;
  77
  78     my %content = $self->content();
  79     foreach(@fields) {
  80         Carp::croak("missing required field $_") unless exists $content{$_};
  81     }
  82 }
  83
  84 sub get_fields {
  85     my($self, @fields) = @_;
  86
  87     my %content = $self->content();
  88
  89     #my %new = ();
  90     #foreach(@fields) { $new{$_} = $content{$_}; }
  91     #return %new;
  92     map { $_ => $content{$_} } grep defined $content{$_}, @fields;
  93 }
  94
  95 sub remap_fields {
  96     my($self,%map) = @_;
  97
  98     my %content = $self->content();
  99     foreach( keys %map ) {
 100         $content{$map{$_}} = $content{$_};
 101     }
 102     $self->content(%content);
 103 }
 104
 105 sub submit {
 106     my($self) = @_;
 107
 108     Carp::croak("Processor subclass did not override submit function");
 109 }
 110
 111 sub dump_contents {
 112     my($self) = @_;
 113
 114     my %content = $self->content();
 115     my $dump = "";
 116     foreach(keys %content) {
 117         $dump .= "$_ = $content{$_}\n";
 118     }
 119     return $dump;
 120 }
 121
 122 # didnt use AUTOLOAD because Net::SSLeay::AUTOLOAD passes right to
 123 # AutoLoader::AUTOLOAD, instead of passing up the chain
 124 sub build_subs {
 125     my $self = shift;
 126     no warnings 'redefine';
 127     foreach(@_) {
 128         eval "sub $_ { my \$self = shift; if(\@_) { \$self->{$_} = shift; } return \$self->{$_}; }";
 129     }
 130 }
 131
 132 1;
 133
 134 __END__
 135
 136 =head1 NAME
 137
 138 Business::OnlinePayment - Perl extension for online payment processing
 139
 140 =head1 SYNOPSIS
 141
 142   use Business::OnlinePayment;
 143
 144   my $transaction = new Business::OnlinePayment($processor, %processor_info);
 145   $transaction->content(
 146                         type       => 'Visa',
 147                         amount     => '49.95',
 148                         cardnumber => '1234123412341238',
 149                         expiration => '0100',
 150                         name       => 'John Q Doe',
 151                        );
 152   $transaction->submit();
 153
 154   if($transaction->is_success()) {
 155     print "Card processed successfully: ".$transaction->authorization()."\n";
 156   } else {
 157     print "Card was rejected: ".$transaction->error_message()."\n";
 158   }
 159
 160 =head1 DESCRIPTION
 161
 162 Business::OnlinePayment is a generic module for processing payments through
 163 online credit card processors, electronic cash systems, etc.
 164
 165 =head1 METHODS AND FUNCTIONS
 166
 167 =head2 new($processor, %processor_options);
 168
 169 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.
 170
 171 =head2 content(%content);
 172
 173 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:
 174
 175 =over 4
 176
 177 =item * type
 178
 179 Transaction type, supported types are:
 180 Visa, MasterCard, American Express, Discover, Check (not all processors support all these transaction types).
 181
 182 =item * login
 183
 184 Your login name to use for authentication to the online processor.
 185
 186 =item * password
 187
 188 Your password to use for authentication to the online processor.
 189
 190 =item * action
 191
 192 What to do with the transaction (currently available are: Normal Authorization, Authorization Only, Credit, Post Authorization)
 193
 194 =item * description
 195
 196 A description of the transaction (used by some processors to send information to the client, normally not a required field).
 197
 198 =item * amount
 199
 200 The amount of the transaction, most processors dont want dollar signs and the like, just a floating point number.
 201
 202 =item * invoice_number
 203
 204 An invoice number, for your use and not normally required, many processors require this field to be a numeric only field.
 205
 206 =item * customer_id
 207
 208 A customer identifier, again not normally required.
 209
 210 =item * name
 211
 212 The customers name, your processor may not require this.
 213
 214 =item * address
 215
 216 The customers address (your processor may not require this unless you are requiring AVS Verification).
 217
 218 =item * city
 219
 220 The customers city (your processor may not require this unless you are requiring AVS Verification).
 221
 222 =item * state
 223
 224 The customers state (your processor may not require this unless you are requiring AVS Verification).
 225
 226 =item * zip
 227
 228 The customers zip code (your processor may not require this unless you are requiring AVS Verification).
 229
 230 =item * country
 231
 232 Customer's country.
 233
 234 =item * phone
 235
 236 Customer's phone number.
 237
 238 =item * fax
 239
 240 Customer's fax number.
 241
 242 =item * email
 243
 244 Customer's email address.
 245
 246 =item * card_number
 247
 248 Credit card number (obviously not required for non-credit card transactions).
 249
 250 =item * exp_date
 251
 252 Credit card expiration (obviously not required for non-credit card transactions).
 253
 254 =item * account_number
 255
 256 Bank account number for electronic checks or electronic funds transfer.
 257
 258 =item * routing_code
 259
 260 Bank's routing code for electronic checks or electronic funds transfer.
 261
 262 =item * bank_name
 263
 264 Bank's name for electronic checks or electronic funds transfer.
 265
 266 =back
 267
 268 =head2 submit();
 269
 270 Submit the transaction to the processor for completion
 271
 272 =head2 is_success();
 273
 274 Returns true if the transaction was submitted successfully, false if it failed (or undef if it has not been submitted yet).
 275
 276 =head2 failure_status();
 277
 278 If the transactdion failed, it can optionally return a specific failure status
 279 (normalized, not gateway-specific).  Currently defined statuses are: "expired",
 280 "nsf" (non-sufficient funds), "stolen", "pickup", "blacklisted" and
 281 "declined" (card/transaction declines only, not other errors).
 282
 283 Note that (as of Aug 2006) this is only supported by some of the newest
 284 processor modules, and that, even if supported, a failure status is an entirely
 285 optional field that is only set for specific kinds of failures.
 286
 287 =head2 result_code();
 288
 289 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.
 290
 291 =head2 test_transaction();
 292
 293 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).
 294
 295 =head2 require_avs();
 296
 297 Providing a true argument to this module will turn on address verification (if the processor supports it).
 298
 299 =head2 transaction_type();
 300
 301 Retrieve the transaction type (the 'type' argument to contents();).  Generally only used internally, but provided in case it is useful.
 302
 303 =head2 error_message();
 304
 305 If the transaction has been submitted but was not accepted, this function will return the provided error message (if any) that the processor returned.
 306
 307 =head2 authorization();
 308
 309 If the transaction has been submitted and accepted, this function will provide you with the authorization code that the processor returned.
 310
 311 =head2 server();
 312
 313 Retrieve or change the processor submission server address (CHANGE AT YOUR OWN RISK).
 314
 315 =head2 port();
 316
 317 Retrieve or change the processor submission port (CHANGE AT YOUR OWN RISK).
 318
 319 =head2 path();
 320
 321 Retrieve or change the processor submission path (CHANGE AT YOUR OWN RISK).
 322
 323 =head1 AUTHORS
 324
 325 Jason Kohles, email@jasonkohles.com
 326
 327 (v3 rewrite) Ivan Kohler <ivan-business-onlinepayment@420.am>
 328
 329 =head1 DISCLAIMER
 330
 331 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
 332 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
 333 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 334
 335
 336 =head1 SEE ALSO
 337
 338 http://420.am/business-onlinepayment/
 339
 340 For verification of credit card checksums, see L<Business::CreditCard>.
 341
 342 =cut