What is a Payment Gateway Integration?

Ads Factory has an embedded engine of administrating Payment Processor Parameters and interaction with payments of ads related items. Each Gateway is conceived as a plugin automatically loaded if configured. All Payment Gateways Plugins are stored in the components/com_adsman/plugins/payment/ and they are all extending the payment_object generic gateway. In the Ads Factory 1.5.8 installation are included payment gateways plugins for PayPal, Moneybookers and 2checkout.
A plugin for gateway Example can include the files:
pay_example.php
pay_example.en.php
pay_example.notify.php
External js,css or images are optional to design matters.

How do I create one gateway plugin?

First we create the php file containing the Payment Gateway processing Class. The file and the class must be named identically (of course the file must have a .php extension) having the name prefixed by `pay_`. ( a plugin for gateway Example must have the class name pay_example and the file name pay_example.php ).
For start the file should contain the following:

	< ?php
// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );
define('EXAMPLE_LOG',0);

require_once(ADS_COMPONENT_PATH."/plugins/payment/payment_object.php");

class pay_example extends payment_object{
var $_db=null;
var $classname="pay_example";
var $classdescription="Example Payment method";

var $ipn_response=null;
var $action=null;

function pay_example(&$db){

parent::payment_object($db);
$this->action="PAYMENT URL OF THE GATEWAY";

}

function ipn($d){
// TO DO
}
function show_admin_config()
{
// TO DO
}
function save_admin_config()
{
// TO DO
}
function show_payment_form($order_id,$item_description,$itemname,$quantity,$price,$currency,$return_url=null)
{
// TO DO
}

function log_ipn_results($success) {
if (!EXAMPLE_LOG) return; // is logging turned off?

}

function validate_ipn()
{
// TO DO
}
function getLogo()
{
}

}

function ipn($d)
processes the Gateway IPN (the $d param will be an array with the request values - $_REQUEST).

show_payment_form($order_id,$item_description,$itemname,$quantity,$price,$currency,$return_url=null)
this function MUST be overwritten. It is the Gateway specific part. Here you display the HTML needed for the payment form. Specific to each Payment processor. Parameters are:
$order_id – unique identifier for the transaction.
$item_description – the description of the product (payment item) the user is paying for. You should display this in order to confirm this with the user.
$itemname – this is the PAYMENT ITEM internal name. YOU have to pass it on, so that it gets back per IPN. If no IPN is needed, then you can ignore it.
$quantity – the amount of item the user purchases; most time it is one.
$price – the item price.
$currency – the currency you set up in payment item admin.
$return_url – the url to pass the gateway as return url after payment was processed. (IT IS NOT THE IPN URL).


show_admin_config()

* this function MUST be overwritten. It displays the ADMIN form for configuring the Processor. For instance you can ask the moneybookers email.
* very important- the form must look like this:

[HERE YOUR CUSTOM VARIABLES]



save_admin_config()

* in this function you save the variables from the config form in the database.
* you must use the PARAMS field of the #__ads_paysystems table in the row for your payment system (where classname='$this->classname')
* We recommend to format the parameters like standard joomla parameters (variablename=value\n)
* Have a look at the Moneybookers class to see an example.


getLogo()

* overwrite this if you want to place the Processor logo somewhere else then in
/plugins/payment/{$this->classname}.gif or /plugins/payment/{$this->classname}.png or /plugins/payment/{$this->classname}.jpg
* you can specify an external image.

For payment gateways with IPN APIs you must create the pay_example.notify.php file and you can use one of the existent gateways as example.

Install and ready to go

After creating and copying the files in the components/com_adsman/plugins/payment/ directory you must create a database record in the `#__ads_paysystems` table and ready for configuration and paying.

Revised "Ads Factory" version 1.5.8.