add failure_status field and documentation

diff --git a/Changes b/Changes
index 7672d21..5b4f7d5 100644 (file)
--- a/Changes
+++ b/Changes
@@ -3,7 +3,8 @@ Revision history for Perl extension Business::OnlinePayment.
 3.00_04  unreleased
        - oops, forgot _03 changelog in _03
        - B:OP:HTTPS: require Net::SSLeay 1.30 and remove _my_https_post kludge
-       - no warnings "redefine"
+       - eliminate warnings about redefined subroutes
+       - failure statues
 
 3.00_03  Wed Mar 16 02:41:59 PST 2005
        - https_post now accepts a scalar of raw content instead of key value

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.

diff --git a/notes_for_module_writers b/notes_for_module_writers
index bead4e8..718107e 100644 (file)
--- a/notes_for_module_writers
+++ b/notes_for_module_writers
@@ -1,13 +1,19 @@
-These are the old v2 notes.  Business::OnlinePayment::OpenECHO is the first
-"v3-ish" module, if you're writing an HTTPS-interface module, try starting
-from there until there's better v3 module writer's docs.
-
-$Id: notes_for_module_writers,v 1.2 2004-09-03 23:20:25 ivan Exp $
-
 Information on creating a new processor backend to go with
 Business::OnlinePayment.
+-----------------------------------------------------------
+
+NOTE: 
+
+    These are the old v2 notes.  
+
+    If you're writing a new module, see these first and then read
+    notes_for_module_writers_v3
+
+    If you're updating an existing module for v3, go directly to
+    notes_for_module_writers_v3
+
 
-create a subclass of Business::OnlinePayment called
+Create a subclass of Business::OnlinePayment called
 Business::OnlinePayment::(processor name).  You should override at least
 the following functions (look at Business::OnlinePayment::AuthorizeNet as
 an example).

diff --git a/notes_for_module_writers_v3 b/notes_for_module_writers_v3
new file mode 100644 (file)
index 0000000..9c2dd72
--- /dev/null
+++ b/notes_for_module_writers_v3
@@ -0,0 +1,40 @@
+These are the module writer's notes for v3.  See the regular
+"notes_for_module_writers" file first.
+
+
+- If your gateway is HTTPS-based, use (or convert to)
+  Business::OnlinePayment::HTTPS !!
+
+    - Business::OnlinePayment::OpenECHO is the first "v3-ish" module, try
+      starting from there.
+
+
+- Handling failures:
+
+    - If your processor module encounters a setup problem, communication
+      error or other problem that's prevents the card from even being
+      run, you should die (or croak) with a useful error message.  Setting
+      is_success to 0 and returning normally should only be done when the
+      transaction *processing* was sucessful (or at least elicited some sort
+      of result from the gateway), but the transaction itself returned a
+      "normal" decline status of some sort.
+      
+    - (NEW IN 3.00_04) You should set "failure_status" depending on the
+      specific failure result, if (and only if) the failure results from one
+      of the defined statuses:
+
+      - "expired"
+      - "nsf" (non-sufficient funds / credit limit)
+      - "stolen"
+      - "pickup"
+      - "blacklisted"
+      - "decline" (other card/transaction declines only, not other errors)
+  
+      You should use code like this so your module can work with B:OP versions
+      before 3.00_04:
+
+        $self->build_subs('failure_status') unless $self->can('failure_status');
+
+      (or add "failure_status" to your build_subs call if you have one during
+      initialization)
+