Differences

This shows you the differences between the selected revision and the current version of the page.

--- development:gateways 2008/08/24 09:46
+++ development:gateways 2008/10/24 10:06 current
@@ Line 1: / Line 1: @@
 ====== Payment Gateways ======
+Instructions for adding a new payment gateway. All payment gateway code is located in includes/paymentapi/ folder.  Inside this folder you will need to create a new folder to house your custom code created below.
 ===== Config.php =====
@@ Line 15: / Line 16: @@
 </code>
- = Item 1 : Definition of item 1.
+  = $data['gateway']['name'] : (string) An internal name and it must not include any spaces.
-  = Item 2 : Definition of item 2.
+  = $data['gateway']['displayname'] : (string) What will be displayed to the administrator
-  = : Second definition of item 2.
+  = $data['gateway']['showas'] : (string) What you would like it to showas. Normally this will be Credit Card or something similar. The administrator can always change this.
-  = Item 3 : Definition of item 3.
+  = $data['gateway']['version'] : (string) Your version number. It is used primarily if you are going to release it for others.
-  = Item 4 :
+  = $data['gateway']['extraTxt'] : (string) An extra parameter. For example some gateways require the merchant id which could be entered here.
-  = Item 5 :
+  = $data['gateway']['extra2Txt'] : (string) An additional extra parameter. It is included in case your gateway requires two forms of authentication.
-  = Item 6 : Definition of items 4 through 6.
+  = $data['gateway']['cconsite'] : (string) This variable is either Y or N. Y means you are going to take the credit card on site and the site must have an SSL certificate installed. N means the gateway will handle this.
+===== readme.php =====
+The readme.php file is required so you can add any instructions for using the Payment Gateway. It will be accessible through the administration in a pop up window.
+===== sr.php =====
+The file sr.php or send and receive is used to handle setting up the form and handling the post back.
+This file includes two php functions and they are:
+  - function check_createForm($params)
+  - function check_processTransaction($params)
+These functions include the name of your gateway then the function name. The first portion comes from the $data['gateway']['name'] variable set in the config file.
+So if you named your gateway "kingarthur" then your functions would be:
+  - function kingarthur_createForm($params)
+  - function kingarthur_processTransaction($params)
+These methods are used by the core files to tell the difference from each gateway.
+Now that the function names are out of the way we will move on to the $params array that is passed to the functions.
+==== Create Form ====
+The createform function has these available $params.
+    * $params['oID'] - Order ID
+    * $params['extra'] - The extra info
+    * $params['extra2'] - The second extra info
+    * $params['oProduct'] - The product name ordered
+    * $params['oTotal'] - The total price
+    * $params['userinfo'] ? An array of all the users details.
+If you wish to see all of the available params you can add the following php inside the function:
+<code php>print_r($params); die;</code>
+Then a list of variables will be printed when you place a test ad.
+==== Process Transaction ====
+The processTransaction function has these available $params.
+    * $params['gatewayid'] - The id of the gateway
+    * $params['approved'] - Y or N depending on if it is approved.
+    * $params['extra'] - The extra data defined in administration
+    * $params['extra2'] - Same as above.
+Plus any others from your Payment Gateway. You will need to refer to their documentation on what they are.
+Since the check / money order gateway doesn't include the post back information you will probably need, we will use the processTransaction function from the Paymate gateway:
+<code php>
+function paymate_processTransaction($params)
+{
+	global $db,$Orders,$userid;
+	$orderid = (int)@$params['ref'];
+	switch ($params['responseCode'])
+	{
+		case "PA":
+			$Orders->logTransaction($params['gatewayid'], $orderid, 'Payment is approved', $userid, $params['transactionID'], $params['paymentAmount']);
+			if($Orders->updateOrder($orderid, 'Y'))
+			{
+				return TRUE;
+			}
+			else
+			{
+				//an error occured
+				return "Payment was made but your order has not been approved. Please contact support for help.";
+			}
+		break;
+		case "PD":
+			$Orders->logTransaction($params['gatewayid'], $orderid, 'Payment is declined', $userid, $params['transactionID'], $params['paymentAmount']);
+			return "Payment is declined";
+		break;
+		case "PP":
+			$Orders->logTransaction($params['gatewayid'], $orderid, 'Payment is processing', $userid, $params['transactionID'], $params['paymentAmount']);
+			return "Payment is processing";
+		break;
+		default:
+			$Orders->logTransaction($params['gatewayid'], $orderid, 'An error occured', $userid, $params['transactionID'], $params['paymentAmount']);
+			return "We are sorry but an occured.";
+		break;
+	}
+}
+</code>
+Starting from the top we include global $db, $Orders, $userid. I will not go into details what the global does but you can find out from php.net.
+Next we have $orderid = (int)@$params['ref'];
+The $params['ref'] comes from Paymate and that is the internal reference for 68 Classifieds so it knows what order to approve.
+After that comes a switch statement which is the response code Paymate sent.
+Through each case we call the logtransaction function so the administrator knows they tried to complete the payment but something happened.
+Finally if the order is approved. Paymate uses the PA which I assume means PAID.
+We then update the order with this call:
+<code php>
+if($Orders->updateOrder($orderid, 'Y'))
+{
+	return TRUE;
+}
+else
+{
+	//an error occured
+	return "Payment was made but your order has not been approved. Please contact support for help.";
+}
+</code>
+If it returns true then the order was successfully updated if not it returns an error and something happened inside the Orders class to make the order not be updated.
+As you can see creating a custom gateway is not a simple process and as such is not supported by us. A lot of things can go wrong and it will take some trial and error getting it setup properly.
+===== External Resources  =====
+  * [[http://php.net|PHP Website]]
+  * [[http://www.68classifieds.com/forums|68 Classifieds Forums]]

Have more questions? Visit our community forums.

Documentation

Differences

Search Documentation

Support

Wiki