root / drupal7 / sites / all / modules / commerce / modules / payment / commerce_payment.api.php @ 70a4c29b
1 |
<?php
|
---|---|
2 |
|
3 |
/**
|
4 |
* @file
|
5 |
* Hooks provided by the Payment module.
|
6 |
*/
|
7 |
|
8 |
|
9 |
/**
|
10 |
* Defines rows for use in payment totals area handlers on Views.
|
11 |
*
|
12 |
* The payment totals area handler totals the amount of payments received by
|
13 |
* currency for all the payment transactions in a View. The array of totals are
|
14 |
* is used to build a table containing rows for each of the totals and/or the
|
15 |
* remaining balance of the order by default. Other modules may use this hook to
|
16 |
* add additional rows to the table.
|
17 |
*
|
18 |
* @param $totals
|
19 |
* An array of payment totals whose keys are currency codes and values are the
|
20 |
* total amount paid in each currency.
|
21 |
* @param $order
|
22 |
* If available, the order object to which the payments apply.
|
23 |
*
|
24 |
* @return
|
25 |
* An array of table row data as expected by theme_table(). Row arrays may
|
26 |
* contain an additional weight key with the value being an integer used to
|
27 |
* sort the rows prior to display.
|
28 |
*
|
29 |
* @see commerce_payment_commerce_payment_totals_rows()
|
30 |
* @see commerce_payment_commerce_payment_totals_row_info()
|
31 |
* @see theme_table()
|
32 |
*/
|
33 |
function hook_commerce_payment_totals_row_info($totals, $order) { |
34 |
$rows = array(); |
35 |
|
36 |
if (count($totals) <= 1) { |
37 |
// Add a row for the remaining balance on the order.
|
38 |
if ($order) { |
39 |
$balance = commerce_payment_order_balance($order, $totals); |
40 |
|
41 |
$rows[] = array( |
42 |
'data' => array( |
43 |
array('data' => t('Order balance'), 'class' => array('label')), |
44 |
array('data' => commerce_currency_format($balance['amount'], $balance['currency_code']), 'class' => array('balance')), |
45 |
), |
46 |
'class' => array('order-balance'), |
47 |
'weight' => 10, |
48 |
); |
49 |
} |
50 |
} |
51 |
|
52 |
return $rows; |
53 |
} |
54 |
|
55 |
/**
|
56 |
* Allows you to alter payment totals rows.
|
57 |
*
|
58 |
* @param $rows
|
59 |
* Array of payment totals rows exposed by
|
60 |
* hook_commerce_payment_totals_row_info() implementations.
|
61 |
* @param $totals
|
62 |
* An array of payment totals whose keys are currency codes and values are the
|
63 |
* total amount paid in each currency.
|
64 |
* @param $order
|
65 |
* If available, the order object to which the payments apply.
|
66 |
*
|
67 |
* @see hook_commerce_payment_totals_row_info()
|
68 |
*/
|
69 |
function hook_commerce_payment_totals_row_info_alter(&$rows, $totals, $order) { |
70 |
// Alter the weight of order balance rows to appear first.
|
71 |
foreach ($rows as $key => &$row) { |
72 |
if (in_array('order-balance', $row['class'])) { |
73 |
$row['weight'] = -10; |
74 |
} |
75 |
} |
76 |
} |
77 |
|
78 |
/**
|
79 |
* @defgroup commerce_payment_method Payment Method API
|
80 |
* @{
|
81 |
* API for integrating payment methods into the Drupal Commerce framework.
|
82 |
*/
|
83 |
|
84 |
/**
|
85 |
* Define payment methods available to the Commerce Payment framework.
|
86 |
*
|
87 |
* The Payment module uses this hook to gather information on payment methods
|
88 |
* defined by enabled modules.
|
89 |
*
|
90 |
* Payment methods depend on a variety of callbacks that are used to configure
|
91 |
* the payment methods via Rules actions, integrate the payment method with the
|
92 |
* checkout form, handle display and manipulation of transactions after the fact,
|
93 |
* and allow for administrative payment entering after checkout. The Payment
|
94 |
* module ships with payment method modules useful for testing and learning, but
|
95 |
* all integrations with real payment providers will be provided as contributed
|
96 |
* modules. The Payment module will include helper code designed to make different
|
97 |
* types of payment services easier to integrate as mentioned above.
|
98 |
*
|
99 |
* Each payment method is an associative array with the following keys:
|
100 |
* - method_id: string identifying the payment method (must be a valid PHP
|
101 |
* identifier).
|
102 |
* - base (optional): string used as the base for callback names, each of which
|
103 |
* will be defaulted to [base]_[callback] unless explicitly set; defaults
|
104 |
* to the method_id if not set.
|
105 |
* - title: the translatable full title of the payment method, used in
|
106 |
* administrative interfaces.
|
107 |
* - display_title (optional): the title to display on forms where the payment
|
108 |
* method is selected and may include HTML for methods that require images and
|
109 |
* special descriptions; defaults to the title.
|
110 |
* - short_title (optional): an abbreviated title that may simply include the
|
111 |
* payment provider’s name as it makes sense to the customer (i.e. you would
|
112 |
* display PayPal, not PayPal WPS to a customer); defaults to the title.
|
113 |
* - description (optional): a translatable description of the payment method,
|
114 |
* including the nature of the payment and the payment gateway that actually
|
115 |
* captures the payment.
|
116 |
* - active (optional): TRUE of FALSE indicating whether or not the default
|
117 |
* payment method rule configuration for this payment method should be
|
118 |
* enabled by default; defaults to FALSE.
|
119 |
* - checkout (optional): TRUE or FALSE indicating whether or not payments can
|
120 |
* be processed via this payment method through the checkout form; defaults
|
121 |
* to TRUE.
|
122 |
* - terminal (optional): TRUE or FALSE indicating whether or not payments can
|
123 |
* be processed via this payment method through the administrative payment
|
124 |
* terminal on an order’s Payment tab; defaults to TRUE.
|
125 |
* - offsite (optional): TRUE or FALSE indicating whether or not the customer
|
126 |
* must be redirected offsite to put in their payment information; used
|
127 |
* specifically by the off-site payment redirect checkout pane; defaults to
|
128 |
* FALSE.
|
129 |
* - offsite_autoredirect (optional): TRUE or FALSE indicating whether or not
|
130 |
* the customer should be automatically redirected to an offsite payment site
|
131 |
* on the payment step of checkout; defaults to FALSE.
|
132 |
* - callbacks (optional): an array of callback function names for the various
|
133 |
* types of callback required for all the payment method operations, arguments
|
134 |
* per callback in parentheses:
|
135 |
* - settings_form: the name of the CALLBACK_commerce_payment_method_settings_form()
|
136 |
* of the payment method.
|
137 |
* - submit_form: the name of the CALLBACK_commerce_payment_method_submit_form()
|
138 |
* of the payment method.
|
139 |
* - submit_form_validate: the name of the CALLBACK_commerce_payment_method_submit_form_validate()
|
140 |
* of the payment method.
|
141 |
* - submit_form_submit: the name of the CALLBACK_commerce_payment_method_submit_form_submit()
|
142 |
* of the payment method.
|
143 |
* - redirect_form: the name of the CALLBACK_commerce_payment_method_redirect_form()
|
144 |
* of the payment method.
|
145 |
* - redirect_form_validate: the name of the CALLBACK_commerce_payment_method_redirect_form_validate()
|
146 |
* of the payment method.
|
147 |
* - redirect_form_submit: the name of the CALLBACK_commerce_payment_method_redirect_form_submit()
|
148 |
* of the payment method.
|
149 |
* - file (optional): the filepath of an include file relative to the method's
|
150 |
* module containing the callback functions for this method, allowing modules
|
151 |
* to store payment method code in include files that only get loaded when
|
152 |
* necessary (like the menu item file property).
|
153 |
*
|
154 |
* @return
|
155 |
* An array of payment methods, using the format defined above.
|
156 |
*/
|
157 |
function hook_commerce_payment_method_info() { |
158 |
$payment_methods['paypal_wps'] = array( |
159 |
'base' => 'commerce_paypal_wps', |
160 |
'title' => t('PayPal WPS'), |
161 |
'short_title' => t('PayPal'), |
162 |
'description' => t('PayPal Website Payments Standard'), |
163 |
'terminal' => FALSE, |
164 |
'offsite' => TRUE, |
165 |
'offsite_autoredirect' => TRUE, |
166 |
); |
167 |
return $payment_methods; |
168 |
} |
169 |
|
170 |
/**
|
171 |
* Alter payment methods defined by other modules.
|
172 |
*
|
173 |
* This function is run before default values have been merged into the payment
|
174 |
* methods.
|
175 |
*
|
176 |
* @param $payment_methods
|
177 |
* An array of payment methods, keyed by method id.
|
178 |
*/
|
179 |
function hook_commerce_payment_method_info_alter(&$payment_methods) { |
180 |
// No example.
|
181 |
} |
182 |
|
183 |
/**
|
184 |
* Payment method callback; return the settings form for a payment method.
|
185 |
*
|
186 |
* @param $settings
|
187 |
* An array of the current settings.
|
188 |
* @return
|
189 |
* A form snippet.
|
190 |
*/
|
191 |
function CALLBACK_commerce_payment_method_settings_form($settings = NULL) { |
192 |
// No example.
|
193 |
} |
194 |
|
195 |
/**
|
196 |
* Payment method callback; generation callback for the payment submission form.
|
197 |
*
|
198 |
* @param $payment_method
|
199 |
* An array of the current settings.
|
200 |
* @param $pane_values
|
201 |
* The current values of the pane.
|
202 |
* @param $checkout_pane
|
203 |
* The checkout pane array. The checkout pane will be NULL if the payment is
|
204 |
* being added through the administration form.
|
205 |
* @param $order
|
206 |
* The order object.
|
207 |
* @return
|
208 |
* A form snippet for the checkout pane.
|
209 |
*/
|
210 |
function CALLBACK_commerce_payment_method_submit_form($payment_method, $pane_values, $checkout_pane, $order) { |
211 |
// No example.
|
212 |
} |
213 |
|
214 |
/**
|
215 |
* Payment method callback; validate callback for the payment submission form.
|
216 |
*
|
217 |
* @param $payment_method
|
218 |
* An array of the current settings.
|
219 |
* @param $pane_form
|
220 |
* The pane form.
|
221 |
* @param $pane_values
|
222 |
* The current values of the pane.
|
223 |
* @param $order
|
224 |
* The order object.
|
225 |
* @param $form_parents
|
226 |
* The identifier of the base element of the payment pane.
|
227 |
*/
|
228 |
function CALLBACK_commerce_payment_method_submit_form_validate($payment_method, $pane_form, $pane_values, $order, $form_parents = array()) { |
229 |
// No example.
|
230 |
} |
231 |
|
232 |
/**
|
233 |
* Payment method callback; validate callback for the payment submission form.
|
234 |
*
|
235 |
* @param $payment_method
|
236 |
* An array of the current settings.
|
237 |
* @param $pane_form
|
238 |
* The pane form.
|
239 |
* @param $pane_values
|
240 |
* The current values of the pane.
|
241 |
* @param $order
|
242 |
* The order object.
|
243 |
* @param $charge
|
244 |
* A price structure that needs to be charged.
|
245 |
*/
|
246 |
function CALLBACK_commerce_payment_method_submit_form_submit($payment_method, $pane_form, $pane_values, $order, $charge) { |
247 |
// No example.
|
248 |
} |
249 |
|
250 |
/**
|
251 |
* Payment method callback; generation callback for the payment redirect form.
|
252 |
*
|
253 |
* Returns form elements that should be submitted to the redirected payment
|
254 |
* service; because of the array merge that happens upon return, the service’s
|
255 |
* URL that should receive the POST variables should be set in the #action
|
256 |
* property of the returned form array.
|
257 |
*/
|
258 |
function CALLBACK_commerce_payment_method_redirect_form($form, &$form_state, $order, $payment_method) { |
259 |
// No example.
|
260 |
} |
261 |
|
262 |
/**
|
263 |
* Payment method callback; cancellation callback for the redirected payments.
|
264 |
*
|
265 |
* If the customer cancels payment or payment fails at the redirected payment
|
266 |
* service, the customer will be sent back to the previous checkout page upon
|
267 |
* return from the payment service. Before the redirect occurs, the payment
|
268 |
* method module has the opportunity to take additional action by implementing
|
269 |
* this callback. Note that updating the order status and performing the
|
270 |
* redirect are handled by the Payment module, so these two operations should
|
271 |
* not be duplicated by the payment method module.
|
272 |
*/
|
273 |
function CALLBACK_commerce_payment_method_redirect_form_back($order, $payment_method) { |
274 |
// No example.
|
275 |
} |
276 |
|
277 |
/**
|
278 |
* Payment method callback; validation callback for redirected payments.
|
279 |
*
|
280 |
* Upon return from a redirected payment service, this callback provides the
|
281 |
* payment method an opportunity to validate any returned data before proceeding
|
282 |
* to checkout completion; should return TRUE or FALSE indicating whether or not
|
283 |
* the customer should proceed to checkout completion or go back a step in the
|
284 |
* checkout process from the payment page.
|
285 |
*
|
286 |
* @param $order
|
287 |
* The order object.
|
288 |
* @param $payment_method
|
289 |
* The payment method array.
|
290 |
* @return
|
291 |
* TRUE if the customer should proceed to checkout completion or FALSE to go
|
292 |
* back one step in the checkout process.
|
293 |
*/
|
294 |
function CALLBACK_commerce_payment_method_redirect_form_validate($order, $payment_method) { |
295 |
// No example.
|
296 |
} |
297 |
|
298 |
/**
|
299 |
* Payment method callback; submission callback for redirected payments.
|
300 |
*
|
301 |
* Upon return from a redirected payment service, this callback provides the
|
302 |
* payment method an opportunity to perform any submission functions necessary
|
303 |
* before the customer is redirected to checkout completion.
|
304 |
*
|
305 |
* @param $order
|
306 |
* The order object.
|
307 |
* @param $payment_method
|
308 |
* The payment method array.
|
309 |
*/
|
310 |
function CALLBACK_commerce_payment_method_redirect_form_submit($order, $payment_method) { |
311 |
// No example.
|
312 |
} |
313 |
|
314 |
/**
|
315 |
* @} End of "ingroup commerce_payment_method"
|
316 |
*/
|
317 |
|
318 |
/**
|
319 |
* Populates an order's data array with payment methods available in checkout.
|
320 |
*
|
321 |
* The Payment module primarily depends on Rules to populate the payment method
|
322 |
* checkout pane with options using an action that enables a particular payment
|
323 |
* method for use. The action adds payment method instance information to the
|
324 |
* order's data array that is used by the pane form to add options to the radio
|
325 |
* select element. This hook may be used to do the same thing, meaning it should
|
326 |
* not return any information but update the order object's data array just like
|
327 |
* the payment method enabling action.
|
328 |
*
|
329 |
* It should be noted that using Rules is the preferred method, as this hook is
|
330 |
* being made available secondarily through the use of rules_invoke_all().
|
331 |
*
|
332 |
* @param $order
|
333 |
* The order object represented on the checkout form.
|
334 |
*
|
335 |
* @see commerce_payment_pane_checkout_form()
|
336 |
* @see commerce_payment_enable_method()
|
337 |
* @see rules_invoke_all()
|
338 |
*/
|
339 |
function hook_commerce_payment_methods($order) { |
340 |
// No example. See commerce_payment_enable_method() for a guide to what you
|
341 |
// must add to the order's data array.
|
342 |
} |
343 |
|
344 |
/**
|
345 |
* Allows modules to specify a uri for a payment transaction.
|
346 |
*
|
347 |
* When this hook is invoked, the first returned uri will be used for the
|
348 |
* payment transaction. Thus to override the default value provided by the
|
349 |
* Payment UI module, you would need to adjust the order of hook invocation via
|
350 |
* hook_module_implements_alter() or your module weight values.
|
351 |
*
|
352 |
* @param $transaction
|
353 |
* The payment transaction object whose uri is being determined.
|
354 |
*
|
355 |
* @return
|
356 |
* The uri elements of an entity as expected to be returned by entity_uri()
|
357 |
* matching the signature of url().
|
358 |
*
|
359 |
* @see commerce_payment_transaction_uri()
|
360 |
* @see hook_module_implements_alter()
|
361 |
* @see entity_uri()
|
362 |
* @see url()
|
363 |
*/
|
364 |
function hook_commerce_payment_transaction_uri($transaction) { |
365 |
// No example.
|
366 |
} |
367 |
|
368 |
/**
|
369 |
* Allows you to prepare payment transaction data before it is saved.
|
370 |
*
|
371 |
* @param $transaction
|
372 |
* The payment transaction object to be saved.
|
373 |
*
|
374 |
* @see rules_invoke_all()
|
375 |
*/
|
376 |
function hook_commerce_payment_transaction_presave($transaction) { |
377 |
// No example.
|
378 |
} |
379 |
|
380 |
/**
|
381 |
* Allows you to respond when an order is first considered paid in full.
|
382 |
*
|
383 |
* The unpaid balance of an order is calculated by subtracting the total amount
|
384 |
* of all successful payment transactions referencing the order from the order's
|
385 |
* total. If the balance is less than or equal to zero, it is considered paid in
|
386 |
* full. The first time an order's balance falls to or below zero, this hook is
|
387 |
* invoked to allow modules to perform special maintenance as necessary. This
|
388 |
* hook is invoked before the "When an order is first paid in full" Rules event.
|
389 |
*
|
390 |
* Through the administration of payment transactions, it is possible for an
|
391 |
* order's balance to go above zero. It is then possible for the balance to go
|
392 |
* back down to or below zero. In either of these cases, no further action is
|
393 |
* taken. At present, this hook and Rules event are only meant to be invoked the
|
394 |
* first time an order is considered paid in full.
|
395 |
*
|
396 |
* @param $order
|
397 |
* The order that was just paid in full.
|
398 |
* @param $transaction
|
399 |
* The successful transaction that just caused the order's balance to drop to
|
400 |
* or below zero.
|
401 |
*/
|
402 |
function hook_commerce_payment_order_paid_in_full($order, $transaction) { |
403 |
// No example.
|
404 |
} |
405 |
|
406 |
/**
|
407 |
* Defines payment transaction statuses.
|
408 |
*
|
409 |
* A payment transaction represents any attempted payment via a payment method
|
410 |
* and includes a variety of properties used for tracking the amount, outcome,
|
411 |
* and parameters of the transaction. One of these is the transaction’s local
|
412 |
* status, not to be confused with its remote_status that stores the exact
|
413 |
* status of the transaction at the payment provider.
|
414 |
*
|
415 |
* Transaction statuses are used to visually represent in the order’s Payment
|
416 |
* tab whether or not the payment should be considered a success (meaning money
|
417 |
* was actually collected) and are accordingly considered when calculating the
|
418 |
* remaining balance of an order. Because payment statuses are critical
|
419 |
* functionality components, the default statuses listed below are actually
|
420 |
* defined in the function used to load all payment transaction statuses:
|
421 |
* - Pending: further action is required to determine if the attempted payment
|
422 |
* was a success or failure; used for payment methods like e-checks that may
|
423 |
* require time to clear or credit card authorizations that haven’t been
|
424 |
* captured yet
|
425 |
* - Success: the transaction is complete and a success, meaning the amount of
|
426 |
* this transaction will be subtracted from the order total to determine the
|
427 |
* outstanding balance on the order
|
428 |
* - Failure: the attempted transaction failed and will not be counted in totals
|
429 |
*
|
430 |
* Additional statuses may be defined via this hook, but there is no general
|
431 |
* alteration. The properties of the default statuses may be altered as long as
|
432 |
* the actual status key is preserved via the use of array merging.
|
433 |
*
|
434 |
* The payment transaction status array structure is as follows:
|
435 |
* - status: machine-name identifying the payment transaction status using
|
436 |
* lowercase alphanumeric characters, -, and _
|
437 |
* - title: the translatable title of the transaction status, used in
|
438 |
* administrative interfaces
|
439 |
* - icon: the path to the status’s icon relative to the Drupal root directory
|
440 |
* - total: TRUE or FALSE indicating whether or not transactions in this
|
441 |
* status should be totaled to determine the balance of an order
|
442 |
*
|
443 |
* @return
|
444 |
* An array of payment transaction status arrays keyed by status.
|
445 |
*
|
446 |
* @see commerce_payment_transaction_statuses()
|
447 |
*/
|
448 |
function hook_commerce_payment_transaction_status_info() { |
449 |
$statuses = array(); |
450 |
|
451 |
// COMMERCE_PAYMENT_STATUS_SUCCESS is a constant defined in the Payment module.
|
452 |
$statuses[COMMERCE_PAYMENT_STATUS_SUCCESS] = array( |
453 |
'status' => COMMERCE_PAYMENT_STATUS_SUCCESS, |
454 |
'title' => t('Success'), |
455 |
'icon' => drupal_get_path('module', 'commerce_payment') . '/theme/icon-success.png', |
456 |
'total' => TRUE, |
457 |
); |
458 |
|
459 |
return $statuses; |
460 |
} |