Wiki guide

[ruilong]

Hi, since I am developing a new payment gateway for a client now, I thougt that I could spend some time on writing a quick guide on how to create modules. Please make your additions and changes to it where it's needed and then maybe we can get it into the wiki?

Step 1. Create folder.
Just create a folder with the name of the module. We will call this module cashondelivery so the folder name should be “cashondelivery” with small letters.

Step 2. Create class.
Create a new file called cashondelivery.php
In the top of the file, write the following

class CashOnDelivery extends PaymentModule
{
}

The class is now named CashOnDelivery and is an extension of the PaymentModule class (classes/paymentmodule.php) which means that all functions inside the PaymentModule class is available.

Step 3. Create Constructor

function __construct()    {
$this->name = 'cashondelivery';
$this->tab = 'Payment';
$this->version = 0.1;
$this->currencies = false;
parent::__construct();
/* The parent construct is required for translations */
$this->page = basename(__FILE__, '.php');
$this->displayName = $this->l('Cash on delivery (COD)');
$this->description = $this->l('Accept cash on delivery payments');
}

What does it do?
$this->name = 'cashondelivery';
This names the module, it’s important that it’s all small letters, so it matches folder and file name.
$this->tab = 'Payment';
This sets the tab under which the module is visible, since this is a Payment module we write Payment, but you can also name it Blocks and it will be visible in the list of the blocks modules on the modules page, or you can create your own list by naming it to anything you want.
$this->version = 0.1;
Version number of the module, it’s a good idea to always increase this as you make bugfixes or new additions, so the users now what version they have.
$this->currencies = false;
Does the payment module allow currencies restriction to be set?
parent::__construct();
/* The parent construct is required for translations */
$this->page = basename(__FILE__, '.php');
$this->displayName = $this->l('Cash on delivery (COD)');
This is the name of the module that will be displayed in the admin
$this->description = $this->l('Accept cash on delivery payments');
A short description about the module, also visible in the admin.

Installation function

function install()
{
parent::install();
$this->registerHook('payment');
$this->registerHook('paymentReturn');
}

This function is executed when the user clicks on “Install” button in admin. It’s possible to add Database modifications if needed, like configuration pre-sets or similar commands that is needed to run the module.
The code above will register the hook to be possible to execute on hook payment and paymentReturn, but you can select your own hooks here.
Some hooks that are available are
• payment (Executed when payment step I admin is reached)
• paymentReturn (Don’t know, but should be when a return is made)
• rightColumn (The Right column of the site, this is used to place blocks)
• leftColumn (Same as rightColumn, but on the left side)
• top (Top of the page)
• adminStatsModules (Start page of Stats tab)
• footer (Footer of the page)
• home (Home page, same as homefeatured products)
• orderConfirmation
• extraLeft (on product details page)
• header (Header of the html)

Now if you do some kind of database alterations in the install function, it’s a good idea to clean up these changes when the user clicks uninstall, do do this, add a function called “uninstall”
It could look like this

function uninstall()
{
if (!Configuration::deleteByName('NAME OF CONFIG VARIABLE') OR !parent::uninstall())
return false;
return true;
}

What you need to add now, is the code that is executed when the hook is called, different hooks use different names on the functions, for paymentHook, it should be named hookPayment($params) so the code we add next is

function hookPayment($params)
{
global $smarty;
foreach ($params['cart']->getProducts() AS $product)
if (Validate::isUnsignedInt(ProductDownload::getIdFromIdProduct(intval($product['id_product']))))
return false;
$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.tpl');
}

The variable $params that is passed to the function call is used to get information from the system, like cart, cookie information and such.
global $smarty; lets you access the smarty commands inside the function i.e. call the tpl file and passing information to the tpl compilation.
$smarty->assign(array(‘VARIABLE’ => value, ‘VARIABLE 2’ => value2));
This is used to pass information to the tpl file, like special variable to display to the user.
return $this->display(__FILE__,’payment.tpl’); this is the call that will execute the tpl file inside the folder and return the html to the page renderer.
Since we also added the hook paymentReturn, we need a function for displaying that data also, so we add

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

Now the class file is completed, and we move on to the next step.

[ruilong]

Step 4. Create payment.tpl
Start by creating a new file called payment.tpl and paste the following code to it.

{l s='Pay with cash on delivery (COD)' mod='cashondelivery'}

{l s='You pay for the merchandise upon delivery' mod='cashondelivery'}

The above code is regular html with a few exceptions. Remember in the class file and hookPayment function we added some variables to the smarty with $smarty->assign? These values are now access by {$this_path_ssl} and {$this_path}. Note that all text in entered in english and by using the function ls? {ls=’TEXT TO DISPLAY’ mod=’YOUR MODULE NAME’}
Now, what happens here? Well, it’s just displaying a link to validation.php so in the next step we are going to create validation.php and execute some functions to save the order.

[ruilong]

Step 5. Validation.php
Create a new file in the folder and name it validation.php
The following code should be added

