commerce_payment.api.php in Commerce Core 7

Hooks provided by the Payment module.

File

modules/payment/commerce_payment.api.php

<?php

/**
 * @file
 * Hooks provided by the Payment module.
 */

/**
 * Defines rows for use in payment totals area handlers on Views.
 *
 * The payment totals area handler totals the amount of payments received by
 * currency for all the payment transactions in a View. The array of totals are
 * is used to build a table containing rows for each of the totals and/or the
 * remaining balance of the order by default. Other modules may use this hook to
 * add additional rows to the table.
 *
 * @param $totals
 *   An array of payment totals whose keys are currency codes and values are the
 *   total amount paid in each currency.
 * @param $order
 *   If available, the order object to which the payments apply.
 *
 * @return
 *   An array of table row data as expected by theme_table(). Row arrays may
 *   contain an additional weight key with the value being an integer used to
 *   sort the rows prior to display.
 *
 * @see commerce_payment_commerce_payment_totals_rows()
 * @see commerce_payment_commerce_payment_totals_row_info()
 * @see theme_table()
 */
function hook_commerce_payment_totals_row_info($totals, $order) {
  $rows = array();
  if (count($totals) <= 1) {

    // Add a row for the remaining balance on the order.
    if ($order) {
      $balance = commerce_payment_order_balance($order, $totals);
      $rows[] = array(
        'data' => array(
          array(
            'data' => t('Order balance'),
            'class' => array(
              'label',
            ),
          ),
          array(
            'data' => commerce_currency_format($balance['amount'], $balance['currency_code']),
            'class' => array(
              'balance',
            ),
          ),
        ),
        'class' => array(
          'order-balance',
        ),
        'weight' => 10,
      );
    }
  }
  return $rows;
}

/**
 * Allows you to alter payment totals rows.
 *
 * @param $rows
 *   Array of payment totals rows exposed by
 *   hook_commerce_payment_totals_row_info() implementations.
 * @param $totals
 *   An array of payment totals whose keys are currency codes and values are the
 *   total amount paid in each currency.
 * @param $order
 *   If available, the order object to which the payments apply.
 *
 * @see hook_commerce_payment_totals_row_info()
 */
function hook_commerce_payment_totals_row_info_alter(&$rows, $totals, $order) {

  // Alter the weight of order balance rows to appear first.
  foreach ($rows as $key => &$row) {
    if (in_array('order-balance', $row['class'])) {
      $row['weight'] = -10;
    }
  }
}

/**
 * @defgroup commerce_payment_method Payment Method API
 * @{
 * API for integrating payment methods into the Drupal Commerce framework.
 */

