Creating your own payment module

The rationale

PrestaShop provides a seller (and his customers) with many ways to handle payment for goods, thanks to the modules installed by default. PayPal, Hipay or Authorize.Net are just a few of the modules that are a click away from activation.

Still, not all payment solutions are available by default, and if you do not find the one you need on the PrestaShop Addons website, you might have to work one out yourself – and why not, sell it to other shop owners on PrestaShop Addons!

This tutorial was created to help you with this task.

Creating a basic module

A payment module is just like any other PrestaShop module, so you won't be surprised by the first few methods – except for the fact that the main class does not extend the Module object, but the PaymentModule one. Apart from that, the __construct(), install() and uninstall() methods are mostly as described in the Developer Guide.mypayment.php

class MyPayment extends PaymentModule{ public function __construct() { $this->name = 'mypayment'; $this->tab = 'payments_gateways'; $this->version = 0.1; $this->author = 'PrestaShop'; $this->currencies = true; $this->currencies_mode = 'radio'; parent::__construct(); $this->displayName = $this->l('Hipay'); $this->description = $this->l('Hipay API implementation'); if (!sizeof(Currency::checkPaymentCurrencies( $this->id))) $this->warning = $this->l('No currency set for this module'); }}

You'll notice a few lines that are not present in the module tutorial from the Developer Guide:

• $this->currencies = true;: XXX.

• $this->currencies_mode = 'radio';: Indicates the type of restrictions the module should answer to. If 'radio', then the module can only apply to one currency; if checkbox, then it can apply to any number of currencies.

• if (!sizeof(Currency::checkPaymentCurrencies($this->id))): checks whether XXX.

The install() method is where you set the different values pertaining to your module, either the needed constants, or filling up the database.mypayment.php

public function install(){ if (!parent::install() OR !$this->registerHook('payment') OR !$this->registerHook('paymentReturn') OR !Configuration::updateValue('MYPAYMENT_MERCHANT_ID', '32029e6d2bcb25cab87232d92c7c634c') OR !Configuration::updateValue('MYPAYMENT_MERCHANT_KEY', '8790eb2d0fec01c544d57e839b1b3b62') OR !Configuration::updateValue('MYPAYMENT_NO_SHIPPING', '0')) return false; return true;}

All of these values should be discarded by the uninstall() method:mypayment.php

public function uninstall(){ return (parent::uninstall() AND Configuration::deleteByName('MYPAYMENT_MERCHANT_ID') AND Configuration::deleteByName('MYPAYMENT_MERCHANT_KEY') AND Configuration::deleteByName('MYPAYMENT_NO_SHIPPING') );}

This are the basics. Not any PrestaShop module should be released without these methods. Note that these are sample configuration values; you should use only the ones necessary to your provider's needs.

Now let's jump to the specifics.

Building the hooks

As you might know already, PrestaShop's module framework is based on a system of hooks. If you are not aware of what hooks are, read Julien Breux's Understanding and using hooks.

Every PrestaShop payment modules should implement a set of predefined methods, which are called by hooks that are triggered during the payment process (front-office) or as part of the admin interface (back-office).

hookPayment() hook

This might be the most important hook, as it is always called – namely, when displaying the payment option in the check-out process. It is also the entry point to whole payment process: exploring hookPayment will take us through many PHP and TPL files, each serving a specific purpose.mypayment.php

public function hookPayment($params){ if (!$this->active) return ; global $smarty; $smarty->assign(array( 'this_path' => $this->_path, 'this_path_ssl' => Tools::getShopDomainSsl(true, true).__PS_BASE_URI__.'modules/'.$this->name.'/' ) ); return $this->display(__FILE__, 'payment.tpl');}

The whole point of this hook is to display the payment.tpl template at the right location on the frontpage (namely, the payment method choosing page).

payment.tpl file

Our hookPayment() code calls for a template file which is very simple, but should match a few essential points.

Here's a a sample template file:payment.tpl

<p class="payment_module"> <a href="{$this_path_ssl}validation.php" title="{l s='Pay with MyPayment module' mod='mypayment'}"> <img src="{$this_path}mypayment.gif" alt="{l s='Pay with MyPayment module' mod='mypayment'}" style="float:left;" /> <br />{l s='Pay with MyPayment module' mod='mypayment'} <br />{l s='A great way to pay online!' mod='mypayment'} <br style="clear:both;" /> </a></p>

Here is what PrestaShop needs in that template file:

• wrapper <P> tag with the "payment_module" class.

• a link to a PHP file, which role is to validate the payment method choice (recommended: validation.php or payment.php).

• HTML elements should feature a mod attribute, with the module's name as only value

• (optional) an image, ideally the payment provider's logo, making it easier to make a decision. Must be left aligned (style="float:left;"), and with size 86*49.

• {optional) at most two lines of description.

This template merely creates a link to validation.php, which is the first real step in putting your payment method into the payment process.

The payment method validation file: validation.php

In this step of the payment process, the customer has chosen his mean of payment. Now we need to display a form to obtain his payment details – typically, his credit card details, unless the process is different for the payment gateway provider.validation.php

<?php include(dirname(__FILE__).'/../../config/config.inc.php');include(dirname(__FILE__).'/../../header.php');include(dirname(__FILE__).'/mypayment.php'); if (!$cookie->isLogged()) Tools::redirect('authentication.php?back=order.php'); $mypayment= new MyPayment();echo $mypayment->execPayment($cart); include_once(dirname(__FILE__).'/../../footer.php'); ?>

The first lines are files which contain methods that we need for the process to continue:

• config.inc.php is PrestaShop's own configuration, with important data, such as the MySQL access identifiers.

• header.php and footer.php are the theme's header and footer file, which will build the theme for us around the payment form.

• mypayment.php is our own module's PHP file. This way, we can easily use methods that were define in that file.

We must make sure that the user is already logged, and if not, redirect him to the authentication form.

Once the user is logged with certainty, we can trigger the needed function, execPayment(), which is defined in the main module file. The $cart variable is handled by PrestaShop.

Here is a sample execPayment() method:mypayment.php

public function execPayment($cart){ if (!$this->active) return; global $cookie, $smarty; $smarty->assign(array( 'this_path' => $this->_path, 'this_path_ssl' => (Configuration::get('PS_SSL_ENABLED')?'https://':'http://') .htmlspecialchars($_SERVER['HTTP_HOST'], ENT_COMPAT,'UTF-8') .__PS_BASE_URI__.'modules/'.$this->name.'/') ); return $this->display(__FILE__, 'payment_execution.tpl');}

The point of execPayment() is to:

• assert that the module is indeed active.

• assign values to the Smarty engine, pertaining to the module's path.

• display the payment_execution.tpl template file.

payment_execution.tpl

hookPaymentReturn() hook

Another essential hook, hookPaymentReturn() is called

public function hookPaymentReturn($params){ if (!$this->active) return ; return $this->display(__FILE__, 'confirmation.tpl');}

getContent() hook

The getContent() hook is specifically triggered when the user clicks on the module's "Configure" link. Thus, the method should feature all the interface and methods calls necessary to have the user configure the payment gateway properly. If your module doesn't need configuring, then this method is not necessary.

***

Basic modules can feature the whole configuration page within the getContent() method. For more complexes pages, it is recommended to separate the configuration code to another page with its own object and methods. for instance :mypayment.php

public function getContent(){ include(_PS_MODULE_DIR_.$this->name.'/settings.php'); $mypaymentSettings = new MyPaymentSettings(); return $mypaymentSettings->home();}

execPayment() hook

hookOrderConfirmation() hook

preparePayment() hook

validate() hook