1 package Business::OnlinePayment::PayflowPro;
4 use vars qw($VERSION $DEBUG);
5 use Carp qw(carp croak);
8 use Business::OnlinePayment::HTTPS 0.06;
10 use base qw(Business::OnlinePayment::HTTPS);
13 $VERSION = eval $VERSION;
16 # return current request_id or generate a new one if not yet set
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"};
26 return $self->_new_request_id();
32 my $md5 = Digest::MD5->new();
33 $md5->add( $$, time(), rand(time) );
34 return $md5->hexdigest();
41 my $level = shift || 0;
43 $self->{"__DEBUG"} = $level;
48 $Business::OnlinePayment::HTTPS::DEBUG = $level;
50 return ref($self) ? ( $self->{"__DEBUG"} || $DEBUG ) : $DEBUG;
53 # cvv2_code: support legacy code and but deprecate method
54 sub cvv2_code { shift->cvv2_response(@_); }
60 # standard B::OP methods/data
61 $self->server("payflowpro.paypal.com");
63 $self->path("/transaction");
67 client_certification_id client_timeout
70 order_number avs_code cvv2_response
71 response_page response_code response_headers
74 # module specific data
76 $self->debug( $opts{debug} );
80 # HTTPS Interface Dev Guide: must be set but will be removed in future
81 $self->client_certification_id("ClientCertificationIdNotSet");
83 # required: 45 secs recommended by HTTPS Interface Dev Guide
84 $self->client_timeout(45);
86 $self->test_server( "pilot-payflowpro.paypal.com" );
92 my %content = $self->content();
96 'normal authorization' => 'S', # Sale transaction
97 'credit' => 'C', # Credit (refund)
98 'authorization only' => 'A', # Authorization
99 'post authorization' => 'D', # Delayed Capture
100 'void' => 'V', # Void
103 $content{'action'} = $actions{ lc( $content{'action'} ) }
104 || $content{'action'};
110 'american express' => 'C',
114 #'check' => 'ECHECK',
117 $content{'type'} = $types{ lc( $content{'type'} ) } || $content{'type'};
119 $self->transaction_type( $content{'type'} );
121 # stuff it back into %content
122 $self->content(%content);
126 my ( $self, %map ) = @_;
127 my %content = $self->content();
128 foreach ( keys %map ) {
132 : $content{ $map{$_} };
134 $self->content(%content);
139 my $expiration = shift;
141 if ( defined($expiration) and $expiration =~ /^(\d+)\D+\d*(\d{2})$/ ) {
142 my ( $month, $year ) = ( $1, $2 );
143 $expdate_mmyy = sprintf( "%02d", $month ) . $year;
145 return defined($expdate_mmyy) ? $expdate_mmyy : $expiration;
151 $self->_map_fields();
153 my %content = $self->content;
155 if ( $self->transaction_type() ne 'C' ) {
156 croak( "PayflowPro can't (yet?) handle transaction type: "
157 . $self->transaction_type() );
160 my $expdate_mmyy = $self->expdate_mmyy( $content{"expiration"} );
161 my $zip = $content{'zip'};
162 $zip =~ s/[^[:alnum:]]//g;
164 $self->server( $self->test_server ) if $self->test_transaction;
166 my $vendor = $self->vendor;
167 my $partner = $self->partner;
169 $self->_revmap_fields(
171 # BUG?: VENDOR B::OP:PayflowPro < 0.05 backward compatibility. If
172 # vendor not set use login although test indicate undef vendor is ok
173 VENDOR => $vendor ? \$vendor : 'login',
174 PARTNER => \$partner,
179 ORIGID => 'order_number',
180 COMMENT1 => 'description',
181 COMMENT2 => 'invoice_number',
183 ACCT => 'card_number',
185 EXPDATE => \$expdate_mmyy, # MM/YY from 'expiration'
188 FIRSTNAME => 'first_name',
189 LASTNAME => 'last_name',
192 COMPANYNAME => 'company',
196 ZIP => \$zip, # 'zip' with non-alnums removed
197 COUNTRY => 'country',
200 my @required = qw( TRXTYPE TENDER PARTNER VENDOR USER PWD );
201 if ( $self->transaction_type() eq 'C' ) { # credit card
202 if ( $content{'action'} =~ /^[CDV]$/
203 && defined( $content{'ORIGID'} )
204 && length( $content{'ORIGID'} ) )
206 push @required, qw(ORIGID);
210 # never get here, we croak above if transaction_type ne 'C'
211 push @required, qw(AMT ACCT EXPDATE);
214 $self->required_fields(@required);
216 my %params = $self->get_fields(
218 VENDOR PARTNER USER PWD TRXTYPE TENDER ORIGID COMMENT1 COMMENT2
219 ACCT CVV2 EXPDATE AMT
220 FIRSTNAME LASTNAME NAME EMAIL COMPANYNAME
221 STREET CITY STATE ZIP COUNTRY
226 my %req_headers = %{ $self->headers || {} };
228 # get request_id from %content if defined for ease of use
229 if ( defined $content{"request_id"} ) {
230 $self->request_id( $content{"request_id"} );
233 unless ( defined( $req_headers{"X-VPS-Request-ID"} ) ) {
234 $req_headers{"X-VPS-Request-ID"} = $self->request_id();
237 unless ( defined( $req_headers{"X-VPS-VIT-Client-Certification-Id"} ) ) {
238 $req_headers{"X-VPS-VIT-Client-Certification-Id"} =
239 $self->client_certification_id;
242 unless ( defined( $req_headers{"X-VPS-Client-Timeout"} ) ) {
243 $req_headers{"X-VPS-Client-Timeout"} = $self->client_timeout();
247 "Content-Type" => "text/namevalue",
248 "headers" => \%req_headers,
251 my ( $page, $resp, %resp_headers ) =
252 $self->https_post( \%options, \%params );
254 $self->response_code( $resp );
255 $self->response_page( $page );
256 $self->response_headers( \%resp_headers );
258 # $page should contain name=value[[&name=value]...] pairs
259 my $cgi = CGI->new("$page");
261 # AVS and CVS values may be set on success or failure
263 if ( defined $cgi->param("AVSADDR") or defined $cgi->param("AVSZIP") ) {
264 if ( $cgi->param("AVSADDR") eq "Y" && $cgi->param("AVSZIP") eq "Y" ) {
267 elsif ( $cgi->param("AVSADDR") eq "Y" ) {
270 elsif ( $cgi->param("AVSZIP") eq "Y" ) {
273 elsif ( $cgi->param("AVSADDR") eq "N" or $cgi->param("AVSZIP") eq "N" )
282 $self->avs_code($avs_code);
283 $self->cvv2_response( $cgi->param("CVV2MATCH") );
284 $self->result_code( $cgi->param("RESULT") );
285 $self->order_number( $cgi->param("PNREF") );
286 $self->error_message( $cgi->param("RESPMSG") );
287 $self->authorization( $cgi->param("AUTHCODE") );
289 # RESULT must be an explicit zero, not just numerically equal
290 if ( $cgi->param("RESULT") eq "0" ) {
291 $self->is_success(1);
294 $self->is_success(0);
304 Business::OnlinePayment::PayflowPro - Payflow Pro backend for Business::OnlinePayment
308 use Business::OnlinePayment;
310 my $tx = new Business::OnlinePayment(
312 'vendor' => 'your_vendor',
313 'partner' => 'your_partner',
314 'client_certification_id' => 'GuidUpTo32Chars',
317 # See the module documentation for details of content()
320 action => 'Normal Authorization',
321 description => 'Business::OnlinePayment::PayflowPro test',
323 invoice_number => '100100',
324 customer_id => 'jsk',
325 name => 'Jason Kohles',
326 address => '123 Anystreet',
330 email => 'ivan-payflowpro@420.am',
331 card_number => '4111111111111111',
332 expiration => '12/09',
334 order_number => 'string',
335 request_id => 'unique_identifier_for_transaction',
340 if ( $tx->is_success() ) {
342 "Card processed successfully: ", $tx->authorization, "\n",
343 "order number: ", $tx->order_number, "\n",
344 "CVV2 response: ", $tx->cvv2_response, "\n",
345 "AVS code: ", $tx->avs_code, "\n",
350 $info = " (CVV2 mismatch)" if ( $tx->result_code == 114 );
353 "Card was rejected: ", $tx->error_message, $info, "\n",
354 "order number: ", $tx->order_number, "\n",
360 This module is a back end driver that implements the interface
361 specified by L<Business::OnlinePayment> to support payment handling
362 via the PayPal's Payflow Pro Internet payment solution.
364 See L<Business::OnlinePayment> for details on the interface this
367 =head1 Standard methods
373 This method sets the 'server' attribute to 'payflowpro.paypal.com'
374 and the port attribute to '443'. This method also sets up the
375 L</Module specific methods> described below.
381 =head1 Unofficial methods
383 This module provides the following methods which are not officially
384 part of the standard Business::OnlinePayment interface (as of 3.00_06)
385 but are nevertheless supported by multiple gateways modules and
386 expected to be standardized soon:
390 =item L<order_number()|/order_number()>
392 =item L<avs_code()|/avs_code()>
394 =item L<cvv2_response()|/cvv2_response()>
398 =head1 Module specific methods
400 This module provides the following methods which are not currently
401 part of the standard Business::OnlinePayment interface:
403 =head2 client_certification_id()
405 This gets/sets the X-VPS-VITCLIENTCERTIFICATION-ID which is REQUIRED
406 and defaults to "ClientCertificationIdNotSet". This is described in
407 Website Payments Pro HTTPS Interface Developer's Guide as follows:
409 "A random globally unique identifier (GUID) that is currently
410 required. This requirement will be removed in the future. At this
411 time, you can send any alpha-numeric ID up to 32 characters in length.
413 NOTE: Once you have created this ID, do not change it. Use the same ID
414 for every transaction."
416 =head2 client_timeout()
418 Timeout value, in seconds, after which this transaction should be
419 aborted. Defaults to 45, the value recommended by the Website
420 Payments Pro HTTPS Interface Developer's Guide.
424 Enable or disble debugging. The value specified here will also set
425 $Business::OnlinePayment::HTTPS::DEBUG in submit() to aid in
426 troubleshooting problems.
428 =head2 expdate_mmyy()
430 The expdate_mmyy() method takes a single scalar argument (typically
431 the value in $content{expiration}) and attempts to parse and format
432 and put the date in MMYY format as required by PayflowPro
433 specification. If unable to parse the expiration date simply leave it
434 as is and let the PayflowPro system attempt to handle it as-is.
438 It is recommended that you specify your own unique request_id for each
439 transaction in %content. A request_id is REQUIRED by the PayflowPro
440 processor. If a request_id is not set, then Digest::MD5 is used to
441 attempt to generate a request_id for a transaction.
443 =head2 Deprecated methods
445 The following methods are deprecated and may be removed in a future
446 release. Values for vendor and partner should now be set as arguments
447 to Business::OnlinePayment->new(). The value for cert_path was used
448 to support passing a path to PFProAPI.pm (a Perl module/SDK from
449 Verisign/Paypal) which is no longer used.
465 The following default settings exist:
471 payflowpro.paypal.com or pilot-payflowpro.paypal.com if
472 test_transaction() is TRUE
480 =head1 Handling of content(%content)
482 The following rules apply to content(%content) data:
486 If 'action' matches one of the following keys it is replaced by the
487 right hand side value:
489 'normal authorization' => 'S', # Sale transaction
490 'credit' => 'C', # Credit (refund)
491 'authorization only' => 'A', # Authorization
492 'post authorization' => 'D', # Delayed Capture
495 If 'action' is 'C', 'D' or 'V' and 'order_number' is not set then
496 'amount', 'card_number' and 'expiration' must be set.
500 If 'type' matches one of the following keys it is replaced by the
501 right hand side value:
505 'american express' => 'C',
509 The value of 'type' is used to set transaction_type(). Currently this
510 module only supports a transaction_type() of 'C' any other values will
511 cause Carp::croak() to be called in submit().
513 Note: Payflow Pro supports multiple credit card types, including:
514 American Express/Optima, Diners Club, Discover/Novus, Enroute, JCB,
517 =head1 Setting Payflow Pro parameters from content(%content)
519 The following rules are applied to map data to Payflow Pro parameters
520 from content(%content):
522 # PFP param => $content{<key>}
523 VENDOR => $self->vendor ? \( $self->vendor ) : 'login',
524 PARTNER => \( $self->partner ),
529 ORIGID => 'order_number',
530 COMMENT1 => 'description',
531 COMMENT2 => 'invoice_number',
533 ACCT => 'card_number',
535 EXPDATE => \( $month.$year ), # MM/YY from 'expiration'
538 FIRSTNAME => 'first_name',
539 LASTNAME => 'last_name',
542 COMPANYNAME => 'company',
546 ZIP => \$zip, # 'zip' with non-alphanumerics removed
547 COUNTRY => 'country',
549 The required Payflow Pro parameters for credit card transactions are:
551 TRXTYPE TENDER PARTNER VENDOR USER PWD ORIGID
553 =head1 Mapping Payflow Pro transaction responses to object methods
555 The following methods provides access to the transaction response data
556 resulting from a Payflow Pro request (after submit()) is called:
558 =head2 order_number()
560 This order_number() method returns the PNREF field, also known as the
561 PayPal Reference ID, which is a unique number that identifies the
566 The result_code() method returns the RESULT field, which is the
567 numeric return code indicating the outcome of the attempted
570 A RESULT of 0 (zero) indicates the transaction was approved and
571 is_success() will return '1' (one/TRUE). Any other RESULT value
572 indicates a decline or error and is_success() will return '0'
575 =head2 error_message()
577 The error_message() method returns the RESPMSG field, which is a
578 response message returned with the transaction result.
580 =head2 authorization()
582 The authorization() method returns the AUTHCODE field, which is the
583 approval code obtained from the processing network.
587 The avs_code() method returns a combination of the AVSADDR and AVSZIP
588 fields from the transaction result. The value in avs_code is as
591 Y - Address and ZIP match
592 A - Address matches but not ZIP
593 Z - ZIP matches but not address
595 undef - AVS values not available
597 =head2 cvv2_response()
599 The cvv2_response() method returns the CVV2MATCH field, which is a
600 response message returned with the transaction result.
604 As of 0.07, this module communicates with the Payflow gateway directly
605 and no longer requires the Payflow Pro SDK or other download. Thanks
606 to Phil Lobbes for this great work.
610 Ivan Kohler <ivan-payflowpro@420.am>
612 Phil Lobbes E<lt>phil at perkpartners.comE<gt>
614 Based on Business::OnlinePayment::AuthorizeNet written by Jason Kohles.
618 perl(1), L<Business::OnlinePayment>, L<Carp>, and the PayPal
619 Integration Center Payflow Pro resources at
620 L<https://www.paypal.com/IntegrationCenter/ic_payflowpro.html>