/**
 * Define payment methods available to the Commerce Payment framework.
 *
 * The Payment module uses this hook to gather information on payment methods
 * defined by enabled modules.
 *
 * Payment methods depend on a variety of callbacks that are used to configure
 * the payment methods via Rules actions, integrate the payment method with the
 * checkout form, handle display and manipulation of transactions after the fact,
 * and allow for administrative payment entering after checkout. The Payment
 * module ships with payment method modules useful for testing and learning, but
 * all integrations with real payment providers will be provided as contributed
 * modules. The Payment module will include helper code designed to make different
 * types of payment services easier to integrate as mentioned above.
 *
 * Each payment method is an associative array with the following keys:
 *  - method_id: string identifying the payment method (must be a valid PHP
 *    identifier).
 *  - base (optional): string used as the base for callback names, each of which
 *    will be defaulted to [base]_[callback] unless explicitly set; defaults
 *    to the method_id if not set.
 *  - title: the translatable full title of the payment method, used in
 *    administrative interfaces.
 *  - display_title (optional): the title to display on forms where the payment
 *    method is selected and may include HTML for methods that require images and
 *    special descriptions; defaults to the title.
 *  - short_title (optional): an abbreviated title that may simply include the
 *    payment provider’s name as it makes sense to the customer (i.e. you would
 *    display PayPal, not PayPal WPS to a customer); defaults to the title.
 *  - description (optional): a translatable description of the payment method,
 *    including the nature of the payment and the payment gateway that actually
 *    captures the payment.
 *  - active (optional): TRUE of FALSE indicating whether or not the default
 *    payment method rule configuration for this payment method should be
 *    enabled by default; defaults to FALSE.
 *  - checkout (optional): TRUE or FALSE indicating whether or not payments can
 *    be processed via this payment method through the checkout form; defaults
 *    to TRUE.
 *  - terminal (optional): TRUE or FALSE indicating whether or not payments can
 *    be processed via this payment method through the administrative payment
 *    terminal on an order’s Payment tab; defaults to TRUE.
 *  - offsite (optional): TRUE or FALSE indicating whether or not the customer
 *    must be redirected offsite to put in their payment information; used
 *    specifically by the off-site payment redirect checkout pane; defaults to
 *    FALSE.
 *  - offsite_autoredirect (optional): TRUE or FALSE indicating whether or not
 *    the customer should be automatically redirected to an offsite payment site
 *    on the payment step of checkout; defaults to FALSE.
 *  - callbacks (optional): an array of callback function names for the various
 *    types of callback required for all the payment method operations, arguments
 *    per callback in parentheses:
 *      - settings_form: the name of the CALLBACK_commerce_payment_method_settings_form()
 *        of the payment method.
 *      - submit_form: the name of the CALLBACK_commerce_payment_method_submit_form()
 *        of the payment method.
 *      - submit_form_validate: the name of the CALLBACK_commerce_payment_method_submit_form_validate()
 *        of the payment method.
 *      - submit_form_submit: the name of the CALLBACK_commerce_payment_method_submit_form_submit()
 *        of the payment method.
 *      - redirect_form: the name of the CALLBACK_commerce_payment_method_redirect_form()
 *        of the payment method.
 *      - redirect_form_back: the name of the CALLBACK_commerce_payment_method_redirect_form_back()
 *        of the payment method.
 *      - redirect_form_validate: the name of the CALLBACK_commerce_payment_method_redirect_form_validate()
 *        of the payment method.
 *      - redirect_form_submit: the name of the CALLBACK_commerce_payment_method_redirect_form_submit()
 *        of the payment method.
 *  - file (optional): the filepath of an include file relative to the method's
 *    module containing the callback functions for this method, allowing modules
 *    to store payment method code in include files that only get loaded when
 *    necessary (like the menu item file property).
 *
 * @return
 *   An array of payment methods, using the format defined above.
 */
function hook_commerce_payment_method_info() {
  $payment_methods['paypal_wps'] = array(
    'base' => 'commerce_paypal_wps',
    'title' => t('PayPal WPS'),
    'short_title' => t('PayPal'),
    'description' => t('PayPal Website Payments Standard'),
    'terminal' => FALSE,
    'offsite' => TRUE,
    'offsite_autoredirect' => TRUE,
  );
  return $payment_methods;
}

/**
 * Alter payment methods defined by other modules.
 *
 * This function is run before default values have been merged into the payment
 * methods.
 *
 * @param $payment_methods
 *   An array of payment methods, keyed by method id.
 */
function hook_commerce_payment_method_info_alter(&$payment_methods) {

  // No example.
}

/**
 * Payment method callback; return the settings form for a payment method.
 *
 * @param $settings
 *   An array of the current settings.
 * @return
 *   A form snippet.
 */
function CALLBACK_commerce_payment_method_settings_form($settings = NULL) {

  // No example.
}

/**
 * Payment method callback; generation callback for the payment submission form.
 *
 * @param $payment_method
 *   An array of the current settings.
 * @param $pane_values
 *   The current values of the pane.
 * @param $checkout_pane
 *   The checkout pane array. The checkout pane will be NULL if the payment is
 *   being added through the administration form.
 * @param $order
 *   The order object.
 * @return
 *   A form snippet for the checkout pane.
 */
function CALLBACK_commerce_payment_method_submit_form($payment_method, $pane_values, $checkout_pane, $order) {

  // No example.
}

/**
 * Payment method callback; validate callback for the payment submission form.
 *
 * @param $payment_method
 *   An array of the current settings.
 * @param $pane_form
 *   The pane form.
 * @param $pane_values
 *   The current values of the pane.
 * @param $order
 *   The order object.
 * @param $form_parents
 *   The identifier of the base element of the payment pane.
 */
