Payment Processor

The payment framework of VikRestaurants can be extended by creating a PHP file declaring the VikRestaurantsPayment class.
The created file must be placed via FTP onto the /administrator/components/com_vikrestaurants/payments/ directory.

In order to develop the class VikRestaurantsPayment please follow the example code below.

<?php

defined('_JEXEC') OR die('Restricted Area');

class VikRestaurantsPayment
{	
	private $order_info;
	private $params;
	
	public static function getAdminParameters()
	{
		return array();
	}
	
	public function __construct($order, $params = array())
	{
		$this->order_info = $order;
		$this->params = $params;
	}
	
	public function showPayment()
	{
		/** See the code below to build this method */
	}
	
	public function validatePayment()
	{
		/** See the code below to build this method */
		return array();

	}

	public function afterValidation($esit = 0)
	{
		/** See the code below to build this method */
	}
}

The parameters form for the administrator section can be built through the getAdminParameters() static method. This is useful to fill in private data or credentials, required for the creation and the validation of the payment/transaction.

A Merchant ID and a Signature Key are an example of parameters that should be visible as well as editable in the back-end.

The parameters of the form are returned as an array with the following structure:

{
	"param_1" : {
		"label" : "Label 1",
		"type" 	: "text"
	},
	"param_2" : {
		"label"   : "Label 2",
		"type" 	  : "select",
		"default" : 1,
		"options" : {
			"1" : "Yes",
			"0" : "No"
		}
	},
	"param_3" : {
		"label"    : "Label 3",
		"type" 	   : "select",
		"multiple" : 1,
		"options"  : [1, 2, 3]
	}
}

• param_1 - the associative key of the array that must be unique (required).
  It is used to get the parameter value from the configuration array.
  
  
• label - the text label of the parameter in the administrator section (optional).
  By placing a double slash (//) after the label, the next text will be displayed as a tip (like "Merchant ID//this is a tip to display...").
• type - used to render the right type of input field in the administrator section (required).
  The values allowed for the type are: custom, select, text or password.
• html - will be used only when the type of the parameter is custom (optional).
• options - an array containing all the possible values to use in the dropdown (required only when the type is select).
  The array may contain associative keys.
• default - the default value to use/set.
• multiple - set the value 1 if it is possible to choose more than one option (considered only when the type is select).

public static function getAdminParameters()
{
	$logo_img = JURI::root().'administrator/components/com_vikrestaurants/payments/mypay/mypay-logo.jpg';
	
	return array(	
		'logo' => array(
			'label' => '',
			'type' => 'custom',
			'html' => '<img src="'.$logo_img.'"/>'
		),
		'merchantid' => array(
			'label' => 'Merchant ID',
			'type' => 'text'
		),
		'testmode' => array(
			'label' => 'Test Mode',
			'type' => 'select',
			'options' => array('Yes', 'No'),
		),
	);
}

The code above will generate a parameters form, in the administrator section, as follows.

If your form doesn't come up, probably there is a syntax error on your file.
When you fill in the admin form, the parameters are stored in the $params (array) property of the class, so that you are able to get the values with the instructions below:

$merchant_id = $this->params['merchantid']; /* returns "539264823539" */
$test = $this->params['testmode']; /* returns "Yes" */

The $order_info property is an associative array containing the order information needed to complete the payment process. You can see below all the available keys of the array.

You can retrieve the information from the $order_info property with the example code below.

$uniq_id = $this->order_info['oid']."-".$this->order_info['sid'];

The method showPayment() of the object VikRestaurantsPayment is invoked every time a user visits the page of a reservation with PENDING Status. Here you need to echo the HTML form that points to the payment creation url of your bank gateway.

In this method it is possible also to make calls via cURL (or something else) to retrieve tokens or to self submit the form to receive additional info that are required for the gateway.

public function showPayment()
{	
	$merchant_id = $this->params['merchantid'];
	
	$action_url = "https://yourbankgateway.com/";
	if ($this->params['testmode'] == 'Yes') {
		$action_url = "https://test.yourbankgateway.com/";
	}

	$form = '<form action="'.$action_url.'" method="post">';
	// put here all the required fields of your gateway
	$form .= '<input type="hidden" name="your_post_data_merchantid" value="'.$merchant_id.'"/>';
	$form .= '<input type="hidden" name="your_post_data_amount" value="'.$this->order_info['total_to_pay'].'"/>';
	$form .= '<input type="hidden" name="your_post_data_notifyurl" value="'.$this->order_info['notify_url'].'"/>';
	$form .= '<input type="hidden" name="your_post_data_description" value="'.$this->order_info['transaction_name'].'"/>';
	// print a button to submit the payment form
	$form .= '<input type="submit" name="_submit" value="Pay Now!" />';
	$form .= '</form>';
	
	echo $form;
}

The validatePayment() method is used to validate the transaction details sent from the bank. This method is invoked by the system every time the Notify URL is visited (the one described in the showPayment() method). Usually the data are sent via POST method, and you can access them by simply using the $_POST super-global variable.

Some gateways require a signature validation to make sure the transaction wasn't corrupted. The signature validation can be created only following the instructions on the official documentation of your bank.

This method must return an associative array with the status of the transaction. The possible keys of the array are the following.

You can pass any other value in the array, but they will be completely ignored during the validation of the transaction.

public function validatePayment()
{
	$array_result = array();
	$array_result['verified'] = 0;
	$array_result['tot_paid'] = ''; /** This value will be stored in the DB */
	
	/** In case of error the log will be sent via email to the admin */
	
	$status = $_POST['status'];
	/** Process your gateway response here */
	if ($status == 'success') {
		$array_result['verified'] = 1;
		/** Set a value for $array_result['tot_paid'] */
		$array_result['tot_paid'] = $_POST['amount'];
	} else {
		$array_result['log'] = "Transaction Error!\n".$_POST['error_msg'];
	}
	
	/** Return the array to VikRestaurants */
	return $array_result;
}

The afterValidation($esit) method is optional and it is generally used to display a message and to redirect the gateway to the order summary view in case of success or failure. Notice that this method should be used from your class only in case the Bank Gateway will not redirect the user to the Return URL.

The $esit argument is a boolean value that represents the status of the transaction. In case of success (1/true) you should print a positive message and redirect the gateway to the return_url address, otherwise (0/false) you should print an error message and redirect the gateway to the error_url address. Remember also to put an exit or die rule at the end of the method to completely stop the flow.

When this method is available, it will be invoked by the system once validatePayment() has been performed.

public function afterValidation($esit = 0)
{	
	$app = JFactory::getApplication();
	
	if ($esit < 1) {
		$app->enqueueMessage('The payment was not verified, please try again.', 'error');
		$app->redirect($this->order_info['error_url']);
	} else {
		$app->enqueueMessage('Thank you! The payment was verified successfully.');
		$app->redirect($this->order_info['return_url']);
	}
	
	exit;
}

You can get HERE the complete code of this example gateway.