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

This page sums up all the plug-in methods, including the most commonly used.

Overview

Depending on its type, a payment plug-in must implement a simple set of methods 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;
  • Those that are required will be mentioned in the required_inc.php file and verified so as to be valid;
  • The input for these methods has the 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 (please check the Plug-in Methods section), 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.

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

 Click here to expand the input parameters available for this method.

Input Parameter

Description

CreditCardNumberThe client's card number.
CardExpYearThe card's expiration year.
CardExpMonthThe card's expiration month.
CreditCardTypeThe card type (e.g. Visa, MasterCard, Maestro, etc.).
CardSecurityCodeThe card's unique code that is available only on the physical card (e.g. last the three digit code on the back of a VISA card).
OrderTotalThe total amount of the order placed on the public store.
CurrencyThe currency used for the transaction.
IPAddressSpecifies the buyer's IP address (used for security purposes).
InvoiceIDThe unique identification number of the invoice created for the order placed on the public store.
PayerFirstNameThe client's first name.
PayerLastNameThe client's last name.
PayerAddressThe client's address: street name, number.
PayerCountryThe client's country.
PayerCityThe client's city.
PayerStateThe client's state.
PayerPostalCodeThe client's postal code.
PayerEmailThe client's email address.
PayerCompanyThe client's company, if he represents one.
PayerPhoneNumberThe client's phone number.
PayerFaxNumberThe customer's fax number.
PayerTaxAccountNumberThe customer's tax account number.
PayerBankNameThe name of the bank used by the client.
PayerBankAccountThe client's bank account number.
TransactionIDfor 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.
 Click here to expand the requested method output parameters.

Output Parameter

Description

ACKWill specify if the outcome of the request was a success or a failure.
BankRefThe possible bank response regarding the transaction.
DateThe date the transaction was made.
This should be an integer number (Please see php time function).
MerchantIDThe merchant's identification number.
APIRequestThe API request in the form that is sent to the processor.
APIResponseThe 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.
AmountThe amount of the invoice.
CurrencyThe currency used for the transaction.
TransactionIDThe identification number returned by the Authorize operation for the specific transaction.
SubscriptionIDThe subscription's identification number.
CardNumberEndingThe last four digits of the card number used by the customer to pay for the order.
CardExpMonthThe client's card expiration month.
CardExpYearThe 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.

 Click here to expand the available input parameters for this method.

Input Parameters

Description

CurrencyThe currency used for the transaction.
OrderTotalThe total amount of the order placed on the public store.
TransactionIDthe identification number returned by the Authorize operation for the specific transaction.
 Click here to expand the requested output parameters for this method.

Output Parameters

Description

ACKWill specify if the outcome of the request was a success or a failure.
BankRefThe possible bank response regarding the transaction.
DateThe date the transaction was made.
This should be an integer number (Please see php time function).
MerchantIDThe merchant's identification number.
APIRequestThe API request in the form that is sent to the processor.
APIResponseThe 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.
AmountThe amount of the invoice.
CurrencyThe currency used for the transaction.
TransactionIDThe identification number returned by the Capture operation for the specific transaction.

GetTrasactionDetails method

This method is meant to obtain information about a certain transaction. If the method is not supported by the gateway, it should return null or an empty array.

There is only one input parameters available for this method.

Input Parameter

Description

TransactionIDthe identification number of any of the operations made before this one.

RefundTransaction method

This method is meant to refund a certain amount of money (less than or equal to the amount that was payed in the Capture operation) to the client.

 Click here to expand the input parameters available for this method.

Input Parameters

Description

CurrencyThe currency used for the transaction.
OrderTotalThe total amount of the order placed on the public store.
TransactionIDThe identification number returned by the Capture operation for the specific transaction.
InvoiceIDThe identification number of the refunded invoice.
 Click here to expand the requested output parameters for this method.

Output Parameters

Description

ACK

Will specify if the outcome of the request was a success or a failure.
BankRefThe possible bank response regarding the transaction.
DateThe date the transaction was made.
This should be an integer number (Please see php time function).
MerchantIDThe merchant's identification number.
APIRequestThe API request in the form that is sent to the processor.
APIResponseThe 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.
AmountThe amount of the invoice.
CurrencyThe currency used for the transaction.
TransactionIDThe identification number returned by the Capture operation for the specific transaction.

RecurringPayment method

The recurring payment is actually a referenced capture method, made using the subscription given by the AuthorizePayment plug-in method.

 Click here to expand the input parameters for this method.

Input Parameters

Description

CurrencyThe currency used for the transaction.
OrderTotalThe total amount of the order placed on the public store.
InvoiceID The identification number of the invoice being paid.
SubscriptionID The identification number of the subscription returned by the AuthorizePayment plug-in method.
 Click here to expand the requested output parameters for this method.
Output ParametersDescription

ACK