function CALLBACK_commerce_payment_method_submit_form_validate($payment_method, $pane_form, $pane_values, $order, $form_parents = array()) {

  // No example.
}

/**
 * Payment method callback; validate callback for the payment submission form.
 *
 * @param $payment_method
 *   An array of the current settings.
 * @param $pane_form
 *   The pane form.
 * @param $pane_values
 *   The current values of the pane.
 * @param $order
 *   The order object.
 * @param $charge
 *   A price structure that needs to be charged.
 */
function CALLBACK_commerce_payment_method_submit_form_submit($payment_method, $pane_form, $pane_values, $order, $charge) {

  // No example.
}

/**
 * Payment method callback; generation callback for the payment redirect form.
 *
 * Returns form elements that should be submitted to the redirected payment
 * service; because of the array merge that happens upon return, the service’s
 * URL that should receive the POST variables should be set in the #action
 * property of the returned form array.
 */
function CALLBACK_commerce_payment_method_redirect_form($form, &$form_state, $order, $payment_method) {

  // No example.
}

/**
 * Payment method callback; cancellation callback for the redirected payments.
 *
 * If the customer cancels payment or payment fails at the redirected payment
 * service, the customer will be sent back to the previous checkout page upon
 * return from the payment service. Before the redirect occurs, the payment
 * method module has the opportunity to take additional action by implementing
 * this callback. Note that updating the order status and performing the
 * redirect are handled by the Payment module, so these two operations should
 * not be duplicated by the payment method module.
 */
function CALLBACK_commerce_payment_method_redirect_form_back($order, $payment_method) {

  // No example.
}

/**
 * Payment method callback; validation callback for redirected payments.
 *
 * Upon return from a redirected payment service, this callback provides the
 * payment method an opportunity to validate any returned data before proceeding
 * to checkout completion; should return TRUE or FALSE indicating whether or not
 * the customer should proceed to checkout completion or go back a step in the
 * checkout process from the payment page.
 *
 * @param $order
 *   The order object.
 * @param $payment_method
 *   The payment method array.
 * @return
 *   TRUE if the customer should proceed to checkout completion or FALSE to go
 *   back one step in the checkout process.
 */
function CALLBACK_commerce_payment_method_redirect_form_validate($order, $payment_method) {

  // No example.
}

/**
 * Payment method callback; submission callback for redirected payments.
 *
 * Upon return from a redirected payment service, this callback provides the
 * payment method an opportunity to perform any submission functions necessary
 * before the customer is redirected to checkout completion.
 *
 * @param $order
 *   The order object.
 * @param $payment_method
 *   The payment method array.
 */
function CALLBACK_commerce_payment_method_redirect_form_submit($order, $payment_method) {

  // No example.
}

/**
 * @} End of "ingroup commerce_payment_method"
 */

/**
 * Populates an order's data array with payment methods available in checkout.
 *
 * The Payment module primarily depends on Rules to populate the payment method
 * checkout pane with options using an action that enables a particular payment
 * method for use. The action adds payment method instance information to the
 * order's data array that is used by the pane form to add options to the radio
 * select element. This hook may be used to do the same thing, meaning it should
 * not return any information but update the order object's data array just like
 * the payment method enabling action.
 *
 * It should be noted that using Rules is the preferred method, as this hook is
 * being made available secondarily through the use of rules_invoke_all().
 *
 * @param $order
 *   The order object represented on the checkout form.
 *
 * @see commerce_payment_pane_checkout_form()
 * @see commerce_payment_enable_method()
 * @see rules_invoke_all()
 */
function hook_commerce_payment_methods($order) {

  // No example. See commerce_payment_enable_method() for a guide to what you
  // must add to the order's data array.
}

