Store
Community Documentation

v3 Knowledgebase

Adding Payment Gateways

Payment Gateways

Implementing new payment gateways is actually a rather easy task, every online payment processor provides guides for developers to implement their service and Phpfox makes it very easy for you to integrate their payment platform into the script.

Showing a new Payment Gateway

The list of payment gateways is fetched from the database, the table phpfox_api_gateway holds general information about each option available. The field `setting` here is a serialized array of the current settings required by the payment processor, for example Paypal requires an email address, internally this is referred to as "paypal_email" so the array would be:

array(
  'paypal_email' => ''
);

and the serialized form of that is:

a:1:{s:12:"paypal_email";s:0:"";}

When that setting is populated in the AdminCP the script (you do not have to handle this) will update this field. The name of the key in the array is a name for your code to work with, it has no other relation within the phpfox script.

So when you are creating your product you can add an entry in the install routine to insert a new record here in this table and you now know how to populate all the fields.

Implementing the payment gateway

A new class must be made for every new payment processor, the file must sit in the /include/library/phpfox/gateway/api/ folder. The name of the file is not so important but it must have the .class.php extension. It also must abide the file-name=>class-name convention, for example if your file is named: 2checkout.class.php your class must be named: class Phpfox_Gateway_Api_2checkout implements Phpfox_Gateway_Interface

Remember that the class name is used internally as path verification.

2 class attributes must be initialized:

private $_aParam = array();	
private $_aCurrency = array('USD', 'GBP', 'EUR', 'AUD', 'CAD');

$_aParam is initialized as an empty array for cleanup purposes, while the currency is the allowed currencies for this payment processor, should you add an invalid currency here and was it used by the client it would not work as the payment processor would always deny the transaction, researching is recommended here.

The functions in this class and the ways you handle payments is what you as a developer must code. There are however 4 important functions that must be implemented:

public function set($aSetting)

When this class is instantiated, for example when a payment has been completed, $aSetting is the response from the payment processor, normally you only need to assign $aSetting to $this->_aParam but other operations are possible here. This function does not return a value.

public function getEditForm()

This returns an array with the settings needed from the set up Payment Gateway section in the AdminCP (/admincp/api/gateway/add/id_<your-payment-gateway>/), this is what the site admin must fill in, here they would put something like their seller id or in the case of paypal their email. The first 4 fields are a freebie from the script, meaning you do not need to code or do anything to show and manage the fields "Title", "Description", "Active" and "Test Mode", Im sure you can see the match from these 4 inputs here and the first 4 fields from the `phpfox_api_gateway` table. The array this function returns of course varies depending on the fields that you need to use, (those fields are the ones the payment processor must provide) but this format is required (of course additional keys are allowed):

array(
	'a_var' => array(
		'phrase' => Phpfox::getPhrase('module.your_variable_title_here'),
		'phrase_info' => Phpfox::getPhrase('module.the_grayed_description_here'),
		'value' => (isset($this->_aParam['setting']['a_var']) ? $this->_aParam['setting']['a_var'] : '')
		)
);

This array is very important as it is the one that will update the database with the settings needed to pass on to the processor. As you can see we are getting 2 phrases (you need to add those and a good place would be the install code when installing the product), the first one ("phrase") is the one shown on the left side at the editing payment gateway screen and the second one (phrase_info) is the one shown below the input field. The value to show in the input field is given by the index "value" in our array, this correspondes to the unserialized form of the `phpfox_api_gateway`.`setting` field in the database.

public function getForm()

This function also returns an array (or false if there is an error) but with a different purpose, this array is the actual set of params required by the payment processor company to actually process orders coming from the client's site. You can place validations here, for example 2checkout does not allow recurrent billings so:

if ($this->_aParam['recurring'] > 0)
{
	return false;	
}

While on this subject let me briefly explain the billing periods, there are 5 billing periods in phpfox: 0 => Never 1 => Monthly 2 => Quarterly 3 => Biannually 4 => Annually

These are the options shown to the user when creating a subscription for example.

One useful (and perhaps obliged) tip is that from the module controllers you can set params that would be available to this class should it ever be instantiated (by means of calling the api.gateway service or a direct Phpfox::getLib('gateway')->load(...)), for example in a controller you can:

$this->setParam('gateway_data', array(
	'item_number' => $aPurchase['purchase_id'])
);

and in this class you would call it as:

$iNumber = $this->_aParam['item_name'];

Now back to our function, we want to return an array, this array must be formatted in this way:

$aForm = array(
	'url' => 'http://url-provided-by-the-payment-processor.domain/maybe-a-specific-file',
	'param' => array(
		'business' => $this->_aParam['setting']['seller_id'],
		'item_name' => $this->_aParam['item_name'],
		'item_number' => $this->_aParam['item_number'],
		'currency_code' => $this->_aParam['currency_code'],
		'other_params' => 'other values'
	)
);

self explanatory but the 'url' key is the url that the script will use for submitting the purchase, the 'param' array is the set of params required by processing company.

public function callback()

Now this is the pretty function, it is the one called when the payment processing company has received and finished the transaction, it is the function that tells the result of the purchase, you also must work the logic to use here as it varies from one payment processor to another, for example 2checkout only returns yes or no since their options are very straightforward (no recurring payments) but paypal has a rather large response message. Keep in mind that at this point you have all the information about the transaction such as transaction id and item name, you can call a specific service function from here if you want but for the most part you may just need to update a field in the database.

Summary

As you've seen the adding of a payment gateway is very simple since phpFox handles most of what happens on the back end.

  • the getForm function defines the params to send the purchase, you can think of this function as the event of sliding the credit card on the machine and entering your vendor id to the credit card company
  • the callback function can be seen as the event of receiving the Ok or Denied from the credit card company, it would also be the awkward moment of telling the client that he has ran out of funds ("Do you have another credit card?")

Adding a Database Entry

Now that the PHP code is completed for your payment gateway you will have to add an entry in the database so it shows up in the AdminCP. The table we need to add information to is:

api_gateway

The fields that are required are:

gateway_id (Unique ID. This must be the same name as the PHP class you created earlier in the "/include/library/phpfox/gateway/api/" folder )
title (Title of your payment gateway. Eg. Paypal, 2checkout etc...)