Page tree
Skip to end of metadata
Go to start of metadata

This page provides a detailed description of the payment plug-in structure, the basic steps in creating a VoipNow Automation Payment Plug-in, explaining the logical and physical structure of a plug-in and the way it interacts with the system.

Logical Structure

A VoipNow Plug-in consists of three parts that you can find fully described below.

Payment Plug-in Manager

It is a configuration file with which the VoipNow Automation interface generates a setup page for the plug-in. It consists of the setup/setup.xml file and the language pack files from the /language folder;

Front-end

This part of the plug-in is present in the VoipNow Automation store and generates the payment inputs, based on the requirements.xml file content (which is saved in the database and can be modified) and on the language pack files from the /language folder.

Gateway Interaction Methods

These methods form a class that enhances the communication between VoipNow Automation and the gateway that needs to be implemented. It will be located in the index.php file.

Physical Structure

A plug-in is composed of one or more files and folders and it is uploaded as an archive in the VoipNow web management interface.

  • Each developer may create plug-ins with different structures, but all developers must follow a basic folder structure in order to be registered in the VoipNow;
  • Aside from the files and folders represented in the image below, the plug-in may also contain a set of back-end custom files and folders, entirely designed by the developer;
  • These files define auxiliary functions that are used internally and serve the purpose of the plug-in's purpose.

The folder structure of a VoipNow Plug-in consists of the following:

The index.php File

  • It is mandatory that every plug-in contains an index.php file in the plug-in root;
  • This file will contain the main gateway or the payment processor interaction class.
  • When a payment request is made, either 4PSA VoipNow Automation or the Automation Store will require this file in order to initiate the class that will handle the communication with the payment processor.

Please find below the structure of the file.

index.php   
<?php 
        class VoipNowPaymentPlugin extends OnlinePaymentInterface implements OnlinePayment {
        // gateway interaction methods
    }
?> 

The Language Folder

  • This folder contains the language pack files of the plug-in.
  • A plug-in can customize the layout of certain configuration areas or can cause JavaScript or HTML alerts to be displayed.
  • All the output messages must be displayed in the language that the customer has selected from the interface.

The user's language support can be achieved from plug-ins as follows: STEP 1: Create a folder named /language in the plug-in root. STEP 2: Create one file for each language defined in VoipNow and place it inside the /language folder.

It is recommended that the file bears the language code. (e.g. en.php)

STEP 3: Define an array with the language pack messages inside each language file. The structure of the array is: key => value.

<?php 
    $plugin_msg_arr = array();
    $plugin_msg_arr['field_name'] = 'This message is displayed as label in Payment Plug-in Management Page.';
	$plugin_msg_arr['verification_alert'] = 'This message is displayed as alert in case of failed verification.';
?>
Keeping the array name is mandatory in order to make it functional.

STEP 4: Use the OnlinePaymentInterface::translate method described in the Plug-in Methods section to display a message in the current user language.

<?php 
	class VoipNowPaymentPlugin extends OnlinePaymentInterface implements OnlinePayment {
		final public function AuthorizePayment($params) {
			// ...
			if (!isset($params['CreditCardNumber'])) {
				// ...
				$message = self :: translate('error_missing_credit_card_number');
				// we can use the method this way because our class extends OnlinePaymentInterface
				return self :: RaiseError($code, $message);
			}
			// ...
		}
    }						
?>

The setup.xml File

  • This file, which is located under the /setup folder, will provide configuration information for the plug-in within the 4PSA VoipNow Automation interface;
  • Once the plug-in is registered, it must be configured for use;
  • The configuration page from 4PSA VoipNow Automation interface will require the setup.xml file in order to generate the setup form;
  • The XML syntax for the setup file is presented in the Setup File section .

The requirements.xml File

  • For each method that has been used, this file will provide information about the fields that will be displayed under the 4PSA VoipNow Automation store;
  • Once the plug-in is configured and in use, if the user will choose to pay with this plug-in, the requirements. xml file will provide details about the required fields specific to each method;
  • This file also uses the XML syntax, which is very similar to the syntax setup.xml .

The required_inc.php File

  • This file will specify the required inputs for each plug-in method;
  • The file contains an array with the names of the plug-in methods as indexes and arrays containing the required fields' names as values;
  • The list of input parameters for each plug-in method can be found in the section called Plug-in Methods section .
<?php 
							
							
	$_required_params = array(
		'AuthorizePatyment' => array(
			'CreditCardType',
			'CreditCardNumber',
			'CardExpMonth',
			'CardExpYear',
			
			'InvoiceID',
			'OrderTotal',
			'IPAddress',
			
			'PayerFirstName',
			'PayerLastName',
			'PayerEmail',
			'PayerCountry'
		),
		// ...
	);
	
?>

The License File

This file contains the plug-in license information. If you want to distribute the plug-in under the General Public License (GPL) agreement, include the following paragraph:

Copyright (C) {year} {name of author}
This program is free software: you can redistribute it and/or modify 
it under the terms of the GNU General Public License as published 
by the Free Software Foundation, either version 3 of the License, or 
(at your option) any later version.
					
This program is distributed in the hope that it will be useful, 
but WITHOUT ANY WARRANTY; without even the implied warranty of 
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 
See the GNU General Public License for more details. 

You should have received a copy of the GNU General Public License 
along with this program. If not, see http://www.gnu.org/licenses/.

The Meta File

Each plug-in must contain a meta file with standard recognition plug-in information. 4PSA VoipNow does not allow uploading and running plug-ins without the following set of informations:

  • Name
  • Version
  • Author

The file content format is the following:

Name: Name of the plug-in
          Version: The plug-in's version, e.g.: 1.0
          Author: Name of the plug-in author
          Homepage: The plug-in's home page
          Update: The date when the plug-in was last modified
#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))

Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 4.0 International.