/**
 * Allows modules to specify a uri for a payment transaction.
 *
 * When this hook is invoked, the first returned uri will be used for the
 * payment transaction. Thus to override the default value provided by the
 * Payment UI module, you would need to adjust the order of hook invocation via
 * hook_module_implements_alter() or your module weight values.
 *
 * @param $transaction
 *   The payment transaction object whose uri is being determined.
 *
 * @return
 *  The uri elements of an entity as expected to be returned by entity_uri()
 *  matching the signature of url().
 *
 * @see commerce_payment_transaction_uri()
 * @see hook_module_implements_alter()
 * @see entity_uri()
 * @see url()
 */
function hook_commerce_payment_transaction_uri($transaction) {

  // No example.
}

/**
 * Allows you to prepare payment transaction data before it is saved.
 *
 * @param $transaction
 *   The payment transaction object to be saved.
 *
 * @see rules_invoke_all()
 */
function hook_commerce_payment_transaction_presave($transaction) {

  // No example.
}

/**
 * Allows you to respond when an order is first considered paid in full.
 *
 * The unpaid balance of an order is calculated by subtracting the total amount
 * of all successful payment transactions referencing the order from the order's
 * total. If the balance is less than or equal to zero, it is considered paid in
 * full. The first time an order's balance falls to or below zero, this hook is
 * invoked to allow modules to perform special maintenance as necessary. This
 * hook is invoked before the "When an order is first paid in full" Rules event.
 *
 * Through the administration of payment transactions, it is possible for an
 * order's balance to go above zero. It is then possible for the balance to go
 * back down to or below zero. In either of these cases, no further action is
 * taken. At present, this hook and Rules event are only meant to be invoked the
 * first time an order is considered paid in full.
 *
 * @param $order
 *   The order that was just paid in full.
 * @param $transaction
 *   The successful transaction that just caused the order's balance to drop to
 *   or below zero.
 */
function hook_commerce_payment_order_paid_in_full($order, $transaction) {

  // No example.
}

/**
 * Defines payment transaction statuses.
 *
 * A payment transaction represents any attempted payment via a payment method
 * and includes a variety of properties used for tracking the amount, outcome,
 * and parameters of the transaction. One of these is the transaction’s local
 * status, not to be confused with its remote_status that stores the exact
 * status of the transaction at the payment provider.
 *
 * Transaction statuses are used to visually represent in the order’s Payment
 * tab whether or not the payment should be considered a success (meaning money
 * was actually collected) and are accordingly considered when calculating the
 * remaining balance of an order. Because payment statuses are critical
 * functionality components, the default statuses listed below are actually
 * defined in the function used to load all payment transaction statuses:
 * - Pending: further action is required to determine if the attempted payment
 *   was a success or failure; used for payment methods like e-checks that may
 *   require time to clear or credit card authorizations that haven’t been
 *   captured yet
 * - Success: the transaction is complete and a success, meaning the amount of
 *   this transaction will be subtracted from the order total to determine the
 *   outstanding balance on the order
 * - Failure: the attempted transaction failed and will not be counted in totals
 *
 * Additional statuses may be defined via this hook, but there is no general
 * alteration. The properties of the default statuses may be altered as long as
 * the actual status key is preserved via the use of array merging.
 *
 * The payment transaction status array structure is as follows:
 * - status: machine-name identifying the payment transaction status using
 *   lowercase alphanumeric characters, -, and _
 * - title: the translatable title of the transaction status, used in
 *   administrative interfaces
 * - icon: the path to the status’s icon relative to the Drupal root directory
 * - total: TRUE or FALSE indicating whether or not transactions in this
 *   status should be totaled to determine the balance of an order
 *
 * @return
 *   An array of payment transaction status arrays keyed by status.
 *
 * @see commerce_payment_transaction_statuses()
 */
function hook_commerce_payment_transaction_status_info() {
  $statuses = array();

  // COMMERCE_PAYMENT_STATUS_SUCCESS is a constant defined in the Payment module.
  $statuses[COMMERCE_PAYMENT_STATUS_SUCCESS] = array(
    'status' => COMMERCE_PAYMENT_STATUS_SUCCESS,
    'title' => t('Success'),
    'icon' => drupal_get_path('module', 'commerce_payment') . '/theme/icon-success.png',
    'total' => TRUE,
  );
  return $statuses;
}

