"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 !!
- - Business::OnlinePayment::OpenECHO is the first "v3-ish" module, try
- starting from there.
+ 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
- "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');
+= (NEW IN 3.01) Introspection =
+
+ - Add an _info subroutine to your module that returns a hashref of
+ information:
+
+ sub _info {
+ {
+ 'info_compat' => '0.01', # always 0.01 for now,
+ # 0.02 will have requirements
+ 'gateway_name' => 'Example Gateway',
+ 'gateway_url' => 'http://www.example.com/',
+ 'module_version' => $VERSION,
+ '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',
+ 'Post Authorization',
+ 'Void',
+ 'Credit',
+ ],
+ };
+ }
+
+ # or a more complicated case with module_notes, different supported actions
+ # per type, and special void requirements:
+
+ sub _info {
+ {
+ 'info_compat' => '0.01', # always 0.01 for now,
+ # 0.02 will have requirements
+ 'gateway_name' => 'Example Gateway',
+ 'gateway_url' => 'http://www.example.com/',
+ 'module_version' => $VERSION,
+ 'module_notes' => 'usage notes',
+ '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',
+ ],
+ 'ECHECK' => [
+ 'Normal Authorization',
+ 'Void',
+ 'Credit',
+ ],
+ },
+ '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) =
+
+ Gateways will return one or two values from Authorization Only and
+ Normal Authorization transactions that must be submitted back with a
+ Post Authorization, Reverse Authorization, Void, or Credit transaction.
+
+ If the gateway returns one value, return this as "authorization"
+
+ If the gateway returns two values, return one as "authorization" and the
+ other as "order_number". Typically "authorization" is the more low-level
+ 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.
+
- (or add "failure_status" to your build_subs call if you have one during
- initialization)
-
projects / Business-OnlinePayment.git / blobdiff