4PSA VoipNow® Automation Payment Developer Guide

Manual Version 63748.4 at 2010/03/03 14:17:56

For suggestions regarding this manual contact:

docs@4psa.com

Distribution of this work or derivative of this work is prohibited unless prior written permission is obtained from the copyright holder.

VoipNow is a Registered Trademark of Rack-Soft, Inc.

4PSA is a Registered Trademark of Rack-Soft, Inc.

Asterisk is a Trademark of Digium, Inc.

Linux is a Registered Trademark of Linus Torvalds.

All other trademarks and copyrights are property of their respective owners.

Table of Contents

Preface

Who Should Read This Guide

Introduction

Creating a Plug-in

The Plug-in Structure

Logical Structure
Physical Structure

The Interaction Between VoipNow and the Plug-in

Interface Interactions Description
Automation Store Interactions Description
Plug-in Methods
Commonly Utilized Plug-in Methods
Plug-in XML Configure Syntax

Plug-in Example

Setup File
Requirements File
Input Requirements
Language File
Plug-in Class

Preface

Who Should Read This Guide

This reference guide should be read by the developers of third-party applications whose purpose is to implement the new payment processors into the 4PSA VoipNow Automation store.

This Payment Plug-in Reference Guide provides the information needed for creating a 4PSA VoipNow Automation Payment Plug-in. It contains a comprehensive description of the system defined interfaces and classes.

Introduction

This guide offers guidelines and references for anyone wishing to modify, extend, or contribute to the 4PSA VoipNow Automation payment plug-ins. Third-party products can interact with the system and may offer more payment options, according to their needs. Beginning with 4PSA VoipNow 2.0.2, developers can build payment plug-ins and upload them using the control panel.

A VoipNow Automation Payment Plug-in is a set of functions, written in the PHP scripting language, that defines the interaction of both VoipNow Automation and the Automation Store with a certain gateway or payment processor.

The Creating a Plug-in chapter of this Guide goes through the basic steps of 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.

Creating a Plug-in

This guide assumes you are already familiar with the 4PSA VoipNow functionality and the PHP programming. This chapter describes the basic steps to be taken in the development of a new plug-in.

The Plug-in Structure

Logical Structure

A VoipNow Plug-in consists of the following parts:

Payment Plug-in Manager - This plug-in part is actually a configuration file with which the VoipNow Automation interface generates a setup page for the plug-in. It contains 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 control panel. 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 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 that are necessary for the plug-in's purpose.

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

The index.php File

Containing an index.php file in the plug-in root is a compulsory demand for every plug-in. 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 requires this file in order to initiate the class that will handle the communication with the payment processor. The file's structure is:

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

The Language Folder

This folder contains the plug-in's language pack files. 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:

Create a folder named /language in the plug-in root.
Create one file for each language defined in the 4PSA VoipNow control panel and place it inside the /language folder.

Note

You must name the file with the language code in order to have effect. (E.g.: en.php)

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.';
?>

Note

In order to be functional, you must keep the array name.

Use the OnlinePaymentInterface::translate method described in the section called “Plug-in Methods” 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 will provide configuration information for the plug-in within the 4PSA VoipNow Automation interface. The file is located under the /setup folder.

After the plug-in is registered, it must be configured in order to be used. 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 the section called “Setup File”.

The requirements.xml File

This file will provide information about the fields that are to be displayed under 4PSA VoipNow Automation store, for each method that has been used. After the plug-in is configured and set 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, very similar with the setup.xml file's syntax.

The required_inc.php File

This file will specify the required inputs for each plug-in method. The file contains an array having as indexes the names of the plug-in's methods and as values arrays containing the required fields' names. E.g.:

<?php 
							
							
	$_required_params = array(
		'AuthorizePatyment' => array(
			'CreditCardType',
			'CreditCardNumber',
			'CardExpMonth',
			'CardExpYear',
			
			'InvoiceID',
			'OrderTotal',
			'IPAddress',
			
			'PayerFirstName',
			'PayerLastName',
			'PayerEmail',
			'PayerCountry'
		),
		// ...
	);
	
?>

The list of input parameters for each plug-in method can be found in the section called “Plug-in Methods”.

The License File

This file contains 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

The Interaction Between VoipNow and the Plug-in

The execution of a payment plug-in is initiated when a payment or a refund command is triggered inside the 4PSA VoipNow Automation interface. This will instantiate the payment plug-in class and execute one of the payment methods available in that class. Further more, another type of interaction between VoipNow interface and the plug-in files is the configure operation. During the configuration process, the VoipNow interface will directly access the setup and requirements XML files and it will display the required information based on the formated data from those files.

Interface Interactions Description

The interactions between 4PSA VoipNow Automation interface and the payment plug-ins are being recognized at two levels:

VoipNow Payment Plug-in Setup Interface
VoipNow Payment Plug-in Usage

VoipNow Payment Plug-in Setup Interface

The Plug-in Setup Interface will load the information from the setup.xml file and will generate a form that contains the inputs needed to set up the plug-in's requirements in order to be able to connect to the gateway.

Further more, the Plug-in Setup Interface will load the information from the requirements.xml file in order to be able to setup the 4PSA VoipNow Automation store interface inputs for each payment plug-in method.

VoipNow Payment Plug-in Usage

