Create a Custom Payment Method Module in Magento: Part One

Being a successful e­-commerce framework, Magento provides lots of payment methods in the core itself. However, you can also create a custom payment method extension to plug in your choice of payment gateway, if it's not already available. 

In this series, we're going to look at the process of creating a custom payment method extension. In this article, we'll start with the back­-end section by setting up a configuration for our custom payment method.

I assume that you're familiar with basic module creation process in Magento. If not, you can refer to this article on custom module development.

A Glance at the File Setup

We'll create a custom module "Custompaymentmethod", so let's have a look at the list of files required for the back­-end configuration setup.

• 
  app/etc/modules/Envato_All.xml: It's a file used to enable our custom module.


• 
  app/code/local/Envato/Custompaymentmethod/etc/config.xml: It's a module configuration file in which we'll declare our custom payment method.


• 
  app/code/local/Envato/Custompaymentmethod/etc/system.xml: It's a system configuration file in which we'll set up configuration options for our custom payment method.


• 
  app/code/local/Envato/Custompaymentmethod/sql/custompaymentmethod_setup/install­-1.0.0.0.php: It's an SQL file which we'll use to create custom fields for our custom payment method.

Create Files and Folders

First, we need to create a module enabler file. Create a file "app/etc/modules/Envato_All.xml" and paste the following contents in that file. We've used "Envato" as our module namespace and "Custompaymentmethod" as our module name. It'll enable our "Custompaymentmethod" module by default.

<?xml version="1.0"?>
<config>
  <modules>
    <Envato_Custompaymentmethod>
      <active>true</active>
      <codePool>local</codePool>
      
      <depends>
        <Mage_Payment />
      </depends>
    </Envato_Custompaymentmethod>
  </modules>
</config>

Nothing fancy here—we've just declared our module under the "local" code pool. However, the important thing to note here is that we've declared that our extension depends on the core "Mage_Payment" extension.

Moving ahead, create an "app/code/local/Envato/Custompaymentmethod/sql/custompaymentmethod_setup/install­-1.0.0.0.php" file with the following contents.

