Debian Codegraph @

notes_for_module_writers_v3

raw
1 These are the module writer's notes for v3. See the regular
2 "notes_for_module_writers" file first.
3
4
5 = Business::OnlinePayment::HTTPS =
6
7 If your gateway is HTTPS-based, use (or convert to)
8 Business::OnlinePayment::HTTPS !!
9
10 Note: The correct thing for modern B:OP: gateway modules that need to
11 speak HTTPS to do is to use Business::OnlinePayment::HTTPS and depend on
12 "Net::HTTPS::Any" (since B:OP itself doesn't).
13
14
15 = Handling failures =
16
17 - If your processor module encounters a setup problem, communication
18 error or other problem that's prevents the card from even being
19 run, you should die (or croak) with a useful error message. Setting
20 is_success to 0 and returning normally should only be done when the
21 transaction *processing* was sucessful (or at least elicited some sort
22 of result from the gateway), but the transaction itself returned a
23 "normal" decline status of some sort.
24
25 - (NEW IN 3.00_04) You should set "failure_status" depending on the
26 specific failure result, if (and only if) the failure results from one
27 of the defined statuses:
28
29 - "expired"
30 - "nsf" (non-sufficient funds / credit limit)
31 - "stolen"
32 - "pickup"
33 - "blacklisted"
34 - "inactive" (inactive card or not authorized for card-not-present) (?)
35 - "decline" (other card/transaction declines only, not other errors)
36
37
38 = (NEW IN 3.01) Introspection =
39
40 - Add an _info subroutine to your module that returns a hashref of
41 information:
42
43 sub _info {
44 {
45 'info_compat' => '0.01', # always 0.01 for now,
46 # 0.02 will have requirements
47 'gateway_name' => 'Example Gateway',
48 'gateway_url' => 'http://www.example.com/',
49 'module_version' => $VERSION,
50 'supported_types' => [ qw( CC ECHECK ) ],
51 'token_support' => 0, #card storage/tokenization support
52 'test_transaction' => 0, #set true if ->test_transaction(1) works
53 'partial_auth' => 0, #can gateway partial auth (new in 3.04)
54 'supported_actions' => [
55 'Normal Authorization',
56 'Authorization Only',
57 'Post Authorization',
58 'Void',
59 'Credit',
60 ],
61 };
62 }
63
64 # or a more complicated case with module_notes, different supported actions
65 # per type, and special void requirements:
66
67 sub _info {
68 {
69 'info_compat' => '0.01', # always 0.01 for now,
70 # 0.02 will have requirements
71 'gateway_name' => 'Example Gateway',
72 'gateway_url' => 'http://www.example.com/',
73 'module_version' => $VERSION,
74 'module_notes' => 'usage notes',
75 'supported_types' => [ qw( CC ECHECK ) ],
76 'token_support' => 1,
77 'test_transaction' => 1,
78 'partial_auth' => 1, #can gateway partial auth (new in 3.04)
79 'supported_actions' => { 'CC' => [
80 'Normal Authorization',
81 'Authorization Only',
82 'Post Authorization',
83 'Void',
84 'Credit',
85 'Tokenize',
86 'Recurring Authorization',
87 'Modify Recurring Authorization',
88 'Cancel Recurring Authorization',
89 ],
90 'ECHECK' => [
91 'Normal Authorization',
92 'Void',
93 'Credit',
94 ],
95 },
96 'CC_void_requires_card' => 1,
97 #? 'CC_reverse_auth_requires_txn_date' => 1,
98 'ECHECK_void_requires_account' => 1, #routing_code, account_number, name
99 };
100 }
101
102
103 = authorization and order_number (NEWLY DOCUMENTED IN 3.01) =
104
105 Gateways will return one or two values from Authorization Only and
106 Normal Authorization transactions that must be submitted back with a
107 Post Authorization, Reverse Authorization, Void, or Credit transaction.
108
109 If the gateway returns one value, return this as "authorization"
110
111 If the gateway returns two values, return one as "authorization" and the
112 other as "order_number". Typically "authorization" is the more low-level
113 value returned from the underlying processing network while "order_number"
114 is a unique tranaction id generated by the gateway.
115
116
117 = txn_date (NEW IN 3.05) =
118
119 Some gateways return a transaction date from Authorization Only / Normal
120 Authorization transactions that must be submitted back for a follow-up
121 Post Authorization, Reverse Authorization, Void, or Credit transaction.
122
123 For the most compatibility with all gateways for follow-up transactions,
124 pass this as well as authorization and order number. Note this field is
125 a recent addition, so always access it like this:
126
127 my $txn_date = $bop_transaction_object->can('txn_date')
128 ? $bop_transaction_object->txn_date
129 : '';
130
131
132 = Moo (NEWLY DOCUMENTED IN 3.04) =
133
134 Feel free to write gateway modules which use Moo. Please do not require
135 Moo newer than 0.091011 at this time (until 2018 or so).
136
137
138 = Partial authorizations (NEWLY DOCUMENTED IN 3.04) =
139
140 If your gateway supports partial authorizations:
141
142 - Declare this in your "sub _info" introspection subroutine:
143 'partial_auth' => 1,
144
145 - Add "partial_auth_amount" to your build_subs call in set_defaults, or add
146 one:
147 $self->build_subs('partial_auth_amount');
148
149 - Honor the transaction 'partial_auth' flag as follows:
150 + If this transaction flag is unset, the application is not expecting to
151 handle a partial authorzation. So, either set the gateway flag disabling
152 partial authorizations, or (if your gateway does not have such a
153 setting), immediately void any partial authorization received and
154 return is_success 0.
155 + If this transaction flag is set, the application can handle a partial
156 authorization. Make sure the flag to enable them is passed to the
157 gateway, if necessary. When a partial authorization is received, return
158 is_success 1, and the amount as "partial_auth_amount":
159 $self->partial_auth_amount( $partial_amount );
160 For normal full authorizations, "partial_auth_amount" must not be set.
161
162