Building a payment gateway plugin

From Sohowiki
Jump to: navigation, search

Page under construction. Steps I (Mike M) went through to teach a guy (Brad R) how to build a payment gateway plugin.


Notes on terms used in this article

The owner of the website that will be installing your payment gateway plugin
The webmaster's customer/website visitor who is purchasing something from the webmaster's website and paying for it via the payment gateway your plugin enables.

What type of gateway is it?

There are generally two types of credit card gateways in terms of how they process payments. Which type is yours?

On-site gateway
Visitor selects the "pay with credit card" option and is presented with a form (on webmaster's website) where he fills-in his credit card number, etc. On submission of the form the card data is passed to the payment gateway "behind the scenes", results are returned instantly, and customer is directed accordingly (failure page or final invoice on success).
Off-site gateway
Visitor is directed to payment gateway's portal site to complete payment, then sent back (along with order result data) to webmaster's website for final order processing.

The four components of a payment gateway

Note: This article currently based on off-site gateways. The process for adding an on-site gateway is mostly the same except there's an extra (fifth) component (the actual form where they fill in their card info), and the pass order data/get result return process works a little differently.

  1. payment_options.php - Place in sitebuilder admin tool where webmaster fills-in gateway account id and whatever other data is required by the gateway, and can choose your gateway as the primary credit card processor to be used in his website checkout process.
  2. pgm-checkout.php - Outputs payment option choices to website visitor based on what webmaster sets in Payment Options
  3. pgm-payment_gateway.php - Passes the checkout order data to the gateway.
  4. pgm-show_invoice.php - Catches response from gateway and directs website customer accordingly to final invoice (on success) or failure page if payment attempt did not succeed (e.g., because of declined credit card, etc.).


All of the neccessary additions to the Payment Options screen can be accomplished by attaching to 4 pre-defined hook locations.

  1. payment_options.php:pay_types - Simple, one-line include where you define a code that will identify your gateway in various places.
  2. payment_options.php:config_form - The include file you attach to this hook should contain the HTML for the config form. This is the form field(s) where the user fills-in his merchant id (or whatever) for your your gateway.
  3. payment_options.php:save_gateway_config_info - Lines of code that store submitted config form info in database somewhere.
  4. payment_options.php:gateway_checkbox - HTML table row containing checkbox field and label for your gateway, so webmaster will be able to select it as an available payment option.


  1. Add condition check to output hidden PAY_TYPE form/field if your gateway is set as the primary credit card processor in Payment Options
  2. Add check for your gateway to condition that determines whether to show credit/debit card payment option to website visitor if one of the defined (checked for) credit card gateways is choosen in Payment Options.


Working example: eTelegate

Install Manifest

Here is what the install_manifest.php file looks like for the eTelegate payment gateway plugin.

$plugin_folder = "etelegate";
$plugin_title = "eTelegate Payment Gateway";
$plugin_version = "1.1";
$plugin_author = ", Inc.";
$plugin_homepage = "";
$plugin_icon = "plugin_icon.gif";
$plugin_options_link = "../../program/modules/mods_full/shopping_cart/payment_options.php";

# Description text
$plugin_description = "Use the eTelegate payment gateway to accept online credit card payments from your shopping cart customers.";

# payment_options.php
hook_attach("payopts-save_gateway_config_info.php", "payment_options.php:save_gateway_config_info");
hook_attach("payopts-pay_types.php", "payment_options.php:pay_types");
hook_attach("payopts-gateway_checkbox.php", "payment_options.php:gateway_checkbox");
hook_attach("payopts-config_form.php", "payment_options.php:config_form");

# pgm-checkout.php
hook_replace("shopping/pgm-checkout.php", "checkout-cc_img_form.php");
hook_replace("sohoadmin/client_files/shopping_cart/pgm-checkout.php", "checkout-cc_img_form.php");
hook_attach("checkout-pay_button.php", "pgm-checkout.php:gateway_button");

# pgm-payment_gateway.php
hook_attach("paygate-plugin_paytypes.php", "pgm-payment_gateway.php:plugin_paytypes");
hook_attach("pgm-payment_gateway-catch.php", "pgm-payment_gateway.php:gateway_submit");

# pgm-show_invoice.php
hook_attach("showinv-gateway_catch.php", "pgm-show_invoice.php:gateway_catch");
Personal tools