This document details the interface provided by payment gateway objects, and is intended to serve as a guide for the creation of new payment gateways.

Starting with version 0.5.0, the payment gateway is modular. Each gateway has a short name, referenced here as gw_name, and consists of three parts:

• gw_name.class.php, located in private/plugins/paypal/classes/gateways. Handles all payment functions.
• gw_name_ipn.php, located in public_html/paypal/ipn. Handles IPN messages.
• gw_name_language.php, located in private/plugins/paypal/language. Provides language strings.

The actual payment gateway is gw_name.class.php. The class must be named gw_name and must extend class PaymentGw.

/** Import base gateway class */
USES_paypal_gateway();

class gw_name extends PaymentGw { ...

Several functions are expected to be available from the gateway, either defined by the gateway or inherited from the PaymentGw class.

The cart items array is an associative array of item_id⇒item_info elements.

$cartItems = array(
    'item_id_1' => array(
        'item_name' => {item name or short description},
        'quantity' => {quantity of items},
        'price' => {unit price},
        'options' => array({array of item option values}),
        'shipping' => {per-item shipping amount},
        'weight' => {per-item shipping weight},
    ),
    'item_id_2' => array(...
    ),
);

“item_id_1” and “item_id_2” refer to the actual item ID. This may be an integer for a catalog item or a string if the item is provided by another plugin.

This function needs to iterate through the $cartItems array and prepare the order button. Both the buyer's user ID, even if Anonymous, and the $cartID value should be added to the “custom” array to be passed through to the IPN handler.

$custom_arr

Creates the checkout button for a shopping cart. This function receives the cart ID and an array of cart items, and must set the necessary form variables for a cart upload or checkout button.

inter-plugin communications are handled by web service functions in services.inc.php. The format of the function call is

$status = PLG_invokeService('paypal', 'ServiceName', $args, $output, $svc_msg);

The returned value will be one of the constants defined in lib-plugins.php, such as PLG_RET_OK or PLG_RET_ERROR. The value will be returned in $output and may be an array or a scalar value.

The $args parameter is normally an array and its values will depend on the service being invoked.

Purchase buttons for external items are created by calling PLG_invokeService('paypal', 'genButton', $args, $output, $svc_msg). The $args parameter should be an array and should contain the following name⇒value pairs:

The $output variable is an array of buttons, containing the requested button type (“buy_now”, “pay_now”, etc.) and/or an add_cart element:

$output = array(
    'buy_now' => "Buy Now" button code,
    'add_cart' => "Add to Cart" button code
);

Example:

$args = array(
    'btn_type' => 'donation',
    'item_number' => 'donation:2238746',
    'item_name' => 'Donation to the Food Drive',
    'amount' => 10,
    'quantity' => 1
);
$status = PLG_invokeService('paypal', 'genButton', $args, $output, $svc_msg);
if ($status == PLG_RET_OK) {
    $button_code = $output['buy_now'];
} else {
    $button_code = '';
}

A service function is available to return the configured currency as a short string (“USD”, “CAD”, “GBP”). In this case the $args parameter is not used and $output contains a string.

$status = PLG_invokeService('paypal', 'getCurrency', $args, $output, $svc_msg);
$currency = $status == PLG_RET_OK ? $output : 'Unknown';

For an external plugin to get a URL to a page controlled by the PayPal plugin, the getUrl service can be invoked. Currently the only URL available is for a specific IPN transaction so that another plugin can link to the transaction by which it was paid.

  $args = array(
      'type' => 'ipn',    // the only type currently supported
      'id' => $ipn_txn_id
  );
  $status = PLG_invokeService('paypal', 'getUrl', $args, $output, $svc_msg);
  if ($status == PLG_RET_OK) {
      $url = $output;
      // something like "http://yoursite.com/paypal/index.php?view=ipnlog&op=single&txn_id=29384857"
  }

Plugins wishing to interact with the PayPal plugin must provide some service functions of their own.

Sets the $output variable to an array of values describing the plugin's product. The full product ID is already known to the Paypal plugin, and is provided in the $args parameter as an array:

$args = array($plugin_name, $item_id);

The plugin's service_productinfo_X() function then creates the $output value:

$output = array(
    'product_id' => implode(':', $args),
    'name' => $item_name,
    'short_description' => $item_description
    'description' => $item_full_description,
    'price' => $unit_price,
);

The description is optional, but all other fields should be defined.

This function is called by the payment gateway's IPN processor and handles the actual purchase. The $args array is populated with information from the IPN message in two parts: 'item' contains item information while 'ipn_data' contains the full IPN message. The $output variable should be populated with information similar to service_productinfo_piName, but with a bit more detail.

$item = $args['item'];
$ipn_data = $args['ipn_data'];
 
$item_id = explode(':', $item['item_id']);  // split id into plugin name and item ID
$sql = {query to retrieve an item}
$A = DB_fetchArray(DB_query($sql), false);
$output = array('product_id' => $item['item_id'],
    'name' => $A['name'],
    'short_description' => $A['name'],
    'description' => $A['description'],
    'price' =>  (float)$A['price'],
    // The rest are needed only for file download items:
    'expiration' => NULL,
    'download' => 0,
    'file' =>''
);

Detail of the 'item' element of the $args array:

Notifications are received via Instant Payment Notification. The return URL is specified with the button code from PAYPAL_genButton(). The notification variables are based on PayPal's IPN structure, so other gateways should convert their variable names to PayPal's. These are the variables that are used.