Will specify if the outcome of the request was a success or a failure.
BankRefThe possible bank response regarding the transaction.
DateThe date the transaction was made.
This should be an integer number (Please see php time function).
MerchantIDThe merchant's identification number.
APIRequestThe API request in the form that is sent to the processor.
APIResponseThe 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.
AmountThe amount of the invoice.
CurrencyThe currency used for the transaction.
TransactionIDThe identification number returned by the Capture operation for the specific transaction.

VoidPayment method

This method cancels the payment of an existing invoice. The payment status of the voided invoice can be only pending or authorized since the void method only releases the money that were blocked in the customer's bank account when the invoice was authorized.

 Click here to expand the input parameters available for this method.

Input Parameters

Description

CurrencyThe currency used for the transaction.
OrderTotalThe total amount of the order placed on the public store.
TransactionIDThe identification number returned by the Capture operation for the specific transaction.
InvoiceIDThe identification number of the refunded invoice.
 Click here to expand the requested output parameters for this method.
Output ParametersDescription

ACK

Will specify if the outcome of the request was a success or a failure.
BankRefThe possible bank response regarding the transaction.
DateThe date the transaction was made.
This should be an integer number (Please see php time function).
MerchantIDThe merchant's identification number.
APIRequestThe API request in the form that is sent to the processor.
APIResponseThe 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.
AmountThe amount of the invoice.
CurrencyThe currency used for the transaction.
TransactionIDThe identification number returned by the Capture operation for the specific transaction.

Creating a Subscription method

For many gateways, it is not possible to realize a referenced transaction using a transaction ID from operations that have already been completed. In this case, there is a need for a work-around. Many of these gateways offer account management APIs which can be used afterwards for payments.

Therefore, a new method that handles the account creation must be added to the payment plug-in class.

  • This function will be called from the AuthorizePayment class method, but only if the Authorize call was successful.
  • It is useless to create a subscription including all the details if the payment operation has failed.
  • After calling the subscription method from within the AuthorizePayment class method, if the subscription was a success, the SubscriptionID value that is returned by this method must be given a returned unique token that identifies the newly created subscription.
  • Considering this, the RecurringPayment class method will be made using this SubscriptionID .

This class method is only a referenced capture transaction and does not offer the gateway the possibility to charge the client freely. Every operation must be triggered from within the new plug-in and not by the gateway.

Commonly Utilized Plug-in methods

For each plug-in there must be some common methods for returning errors, finding the plug-in's root folder or storing its common elements.

<?php 
	class OnlinePaymentInterface {
	
		const method_preauth
		const method_processauth
		const method_auth
		const method_capture
		const method_refund
		const method_partial_refund
		const method_recurrent
		const method_subscribe
		
		public function LoadLanguagePack()
		
		public function GetPaymentPluginRoot()
		
		public function GetPluginParams()
		
		public function Translate(string $lp_key)
		
		public function RaiseError($code = '', $message = '', $location = ERR_PLUGIN_API, $severity = E_USER_ERROR)
		
		protected function ErrorAttachLogs($request, $response = null)
		
	}	
?>

To make things easier and for security purposes, every plug-in must contain a class named OnlinePaymentInterface.

OnlinePaymentInterface::method_*

This method constants are used to specify the output for the payment plug-in class methods. The output will be further used by 4PSA VoipNow Automation store in order to log the transaction or to display the details to the client.

OnlinePaymentInterface::LoadLanguagePack

This function is used to load the language pack for the plug-in.

OnlinePaymentInterface::GetPaymentPluginRoot

This function will return the plug-in root folder needed for loading auxiliary files. e.g. the required fields file.

OnlinePaymentInterface::GetPluginParams

This function should be used in the plug-in class constructor for loading the gateway credentials stored in the database.

OnlinePaymentInterface::Translate

This function is used for translating the language keys from the language packs.

<?php 
	self::Translate('language_key');
?>

OnlinePaymentInterface::RaiseError

This function is used for returning an error. The function's parameters will offer a code for each error, a message explaining what was wrong, a location for where the error occurred (inside the plug-in - ERR_PLUGIN_API, inside the handler - ERROR_PLUGIN_HANLDER or it ca be a custom location - ERROR_PLUGIN_CUSTOM) and a severity level (the severity level is defined with the help of the PHP error predefined constants).

OnlinePaymentInterface::ErrorAttachLogs

This function will help the developer attach the function's inputs and outputs of each method (it is mandatory for the two parameters to have the same form that they are sent and received to and from the gateway) to the error message. This method will always be used before

OnlinePaymentInterface::RaiseError

This function helps to build the message correctly. Without it, the error message will not contain the two elements.

Plug-in XML configure syntax

Both the setup and the requirements files use the same XML syntax, the differences between these two files being minimal. Both files contain the XML header:

<?xml version="1.0" encoding="UTF-8"?>

The root tag for both files has the pimmodule name and the attributes below.

Attribute

Details

NameThe default name of the plug-in.
This can be changed from the setup interface, but the changed name can only be stored in the database and not in the XML file.
UidThe plug-in's unique identifier. The identifier is the same as the plug-in class name.
versionThe plug-in's version.
typeThe plug-in's type:
  • payment - for payment plug-ins.
  • fraud - for fraud plug-ins.