<?php
$installer = $this;
$installer->startSetup();
$installer->run("
ALTER TABLE `{$installer->getTable('sales/quote_payment')}` 
ADD `custom_field_one` VARCHAR( 255 ) NOT NULL,
ADD `custom_field_two` VARCHAR( 255 ) NOT NULL;
 
ALTER TABLE `{$installer->getTable('sales/order_payment')}` 
ADD `custom_field_one` VARCHAR( 255 ) NOT NULL,
ADD `custom_field_two` VARCHAR( 255 ) NOT NULL;
");
$installer->endSetup();

It's an install file of our module which will create "custom_field_one" and "custom_field_two" fields in the payment related tables.

Next, we need to create a module configuration file. Create "app/code/local/Envato/Custompaymentmethod/etc/config.xml" and paste the following contents in that file.

<?xml version="1.0"?>
<config>
  <modules>
    <Envato_Custompaymentmethod>
      <version>1.0.0.0</version>
    </Envato_Custompaymentmethod>
  </modules>

  <global>
    <fieldsets>
      <sales_convert_quote_payment>
        <custom_field_one>
          <to_order_payment>*</to_order_payment>
        </custom_field_one>
        <custom_field_two>
          <to_order_payment>*</to_order_payment>
        </custom_field_two>
      </sales_convert_quote_payment>
    </fieldsets>
    
    <helpers>
      <custompaymentmethod>
        <class>Envato_Custompaymentmethod_Helper</class>
      </custompaymentmethod>
    </helpers>

    <blocks>
      <custompaymentmethod>
        <class>Envato_Custompaymentmethod_Block</class>
      </custompaymentmethod>
    </blocks>
        
    <models>
      <custompaymentmethod>
        <class>Envato_Custompaymentmethod_Model</class>
      </custompaymentmethod>
    </models>

    <resources>
      <custompaymentmethod_setup>
        <setup>
          <module>Envato_Custompaymentmethod</module>
        </setup>
      </custompaymentmethod_setup>
    </resources>
  </global>

  <default>
    <payment>
      <custompaymentmethod>
        <active>1</active>
        <model>custompaymentmethod/paymentmethod</model>
        <order_status>pending</order_status>
        <title>CustomPaymentMethod</title>
        <allowspecific>0</allowspecific>
        <payment_action>sale</payment_action>
      </custompaymentmethod>
    </payment>
  </default>
  
  <frontend>
    <routers>
      <custompaymentmethod>
        <use>standard</use>
        <args>
          <module>Envato_Custompaymentmethod</module>
          <frontName>custompaymentmethod</frontName>
        </args>
      </custompaymentmethod>
    </routers>
  </frontend>
</config>

Let's have a look at some of the important elements in a "config.xml" file. In the front­-end checkout process, when a user selects our custom payment method, we'll show two text boxes for inputting the information. These are just for the purpose of demonstrating the use of custom fields in a front­-end payment method. 

We'll see that in detail a bit later, but for now just assume that we need to save custom fields related to our custom payment method during the order creation. The <fieldsets> and <sales_convert_quote_payment> tags are exactly for that purpose—they'll tell Magento to save these fields as well with order information.

Next, we've declared the usual helpers, blocks and models related tags, which we'll implement in the other parts of this series. Further, we've declared resources for our custom module using the <custompaymentmethod_setup> tag. Recall the "install­-1.0.0.0.php" file we mentioned earlier. Yes, it's exactly related to that install file. Magento will detect this file, and run the necessary SQL install scripts for our module.

Finally, we plug in our custom payment method using the <custompaymentmethod> tag under the <payment> tag. Under that tag, we've set up the default configuration for our payment method like "active", "order_status", "payment_action", etc. At the end of the file, we've declared a front­-end router for our module, which will be implemented in the other parts of this series.

Let's move on to the next important file, the "system.xml" file. Create a file "app/code/local/Envato/Custompaymentmethod/etc/system.xml" and paste the following contents in that file.

<?xml version="1.0"?>
<config>    
  <sections>
    <payment>
      <groups>
        <custompaymentmethod translate="label" module="custompaymentmethod">
          <label>CustomPaymentMethod Module</label>
          <sort_order>1000</sort_order>
          <show_in_default>1</show_in_default>
          <show_in_website>1</show_in_website>
          <show_in_store>0</show_in_store>
          <fields>
            <title translate="label">
              <label>Title</label>
              <frontend_type>text</frontend_type>
              <show_in_default>1</show_in_default>
              <show_in_website>1</show_in_website>
              <show_in_store>0</show_in_store>
              <sort_order>1</sort_order>
            </title>
            <active translate="label">
              <label>Enabled</label>
              <frontend_type>select</frontend_type>
              <source_model>adminhtml/system_config_source_yesno</source_model>
              <show_in_default>1</show_in_default>
              <show_in_website>1</show_in_website>
              <show_in_store>0</show_in_store>
              <sort_order>2</sort_order>
            </active>
            <order_status translate="label">
              <label>New order status</label>
              <frontend_type>select</frontend_type>
              <source_model>adminhtml/system_config_source_order_status</source_model>
              <show_in_default>1</show_in_default>
              <show_in_website>1</show_in_website>
              <show_in_store>0</show_in_store>
              <sort_order>3</sort_order>
            </order_status>
            <allowspecific translate="label">
              <label>Payment from applicable countries</label>
              <frontend_type>allowspecific</frontend_type>
              <source_model>adminhtml/system_config_source_payment_allspecificcountries</source_model>
              <show_in_default>1</show_in_default>
              <show_in_website>1</show_in_website>
              <show_in_store>1</show_in_store>
              <sort_order>4</sort_order>
            </allowspecific>
            <specificcountry translate="label">
              <label>Payment from Specific countries</label>
              <frontend_type>multiselect</frontend_type>
              <source_model>adminhtml/system_config_source_country</source_model>
              <show_in_default>1</show_in_default>
              <show_in_website>1</show_in_website>
              <show_in_store>1</show_in_store>
              <sort_order>5</sort_order>
            </specificcountry>
          </fields>
        </custompaymentmethod>
      </groups>
    </payment>
  </sections>
</config>

In this file, we simply declare configurable fields for our custom payment method. Go ahead and enable the module from the back­-end. Go to System > Configuration > Sales > Payment Methods, which will list all the payment methods. You should see "CustomPaymentMethod Module" listed as one of the payment methods!

Conclusion

Today, we've just looked at the initial back-end configuration setup for our custom payment method. In the upcoming articles of this series, we'll see its front-end counterpart. Don't forget to share your thoughts using the feed below.