Project

General

Profile

Payment Plugins » History » Version 1

Max Milbers, 07/07/2011 02:11 PM

1 1 Max Milbers
h1. Payment Plugins
2
Payment plugins are used both in the front-end and the backend. They must be created as classes deriving from the base class *vmPaymentPlugin*:
3
4
5
<pre><code class="php">
6
class plgVmPayment<myPlugin> extends vmPaymentPlugin {
7
	function plgVmPayment<myPlugin>(&$subject, $config) {
8
		$this->_pelement = basename(__FILE__, '.php');	// Required!
9
		$this->_createTable();				// Required, see below
10
		parent::__construct($subject, $config);
11
	}
12
}
13
</code></pre>
14
15
Below is the list with events and a description on what moment they are fired.
16
* *plgVmOnSelectPayment()* - This event is fired during the checkout process. It allows the shopper to select one of the available payment methods.
17
It should display a radio button (name: paym_id) to select the payment method. Other information (like credit card info) might be selected as well, depending on the plugin.
18
+Return:+
19
It must return the HTML code for displaying the form (radio button and optional extra selections).
20
+Parameters:+
21
# (VirtueMartCart object) The cart object 
22
# (integer, default 0) ID of an already selected payment method ID, if any
23
24
* *plgVmOnPaymentSelectCheck()* - This event is fired after the payment method has been selected. It can be used to store
25
additional payment info in the cart.
26
+Return:+
27
Plugins that were not selected must return null, otherwise True of False must be returned indicating Success or Failure.
28
+Parameters:+
29
# (VirtueMartCart object) The cart object 
30
31
32
33
* *plgVmOnCheckoutCheckPaymentData()* - This event is fired during the checkout process. It can be used to validate the payment data as entered by the user.
34
+Return:+
35
Plugins that were not selected must return null, otherwise True of False must be returned indicating Success or Failure.
36
+Parameters:+
37
None
38
39
* *plgVmOnConfirmedOrderStorePaymentData()* - This event is fired after the payment has been processed; it stores the payment method-specific data.
40
All plugins _must_ reimplement this method.
41
+Return:+
42
If the plugin is NOT actually executed (not the selected payment method), this method must return NULL
43
If this plugin IS executed, it MUST return the order status code that the order should get. This triggers the stock updates if required
44
+Parameters:+
45
# (integer) The ordernumber being processed
46
# (object) Data from the cart
47
# (array) Price information for this order
48
	
49
* *plgVmOnShowOrderPaymentBE()* - This method is fired when showing the order details in the backend. It displays the the payment method-specific data.
50
All plugins _must_ reimplement this method.
51
+Return:+
52
Null when for payment methods that were not selected, text (HTML) otherwise
53
+Parameters:+
54
# (integer) The order ID
55
# (integer) Payment method used for this order
56
57
* *plgVmOnCancelPayment()* - This event is fired each time the status of an order is changed to Cancelled. It can be used to refund payments, void authorization etc.
58
When reimplementing this methis, the body _must_ start with this code:
59
<pre><code class="php">$_paymethodID = $this->getPaymentMethodForOrder($_orderID);
60
if (!$this->selectedThisMethod($this->_pelement, $_paymethodID)) {
61
	return;
62
}</code></pre>
63
+Parameters:+
64
 (integer The order ID
65
 (char) Previous order status
66
 (char) New order status
67
68
* *plgVmOnShipOrderPayment()* - This event is fired when the status of an order is changed to Shipped. It can be used to confirm or capture payments
69
When reimplementing this methis, the body _must_ start with this code:
70
<pre><code class="php">$_paymethodID = $this->getPaymentMethodForOrder($_orderID);
71
if (!$this->selectedThisMethod($this->_pelement, $_paymethodID)) {
72
	return;
73
}</code></pre>
74
+Return:+
75
True on success, False on failure, Null if this plugin was not activated
76
+Parameters:+
77
# (integer) Order ID
78
79
Other helper functions inherited from the base class:
80
81
* *_ createTable()* - This method is used to create and maintain the plugin specific database table(s).
82
It _must_ be reimplemented by all plugins.
83
+Example:+
84
<pre><code class="php">
85
$_scheme = DbScheme::get_instance();
86
$_scheme->create_scheme('#__vm_order_payment_'.$this->_pelement);
87
$_schemeCols = array(
88
	 'id' => array (
89
			 'type' => 'int'
90
			,'length' => 11
91
			,'auto_inc' => true
92
			,'null' => false
93
	)
94
	,'order_id' => array (
95
			 'type' => 'int'
96
			,'length' => 11
97
			,'null' => false
98
	)
99
	,'payment_method_id' => array (
100
			 'type' => 'text'
101
			,'null' => false
102
	)
103
);
104
$_schemeIdx = array(
105
	 'idx_order_payment' => array(
106
			 'columns' => array ('order_id')
107
			,'primary' => false
108
			,'unique' => false
109
			,'type' => null
110
	)
111
);
112
$_scheme->define_scheme($_schemeCols);
113
$_scheme->define_index($_schemeIdx);
114
if (!$_scheme->scheme()) {
115
	JError::raiseWarning(500, $_scheme->get_db_error());
116
}
117
$_scheme->reset();
118
</code></pre>
119
120
* *getPaymentMethodForOrder()* - Get the order payment ID for a given order number
121
+Return:+
122
The payment method ID, or -1 when not found 
123
+Parameters:+
124
# (integer) The order ID
125
126
* *getThisMethodName()* - Get the name of the payment method.
127
This method can _not_ be reimplemented
128
+Return:+
129
Paymenent method name
130
+Parameters:+
131
# (integer) The payment method ID
132
133
* *selectedThisMethod()* - This method checks if the selected payment method matches the current plugin
134
+Return:+
135
True if the calling plugin has the given payment ID, False otherwise.
136
+Parameters:+
137
# (string) Element name, taken from the plugin filename
138
# (integer) The payment method ID
139
140
* *writePaymentData()* - This method writes all payment plugin specific data to the plugin's table
141
+Return:+
142
True if the calling plugin has the given payment ID, False otherwise.
143
+Parameters:+
144
# (array) Indexed array in the format 'column_name' => 'value'
145
# (string) Table name