include(dirname(__FILE__).'/../../config/config.inc.php');
include(dirname(__FILE__).'/../../header.php');
include(dirname(__FILE__).'/cashondelivery.php');
$confirm = Tools::getValue('confirm');
/* Validate order */
if ($confirm)
{
$cashOnDelivery = new CashOnDelivery();
$total = floatval(number_format($cart->getOrderTotal(true, 3), 2, '.', ''));
$cashOnDelivery->validateOrder(intval($cart->id), _PS_OS_PREPARATION_, $total, $cashOnDelivery->displayName);
$order = new Order(intval($cashOnDelivery->currentOrder));
Tools::redirectLink(__PS_BASE_URI__.'order-confirmation.php?id_cart='.intval($cart->id).'&id;_module='.intval($cashOnDelivery->id).'&id;_order='.intval($cashOnDelivery->currentOrder));
}
else
{
/* or ask for confirmation */ 
$smarty->assign(array('currency_default' => new Currency(Configuration::get('PS_CURRENCY_DEFAULT')),'total' => number_format($cart->getOrderTotal(true, 3), 2, '.', ''),'this_path_ssl' => (Configuration::get('PS_SSL_ENABLED') ? 'https://' : 'http://').htmlspecialchars($_SERVER['HTTP_HOST'], ENT_COMPAT, 'UTF-8').__PS_BASE_URI__.'modules/cashondelivery/'));
$smarty->assign('this_path', __PS_BASE_URI__.'modules/cashondelivery/');
echo Module::display(__FILE__, 'validation.tpl');
}
include(dirname(__FILE__).'/../../footer.php');

Let’s have a look at the code
include(dirname(__FILE__).'/../../config/config.inc.php');
include(dirname(__FILE__).'/../../header.php');
include(dirname(__FILE__).'/cashondelivery.php');
These lines calles config, header and the cashondelivery class we created earlier, config and header is needed by Prestashop for displaying the page correctly. At the end of the code we also call footer.php, this is also needed if you want to display something to the front-end user.
This line

$cashOnDelivery->validateOrder(intval($cart->id), _PS_OS_PREPARATION_, $total, $cashOnDelivery->displayName);

Makes a call to cashOnDelivery class that we created earlier and the function validateOrder, now as you remember the validateOrder is not inside the cashOnDelivery but can be found in classes/paymentmodule.php, but it’s possible to access it thanks to the fact that cashOnDelivery class is an extension of paymentmodule. validateOrder is what creates the order.
The rest of the code is a redirect and the display of the confirmation page, the confirmation page is called in the same way as payment.tpl, by assigning values to the $smarty and caling the validation.tpl by “echo Module::display(__FILE__,’validation.tpl’);”

[ruilong]

Step 6. Create confirmation page
Now since we have created a call for validation.tpl we also need to create that file, start by creating a new file and name it validation.tpl.
And copy this code to it

{capture name=path}{l s='Shipping'}{/capture}
{include file=$tpl_dir./breadcrumb.tpl}
{l s='Order summation' mod='cashondelivery'}
{assign var='current_step' value='payment'}
{include file=$tpl_dir./order-steps.tpl}
{l s='Cash on delivery (COD) payment' mod='cashondelivery'}
<form action="{$this_path_ssl}validation.php" method="post">
<input type="hidden" name="confirm" value="1" />



{l s='You have chosen the cash on delivery method.' mod='cashondelivery'}



{l s='The total amount of your order is' mod='cashondelivery'}
{convertPriceWithCurrency price=$total currency=$currency_default}









{l s='Please confirm your order by clicking \'I confirm my order\'' mod='cashondelivery'}.



{l s='Other payment methods' mod='cashondelivery'}
<input type="submit" name="submit" value="{l s='I confirm my order' mod='cashondelivery'}" class="exclusive_large" />

</form>

As you can see, this follow the same scheme as the payment.tpl, text is printed by {ls=’TEXT’ mod=’YOU MODULE NAME’} and variables assigned to the smarty object are printed by {$VARIABLE}
Now it’s done, you have created a “cash on delivery” module. By using the above method to create modules, you should be able to create payment modules for most of the payment gateways relatively easy.

[ruilong]

Hooks and functions
Different hooks have different function names that are called when they need to be executed. Below I will list a few by hookname (function name)
• payment (hookPayment)
• paymentReturn (hookPaymentReturn)
• rightColumn (hookRightColumn)
• leftColumn (hookLeftColumn)
• top (hookTop)
• adminStatsModules (hookAdminStatsModules)
• footer (hookFooter)
• home (hookHome)
• orderConfirmation (hookOrderConfirmation)
• extraLeft (hookExtraLeft)
• header ()
• authentication (hookAuthentication)
• createAccount (hookCreateAccount)

[bluewings]

thanks ,it's very easy to understand

[bluewings]

A new problem comes to me . When i finish all of this , how can i install the module

[baralitetill]

create a folder in your modules folder with the name of your module

[ruttroh]

I found this very helpful and easy to follow. Thank you.

[ding]

very useful,thx

[secondprof51]

Thnaks for the helpful post. I have been searching for this since a while. Thanks once agina

[shacker]

Very usefull.

[Celeborn]

Good guide, thank you for your time!

[karisa.ro]

thx a lot...

[vietnam]

Very useful . I`m traing to write something like this, to explain what the classes do .

[EGBee]

Very helpful bro.. Many thanks! This is simply for Cash on Delivery but how can i create a Payment Gateway module that redirects to my API provider (Bank) and then return back to the site when the transaction is success?

[Baidi]

Can we modify this to Custom Payment module?

 

I mean, the module is useful for any users to create their own payment method such as Bank Transfer or Cash Deposit.