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

The config.php file includes the following code: 

<?php 
$data['gateway']['name'] = "check";
$data['gateway']['displayname'] = "Email Only";
$data['gateway']['showas'] = "Check or Money Order";
$data['gateway']['version'] = "v1";
$data['gateway']['extraTxt'] = "Leave Blank";
$data['gateway']['extra2Txt'] = "Leave Blank";
$data['gateway']['cconsite'] = 'N';
?>

$data['gateway']['name']
(string) An internal name and it must not include any spaces.
$data['gateway']['displayname']
(string) What will be displayed to the administrator
$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.
$data['gateway']['version']
(string) Your version number. It is used primarily if you are going to release it for others.
$data['gateway']['extraTxt']
(string) An extra parameter. For example some gateways require the merchant id which could be entered here.
$data['gateway']['extra2Txt']
(string) An additional extra parameter. It is included in case your gateway requires two forms of authentication.
$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:

  1. function check_createForm($params)
  2. 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:

  1. function kingarthur_createForm($params)
  2. 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.

If you wish to see all of the available params you can add the following php inside the function: 

print_r($params); die;

Then a list of variables will be printed when you place a test ad.

Process Transaction

The processTransaction function has these available $params.

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: 

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;	
	}
}

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: 

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.";
}

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