API for 3rd party Payment Gateway Integration

Implementing a Payment Gateway requires PHP knowledge and is not part of support, this documentation is written for programmers. Already available Gateways can be seen here.

Uploading an already set up payment gateway pack requires you to go to Components → Ads Factory → Settings → Payment Gateways and click on Install new item button.

The payment gateway folder and files will have to be located in [SITE_ROOT]\administrator\components\com_adsfactory\thefactory\payments\plugins\gateways\

The main folder will be named "pay_mygateway" and contain the following files:

  • controller.php (gateway logic and frontend form)
  • form.xml (the admin form)
  • logo.png (optional)


Must contain:

defined('_JEXEC') or die('Restricted access');

Then a class named after the gateway folder which extends "TheFactoryPaymentGateway" has to be created, it must also contain:

class Pay_mygateway extends TheFactoryPaymentGateway
    var $name='pay_mygateway';  //gateway name, used to load gateway parameters saved with form.xml
    var $fullname='My Payment Gateway';

controller Functions

  • getPaymentForm function is required in each gateway and must be overwritten in the class. This function contains the Gateway specific part, in it you display the Payment form specific for each Payment Processor.

    function getPaymentForm($order,$items,$urls,$shipping=null,$tax=null)
           function getPaymentForm($order,$items,$urls,$shipping=null,$tax=null)
        $model=&JModel::getInstance('Gateways','JTheFactoryModel');  //loads TheFactory gateway model
        $params=$model->loadGatewayParams($this->name);  //loads gateway parameters

Payment Form Values

$paypal_addresswebsite paypal email
$orderobject containing order data
$urlsreturn_url, cancel_url, notify_url


URL Description
return_urlThe URL where the gateway will redirect after payment is completed
cancel_urlThe URL where the gateway will redirect if payment is cancelled
notify_urlThe IPN (Instant Payment Notification) URL

  • The processIPN function is also included in the class and must be overwritten with Gateway Specific data. This function must process the Gateway IPN and return a status for the Payment in the Ads system, stored in the $paylog.

The relevant Ads payment statuses are: ok, error and manual_check. These are extension specific and should be used as they are.

  • The processTask function is the entry point for the "gateway" task of the Payments Processor controller. See the Bank Transfer gateway implementation as an example.

Any number of functions can be created depending on the Payment Processor's features and requirements, an example of such a function is the validate_ipn() used in the Pay Pal implementation. Use their specific documentation to see where something more is needed.

(!) Documentation based on Ads Factory version 4.4.0