Payment plugin
- Introduction
- Plugin Structure
- Naming conventions
- The Manifest
- Creating the primary payment plugin class
- Display payment method in checkout
- Prepare to redirect to payment gateway or to process payment
- After payment is made
Introduction
Creating a payment plugin for J2Store is fairly a simple process if you are good in PHP and the Joomla MVC structure.
J2Store comes with a Payment library and wrappers that makes creating a plugin a breather. Integrations offered by different payment gateways can be broadly classified into two types
1.Redirect (also called Form, hosted, off-site) : Customer will be redirected to the payment gateway to make payment, like the Paypal standard. 2.Direct: Customer will enter the credit card information in your site and stay in your site. Payment will be processed in the background using a cURL request.
So, before diving into the coding, you should first decide which type of integration are you going to make.
Most payment gateways provide both these types, while some gateways only provide you with a Redirect method.
Plugin Structure
There is a folder structure and a few naming conventions, that should be followed during the development of a payment plugin for J2Store.
A typical payment plugin should look like this:
1
├── plg_example/
2
│ ├── payment_example.php
3
│ ├── payment_example.xml
4
│ │ ├── payment_example/
5
│ │ ├── tmpl/
6
│ │ │ ├── form.php
7
│ │ │ ├── prepayment.php
8
│ │ │ ├── message.php
Copied!
Naming conventions
The manifest, the primary file, the template folder of the plugin should be start with the prefix ”payment_”. Otherwise, J2Store will not recognise your plugin as a payment plugin. So our example plugin is named as: payment_example
Make sure that the name of the file is in lower case and there are no spaces or any other characters in the file name.##The Manifest
The plugin’s manifest should follow the joomla plugin creation basics.An example manifest should look like this:
1
<?xml version="1.0" encoding="utf-8"?>
2
<extension version="2.5" type="plugin" group="j2store" method="upgrade">
3
<name>Example</name>
4
<version>1.0</version>
5
<creationDate>June 2015</creationDate>
6
<author>J2Store</author>
7
<authorEmail>[email protected]</authorEmail>
8
<authorUrl>http://www.j2store.org</authorUrl>
9
<copyright>2015 Example Company</copyright>
10
<license>GNU General Public License v3 or later versions</license>
11
<description>Description of your plugin </description>
12
13
<files>
14
<filename plugin="payment_example">payment_example.php</filename>
15
<filename>index.html</filename>
16
<folder>payment_example</folder>
17
</files>
18
<languages>
19
<language tag="en-GB">languages/en-GB.plg_j2store_payment_example.ini</language>
20
</languages>
21
<config>
22
<fields name="params">
23
<fieldset name="basic">
24
25
<field
26
name="articleid"
27
type="text"
28
size="10"
29
default=""
30
label="j2store_thanks_msg"
31
description="j2store_thanks_msg_desc"
32
/>
33
34
<field
35
name="geozone_id"
36
type="geozonelist"
37
default=""
38
label="J2STORE_GEOZONE"
39
description="J2STORE_GEOZONE_DESC"
40
addfieldpath="/administrator/components/com_j2store/models/fields"
41
/>
42
</fieldset>
43
</fields>
44
</config>
45
</extension>
Copied!
Also refer the manifest of the Paymill plugin that comes built in with the J2Store package.
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. Normally a thank you article.
geozone_id: Store owner can restrict the appearance of this method to a particular geozone or for all geozones.
You can create more parameters depending upon your gateway requirements. Refer the plugins that come with the J2Store package.
Creating the primary payment plugin class: payment_example.php
The payment plugin class should essential have 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
Let us start creating the file.
Make sure the name of the class suffix is same as your plugin file’s name. And it should extend the J2StorePaymentPlugin class.
1
defined('_JEXEC') or die('Restricted access');
2
require_once (JPATH_ADMINISTRATOR.'/components/com_j2store/library/plugins/payment.php');
3
class plgJ2StorePayment_example extends J2StorePaymentPlugin
4
{
5
//IMPORTANT. The following variable identifies the plugin to j2store
6
var $_element = 'payment_example';
Copied!
As mentioned earlier, a payment plugin is triggered in three places in the Checkout steps (for different purposes). Let us go one by one based on their purpose.
1.Shipping and Payment step
The plugin will be listed in this step. When customer chooses your payment method, then you have the option to display a short message / instruction or a credit card form. The best use case is the display of a credit card form.
Use the following wrapper to display a form or a short message.
1
function _renderForm( $data )
2
{
3
$html =
Payment plugin - J2Store Documentation
this->_getLayout('form', $v`ars);
4
return $html;
5
}
Copied!
The _getLayout method will call the template / layout file (form.php) from the payment_example/tmpl/ folder.
The _getLayout method is actually a glorified include and 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
The beauty of the _getLayout method is that it will respect the template overrides. So users can override the layout without editing the core file.
2.Prepare to redirect customer to the gateway or to process payment at the Order summary step (Last step of the checkout)
When customer reaches this step, the order will be saved. And you will have an order id.
The following wrapper method is executed and it returns normally a Place order button (may be a hidden form). Check the Paymill plugin or the cash on delivery plugin.
1
function _prePayment( $data )
2
{
3
$vars = new stdClass();
4
$vars->callback_url = JUri::root().'/index.php?option=com_j2store&view=checkout&task=confirmPayment&orderpayment_type=payment_example&paction=callback';
5
$html = $this->_getLayout('prepayment', $vars);
6
return $html;
7
}
Copied!
3.After payment is made
When 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 ( which serves multiple purposes. For example, 1. Callback 2. To get a thank you article and display it to the customer)
Here is a sample code for the _postPayment wrapper
1
function _postPayment( $data )
2
{
3
// Process the payment
4
$app = JFactory::getApplication();
5
$paction = $app ->input->getString('paction');
6
7
$vars = new JObject();
8
9
switch ($paction)
10
{
11
case "display":
12
$vars->message = 'Thank you for the order.';
13
$html = $this->_getLayout('message', $vars);
14
//get the thank you message from the article (ID) provided in the plugin params
15
$html .= $this->_displayArticle();
16
break;
17
case "callback":
18
//Its a call back. You can update the order based on the response from the payment gateway
19
$vars->message = 'Some message to the gateway'
20
$html = $this->_getLayout('message', $vars);
21
echo $html;
22
$app->close();
23
break;
24
case "cancel":
25
//cancel is called.
26
$vars->message = 'Sorry, you have cancelled the order'
27
$html = $this->_getLayout('message', $vars);
28
break;
29
default:
30
$vars->message = 'Seems an unknow request.'
31
$html = $this->_getLayout('message', $vars);
32
break;
33
}
34
35
return $html;
36
}
Copied!
As you can see, we use a switch to serve different purposes.
In redirect methods, you will normally be asked to supply the following urls
1
Return url : Where to return customers after payment is made
2
Cancel url : Where to return customers when they cancel
3
Callback (or notification): Where to send the callback (when payment is made)
Copied!
For all these three, you can use the confirmPayment task (in the checkouts.php controller)
An example url would look like:
index.php?option=comj2store&view=checkout&task=confirmPayment&orderpaymenttype=payment_example&paction=display
Notice the two parameters here:
1
orderpayment_type = the name of the payment plugin
2
paction = an action to perform in the postPayment wrapper.
Copied!
If you are integrating the direct (credit card) method, then refer the Paymill or the sagePay plugins in the j2store package for more information
A complete payment plugin class will look like the following
1
loadLanguage('', JPATH_ADMINISTRATOR);
2
}
3
4
5
/**
6
* Prepares variables for the payment form.
7
* Displayed when customer selects the method in Shipping and Payment step of Checkout
8
*
9
* @return unknown_type
10
*/
11
function _renderForm($data)
12
{
13
$user = JFactory::getUser();
14
$vars = new JObject();
15
$vars->onselection_text = 'You have selected this method. You will be redirected.';
16
//if this is a direct integration, the form layout should have the credit card form fields.
17
$html = $this->_getLayout('form', $vars);
18
19
return $html;
20
}
21
22
/**
23
* Method to display a Place order button either to redirect the customer or process the credit card information.
24
* @param $data array form post data
25
* @return string HTML to display
26
*/
27
function _prePayment($data)
28
{
29
// get component params
30
$params = J2Store::config();
31
$currency = J2Store::currency();
32
33
// prepare the payment form
34
35
$vars = new JObject();
36
$vars->order_id = $data['order_id'];
37
$vars->orderpayment_id = $data['orderpayment_id'];
38
39
F0FTable::addIncludePath(JPATH_ADMINISTRATOR . '/components/com_j2store/tables');
40
$order = F0FTable::getInstance('Order', 'J2StoreTable')->getClone();
41
$order->load(array('order_id' => $data['order_id']));
42
$currency_values = $this->getCurrency($order);
43
44
$vars->currency_code = $currency_values['currency_code'];
45
$vars->orderpayment_amount = $currency->format($order->order_total, $currency_values['currency_code'], $currency_values['currency_value'], false);
46
47
48
$return_url = $rootURL . JRoute::_("index.php?option=com_j2store&view=checkout&task=confirmPayment&orderpayment_type=" . $this->_element . "&paction=display");
49
$cancel_url = $rootURL . JRoute::_("index.php?option=com_j2store&view=checkout&task=confirmPayment&orderpayment_type=" . $this->_element . "&paction=cancel");
50
$callback_url = JURI::root() . "index.php?option=com_j2store&view=checkout&task=confirmPayment&orderpayment_type=" . $this->_element . "&paction=callback&tmpl=component";
51
52
$orderinfo = $order->getOrderInformation();
53
54
$vars->invoice = $order->getInvoiceNumber();
55
56
$html = $this->_getLayout('prepayment', $vars);
57
return $html;
58
}
59
60
/**
61
* Processes the payment form
62
* and returns HTML to be displayed to the user
63
* generally with a success/failed message
64
*
65
* @param $data array form post data
66
* @return string HTML to display
67
*/
68
function _postPayment($data)
69
{
70
// Process the payment
71
$app = JFactory::getApplication();
72
$paction = $app->input->getString('paction');
73
74
$vars = new JObject();
75
76
switch ($paction) {
77
case "display":
78
$vars->message = 'Thank you for the order.';
79
$html = $this->_getLayout('message', $vars);
80
//get the thank you message from the article (ID) provided in the plugin params
81
$html .= $this->_displayArticle();
82
break;
83
case "callback":
84
//Its a call back. You can update the order based on the response from the payment gateway
85
$vars->message = 'Some message to the gateway'
86
//process the response from the gateway
87
$this->_processSale();
88
$html = $this->_getLayout('message', $vars);
89
echo $html;
90
$app->close();
91
break;
92
case "cancel":
93
//cancel is called.
94
$vars->message = 'Sorry, you have cancelled the order'
95
$html = $this->_getLayout('message', $vars);
96
break;
97
default:
98
$vars->message = 'Seems an unknow request.'
99
$html = $this->_getLayout('message', $vars);
100
break;
101
}
102
103
return $html;
104
}
105
106
107
/**
108
* Processes the sale payment
109
*
110
*/
111
private function _processSale()
112
{
113
114
$app = JFactory::getApplication();
115
$data = $app->input->getArray($_POST);
116
117
//get the order id sent by the gateway. This may differ based on the API of your payment gateway
118
$order_id = $data['YOUR_PAYMENT_GATEWAY_FIELD_HOLDING_ORDER_ID'];
119
120
// load the orderpayment record and set some values
121
$order = F0FTable::getInstance('Order', 'J2StoreTable')->getClone();
122
123
if ($order->load(array('order_id' => $order_id))) {
124
125
$order->add_history(JText::_('J2STORE_CALLBACK_RESPONSE_RECEIVED'));
126
127
//run any checks you want here.
128
//if payment successful, call : $order->payment_complete ();
129
130
131
132
// save the data
133
if (!$order->store()) {
134
$errors[] = $order->getError();
135
}
136
//clear cart
137
$order->empty_cart();
138
}
139
140
return count($errors) ? implode("\n", $errors) : '';
141
}
Copied!
If the payment is successful, you should call the following method
1
$order->payment_complete();
2
$order->empty_cart();
Copied!
If you want to update the status of order, you can call the following method
1
$order->update_status($order_status_id, $notify_customer);
Copied!
1
$order_status_id = The status to which the order to be set.
2
You can get the ID of the order status from J2Store -> Localisation -> Order statuses.
3
4
$notify_customer = a Boolen value. Whether to notify the customer or not about the update to the order.
Copied!
Next steps
Successfully created the payment gateway ? Well you can share it with other J2Store users via our Extensions Directory. Contact us to get your plugin listed for sale (or for free distribution).
Last modified 1yr ago