subtypeThe plug-in's subtype:
  • gateway - for payment processors that use credit card payment.
  • virtual - for virtual processors that use virtual payment accounts or agreements.
  • offline - for offline payment methods, like check or wire transfers.
<pimmodule name="MODULE_NAME" uid="UID" version="VERSION" type="TYPE" subtype="SUBTYPE">
		<!-- config content -->
	</pimmodule>

Setup file

Here is an example of a configured field:

<fieldset langname="LANGUAGE_KEY" collapse="1">
		<field langname="pe_endpoint" param="endpoint" type="text" required="1" size="large" validate="/^(ht|f)tp(s?)\:\/\/[0-9a-z]([-.\w]*[0-9a-z])*(:(0-9)*)*(\/?)([\~a-z0-9\-\.\?\=\,\'\/\\\+&%\$#_]*)?$/i" alert="regexp=pe_error_incorect_pe_endpoint,notempty=pe_error_invalid_pe_endpoint" default="https://pluginexample.foo.ext" />
	</fieldset>

Title

It will change the VoipNow Automation page title under the setup page. The title is specified as a language key within the langname attribute.

<title name="LANGUAGE_KEY" />

Fieldset

It will group the fields into field sets for easier comprehension. The field list title is set using the same attribute as for the title tag. The field set can be configured in three states, defined by the collapse attribute with the following values:

0 - the field set cannot be collapsed.

1 - the field set can be collapsed, but it is not collapsed by default.

2 - the field set can be and is by default collapsed.

Example of a field set structure:
<fieldset langname="LANGUAGE_KEY" collapse="1">
		<!-- config content -->
	</fieldset>
Within each field set, the tag field will be used to define the input fields needed for the setup section. The field tags can be formatted through the attributes below.

Attribute

Detail

langnameIt will set the input's label and it is defined as a language pack key.
tipIt will set a text placed after the input.
paramIt will define the input's name as it will be used in the setup section and stored in the database.
typeIt will define the input's type:
  • text - HTML text input.
  • textarea - HTML textarea input.
  • select - HTML select input.
  • checkbox - HTML checkbox input.
  • selection_lists - it will display selection lists.
sizeIt will define the input's size. The size can be selected between small, medium, large and x-large.
requiredIt will specify if the input is required.
validateIt will define a regular expression for the inputs's validation.
alertIt will define the errors language keys for the two validation elements, required and validate . The error messages will have the following content: validation_key=error_language_key.
A validation key can be:
  • notempty related to the required attribute.
  • array_notempty related to the required attribute of the selection_lists field that is described below and to the regexp attribute that defines the error for the validate regular expression.
default

It will define the field's default value.

alert="regexp=pe_error_incorect_pe_endpoint,notempty=pe_error_invalid_pe_endpoint"
A field type that is slightly different from the others is selection_lists. This field offers the possibility of displaying two lists: one with the elements that can be selected and one with the elements that have already been selected.

<field langname="pe_curency_title" param="currency" type="selection_lists" size="medium" required="1"  alert="array_notempty=pe_error_invalid_pe_curency_title">		
		<lefttitle langname="pe_currency_left_title"/>	
		<leftvalue value="USD"/>
		<leftvalue value="CAD"/>
		<righttitle langname="pe_currency_right_title"/>
	</field>
The difference between the selection_lists field and the other ones is that it contains specific tags:
  • lefttitle - it will define the title of the left list (the list the user selects from). The title will be defined through the attribute langname.
  • leftvalue - it will define items for the left list. The values of this list will be defined through the value attribute that will be used both as value and as language key.
  • righttitle - it will define the title of the right list (that shows the already selected items).
  • rightvalue - it will define items from the right list. These items will act as the default selected items, but only at the first load of the setup page. If the list is modified or saved, the setup page will then load the saved information.
If the selection_lists field is used for selecting the currency and you need all the currencies 4PSA VoipNow Automation supports, in the lefttile tag, the attribute type can be used with the value all.
<lefttitle langname="pe_currency_left_title" type="all">
As well as the selection_lists element, the select element has it's own inner tag, fieldvalue that allows adding items to the select field. The value from this field will act the same way as the ones from leftvalue or rightvalue.
<field langname="pe_select" param="selectex" type="select" required="1" size="medium" alert="notempty=pe_error_invalid_pe_endpoint" default="VALUE_01" />
		<fieldvalue value="VALUE_01">
		<fieldvalue value="VALUE_02">
		<fieldvalue value="VALUE_03">
	</field>

Requirements file

Unlike the setup file, the requirements file does not use the fieldset or the title tags. The requirements file will use a new tag named operation that has only one attribute, named, in order to specify the operation's name. This file has to include all the operations currently present in the OnlinePayment interface.

The content of the operation tag is 100% similar to the content of the fieldset tag from the setup file (see the section called “Requirements File”) with the mention that the selection_lists tag is not used.

Furthermore, there will be little modification in the field tag attributes as well. Thus, the default one will be replaced with the position one. Its function is to establish the order of the inputs in the store form.

#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))
  • No labels

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