root / drupal7 / sites / all / modules / commerce / modules / payment / commerce_payment.api.php @ 9d13637e
1 | 85ad3d82 | Assos Assos | <?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 | 9d13637e | Assos Assos | function CALLBACK_commerce_payment_method_redirect_form_back($order, $payment_method) { |
274 | 85ad3d82 | Assos Assos | // 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 | 9d13637e | Assos Assos | * hook is invoked before the "When an order is first paid in full" Rules event.
|
389 | 85ad3d82 | Assos Assos | *
|
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 | } |