/**
 * Allows you to act when a transaction is updated.
 *
 * If you want to perform an action when a transaction changes states, you can
 * use this hook to do so. You can load the original transaction here and
 * compare.
 *
 * @param $transaction
 *   The transaction being updated.
 */
function hook_commerce_payment_transaction_update($transaction) {

  // No example.
}

/**
 * Allows you to act when a transaction is created.
 *
 * @param $transaction
 *   The transaction being created.
 */
function hook_commerce_payment_transaction_insert($transaction) {

  // No example.
}

/**
 * Allows you to act when a transaction is being deleted.
 *
 * @param $transaction
 *   The transaction being deleted.
 */
function hook_commerce_payment_transaction_delete($transaction) {

  // No example.
}

/**
 * Allows you to act when transactions are being loaded.
 *
 * @param $transactions
 *   An array of transactions indexed by transaction_id.
 */
function hook_commerce_payment_transaction_load($transactions) {
  $result = db_query('SELECT transaction_id, foo FROM {mytable} WHERE transaction_ids IN (:transaction_ids)', array(
    ':transaction_ids' => array_keys($transactions),
  ));
  foreach ($result as $record) {
    $transactions[$record->transaction_id]->foo = $record->foo;
  }
}

/**
 * Alter the card types defined by the Payment module.
 *
 * This function is run after the known global card types are defined so a site
 * can include non-standard card types. Card type definitions are associative
 * arrays with the following keys:
 * - id: the machine-name for the card type.
 * - label: the label to use for the card type in the user interface.
 * - number_prefixes: an array of the number patterns and ranges at the start
 *   of numbers for this card type that identify valid card numbers.
 * - number_lengths: an array of the card number lengths this type supports.
 * - security_code_length: the length of this card type's security codes.
 * - uses_luhn: boolean indicating whether or not to attempt Luhn algorithm
 *   based number valiation on cards of this type.
 *
 * @param $card_types
 *   An array of card type definitions, keyed by card type id.
 *
 * @see CommercePaymentCreditCard::getTypes()
 */
function hook_commerce_card_type_info_alter(&$card_types) {

  // No example.
}

Functions

Name	Description
CALLBACK_commerce_payment_method_redirect_form	Payment method callback; generation callback for the payment redirect form.
CALLBACK_commerce_payment_method_redirect_form_back	Payment method callback; cancellation callback for the redirected payments.
CALLBACK_commerce_payment_method_redirect_form_submit	Payment method callback; submission callback for redirected payments.
CALLBACK_commerce_payment_method_redirect_form_validate	Payment method callback; validation callback for redirected payments.
CALLBACK_commerce_payment_method_settings_form	Payment method callback; return the settings form for a payment method.
CALLBACK_commerce_payment_method_submit_form	Payment method callback; generation callback for the payment submission form.
CALLBACK_commerce_payment_method_submit_form_submit	Payment method callback; validate callback for the payment submission form.
CALLBACK_commerce_payment_method_submit_form_validate	Payment method callback; validate callback for the payment submission form.
hook_commerce_card_type_info_alter	Alter the card types defined by the Payment module.
hook_commerce_payment_methods	Populates an order's data array with payment methods available in checkout.
hook_commerce_payment_method_info	Define payment methods available to the Commerce Payment framework.
hook_commerce_payment_method_info_alter	Alter payment methods defined by other modules.
hook_commerce_payment_order_paid_in_full	Allows you to respond when an order is first considered paid in full.
hook_commerce_payment_totals_row_info	Defines rows for use in payment totals area handlers on Views.
hook_commerce_payment_totals_row_info_alter	Allows you to alter payment totals rows.
hook_commerce_payment_transaction_delete	Allows you to act when a transaction is being deleted.
hook_commerce_payment_transaction_insert	Allows you to act when a transaction is created.
hook_commerce_payment_transaction_load	Allows you to act when transactions are being loaded.
hook_commerce_payment_transaction_presave	Allows you to prepare payment transaction data before it is saved.
hook_commerce_payment_transaction_status_info	Defines payment transaction statuses.
hook_commerce_payment_transaction_update	Allows you to act when a transaction is updated.
hook_commerce_payment_transaction_uri	Allows modules to specify a uri for a payment transaction.