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_03';
  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     foreach(@_) {
 126         eval "sub $_ { my \$self = shift; if(\@_) { \$self->{$_} = shift; } return \$self->{$_}; }";
 127     }
 128 }
 129
 130 1;
 131
 132 __END__
 133
 134 =head1 NAME
 135
 136 Business::OnlinePayment - Perl extension for online payment processing
 137
 138 =head1 SYNOPSIS
 139
 140   use Business::OnlinePayment;
 141
 142   my $transaction = new Business::OnlinePayment($processor, %processor_info);
 143   $transaction->content(
 144                         type       => 'Visa',
 145                         amount     => '49.95',
 146                         cardnumber => '1234123412341238',
 147                         expiration => '0100',
 148                         name       => 'John Q Doe',
 149                        );
 150   $transaction->submit();
 151
 152   if($transaction->is_success()) {
 153     print "Card processed successfully: ".$transaction->authorization()."\n";
 154   } else {
 155     print "Card was rejected: ".$transaction->error_message()."\n";
 156   }
 157
 158 =head1 DESCRIPTION
 159
 160 Business::OnlinePayment is a generic module for processing payments through
 161 online credit card processors, electronic cash systems, etc.
 162
 163 =head1 METHODS AND FUNCTIONS
 164
 165 =head2 new($processor, %processor_options);
 166
 167 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.
 168
 169 =head2 content(%content);
 170
 171 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:
 172
 173 =over 4
 174
 175 =item * type
 176
 177 Transaction type, supported types are:
 178 Visa, MasterCard, American Express, Discover, Check (not all processors support all these transaction types).
 179
 180 =item * login
 181
 182 Your login name to use for authentication to the online processor.
 183
 184 =item * password
 185
 186 Your password to use for authentication to the online processor.
 187
 188 =item * action
 189
 190 What to do with the transaction (currently available are: Normal Authorization, Authorization Only, Credit, Post Authorization)
 191
 192 =item * description
 193
 194 A description of the transaction (used by some processors to send information to the client, normally not a required field).
 195
 196 =item * amount
 197
 198 The amount of the transaction, most processors dont want dollar signs and the like, just a floating point number.
 199
 200 =item * invoice_number
 201
 202 An invoice number, for your use and not normally required, many processors require this field to be a numeric only field.
 203
 204 =item * customer_id
 205
 206 A customer identifier, again not normally required.
 207
 208 =item * name
 209
 210 The customers name, your processor may not require this.
 211
 212 =item * address
 213
 214 The customers address (your processor may not require this unless you are requiring AVS Verification).
 215
 216 =item * city
 217
 218 The customers city (your processor may not require this unless you are requiring AVS Verification).
 219
 220 =item * state
 221
 222 The customers state (your processor may not require this unless you are requiring AVS Verification).
 223
 224 =item * zip
 225
 226 The customers zip code (your processor may not require this unless you are requiring AVS Verification).
 227
 228 =item * country
 229
 230 Customer's country.
 231
 232 =item * phone
 233
 234 Customer's phone number.
 235
 236 =item * fax
 237
 238 Customer's fax number.
 239
 240 =item * email
 241
 242 Customer's email address.
 243
 244 =item * card_number
 245
 246 Credit card number (obviously not required for non-credit card transactions).
 247
 248 =item * exp_date
 249
 250 Credit card expiration (obviously not required for non-credit card transactions).
 251
 252 =item * account_number
 253
 254 Bank account number for electronic checks or electronic funds transfer.
 255
 256 =item * routing_code
 257
 258 Bank's routing code for electronic checks or electronic funds transfer.
 259
 260 =item * bank_name
 261
 262 Bank's name for electronic checks or electronic funds transfer.
 263
 264 =back
 265
 266 =head2 submit();
 267
 268 Submit the transaction to the processor for completion
 269
 270 =head2 is_success();
 271
 272 Returns true if the transaction was submitted successfully, false if it failed (or undef if it has not been submitted yet).
 273
 274 =head2 result_code();
 275
 276 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.
 277
 278 =head2 test_transaction();
 279
 280 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).
 281
 282 =head2 require_avs();
 283
 284 Providing a true argument to this module will turn on address verification (if the processor supports it).
 285
 286 =head2 transaction_type();
 287
 288 Retrieve the transaction type (the 'type' argument to contents();).  Generally only used internally, but provided in case it is useful.
 289
 290 =head2 error_message();
 291
 292 If the transaction has been submitted but was not accepted, this function will return the provided error message (if any) that the processor returned.
 293
 294 =head2 authorization();
 295
 296 If the transaction has been submitted and accepted, this function will provide you with the authorization code that the processor returned.
 297
 298 =head2 server();
 299
 300 Retrieve or change the processor submission server address (CHANGE AT YOUR OWN RISK).
 301
 302 =head2 port();
 303
 304 Retrieve or change the processor submission port (CHANGE AT YOUR OWN RISK).
 305
 306 =head2 path();
 307
 308 Retrieve or change the processor submission path (CHANGE AT YOUR OWN RISK).
 309
 310 =head1 AUTHORS
 311
 312 Jason Kohles, email@jasonkohles.com
 313
 314 (v3 rewrite) Ivan Kohler <ivan-business-onlinepayment@420.am>
 315
 316 =head1 DISCLAIMER
 317
 318 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
 319 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
 320 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 321
 322
 323 =head1 SEE ALSO
 324
 325 http://420.am/business-onlinepayment/
 326
 327 For verification of credit card checksums, see L<Business::CreditCard>.
 328
 329 =cut