Home » Documentation » Ubercart API

hook_payment_gateway
Function hook_payment_gateway() in uc_payment.module:
<?php
  hook_payment_gateway()
?>

Description:

Payment gateways are an essential part of the overall payment system. They bridge your Ubercart installation with a service that will actually process the payment information you receive. Some example services that do this are PayPal and Authorize.net. Every payment gateway will have a different way for you to securely submit the data you have collected from your customer to complete their payment. They will also return information based on the success or failure of the attempted payment.

hook_payment_gateway() defines payment gateways to let Ubercart know which ones are available, what payment methods they work with, and how to go about processing payments with them.

Here in the payment gateway array, you reference a method by its ID. Each payment method the gateway is able to process should have a key with the value being the name of the function that the payment system will call to process the payment. (This happens in the function uc_payment_process() in uc_payment.module.)

Every callback is expected to accept the same arguments, which are simply $order_id for the order ID that the payment is for, $amount for the amount to be paid, and $data for any necessary data passed to this function by the part of the payment method code that calls uc_payment_process(). The callback function should take care of all of the interaction with the gateway's service and log the appropriate information.

The example credit card gateway just assumes the payment completes fine. It then logs a message to the order's admin comments. Finally, it prepares the expected return value of a gateway callback, an array using the following keys and values:

Key Type Value
success bool TRUE or FALSE to report on whether or not the payment was received successfully.
comment string The comment left for the payment in the payments table. Use t().
message string The message presented to the user through the normal Drupal message system. This message is suppressed if the payment is being charged automatically in the checkout process. Use t().
uid* int The ID of the active user to be logged into the payments table. Defaults to 0.
data* mixed Any sort of data you want to pass back to be stored in the payments table. Arrays will be serialized automatically prior to insertion.
log_payment* bool TRUE or FALSE to indicate whether or not the payment should be logged for the order; defaults to TRUE. An example use case for FALSE is for authorizing a credit card but not capturing the money. Such a payment has not been completed and should not be logged for the order, but we still want to indicate whether or not the authorization was a success.
* Key is optional.

Feel free to use your callback function to call any other function you've created or need to communicate with the payment gateway's web service. It would be helpful to note that information collected and saved regarding payment can be found in the payment details array of the order object. To load the order in your callback, use:

<?php
  $order = uc_order_load($order_id);
  // Now you can access the payment details with $order->payment_details.
  drupal_set_message('<pre>'. print_r($order->payment_details, TRUE) .'</pre>');
?>

Documented payment methods will let you know what payment details are saved for that method. This is particularly useful for the credit payment method, as you will need to access to the credit card information to be able to process your order!

Return value:

Returns an array of payment gateways, which are arrays with the following keys:

Key Type Value
id string The internal ID of the payment gateway, using a-z, 0-9, and - or _.
title string The name of the payment gateway displayed to the user. Use t().
description string A short description of the payment gateway.
settings string The name of a function that returns an array of settings form elements for the gateway.
credit_txn_types array Payment gateways that process credit payments can use this optional key. Its value should be an array of constants designating which types of credit transactions the gateway accommodates. The available constants are UC_CREDIT_AUTH_ONLY, UC_CREDIT_PRIOR_AUTH, UC_CREDIT_AUTH_CAPTURE, UC_CREDIT_REFERENCE_TXN; defaults to UC_CREDIT_AUTH_CAPTURE which will authorize and capture funds all at once.

Example:
<?php
function test_gateway_payment_gateway() {
  $gateways[] = array(
    'id' => 'test_gateway',
    'title' => t('Test Gateway'),
    'description' => t('Process credit card payments through the Test Gateway.'),
    'credit' => 'test_gateway_charge',
  );
  return $gateways;
}
?>

The example callback function for the test gateway for the credit payment method is as follows:

<?php
function test_gateway_charge($order_id, $amount, $data) {
  global $user;

 

$message = t('Credit card charged: !amount', array('!amount' => uc_currency_format($amount)));
  uc_order_comment_save($order_id, $user->uid, $message, 'admin');

 

$result = array(
    'success' => TRUE,
    'comment' => t('Card charged, resolution code: 0022548315'),
    'message' => t('Credit card payment processed successfully.'),
    'uid' => $user->uid,
  );
  return $result;
}
?>