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