Document best-practice eval of the submit() method in example

diff --git a/Changes b/Changes
index dfef5f6..f3fc130 100644 (file)
--- a/Changes
+++ b/Changes
@@ -5,6 +5,7 @@ Revision history for Perl extension Business::OnlinePayment.
         - Document expiration is MM/YY and fix the example
         - Document repository moved from CVS to git
         - Add avs_code and cvv2_response to build_subs, they're standard fields
+        - Document best-practice eval of the submit() method in example
 
 3.02    Fri Aug 19 16:20:04 PDT 2011
         - Fix fatal error calling ->info('supported_actions') on a gateway that

diff --git a/OnlinePayment.pm b/OnlinePayment.pm
index e7c9bcb..f8417ba 100644 (file)
--- a/OnlinePayment.pm
+++ b/OnlinePayment.pm
@@ -275,12 +275,21 @@ Business::OnlinePayment - Perl extension for online payment processing
                         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
@@ -631,7 +640,11 @@ verification (if the processor supports it).
 
 =head2 submit()
 
-Submit the transaction to the processor for completion
+Submit the transaction to the processor for completion.
+
+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
 
@@ -655,10 +668,8 @@ are: "expired", "nsf" (non-sufficient funds), "stolen", "pickup",
 "blacklisted" and "declined" (card/transaction declines only, not
 other errors).
 
-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.
+Note that not all processor modules support this, and that if supported,
+it may not be set for all declines.
 
 =head2 authorization()