From 7b3f32e925e0acec89f1ea2421a25d5decc6216f Mon Sep 17 00:00:00 2001 From: ivan Date: Sun, 15 Nov 2009 01:41:17 +0000 Subject: [PATCH] add order_number to documentation on return data, refactor docs slightly --- Changes | 1 + OnlinePayment.pm | 158 +++++++++++++++++++++++++++++++++++-------------------- TODO | 5 +- 3 files changed, 106 insertions(+), 58 deletions(-) diff --git a/Changes b/Changes index 1ea790d..8b9f288 100644 --- a/Changes +++ b/Changes @@ -3,6 +3,7 @@ Revision history for Perl extension Business::OnlinePayment. 3.01 unreleased - Add fields to documentation: tax, freight, duty, tax_exempt, po_number. + - Add return field to documentation: order_number 3.00 Mon Aug 17 15:55:11 PDT 2009 - It finally happened. diff --git a/OnlinePayment.pm b/OnlinePayment.pm index a43b87b..05d89bd 100644 --- a/OnlinePayment.pm +++ b/OnlinePayment.pm @@ -12,23 +12,24 @@ $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, - fraud_score => undef, - fraud_transaction_id => undef, +my @methods = qw( + authorization + order_number + error_message + failure_status + fraud_detect + is_success + maximum_risk + path + port + require_avs + result_code + server + server_response + test_transaction + transaction_type + fraud_score + fraud_transaction_id ); sub new { @@ -41,7 +42,7 @@ sub new { croak("unknown processor $processor ($@)") if $@; my $self = bless {processor => $processor}, $subclass; - $self->build_subs(keys %fields); + $self->build_subs(@methods); if($self->can("set_defaults")) { $self->set_defaults(%data); @@ -112,7 +113,7 @@ sub _pre_submit { unless ( $@ =~ m/^Can\'t locate/ ); } else { my $risk_tx = bless( { processor => $fraud_detection }, $subclass ); - $risk_tx->build_subs(keys %fields); + $risk_tx->build_subs(@methods); if ($risk_tx->can('set_defaults')) { $risk_tx->set_defaults(); } @@ -197,7 +198,7 @@ sub build_subs { } } -#helper sub +#helper method sub silly_bool { my( $self, $value ) = @_; @@ -241,9 +242,9 @@ Business::OnlinePayment - Perl extension for online payment processing 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 @@ -254,7 +255,9 @@ 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. -=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 @@ -527,16 +530,39 @@ at more than one rate) =back -=head2 submit(); +=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 +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). + +=head2 require_avs() + +Providing a true argument to this module will turn on address +verification (if the processor supports it). + +=head1 TRANSACTION SUBMISSION METHOD + +=head2 submit() Submit the transaction to the processor for completion -=head2 is_success(); +=head1 TRANSACTION RESULT METHODS + +=head2 is_success() Returns true if the transaction was submitted successfully, false if it failed (or undef if it has not been submitted yet). -=head2 failure_status(); +=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 failure_status() If the transaction failed, it can optionally return a specific failure status (normalized, not gateway-specific). Currently defined statuses @@ -549,64 +575,82 @@ 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. -=head2 result_code(); +=head2 authorization() -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. +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 test_transaction(); +=head2 order_number() -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). +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 require_avs(); +=head2 fraud_score() -Providing a true argument to this module will turn on address -verification (if the processor supports it). +Retrieve or change the fraud score from any Business::FraudDetect plugin -=head2 transaction_type(); +=head2 fraud_transaction_id() -Retrieve the transaction type (the 'type' argument to contents()). -Generally only used internally, but provided in case it is useful. +Retrieve or change the transaction id from any Business::FraudDetect plugin -=head2 error_message(); +=head2 result_code() -If the transaction has been submitted but was not accepted, this -function will return the provided error message (if any) that the -processor returned. +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 authorization(); +=head1 MISCELLANEOUS INTERNAL METHODS -If the transaction has been submitted and accepted, this function will -provide you with the authorization code that the processor returned. +=head2 transaction_type() -=head2 server(); +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). -=head2 fraud_score(); +=head1 HELPER METHODS FOR GATEWAY MODULE AUTHORS -Retrieve or change the fraud score from any Business::FraudDetect plugin +=head2 build_subs( @sub_names ) -=head2 fraud_transaction_id(); +Build setter/getter subroutines for new return values. -Retrieve or change the transaction id from any Business::FraudDetect plugin +=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 0 if the value starts with y, Y, t or T. +Returns 1 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 diff --git a/TODO b/TODO index d570440..83b73f7 100644 --- a/TODO +++ b/TODO @@ -3,4 +3,7 @@ - Use Net::HTTPS::Any - hmm... requires HTTP::Headers v1.59 - move revmap_fields into the base class - +- remap_fields: Not the cleanest thing to mix up our namespace with the + processor-specific names. +- Define a better model of exception handling that doesn't involve dying on + some things. -- 2.11.0