After a client has made his first payment and the product has been deployed, the amount of money paid for it needs to be captured. This will be done from the VoipNow Automation Interface, using one of the available plug-in methods.

This will be done from the Orders and the Invoices pages. There, for each invoice, the user can capture the payment, refund a part of the money, etc.

Automation Store Interactions Description

A payment plug-in's execution is triggered when an user is trying to complete a payment operation. At that moment, an instance of the payment plug-in class will be created and, afterwards, a specific payment method will be called. The method will communicate with the gateway or with the payment processor sending via different methods (usually SOAP or XML RPC) informations about the payment and will grab the processor's response towards the given data. The response will be formated and returned to the Automation store.

Also, the Automation store will be able load the xml requirements from the database (this will be the same as the content of the requirements.xml file or a modified version of this content) in order to be able to create a payment form for the user.

Plug-in Methods

Depending of it's type, a payment plug-in must implement a simple set of methods that are defined within the OnlinePayment interface.

<?php 
	interface OnlinePaymentInterface {
		public function PreAuthorisePayment(array $params);
		public function ProcessPreAuthorisePayment(array $params);	
		public function AuthorisePayment(array $params);
		public function CapturePayment(array $params);
		public function GetTransactionDetails(array $params);
		public function RefundTransaction(array $params);
		public function RecurringPayment(array $params);
    public function CheckSubscriptionValidity(array $params);
    public function Void(array $params);
	}
?>

Each method must have a set of parameters. Some of these parameters will be required all the time. The required ones will be mentioned in the required_inc.php file and verified to be valid. The input for these methods has a shape of an array.

<?php 
	$plugin = new VoipNowPaymentPlugin();
	$params_authorise = array(
		'CreditCardNumber' => '4111111111111111',
		'CardExpMont' => '09',
		'CardExpYear' => '2010',
		'CreditCardType' => 'Visa',
		'OrderTotal' => '20.21',
		'Currency' => 'USD';
	);
	$plugin->AuthorizePayment($params_authorize);
?>

Also, each method has a required set of parameters that must be returned by the coder. A method's output has the shape of an array. Considering the fact that a class method must return one or more outputs for each transaction that takes place inside it (see the section called “Plug-in Methods”), the array will have the following shape:

<?php 
	$result = array();
	$result[METHOD_NAME_CONSTANT] = array(
		'output_index' => 'output_value',
		// ...
	);
?>

where METHOD_NAME_CONSTANT is a constant from OnlinePaymentInterface class. E.g:

<?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);
			}
			// ...
			$result = array();
			$result[parent::method_auth] = array();
			// ...
			$result[parent::method_auth]['CardNumberEnding'] = 'value';	// the last 4 digits of the card number
			$result[parent::method_auth]['CardExpMonth'] = 'value';		// the expire 
			$result[parent::method_auth]['CardExpYear'] = 'value';		// date of the card
			return $result;
		}
    }		
?>

AuthorizePayment Method

This method is only meant to block a certain amount of money on the client's card account that can be later withdrawn by the merchant with the help of a Capture operation.

The method's available input parameters are:

CreditCardNumber - the client's card number.
CardExpYear - the card expiration year.
CardExpMonth - the card expiration month.
CreditCardType - the card type (e.g.: Visa, MasterCard, Maestro, etc.).
CardSecurityCode - the card unique code that is available only on the physical card (e.g. last the three digit code on the back of a VISA card).
OrderTotal - the total amount of the order placed on the public store.
Currency - the currency used for the transaction.
IPAddress - specifies the buyer's IP address (used for security purposes).
InvoiceID - the unique identification number of the invoice created for the order placed on the public store.
PayerFirstName - the client's first name.
PayerLastName - the client's last name.
PayerAddress - the client's address: street name, number.
PayerCountry - the client's country.
PayerCity - the client's city.
PayerState - the client's state.
PayerPostalCode - the client's postal code.
PayerEmail - the client's email address.
PayerCompany - the client's company, if he represents one.
PayerPhoneNumber - the client's phone number.
PayerFaxNumber - the customer's fax number.
PayerTaxAccountNumber - the customer's tax account number.
PayerBankName - the name of the bank used by the client.
PayerBankAccount - the client's bank account number.
TransactionID - for the other payment methods that do not use card details (check and wire transfer) but a subscription, you can use this parameter to pass the credentials.

Requested method output parameters are:

ACK - will specify if the outcome of the request was success or failure.
BankRef - the possible bank response regarding the transaction.
Date - the date when the transaction was made. This should be an integer number (see php time function).
MerchantID - the merchant's identification number.
APIRequest - the API request in the form that is sent to the processor.
APIResponse - the API response in the form that is received from the processor.
Error - if the processor will return an error, it will be displayed here. This parameter is an array itself with the following indexes:
- code - the error code (the code returned by the gateway or the error's internal code that appeared inside the plug-in).
- location - the error location.
- message - the error message.
- severity - the error severity.
Amount - the amount of the invoice.
Currency - the currency used for the transaction.
TransactionID - the identification number returned by the Authorize operation for the specific transaction.
SubscriptionID - the subscription's identification number.
CardNumberEnding - the last four digits of the card number used by the customer to pay for the order.
CardExpMonth - the client's card expiration month.
CardExpYear - the client's card expiration year.

CapturePayment Method

This method is meant to retrieve the amount of money that was blocked in the client's bank account by the Authorize operation.