How to Create j2Store Payment Plugin

In this plugin, customers are redirected to the payment gateway to make payment, like the Paypal standard.

1. Naming of Plugin

The manifest, the primary file, the template folder of the plugin should start with the prefix "payment_". Otherwise, J2Store will not recognise the plugin as a payment plugin. For example, payment_example.

So, in the plugin folder (plg_example), there will be two files and one subfolder:

  1. payment_example.xml
  2. payment_example.php
  3. payment_example (subfolder)

Inside the folder payment_example, create another folder tmpl which contains three files:

  1. form.php
  2. prepayment.php
  3. message.php

2. Manifest File (payment_example.xml)

The manifest file follows the Joomla plugin system. The group should be j2store. The following parameters are standard in the payment plugins:

  • articleid: The ID of an article which should be displayed to the customer after the payment. It is normally a thank you article.
  • geozone_id: You can restrict the appearance of this method to a particular geozone or for all geozones.

You can create more parameters depending upon your payment gateway requirements.

3. Primary File (payment_example.php)

The payment plugin class contains three methods:

  1. _renderForm() - called at the shipping and payment step
  2. _prePayment() - called at the last checkout step
  3. _postPayment() - called after the payment is made

It should extend the J2StorePaymentPlugin class. For example,

defined('_JEXEC') or die;
require_once (JPATH_ADMINISTRATOR.'/components/com_j2store/library/plugins/payment.php');
class plgJ2StorePayment_example extends J2StorePaymentPlugin
{
 // IMPORTANT. The following variable identifies the plugin to j2store
 var $_element = 'payment_example';
 
 protected $autoloadLanguage = true;
 
 // Prepares variables for the payment form.
 // Displayed when customer selects the method in Shipping and Payment step of Checkout
 function _renderForm($data)
 {

 }
 
 // Display a Place order button either to redirect the customer or process the credit card information
 // $data array form post data
 function _prePayment($data)
 {
 
 }
 
 // Processes the payment form and returns HTML to be displayed to the user generally with a success/failed message
 function _postPayment($data)
 {
 
 }
}

1. Shipping and Payment step

When customer chooses a payment method, then you have the option to display a short message or instruction or a credit card form.

// Prepares variables for the payment form.
 // Displayed when customer selects the method in Shipping and Payment step of Checkout
 function _renderForm($data)
 {
 $user = JFactory::getUser();
 $vars = new JObject();
 $vars->onselection_text = $this->params->get('onselection', 'You will be redirected to payment gateway.');
 
 //if this is a direct integration, the form layout should have the credit card form fields.
 $html = $this->_getLayout('form', $vars);
 
 return $html;
 }

The _getLayout method will call the template layout file (form.php) from the payment_example/tmpl/ folder. It accepts a second argument, which can be an object or array. You can pass any data into the second argument which can be used in the form.php file.

With the _getLayout method, you can use template overrides. So, users can override the layout without editing the core file.

2. Redirect customer to Payment Gateway

When customer reaches this step, the order is saved. You will have an order id.

// Display a Place order button either to redirect the customer or process the credit card information
 // $data array form post data
 function _prePayment($data)
 {
 $uri = JUri::getInstance();
 
 // Get component params
 $params = J2Store::config();
 $currency = J2Store::currency();
 
 // Prepare the payment form
 $vars = new JObject();
 $vars->order_id = $data['order_id'];
 $vars->orderpayment_id = $data['orderpayment_id'];
 $vars->orderpayment_amount = $data['orderpayment_amount'];
 $vars->orderpayment_type = $this->_element;
 
 $vars->api_key = $this->params->get('api_key');
 $vars->auth_token = $this->params->get('auth_token');
 
 $vars->display_name = $this->params->get('display_name');
 $vars->onbeforepayment_text = $this->params->get('onbeforepayment');
 $vars->button_text = $this->params->get('button_text', 'J2STORE_PLACE_ORDER');
 
 F0FTable::addIncludePath(JPATH_ADMINISTRATOR . '/components/com_j2store/tables');
 $order = F0FTable::getInstance('Order', 'J2StoreTable')->getClone();
 $order->load(array('order_id' => $data['order_id']));
 $currency_values = $this->getCurrency($order);

$vars->currency_code = $currency_values['currency_code'];
 $vars->orderpayment_amount = $currency->format($order->order_total, $currency_values['currency_code'], $currency_values['currency_value'], false);

$return_url = $uri->root() . JRoute::_("index.php?option=com_j2store&view=checkout&task=confirmPayment&orderpayment_type=" . $this->_element . "&paction=display");
 $cancel_url = $uri->root() . JRoute::_("index.php?option=com_j2store&view=checkout&task=confirmPayment&orderpayment_type=" . $this->_element . "&paction=cancel");
 $callback_url = $uri->root() . "index.php?option=com_j2store&view=checkout&task=confirmPayment&orderpayment_type=" . $this->_element . "&paction=callback&tmpl=component";
 
 $vars->callback_url = $callback_url;
 
 $orderinfo = $order->getOrderInformation();

$vars->invoice = $order->getInvoiceNumber();

$html = $this->_getLayout('prepayment', $vars);
 return $html;
 }

Normally, you have to supply the following urls:

  • Return url: Where to return customers after payment is made.
  • Cancel url: Where to return customers when they cancel.
  • Callback (or notification): Where to send the callback (when payment is made).

For all these urls, you can use the confirmPayment task in the checkouts.php controller. There the two parameters in the URL:

  1. orderpayment_type - the name of the payment plugin.
  2. paction - an action to perform in the postPayment wrapper.

3. After payment is made

When the customer clicks place order, they are either re-directed to the payment gateway or to the confirmPayment method in checkout (controller). The confirmPayment method triggers the postPayment event.

You can use a switch to serve different purposes.

// Processes the payment form and returns HTML to be displayed to the user generally with a success/failed message
 function _postPayment($data)
 {
 // Process the payment
 $app = JFactory::getApplication();
 $paction = $app->input->getString('paction');

$vars = new JObject();

switch ($paction)
 {
 case "display":
 $vars->message = 'Thank you for the order.';
 $html = $this->_getLayout('message', $vars);
 // Get the thank you message from the article (ID) provided in the plugin params
 $html .= $this->_displayArticle();
 break;
 
 case "callback":
 // It is a call back. You can update the order based on the response from the payment gateway
 $vars->message = 'Redirect to the payment gateway';
 
 // Process the response from the gateway
 $this->_processSale();
 
 $html = $this->_getLayout('message', $vars);
 echo $html; 
 $app->close();
 break;
 
 case "cancel":
 // Cancel is called. 
 $vars->message = 'Sorry, you have cancelled the order';
 $html = $this->_getLayout('message', $vars);
 break;
 
 default:
 $vars->message = 'Seems an unknow request.';
 $html = $this->_getLayout('message', $vars);
 break;
 }

return $html;
 }

4. Process Sale

If the payment is successful, you should call the following methods:

  1. $order->payment_complete();
  2. $order->empty_cart();

If you want to update the status of order, you can call the following method:

  1. $order->update_status($order_status_id, $notify_customer);

Here, the $order_status_id is the status to which the order to be set. You can get the ID of the order status from J2Store -> Localisation -> Order statuses.
 
The $notify_customer is a Boolen value whether to notify the customer or not about the update to the order.

4. Form (form.php)

In the redirect method, it will display message on selection of the payment method. For example:

defined('_JEXEC') or die;

echo JText::_($vars->onselection_text);

5. Payment Link (prepayment.php)

This file is used to display payment link or place order button. On clicking it, the customer will be redirected to the payment gateway.