Login

New to DJ-Extensions?

Creating payment plugin for DJ-Catalog2

Getting started with Joomla! plugins

Before we start, please make sure that you know the basics of building Joomla! plugins:

https://docs.joomla.org/J4.x:Creating_a_Plugin_for_Joomla

What we should know in the first place is that our plugin should belong to a group named "djcatalog2payment". For example, if the plugin is named "my_plugin" then plugin's directory and its files should be stored in:

JROOT/plugins/djcatalog2payment/my_plugin

The plugin directory should contain one PHP (plugin's class) and one XML (manifest file) files named after the name of the plugin:

JROOT/plugins/djcatalog2payment/my_plugin/my_plugin.php
JROOT/plugins/djcatalog2payment/my_plugin/my_plugin.xml
It is also recommended to place language files inside the "language" directory. In this case, the path and names would be:
JROOT/plugins/djcatalog2payment/my_plugin/my_plugin/lnnguage/en-GB/en-GB.plg_djcatalog2payment_my_plugin.ini
JROOT/plugins/djcatalog2payment/my_plugin/my_plugin/language/en-GB/en-GB.plg_djcatalog2payment_my_plugin.sys.ini

Finally, and this will be covered later in this article, you can create another XML file in the following location:

JROOT/plugins/djcatalog2payment/my_plugin/config/configuration.xml

We strongly suggest you have a look at existing plugins that are the part of DJ-Catalog2 package by default such as "Standard" and "PayPal" payment plugins.

Manifest file

The manifest file of the payment plugin is not different than a regular manifest file. It's important to remember that the "group" attribute should. Here's an example of the manifest file used in "Standard" payment plugin:

<?xml version="1.0" encoding="utf-8"?>
<extension
        type="plugin"
        version="3.0"
        client="site"
        method="upgrade"
        group="djcatalog2payment">
    <name>plg_djcatalog2payment_standard</name>
    <creationDate>March 2015</creationDate>
    <author>DJ-Extensions.com</author>
    <copyright>Copyright (C) 2010-2012 DJ-Extensions.com, All rights reserved.</copyright>
    <license> http://www.gnu.org/licenses GNU/GPL</license>
    <version>1.1</version>
    <description>PLG_DJCATALOG2PAYMENT_STANDARD_DESCRIPTION</description>
    <files>
        <filename plugin="standard">standard.php</filename>
        <filename>index.html</filename>
        <folder>language</folder>
        <folder>config</folder>
    </files>
    <config>
    </config>
</extension>

Plugin class

defined('_JEXEC') or die('Restricted access');
class plgDjcatalog2paymentStandard extends JPlugin
{
	
	protected $autoloadLanguage = true;
	
	protected function isAllowed($plgInfo, $type = 'djcatalog2payment')
	{
		// ....
	}
	
	public function onContentPrepareForm($form, $data)
	{
		// ....
	}
	
	public function onDJC2BeforeSaveOrder($context, $table, $isNew, $plgInfo)
	{
		// ....
	}
	
	public function onDJC2AfterSaveOrder($context, $table, $isNew, $plgInfo)
	{
		// ....
	}
	
	public function onDJC2CheckoutDetailsDisplay($context, $plgInfo)
	{
		// ....
	}
	
	public function onDJC2OrderDetailsDisplay($context, $order, $plgInfo)
	{
		// ....
	}
	
	public function onEmailAfterPaymentDisplay($context, $data, $plgInfo)
	{
		// ....
	}
	
	public function onDJC2PaymentProcess($context, $order, $plgInfo)
	{
		// ....
	}
	
	public function onDJC2EmailAfterPaymentDisplay($context, $order, $plgInfo)
	{
		// ....
	}
}

Methods and events

isAllowed($pluginObject, $pluginGroup)

This method allows you to determine whether your specific plugin should be allowed to be triggered in a specific context. For example, if a customer chooses a different payment method that is not controlled by your plugin then isAllowed method should return false. Usually, the following code should be sufficient in most cases:

protected function isAllowed($plgInfo, $type = 'djcatalog2payment'){
	return (bool)($plgInfo->plugin == $this->_name && $this->_type == $type);
}
  • $pluginObject - this stdClass object corresponds to payment method entity stored in #__djc2_payment_methods table.
    Resource structure:
  `name` varchar(255) NOT NULL,
  `description` text,
  `published` tinyint(4) NOT NULL,
  `plugin` varchar(255) NOT NULL,
  `price` decimal(14,4) DEFAULT NULL,
  `tax_rule_id` int(11) NOT NULL,
  `free_amount` decimal(14,4) DEFAULT NULL,
  `ordering` int(11) NOT NULL DEFAULT '0',
  `params` text,
  `access` int(11) NOT NULL DEFAULT '0',
  `countries` mediumtext,
  `postcodes` text,
  `recurring` tinyint(4) NOT NULL DEFAULT '0',
  • $type (string) - is the name of plugin group that is being triggered. Usually when group is different than "djcatalog2payment" the isAllowed method should return false.

onContentPrepareForm($form, $data)

This event is triggered in the back-end area when administrator is editing a Payment Method. It allows to provide an XML file containing set of additional fields (usually settings) that will later be renderd in payment method "settings" tab:

Below you will find a sample code:

public function onContentPrepareForm($form, $data){
	if ($form->getName() != 'com_djcatalog2.payment') {
		return;
	}
	$plugin = '';
	if (!empty($data) && !empty($data->plugin)) {
		$plugin = $data->plugin;
	} else {
		$jform = JFactory::getApplication()->input->get('jform', array(), 'array');
		if (!empty($jform) && isset($jform['plugin'])) {
			$plugin = $jform['plugin'];
		}
	}
	if ($plugin != $this->_name) {
		return true;
	}
	return $form->loadFile(dirname(__FILE__) . '/config/configuration.xml', false);
}

onDJC2BeforeSaveOrder($context, $table, $isNew, $plgInfo)

This event is triggered right before the order is stored in the database.

  • $context (string) - means the context in which method is called. When user makes the order the following context is used: com_djcatalog2.checkout.payment
  • $table (Djcatalog2TableOrders object) - the object corresponding to #__djc2_orders and #__djc2_order_items tables
  • $isNew (bool) - whether an order represents new or updated row in the database
  • $plgInfo (stdClass object) - corresponds to payment method entity stored in #__djc2_payment_methods table.

onDJC2AfterSaveOrder($context, $table, $isNew, $plgInfo)

This event is triggered right after the order is stored in the database.

  • $context (string) - means the context in which method is called. When user makes the order the following context is used: com_djcatalog2.checkout.payment
  • $table (Djcatalog2TableOrders object) - the object corresponding to #__djc2_orders and #__djc2_order_items tables
  • $isNew (bool) - whether an order represents new or updated row in the database
  • $plgInfo (stdClass object) - corresponds to payment method entity stored in #__djc2_payment_methods table. 

onDJC2CheckoutDetailsDisplay($context, $plgInfo)

This method should return a string, usually HTML formatted that displays the information about the payment. The information will appear during checkout when a customer selects payment method, e.g.:

onDJC2OrderDetailsDisplay($context, $order, $plgInfo)

  • $order (stdClass object) contains all the information about the order that can be found in #__djc2_orders and #__djc2_order_items tables.

This event is triggered when a customer opens the Order Details page which is displayed after a customer confirms the order (finishes checkout). In most cases, this method should render either a link such as the "Pay Now" button. The link should contain a very specific URL that begins the payment processing. The URL should be constructed as follows:

JRoute::_('index.php?option=com_djcatalog2&task=paymentProcess&oid='.$order->id.'&plg='.$plgInfo->plugin.'&plgid='.$plgInfo->id);
When a customer hits that link, the component will keep the record of the fact that the customer initiated the payment and after that, another plugin event (onDJC2PaymentProcess) will be triggered.

onDJC2PaymentProcess($context, $order, $plgInfo)

$order (stdClass object) contains all the information about the order that can be found in #__djc2_orders and #__djc2_order_items tables.

It is probably the most important of all the events which are triggered by DJ-Catalog2 after the checkout. The method, depending on the nature of the payment gateway you are integrating with, is used to either redirect the customer from your site to payment gateway or otherwise process payment request. At this point, you will usually need to return a string containing hidden HTML form which will automatically be posted to the payment processor.

onDJC2PaymentDiscover($context, $plgInfo)

This method is executed before onDJC2PaymentResponse() and it concerns a situation when Payment Gateway sends a notification about the status of customer's payment. This method is supposed to analyze the request from the gateway and return the ID (integer) of the order in which payment status is to be updated.

onDJC2PaymentResponse($context, $order, $model, $plgInfo)

  • $order (stdClass object) contains all the information about the order that can be found in #__djc2_orders and #__djc2_order_items tables.
  • $model (Djcatalog2ModelOrder object) model class that is responsible for saving/updating order details and the most important here - change order status with $model->changeStatus() method.

This method is actually a webhook. It is executed behind the scenes when the payment processor sends to your website a notification about the status of the payment. Here you should receive the data from the gateway, validate it, and update the status of the order using $model->changeStatus() method. The method accepts the following arguments:

changeStatus($order, $value, $notifyUser, $notifyAdmin, $statusComment = '')

where

  • $order - is the original Order object passed to a plugin
  • $value (char) - is the new status of the order, where N=new; A=accepted by the customer; P=paid; F=completed; R=rejected; W=cancelled by customer. In most cases, you will want to update the order with "P" (Paid) status and skip status change for payments which are still pending.
  • $notifyUser (bool) - whether or nor user should receive email notification about the status change
  • $notifyAdmin (bool) - whether or nor administrator should receive email notification about the status change
  • $statusComment (string) - an optional comment that will appear in the email message, next to the name of the new status

© 2023 DJ-Extensions.com. All rights reserved.