X-Git-Url: http://git.freeside.biz/gitweb/?a=blobdiff_plain;f=notes_for_module_writers_v3;h=3376500b5924d441e77656e30575c2cd9fb5b7a4;hb=90b8472dd1f760092933acf0b1a366de2caf9caf;hp=1d848f5c3c53f258a4cfcc103b24eedd2f5ff10a;hpb=a2f221d7e99bdcb1aa55b71f4eabab49232415bd;p=Business-OnlinePayment.git diff --git a/notes_for_module_writers_v3 b/notes_for_module_writers_v3 index 1d848f5..3376500 100644 --- a/notes_for_module_writers_v3 +++ b/notes_for_module_writers_v3 @@ -2,14 +2,17 @@ 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 = + + If your gateway is HTTPS-based, use (or convert to) Business::OnlinePayment::HTTPS !! + Note: The correct thing for modern B:OP: gateway modules that need to speak HTTPS to do is to use Business::OnlinePayment::HTTPS and depend on "Net::HTTPS::Any" (since B:OP itself doesn't). -- Handling failures: += Handling failures = - If your processor module encounters a setup problem, communication error or other problem that's prevents the card from even being @@ -31,16 +34,8 @@ These are the module writer's notes for v3. See the regular - "inactive" (inactive card or not authorized for card-not-present) (?) - "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) - -- (NEW IN 3.01) Introspection: += (NEW IN 3.01) Introspection = - Add an _info subroutine to your module that returns a hashref of information: @@ -55,6 +50,7 @@ These are the module writer's notes for v3. See the regular 'supported_types' => [ qw( CC ECHECK ) ], 'token_support' => 0, #card storage/tokenization support 'test_transaction' => 0, #set true if ->test_transaction(1) works + 'partial_auth' => 0, #can gateway partial auth (new in 3.04) 'supported_actions' => [ 'Normal Authorization', 'Authorization Only', @@ -65,7 +61,8 @@ These are the module writer's notes for v3. See the regular }; } - # or a more complicated case: + # or a more complicated case with module_notes, different supported actions + # per type, and special void requirements: sub _info { { @@ -78,12 +75,14 @@ These are the module writer's notes for v3. See the regular 'supported_types' => [ qw( CC ECHECK ) ], 'token_support' => 1, 'test_transaction' => 1, + 'partial_auth' => 1, #can gateway partial auth (new in 3.04) 'supported_actions' => { 'CC' => [ 'Normal Authorization', 'Authorization Only', 'Post Authorization', 'Void', 'Credit', + 'Tokenize', 'Recurring Authorization', 'Modify Recurring Authorization', 'Cancel Recurring Authorization', @@ -95,16 +94,17 @@ These are the module writer's notes for v3. See the regular ], }, 'CC_void_requires_card' => 1, + #? 'CC_reverse_auth_requires_txn_date' => 1, 'ECHECK_void_requires_account' => 1, #routing_code, account_number, name }; } -- authorization and order_number (NEWLY DOCUMENTED IN 3.01): += authorization and order_number (NEWLY DOCUMENTED IN 3.01) = Gateways will return one or two values from Authorization Only and Normal Authorization transactions that must be submitted back with a - Post Authorization, Void, or Credit transaction. + Post Authorization, Reverse Authorization, Void, or Credit transaction. If the gateway returns one value, return this as "authorization" @@ -113,3 +113,50 @@ These are the module writer's notes for v3. See the regular value returned from the underlying processing network while "order_number" is a unique tranaction id generated by the gateway. + += txn_date (NEW IN 3.05) = + + Some gateways return a transaction date from Authorization Only / Normal + Authorization transactions that must be submitted back for a follow-up + Post Authorization, Reverse Authorization, Void, or Credit transaction. + + For the most compatibility with all gateways for follow-up transactions, + pass this as well as authorization and order number. Note this field is + a recent addition, so always access it like this: + + my $txn_date = $bop_transaction_object->can('txn_date') + ? $bop_transaction_object->txn_date + : ''; + + += Moo (NEWLY DOCUMENTED IN 3.04) = + + Feel free to write gateway modules which use Moo. Please do not require + Moo newer than 0.091011 at this time (until 2018 or so). + + += Partial authorizations (NEWLY DOCUMENTED IN 3.04) = + + If your gateway supports partial authorizations: + + - Declare this in your "sub _info" introspection subroutine: + 'partial_auth' => 1, + + - Add "partial_auth_amount" to your build_subs call in set_defaults, or add + one: + $self->build_subs('partial_auth_amount'); + + - Honor the transaction 'partial_auth' flag as follows: + + If this transaction flag is unset, the application is not expecting to + handle a partial authorzation. So, either set the gateway flag disabling + partial authorizations, or (if your gateway does not have such a + setting), immediately void any partial authorization received and + return is_success 0. + + If this transaction flag is set, the application can handle a partial + authorization. Make sure the flag to enable them is passed to the + gateway, if necessary. When a partial authorization is received, return + is_success 1, and the amount as "partial_auth_amount": + $self->partial_auth_amount( $partial_amount ); + For normal full authorizations, "partial_auth_amount" must not be set. + +