add order_number to documentation on return data, refactor docs slightly

diff --git a/Changes b/Changes
index 1ea790d..8b9f288 100644 (file)
--- 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.
 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.
 
 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 (file)
--- 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 = ();
 
 # 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 {
 );
 
 sub new {


@@ -41,7 +42,7 @@ sub new {
     croak("unknown processor $processor ($@)") if $@;
 
     my $self = bless {processor => $processor}, $subclass;
     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);
 
     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 );
               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();
             }
             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 ) = @_;
 
 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.
 
 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
 
 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.
 
 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
 
 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
 
 
 =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
 
 
 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).
 
 
 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
 
 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.
 
 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).
 
 
 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).
 
 
 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).
 
 
 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
 
 
 =head1 AUTHORS
 

diff --git a/TODO b/TODO
index d570440..83b73f7 100644 (file)
--- 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
 - 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.