- fix HTTPS requires to match code
[Business-OnlinePayment-PayflowPro.git] / PayflowPro.pm
1 package Business::OnlinePayment::PayflowPro;
2
3 use strict;
4 use vars qw($VERSION $DEBUG);
5 use Carp qw(carp croak);
6 use CGI;
7 use Digest::MD5;
8 use Business::OnlinePayment::HTTPS 0.06;
9
10 use base qw(Business::OnlinePayment::HTTPS);
11
12 $VERSION = '0.07_06';
13 $VERSION = eval $VERSION;
14 $DEBUG   = 0;
15
16 # return current request_id or generate a new one if not yet set
17 sub request_id {
18     my $self = shift;
19     if ( ref($self) ) {
20         $self->{"__request_id"} = shift if (@_); # allow value change/reset
21         $self->{"__request_id"} = $self->_new_request_id()
22           unless ( $self->{"__request_id"} );
23         return $self->{"__request_id"};
24     }
25     else {
26         return $self->_new_request_id();
27     }
28 }
29
30 sub _new_request_id {
31     my $self = shift;
32     my $md5  = Digest::MD5->new();
33     $md5->add( $$, time(), rand(time) );
34     return $md5->hexdigest();
35 }
36
37 sub debug {
38     my $self = shift;
39
40     if (@_) {
41         my $level = shift || 0;
42         if ( ref($self) ) {
43             $self->{"__DEBUG"} = $level;
44         }
45         else {
46             $DEBUG = $level;
47         }
48         $Business::OnlinePayment::HTTPS::DEBUG = $level;
49     }
50     return ref($self) ? ( $self->{"__DEBUG"} || $DEBUG ) : $DEBUG;
51 }
52
53 # cvv2_code: support legacy code and but deprecate method
54 sub cvv2_code { shift->cvv2_response(@_); }
55
56 sub set_defaults {
57     my $self = shift;
58     my %opts = @_;
59
60     # standard B::OP methods/data
61     #$self->server("payflow.verisign.com");
62     $self->server("payflowpro.verisign.com");
63     $self->port("443");
64     $self->path("/transaction");
65
66     $self->build_subs(qw( 
67                           partner vendor
68                           client_certification_id client_timeout
69                           headers test_server
70                           cert_path
71                           order_number avs_code cvv2_response
72                           response_page response_code response_headers
73                      ));
74
75     # module specific data
76     if ( $opts{debug} ) {
77         $self->debug( $opts{debug} );
78         delete $opts{debug};
79     }
80
81     # HTTPS Interface Dev Guide: must be set but will be removed in future
82     $self->client_certification_id("ClientCertificationIdNotSet");
83
84     # required: 45 secs recommended by HTTPS Interface Dev Guide
85     $self->client_timeout(45);
86
87     $self->test_server( "pilot-payflowpro.verisign.com" );
88 }
89
90 sub _map_fields {
91     my ($self) = @_;
92
93     my %content = $self->content();
94
95     #ACTION MAP
96     my %actions = (
97         'normal authorization' => 'S',    # Sale transaction
98         'credit'               => 'C',    # Credit (refund)
99         'authorization only'   => 'A',    # Authorization
100         'post authorization'   => 'D',    # Delayed Capture
101         'void'                 => 'V',    # Void
102     );
103
104     $content{'action'} = $actions{ lc( $content{'action'} ) }
105       || $content{'action'};
106
107     # TYPE MAP
108     my %types = (
109         'visa'             => 'C',
110         'mastercard'       => 'C',
111         'american express' => 'C',
112         'discover'         => 'C',
113         'cc'               => 'C',
114
115         #'check'            => 'ECHECK',
116     );
117
118     $content{'type'} = $types{ lc( $content{'type'} ) } || $content{'type'};
119
120     $self->transaction_type( $content{'type'} );
121
122     # stuff it back into %content
123     $self->content(%content);
124 }
125
126 sub _revmap_fields {
127     my ( $self, %map ) = @_;
128     my %content = $self->content();
129     foreach ( keys %map ) {
130         $content{$_} =
131           ref( $map{$_} )
132           ? ${ $map{$_} }
133           : $content{ $map{$_} };
134     }
135     $self->content(%content);
136 }
137
138 sub expdate_mmyy {
139     my $self       = shift;
140     my $expiration = shift;
141     my $expdate_mmyy;
142     if ( defined($expiration) and $expiration =~ /^(\d+)\D+\d*(\d{2})$/ ) {
143         my ( $month, $year ) = ( $1, $2 );
144         $expdate_mmyy = sprintf( "%02d", $month ) . $year;
145     }
146     return defined($expdate_mmyy) ? $expdate_mmyy : $expiration;
147 }
148
149 sub submit {
150     my ($self) = @_;
151
152     $self->_map_fields();
153
154     my %content = $self->content;
155
156     if ( $self->transaction_type() ne 'C' ) {
157         croak( "PayflowPro can't (yet?) handle transaction type: "
158               . $self->transaction_type() );
159     }
160
161     my $expdate_mmyy = $self->expdate_mmyy( $content{"expiration"} );
162     my $zip          = $content{'zip'};
163     $zip =~ s/[^[:alnum:]]//g;
164
165     $self->server( $self->test_server ) if $self->test_transaction;
166
167     my $vendor  = $self->vendor;
168     my $partner = $self->partner;
169
170     $self->_revmap_fields(
171
172         # BUG?: VENDOR B::OP:PayflowPro < 0.05 backward compatibility.  If
173         # vendor not set use login although test indicate undef vendor is ok
174         VENDOR => $vendor ? \$vendor : 'login',
175         PARTNER  => \$partner,
176         USER     => 'login',
177         PWD      => 'password',
178         TRXTYPE  => 'action',
179         TENDER   => 'type',
180         ORIGID   => 'order_number',
181         COMMENT1 => 'description',
182         COMMENT2 => 'invoice_number',
183
184         ACCT    => 'card_number',
185         CVV2    => 'cvv2',
186         EXPDATE => \$expdate_mmyy,    # MM/YY from 'expiration'
187         AMT     => 'amount',
188
189         FIRSTNAME   => 'first_name',
190         LASTNAME    => 'last_name',
191         NAME        => 'name',
192         EMAIL       => 'email',
193         COMPANYNAME => 'company',
194         STREET      => 'address',
195         CITY        => 'city',
196         STATE       => 'state',
197         ZIP         => \$zip,          # 'zip' with non-alnums removed
198         COUNTRY     => 'country',
199     );
200
201     my @required = qw( TRXTYPE TENDER PARTNER VENDOR USER PWD );
202     if ( $self->transaction_type() eq 'C' ) {    # credit card
203         if (   $content{'action'} =~ /^[CDV]$/
204             && defined( $content{'ORIGID'} )
205             && length( $content{'ORIGID'} ) )
206         {
207             push @required, qw(ORIGID);
208         }
209         else {
210
211             # never get here, we croak above if transaction_type ne 'C'
212             push @required, qw(AMT ACCT EXPDATE);
213         }
214     }
215     $self->required_fields(@required);
216
217     my %params = $self->get_fields(
218         qw(
219           VENDOR PARTNER USER PWD TRXTYPE TENDER ORIGID COMMENT1 COMMENT2
220           ACCT CVV2 EXPDATE AMT
221           FIRSTNAME LASTNAME NAME EMAIL COMPANYNAME
222           STREET CITY STATE ZIP COUNTRY
223           )
224     );
225
226     # get header data
227     my %req_headers = %{ $self->headers || {} };
228
229     # get request_id from %content if defined for ease of use
230     if ( defined $content{"request_id"} ) {
231         $self->request_id( $content{"request_id"} );
232     }
233
234     unless ( defined( $req_headers{"X-VPS-Request-ID"} ) ) {
235         $req_headers{"X-VPS-Request-ID"} = $self->request_id();
236     }
237
238     unless ( defined( $req_headers{"X-VPS-VIT-Client-Certification-Id"} ) ) {
239         $req_headers{"X-VPS-VIT-Client-Certification-Id"} =
240           $self->client_certification_id;
241     }
242
243     unless ( defined( $req_headers{"X-VPS-Client-Timeout"} ) ) {
244         $req_headers{"X-VPS-Client-Timeout"} = $self->client_timeout();
245     }
246
247     my %options = (
248         "Content-Type" => "text/namevalue",
249         "headers"      => \%req_headers,
250     );
251
252     my ( $page, $resp, %resp_headers ) =
253       $self->https_post( \%options, \%params );
254
255     $self->response_code( $resp );
256     $self->response_page( $page );
257     $self->response_headers( \%resp_headers );
258
259     # $page should contain name=value[[&name=value]...] pairs
260     my $cgi = CGI->new("$page");
261
262     # AVS and CVS values may be set on success or failure
263     my $avs_code;
264     if ( defined $cgi->param("AVSADDR") or defined $cgi->param("AVSZIP") ) {
265         if ( $cgi->param("AVSADDR") eq "Y" && $cgi->param("AVSZIP") eq "Y" ) {
266             $avs_code = "Y";
267         }
268         elsif ( $cgi->param("AVSADDR") eq "Y" ) {
269             $avs_code = "A";
270         }
271         elsif ( $cgi->param("AVSZIP") eq "Y" ) {
272             $avs_code = "Z";
273         }
274         elsif ( $cgi->param("AVSADDR") eq "N" or $cgi->param("AVSZIP") eq "N" )
275         {
276             $avs_code = "N";
277         }
278         else {
279             $avs_code = "";
280         }
281     }
282
283     $self->avs_code($avs_code);
284     $self->cvv2_response( $cgi->param("CVV2MATCH") );
285     $self->result_code( $cgi->param("RESULT") );
286     $self->order_number( $cgi->param("PNREF") );
287     $self->error_message( $cgi->param("RESPMSG") );
288     $self->authorization( $cgi->param("AUTHCODE") );
289
290     # RESULT must be an explicit zero, not just numerically equal
291     if ( $cgi->param("RESULT") eq "0" ) {
292         $self->is_success(1);
293     }
294     else {
295         $self->is_success(0);
296     }
297 }
298
299 1;
300
301 __END__
302
303 =head1 NAME
304
305 Business::OnlinePayment::PayflowPro - Payflow Pro backend for Business::OnlinePayment
306
307 =head1 SYNOPSIS
308
309   use Business::OnlinePayment;
310   
311   my $tx = new Business::OnlinePayment(
312       'PayflowPro',
313       'vendor'  => 'your_vendor',
314       'partner' => 'your_partner',
315       'client_certification_id' => 'GuidUpTo32Chars',
316   );
317   
318   # See the module documentation for details of content()
319   $tx->content(
320       type           => 'VISA',
321       action         => 'Normal Authorization',
322       description    => 'Business::OnlinePayment::PayflowPro test',
323       amount         => '49.95',
324       invoice_number => '100100',
325       customer_id    => 'jsk',
326       name           => 'Jason Kohles',
327       address        => '123 Anystreet',
328       city           => 'Anywhere',
329       state          => 'GA',
330       zip            => '30004',
331       email          => 'ivan-payflowpro@420.am',
332       card_number    => '4111111111111111',
333       expiration     => '12/09',
334       cvv2           => '123',
335       order_number   => 'string',
336       request_id     => 'unique_identifier_for_transaction',
337   );
338   
339   $tx->submit();
340   
341   if ( $tx->is_success() ) {
342       print(
343           "Card processed successfully: ", $tx->authorization, "\n",
344           "order number: ",                $tx->order_number,  "\n",
345           "CVV2 response: ",               $tx->cvv2_response, "\n",
346           "AVS code: ",                    $tx->avs_code,      "\n",
347       );
348   }
349   else {
350       my $info = "";
351       $info = " (CVV2 mismatch)" if ( $tx->result_code == 114 );
352       
353       print(
354           "Card was rejected: ", $tx->error_message, $info, "\n",
355           "order number: ",      $tx->order_number,         "\n",
356       );
357   }
358
359 =head1 DESCRIPTION
360
361 This module is a back end driver that implements the interface
362 specified by L<Business::OnlinePayment> to support payment handling
363 via the PayPal's Payflow Pro Internet payment solution.
364
365 See L<Business::OnlinePayment> for details on the interface this
366 modules supports.
367
368 =head1 Standard methods
369
370 =over 4
371
372 =item set_defaults()
373
374 This method sets the 'server' attribute to 'payflowpro.verisign.com'
375 and the port attribute to '443'.  This method also sets up the
376 L</Module specific methods> described below.
377
378 =item submit()
379
380 =back
381
382 =head1 Unofficial methods
383
384 This module provides the following methods which are not officially
385 part of the standard Business::OnlinePayment interface (as of 3.00_06)
386 but are nevertheless supported by multiple gateways modules and
387 expected to be standardized soon:
388
389 =over 4
390
391 =item L<order_number()|/order_number()>
392
393 =item L<avs_code()|/avs_code()>
394
395 =item L<cvv2_response()|/cvv2_response()>
396
397 =back
398
399 =head1 Module specific methods
400
401 This module provides the following methods which are not currently
402 part of the standard Business::OnlinePayment interface:
403
404 =head2 client_certification_id()
405
406 This gets/sets the X-VPS-VITCLIENTCERTIFICATION-ID which is REQUIRED
407 and defaults to "ClientCertificationIdNotSet".  This is described in
408 Website Payments Pro HTTPS Interface Developer's Guide as follows:
409
410 "A random globally unique identifier (GUID) that is currently
411 required. This requirement will be removed in the future. At this
412 time, you can send any alpha-numeric ID up to 32 characters in length.
413
414 NOTE: Once you have created this ID, do not change it. Use the same ID
415 for every transaction."
416
417 =head2 client_timeout()
418
419 Timeout value, in seconds, after which this transaction should be
420 aborted.  Defaults to 45, the value recommended by the Website
421 Payments Pro HTTPS Interface Developer's Guide.
422
423 =head2 debug()
424
425 Enable or disble debugging.  The value specified here will also set
426 $Business::OnlinePayment::HTTPS::DEBUG in submit() to aid in
427 troubleshooting problems.
428
429 =head2 expdate_mmyy()
430
431 The expdate_mmyy() method takes a single scalar argument (typically
432 the value in $content{expiration}) and attempts to parse and format
433 and put the date in MMYY format as required by PayflowPro
434 specification.  If unable to parse the expiration date simply leave it
435 as is and let the PayflowPro system attempt to handle it as-is.
436
437 =head2 request_id()
438
439 It is recommended that you specify your own unique request_id for each
440 transaction in %content.  A request_id is REQUIRED by the PayflowPro
441 processor.  If a request_id is not set, then Digest::MD5 is used to
442 attempt to generate a request_id for a transaction.
443
444 =head2 Deprecated methods
445
446 The following methods are deprecated and may be removed in a future
447 release.  Values for vendor and partner should now be set as arguments
448 to Business::OnlinePayment->new().  The value for cert_path was used
449 to support passing a path to PFProAPI.pm (a Perl module/SDK from
450 Verisign/Paypal) which is no longer used.
451
452 =over 4
453
454 =item vendor()
455
456 =item partner()
457
458 =item cert_path()
459
460 =item cvv2_code()
461
462 =back
463
464 =head1 Settings
465
466 The following default settings exist:
467
468 =over 4
469
470 =item server
471
472 payflowpro.verisign.com or pilot-payflowpro.verisign.com if
473 test_transaction() is TRUE
474
475 =item port
476
477 443
478
479 =back
480
481 =head1 Handling of content(%content)
482
483 The following rules apply to content(%content) data:
484
485 =head2 action
486
487 If 'action' matches one of the following keys it is replaced by the
488 right hand side value:
489
490   'normal authorization' => 'S', # Sale transaction
491   'credit'               => 'C', # Credit (refund)
492   'authorization only'   => 'A', # Authorization
493   'post authorization'   => 'D', # Delayed Capture
494   'void'                 => 'V',
495
496 If 'action' is 'C', 'D' or 'V' and 'order_number' is not set then
497 'amount', 'card_number' and 'expiration' must be set.
498
499 =head2 type
500
501 If 'type' matches one of the following keys it is replaced by the
502 right hand side value:
503
504   'visa'               => 'C',
505   'mastercard'         => 'C',
506   'american express'   => 'C',
507   'discover'           => 'C',
508   'cc'                 => 'C',
509
510 The value of 'type' is used to set transaction_type().  Currently this
511 module only supports a transaction_type() of 'C' any other values will
512 cause Carp::croak() to be called in submit().
513
514 Note: Payflow Pro supports multiple credit card types, including:
515 American Express/Optima, Diners Club, Discover/Novus, Enroute, JCB,
516 MasterCard and Visa.
517
518 =head1 Setting Payflow Pro parameters from content(%content)
519
520 The following rules are applied to map data to Payflow Pro parameters
521 from content(%content):
522
523       # PFP param => $content{<key>}
524       VENDOR      => $self->vendor ? \( $self->vendor ) : 'login',
525       PARTNER     => \( $self->partner ),
526       USER        => 'login',
527       PWD         => 'password',
528       TRXTYPE     => 'action',
529       TENDER      => 'type',
530       ORIGID      => 'order_number',
531       COMMENT1    => 'description',
532       COMMENT2    => 'invoice_number',
533
534       ACCT        => 'card_number',
535       CVV2        => 'cvv2',
536       EXPDATE     => \( $month.$year ), # MM/YY from 'expiration'
537       AMT         => 'amount',
538
539       FIRSTNAME   => 'first_name',
540       LASTNAME    => 'last_name',
541       NAME        => 'name',
542       EMAIL       => 'email',
543       COMPANYNAME => 'company',
544       STREET      => 'address',
545       CITY        => 'city',
546       STATE       => 'state',
547       ZIP         => \$zip, # 'zip' with non-alphanumerics removed
548       COUNTRY     => 'country',
549
550 The required Payflow Pro parameters for credit card transactions are:
551
552   TRXTYPE TENDER PARTNER VENDOR USER PWD ORIGID
553
554 =head1 Mapping Payflow Pro transaction responses to object methods
555
556 The following methods provides access to the transaction response data
557 resulting from a Payflow Pro request (after submit()) is called:
558
559 =head2 order_number()
560
561 This order_number() method returns the PNREF field, also known as the
562 PayPal Reference ID, which is a unique number that identifies the
563 transaction.
564
565 =head2 result_code()
566
567 The result_code() method returns the RESULT field, which is the
568 numeric return code indicating the outcome of the attempted
569 transaction.
570
571 A RESULT of 0 (zero) indicates the transaction was approved and
572 is_success() will return '1' (one/TRUE).  Any other RESULT value
573 indicates a decline or error and is_success() will return '0'
574 (zero/FALSE).
575
576 =head2 error_message()
577
578 The error_message() method returns the RESPMSG field, which is a
579 response message returned with the transaction result.
580
581 =head2 authorization()
582
583 The authorization() method returns the AUTHCODE field, which is the
584 approval code obtained from the processing network.
585
586 =head2 avs_code()
587
588 The avs_code() method returns a combination of the AVSADDR and AVSZIP
589 fields from the transaction result.  The value in avs_code is as
590 follows:
591
592   Y     - Address and ZIP match
593   A     - Address matches but not ZIP
594   Z     - ZIP matches but not address
595   N     - no match
596   undef - AVS values not available
597
598 =head2 cvv2_response()
599
600 The cvv2_response() method returns the CVV2MATCH field, which is a
601 response message returned with the transaction result.
602
603 =head1 COMPATIBILITY
604
605 As of 0.07, this module communicates with the Payflow gateway directly
606 and no longer requires the Payflow Pro SDK or other download.  Thanks
607 to Phil Lobbes for this great work.
608
609 =head1 AUTHORS
610
611 Ivan Kohler <ivan-payflowpro@420.am>
612
613 Phil Lobbes E<lt>phil at perkpartners.comE<gt>
614
615 Based on Business::OnlinePayment::AuthorizeNet written by Jason Kohles.
616
617 =head1 SEE ALSO
618
619 perl(1), L<Business::OnlinePayment>, L<Carp>, and the PayPal
620 Integration Center Payflow Pro resources at
621 L<https://www.paypal.com/IntegrationCenter/ic_payflowpro.html>
622
623 =cut