package Business::OnlinePayment;
use strict;
-use vars qw($VERSION);
+use vars qw($VERSION %_info_handler);
use Carp;
require 5.005;
-$VERSION = '3.00_06';
+$VERSION = '3.05';
$VERSION = eval $VERSION; # modperlstyle: convert the string into a number
# Remember subclasses we have "wrapped" submit() with _pre_submit()
my %Presubmit_Added = ();
-my %fields = (
- authorization => undef,
- error_message => undef,
- failure_status => undef,
- fraud_detect => undef,
- is_success => undef,
- maximum_risk => undef,
- path => undef,
- port => undef,
- require_avs => undef,
- result_code => undef,
- server => undef,
- server_response => undef,
- test_transaction => undef,
- transaction_type => undef,
+my @methods = qw(
+ authorization
+ order_number
+ error_message
+ failure_status
+ fraud_detect
+ is_success
+ partial_auth_amount
+ maximum_risk
+ path
+ port
+ require_avs
+ result_code
+ server
+ server_response
+ test_transaction
+ transaction_type
+ fraud_score
+ fraud_transaction_id
+ response_code
+ response_header
+ response_page
+ avs_code
+ cvv2_response
+ txn_date
);
+__PACKAGE__->build_subs(@methods);
+
+#fallback
+sub _info {
+ my $class = shift;
+ ( my $gw = $class ) =~ s/^Business::OnlinePayment:://;
+ {
+ 'info_compat' => '0.00',
+ 'gateway_name' => $gw,
+ 'module_notes' => "Module does not yet provide info.",
+ };
+}
+
+#allow classes to declare info in a flexible way, but return normalized info
+%_info_handler = (
+ 'supported_types' => sub {
+ my( $class, $v ) = @_;
+ my $types = ref($v) ? $v : defined($v) ? [ $v ] : [];
+ $types = { map { $_=>1 } @$types } if ref($types) eq 'ARRAY';
+ $types;
+ },
+ 'supported_actions' => sub {
+ my( $class, $v ) = @_;
+ return %$v if ref($v) eq 'HASH';
+ $v = [ $v ] unless ref($v);
+ my $types = $class->info('supported_types') || {};
+ ( map { $_ => $v } keys %$types );
+ },
+);
+
+sub info {
+ my $class = shift; #class or object
+ my $info = $class->_info;
+ if ( @_ ) {
+ my $key = shift;
+ exists($_info_handler{$key})
+ ? &{ $_info_handler{$key} }( $class, $info->{$key} )
+ : $info->{$key};
+ } else {
+ wantarray ? ( keys %$info ) : [ keys %$info ];
+ }
+}
+
sub new {
my($class,$processor,%data) = @_;
- Carp::croak("unspecified processor") unless $processor;
+ croak("unspecified processor") unless $processor;
my $subclass = "${class}::$processor";
- if(!defined(&$subclass)) {
- eval "use $subclass";
- Carp::croak("unknown processor $processor ($@)") if $@;
- }
+ eval "use $subclass";
+ croak("unknown processor $processor ($@)") if $@;
my $self = bless {processor => $processor}, $subclass;
- $self->build_subs(keys %fields);
if($self->can("set_defaults")) {
- $self->set_defaults();
+ $self->set_defaults(%data);
}
foreach(keys %data) {
$risk_transaction->content( %parent_content );
$risk_transaction->submit();
if ($risk_transaction->is_success()) {
+ $self->fraud_score( $risk_transaction->fraud_score );
+ $self->fraud_transaction_id( $risk_transaction->fraud_transaction_id );
if ( $risk_transaction->fraud_score <= $self->maximum_fraud_score()) {
return 1;
} else {
# Search for an appropriate FD module
foreach my $fraud_class ( @Fraud_Class_Path ) {
my $subclass = $fraud_class . "::" . $fraud_detection;
- if (!defined(&$subclass)) {
- eval "use $subclass ()";
- if ($@) {
- Carp::croak("error loading fraud_detection module ($@)")
- unless ( $@ =~ m/^Can\'t locate/ );
- } else {
- my $risk_tx = bless ( { processor => $fraud_detection } , $subclass );
- $risk_tx->build_subs(keys %fields);
- if ($risk_tx->can('set_defaults')) {
- $risk_tx->set_defaults();
- }
- $risk_tx->_glean_parameters_from_parent($self);
- return $self->_risk_detect($risk_tx);
- }
+ eval "use $subclass ()";
+ if ($@) {
+ croak("error loading fraud_detection module ($@)")
+ unless ( $@ =~ m/^Can\'t locate/ );
+ } else {
+ my $risk_tx = bless( { processor => $fraud_detection }, $subclass );
+ if ($risk_tx->can('set_defaults')) {
+ $risk_tx->set_defaults();
+ }
+ $risk_tx->_glean_parameters_from_parent($self);
+ return $self->_risk_detect($risk_tx);
}
}
- Carp::croak("Unable to locate fraud_detection module $fraud_detection"
+ croak("Unable to locate fraud_detection module $fraud_detection"
. " in \@INC under Fraud_Class_Path (\@Fraud_Class_Path"
. " contains: @Fraud_Class_Path) (\@INC contains: @INC)");
}
push(@missing, $_) unless exists $content{$_};
}
- Carp::croak("missing required field(s): " . join(", ", @missing) . "\n")
+ croak("missing required field(s): " . join(", ", @missing) . "\n")
if(@missing);
}
sub submit {
my($self) = @_;
- Carp::croak("Processor subclass did not override submit function");
+ croak("Processor subclass did not override submit function");
}
sub dump_contents {
}
}
+#helper method
+
+sub silly_bool {
+ my( $self, $value ) = @_;
+ return 1 if $value =~ /^[yt]/i;
+ return 0 if $value =~ /^[fn]/i;
+ #return 1 if $value == 1;
+ #return 0 if $value == 0;
+ $value; #die??
+}
+
1;
__END__
type => 'Visa',
amount => '49.95',
card_number => '1234123412341238',
- expiration => '0100',
+ expiration => '06/15',
name => 'John Q Doe',
);
- $transaction->submit();
-
- if($transaction->is_success()) {
- print "Card processed successfully: ", $transaction->authorization(), "\n";
+
+ eval { $transaction->submit(); };
+
+ if ( $@ ) {
+
+ print "$processor error: $@\n";
+
} else {
- print "Card was rejected: ", $transaction->error_message(), "\n";
+
+ if ( $transaction->is_success() ) {
+ print "Card processed successfully: ". $transaction->authorization()."\n";
+ } else {
+ print "Card was rejected: ". $transaction->error_message(). "\n";
+ }
+
}
=head1 DESCRIPTION
Business::OnlinePayment is a generic module for processing payments
through online credit card processors, electronic cash systems, etc.
-=head1 METHODS AND FUNCTIONS
+=head1 CONSTRUCTOR
-=head2 new($processor, %processor_options);
+=head2 new($processor, %processor_options)
Create a new Business::OnlinePayment object, $processor is required,
and defines the online processor to use. If necessary, processor
only if absolutely necessary (especially path), as the processor
module was probably written with a specific target script in mind.
-=head2 content(%content);
+=head1 TRANSACTION SETUP METHODS
+
+=head2 content(%content)
The information necessary for the transaction, this tends to vary a
little depending on the processor, so we have chosen to use a system
=over 4
-=item * login
+=item login
Your login name to use for authentication to the online processor.
-=item * password
+=item password
Your password to use for authentication to the online processor.
=back
-=head3 GENERAL TRANSACTION FIELDS
+=head3 REQUIRED TRANSACTION FIELDS
=over 4
-=item * type
+=item type
Transaction type, supported types are: CC (credit card), ECHECK
(electronic check) and LEC (phone bill billing). Deprecated types
-are: Visa, MasterCard, American Express, Discover, Check (not all
-processors support all these transaction types).
+are: Visa, MasterCard, American Express, Discover, Check. Not all
+processors support all transaction types.
-=item * action
+=item action
-What to do with the transaction (currently available are: Normal
-Authorization, Authorization Only, Credit, Post Authorization)
+What action being taken by this transaction. Currently available are:
-=item * description
+=over 8
-A description of the transaction (used by some processors to send
-information to the client, normally not a required field).
+=item Normal Authorization
+
+=item Authorization Only
+
+=item Post Authorization
+
+=item Reverse Authorization
+
+=item Void
+
+=item Credit
+
+=item Tokenize
+
+=item Recurring Authorization
+
+=item Modify Recurring Authorization
+
+=item Cancel Recurring Authorization
+
+=back
+
+=item amount
+
+The amount of the transaction. No dollar signs or currency identifiers,
+just a whole or floating point number (i.e. 26, 26.1 or 26.13).
+
+=back
+
+=head3 OPTIONAL TRANSACTION FIELDS
+
+=over 4
+
+=item partial_auth
+
+If you are prepared to handle partial authorizations
+(see L<partial_auth_amount()|/"partial_auth_amount()">
+ in L<TRANSACTION RESULT FIELDS|/"TRANSACTION RESULT FIELDS">),
+pass a true value in this field to enable them.
-=item * amount
+If this flag is not set, a partial authorization will be immediately reversed
+or voided.
-The amount of the transaction, most processors don't want dollar signs
-and the like, just a floating point number.
+=item description
-=item * invoice_number
+A description of the transaction (used by some processors to send
+information to the client, normally not a required field).
+
+=item invoice_number
An invoice number, for your use and not normally required, many
processors require this field to be a numeric only field.
+=item po_number
+
+Purchase order number (normally not required).
+
+=item tax
+
+Tax amount (portion of amount field, not added to it).
+
+=item freight
+
+Freight amount (portion of amount field, not added to it).
+
+=item duty
+
+Duty amount (portion of amount field, not added to it).
+
+=item tax_exempt
+
+Tax exempt flag (i.e. TRUE, FALSE, T, F, YES, NO, Y, N, 1, 0).
+
+=item currency
+
+Currency, specified as an ISO 4217 three-letter code, such as USD, CAD, EUR,
+AUD, DKK, GBP, JPY, NZD, etc.
+
=back
=head3 CUSTOMER INFO FIELDS
=over 4
-=item * customer_id
+=item customer_id
A customer identifier, again not normally required.
-=item * name
+=item name
The customer's name, your processor may not require this.
-=item * first_name
+=item first_name
-=item * last_name
+=item last_name
The customer's first and last name as separate fields.
-=item * company
+=item company
The customer's company name, not normally required.
-=item * address
+=item address
The customer's address (your processor may not require this unless you
are requiring AVS Verification).
-=item * city
+=item city
The customer's city (your processor may not require this unless you
are requiring AVS Verification).
-=item * state
+=item state
The customer's state (your processor may not require this unless you
are requiring AVS Verification).
-=item * zip
+=item zip
The customer's zip code (your processor may not require this unless
you are requiring AVS Verification).
-=item * country
+=item country
Customer's country.
-=item * ship_first_name
+=item ship_first_name
-=item * ship_last_name
+=item ship_last_name
-=item * ship_company
+=item ship_company
-=item * ship_address
+=item ship_address
-=item * ship_city
+=item ship_city
-=item * ship_state
+=item ship_state
-=item * ship_zip
+=item ship_zip
-=item * ship_country
+=item ship_country
These shipping address fields may be accepted by your processor.
Refer to the description for the corresponding non-ship field for
general information on each field.
-=item * phone
+=item phone
Customer's phone number.
-=item * fax
+=item fax
Customer's fax number.
-=item * email
+=item email
Customer's email address.
+=item customer_ip
+
+IP Address from which the transaction originated.
+
=back
=head3 CREDIT CARD FIELDS
=over 4
-=item * card_number
+=item card_number
-Credit card number (obviously not required for non-credit card
-transactions).
+Credit card number.
-=item * cvv2
+=item expiration
+
+Credit card expiration, MM/YY.
+
+=item cvv2
CVV2 number (also called CVC2 or CID) is a three- or four-digit
security code used to reduce credit card fraud.
-=item * expiration
+=item card_token
+
+If supported by your gateway, you can pass a card_token instead of a
+card_number and expiration.
+
+=cut
+
+#=item card_response
+#
+#Some card_token schemes implement a challenge/response handshake. In those
+#cases, this field is used for the response. In most cases the handshake
+#it taken care of by the gateway module.
+
+=item track1
+
+Track 1 on the magnetic stripe (Card present only)
-Credit card expiration (obviously not required for non-credit card
-transactions).
+=item track2
-=item * recurring billing
+Track 2 on the magnetic stripe (Card present only)
+
+=item recurring_billing
Recurring billing flag
=over 4
-=item * account_number
+=item account_number
+
+Bank account number
+
+=item routing_code
-Bank account number for electronic checks or electronic funds
-transfer.
+Bank's routing code
-=item * routing_code
+=item account_type
-Bank's routing code for electronic checks or electronic funds
-transfer.
+Account type. Can be (case-insensitive): B<Personal Checking>,
+B<Personal Savings>, B<Business Checking> or B<Business Savings>.
-=item * account_type
+=item nacha_sec_code
-Account type for electronic checks or electronic funds transfer.
+NACHA SEC Code for US ACH transactions. 'PPD' indicates customer signed a form
+giving authorization for the charge, 'CCD' same for a business checking/savings
+account, 'WEB' for online transactions where a box was checked authorizing the
+charge, and 'TEL' for authorization via recorded phone call (NACHA script
+required).
-=item * account_name
+=item account_name
-Account holder's name for electronic checks or electronic funds
-transfer.
+Account holder's name.
-=item * bank_name
+=item bank_name
-Bank's name for electronic checks or electronic funds transfer.
+Bank name.
-=item * check_type
+=item bank_city
-Check type for electronic checks or electronic funds transfer.
+Bank city.
-=item * customer_org
+=item bank_state
+
+Bank state.
+
+=item check_type
+
+Check type.
+
+=item customer_org
Customer organization type.
-=item * customer_ssn
+=item customer_ssn
-Customer's social security number. Typically only required for
-electronic checks or electronic funds transfer.
+Customer's social security number.
-=item * license_num
+=item license_num
-Customer's driver's license number. Typically only required for
-electronic checks or electronic funds transfer.
+Customer's driver's license number.
-=item * license_dob
+=item license_dob
-Customer's date of birth. Typically only required for electronic
-checks or electronic funds transfer.
+Customer's date of birth.
=back
-=head2 submit();
+=head3 FOLLOW-UP TRANSACTION FIELDS
-Submit the transaction to the processor for completion
+These fields are used in follow-up transactions related to an original
+transaction (Post Authorization, Reverse Authorization, Void, Credit).
-=head2 is_success();
+=over 4
-Returns true if the transaction was submitted successfully, false if
-it failed (or undef if it has not been submitted yet).
+=item authorization
-=head2 failure_status();
+=item order_number
-If the transaction failed, it can optionally return a specific failure
-status (normalized, not gateway-specific). Currently defined statuses
-are: "expired", "nsf" (non-sufficient funds), "stolen", "pickup",
-"blacklisted" and "declined" (card/transaction declines only, not
-other errors).
+=item txn_date
-Note that (as of Aug 2006) this is only supported by some of the
-newest processor modules, and that, even if supported, a failure
-status is an entirely optional field that is only set for specific
-kinds of failures.
+=back
-=head2 result_code();
+=head3 RECURRING BILLING FIELDS
-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.
+=over 4
-=head2 test_transaction();
+=item interval
+
+Interval expresses the amount of time between billings: digits, whitespace
+and units (currently "days" or "months" in either singular or plural form).
+
+=item start
+
+The date of the first transaction (used for processors which allow delayed
+start) expressed as YYYY-MM-DD.
+
+=item periods
+
+The number of cycles of interval length for which billing should occur
+(inclusive of 'trial periods' if the processor supports recurring billing
+at more than one rate)
+
+=back
+
+=head2 test_transaction()
Most processors provide a test mode, where submitted transactions will
not actually be charged or added to your batch, calling this function
it, or generate a fatal error if the processor does not support a test
mode (which is probably better than accidentally making real charges).
-=head2 require_avs();
+=head2 require_avs()
Providing a true argument to this module will turn on address
verification (if the processor supports it).
-=head2 transaction_type();
+=head1 TRANSACTION SUBMISSION METHOD
-Retrieve the transaction type (the 'type' argument to contents()).
-Generally only used internally, but provided in case it is useful.
+=head2 submit()
+
+Submit the transaction to the processor for completion.
-=head2 error_message();
+If there is a gateway communication error or other "meta" , the submit method
+will throw a fatal exception. You can catch this with eval {} if you would
+like to treat gateway co
+
+=head1 TRANSACTION RESULT METHODS
+
+=head2 is_success()
+
+Returns true if the transaction was approved by the gateway, false if
+it was submitted but not approved, or undef if it has not been
+submitted yet.
+
+=head2 partial_auth_amount()
+
+If this transaction was a partial authorization (i.e. successful, but less than
+the requested amount was processed), then the amount processed is returned in
+this field.
+
+(When is_success is true but this field is empty or 0, that indicates a normal
+full authorization for the entire requested amount.)
+
+=head2 error_message()
If the transaction has been submitted but was not accepted, this
function will return the provided error message (if any) that the
processor returned.
-=head2 authorization();
+=head2 failure_status()
+
+If the transaction failed, it can optionally return a specific failure
+status (normalized, not gateway-specific). Currently defined statuses
+are: "expired", "nsf" (non-sufficient funds), "stolen", "pickup",
+"blacklisted" and "declined" (card/transaction declines only, not
+other errors).
+
+Note that not all processor modules support this, and that if supported,
+it may not be set for all declines.
+
+=head2 authorization()
If the transaction has been submitted and accepted, this function will
provide you with the authorization code that the processor returned.
+Store this if you would like to run inquiries or refunds on the transaction
+later.
+
+=head2 order_number()
+
+The unique order number for the transaction generated by the gateway. Store
+this if you would like to run inquiries or refunds on the transaction later.
+
+=head2 card_token()
+
+If supported by your gateway, a card_token can be used in a subsequent
+transaction to refer to a card number.
+
+=head2 txn_date()
+
+Transaction date, as returned by the gateway. Required by some gateways
+for follow-up transactions. Store this if you would like to run inquiries or
+refunds on the transaction later.
+
+=head2 fraud_score()
-=head2 server();
+Retrieve or change the fraud score from any Business::FraudDetect plugin
+
+=head2 fraud_transaction_id()
+
+Retrieve or change the transaction id from any Business::FraudDetect plugin
+
+=head2 response_code()
+
+=head2 response_headers()
+
+=head2 response_page()
+
+These three fields are set by some processors (especially those which use
+HTTPS) when the transaction fails at the communication level rather than
+as a transaction.
+
+response_code is the HTTP response code and message, i.e.
+'500 Internal Server Error'.
+
+response_headers is a hash reference of the response headers
+
+response_page is the raw content.
+
+=head2 result_code()
+
+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.
+
+=head2 avs_code()
+
+=head2 cvv2_response()
+
+=head1 MISCELLANEOUS INTERNAL METHODS
+
+=head2 transaction_type()
+
+Retrieve the transaction type (the 'type' argument to contents()).
+Generally only used internally, but provided in case it is useful.
+
+=head2 server()
Retrieve or change the processor submission server address (CHANGE AT
YOUR OWN RISK).
-=head2 port();
+=head2 port()
Retrieve or change the processor submission port (CHANGE AT YOUR OWN
RISK).
-=head2 path();
+=head2 path()
Retrieve or change the processor submission path (CHANGE AT YOUR OWN
RISK).
+=head1 HELPER METHODS FOR GATEWAY MODULE AUTHORS
+
+=head2 build_subs( @sub_names )
+
+Build setter/getter subroutines for new return values.
+
+=head2 get_fields( @fields )
+
+Get the named fields if they are defined.
+
+=head2 remap_fields( %map )
+
+Remap field content (and stuff it back into content).
+
+=head2 required_fields( @fields )
+
+Croaks if any of the required fields are not present.
+
+=head2 dump_contents
+
+=head2 silly_bool( $value )
+
+Returns 1 if the value starts with y, Y, t or T.
+Returns 0 if the value starts with n, N, f or F.
+Otherwise returns the value itself.
+
+Use this for handling boolean content like tax_exempt.
+
=head1 AUTHORS
+(v2 series)
+
Jason Kohles, email@jasonkohles.com
-(v3 rewrite) Ivan Kohler <ivan-business-onlinepayment@420.am>
+(v3 rewrite)
+
+Ivan Kohler <ivan-business-onlinepayment@420.am>
Phil Lobbes E<lt>phil at perkpartners dot comE<gt>
+=head1 COPYRIGHT
+
+Copyright (c) 1999-2004 Jason Kohles
+Copyright (c) 2004 Ivan Kohler
+Copyright (c) 2007-2018 Freeside Internet Services, Inc.
+
+All rights reserved.
+
+This program is free software; you can redistribute it and/or modify it under
+the same terms as Perl itself.
+
+=head1 HOMEPAGE
+
+Homepage: http://perl.business/onlinepayment
+
+Development: http://perl.business/onlinepayment/ng.html
+
+=head1 MAILING LIST
+
+Please direct current development questions, patches, etc. to the mailing list:
+http://mail.freeside.biz/cgi-bin/mailman/listinfo/bop-devel/
+
+=head1 REPOSITORY
+
+The code is available from our public git repository:
+
+ git clone git://git.freeside.biz/Business-OnlinePayment.git
+
+Or on the web:
+
+ http://git.freeside.biz/gitweb/?p=Business-OnlinePayment.git
+ Or:
+ http://git.freeside.biz/cgit/Business-OnlinePayment.git
+
+Many (but by no means all!) processor plugins are also available in the same
+repository, see:
+
+ http://git.freeside.biz/gitweb/
+ Or:
+ http://git.freeside.biz/cgit/
+
=head1 DISCLAIMER
THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
=head1 SEE ALSO
-http://420.am/business-onlinepayment/
+http://perl.business/onlinepayment
For verification of credit card checksums, see L<Business::CreditCard>.
projects / Business-OnlinePayment.git / blobdiff