add failure_status field and documentation

[Business-OnlinePayment.git] / OnlinePayment.pm

diff --git a/OnlinePayment.pm b/OnlinePayment.pm
index 246066e..6d06887 100644 (file)
--- a/OnlinePayment.pm
+++ b/OnlinePayment.pm
@@ -4,7 +4,7 @@ use strict;
 use vars qw($VERSION); # @ISA @EXPORT @EXPORT_OK $AUTOLOAD);
 use Carp;
 
-require 5.004;
+require 5.005;
 #require Exporter;
 
 #@ISA = (); #qw(Exporter AutoLoader);
@@ -19,6 +19,7 @@ sub VERSION { #Argument "3.00_01" isn't numeric in subroutine entry
 
 my %fields = (
     is_success       => undef,
+    failure_status   => undef,
     result_code      => undef,
     test_transaction => undef,
     require_avs      => undef,
@@ -272,6 +273,17 @@ Submit the transaction to the processor for completion
 
 Returns true if the transaction was submitted successfully, false if it failed (or undef if it has not been submitted yet).
 
+=head2 failure_status();
+
+If the transactdion 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 (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.
+
 =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.