For people who are running a successful business, I have always felt that there is one rule that should surpass them all. “Always make it as easy as possible for customers to give you money.” After all, if you are being honest with yourself, money is the core of why you are in business. With that rule in mind, when you are creating an eCommerce store in Magento, it stands to reason that having a solid and reliable way to collect money from customers should be the number one priority. But, whether you are writing a new payment module or modifying / debugging a pre-existing module, this can also be the most intimidating task as well. But it doesn’t have to be. Magento payment processing, while sophisticated, it is not complicated and is certainly not difficult to learn with a little bit of research and practice.
Most people who shop online use their credit cards. There is a whole slew of reasons and studies to back that up (and I am positive that this will not be true forever), but suffice it to say, you cannot run a successful eCommerce store in the current marketplace and not accept major credit cards. So, in the spirit of making it easy for people to give you money, I want to focus on the foundations of a credit card processing to help you debug, modify or even write your own. Before you read too far, you should make sure that you have a basic understanding of the creation of modules and how modules work in Magento. I will only be discussing the setup of the custom components required for credit card payments.
1. The Basics
A credit card payment module has all of the same basic building blocks as any other module. This of course includes a module declaration xml file in the app/etc/modules folder and you also need a module config xml file in the module’s etc folder. This file will include a section that will outline to Magento that the module is a payment method, and some basic default configuration values that descrive how payments will be processed. This payment configuration section belongs in the default configuration. Below I have outlines some of the main configuration settings that you will probably need to use.
- <active> – Fairly self-explanatory. Is the module active in the system or not.
- <model> – This defines where the Adapter Model is declared (explained below).
- <order_status> – The default status that is applied to all new orders.
- <title> – This is the text that is displayed to the customer in the event that there are multiple payment methods being used on the site.
- <cctypes> – Which credit cards will the module accept.
- AE – American Express
- VI – Visa
- MC – Master Card
- DI – Discover Card
- You can define any configuration value that your module will need in this section. For example, you may have an api key, or a username and password for the gateway.
The best example I can think to show you is in the Magento codebase in app/code/core/Mage/Payment/etc/config.xml
Related: A Guide To Using Urls in Magento
2. The Adapter Model
The most important portion of the payment module is the Adapter Model (defined above in the <model> tag). This model will be called by Magento to process the actual payment. For a credit card module, this model will extend Mage_Payment_Model_Method_Cc which extends Mage_Payment_Model_Method_Abstract. Mage_Payment_Model_Method_Abstract contains the structure that all Magento payment methods require to function, and Mage_Payment_Model_Method_Cc contains some additional requirements for processing credit card payments.
How you write this model is completely up to you. Mage_Payment_Model_Method_Abstract and Mage_Payment_Model_Method_Cc each contain some default variable values that you can override based on the specific requirements of your payment gateway. Inside of Mage_Payment_Model_Method_Abstract there are 2 methods declared that need to be overwritten in your Adapter Model: authorize() and capture(). These are the methods that Magento will call in order to facilitate communication with your gateway. In the administration setting for your payment module (explained in more detail below), if you have selected Authorize Only, the authorize() method will be called during the checkout process. If you specify Authorize and Capture in the setting for the payment module, then only capture() will be called. Keep that in mind when reviewing the requirements from your payment gateway. You MAY need to call authorize() from capture(). Assuming that the module is setup correctly, these 2 methods would normally be the starting point for any debugging that may need to be done. If that doesn’t pan out, I would double check the settings described above.
Related: The Magento Upgrade Guide
The last portion that needs to be taken care of is the configuration options on the back end of the site. This will allow administrators of the website to override the default values that were defined in the payment configuration section of the module’s config xml file. Creation of the administration section for the module is included in the system.xml file in the module’s etc folder. This is a vital section as it allows the administrator to enable or disable the module, set the title for the end user for the method, the new order status for the module, and any credentials and personalized settings that the gateway requires. The best example of one of these files is included in the Magento codebase. The file is located in app/code/core/Mage/Payment/etc/system.xml.
Your First Payment Method
Writing your first payment module can seem like a daunting task. It is one of the most important components of any eCommerce site but it doesn’t need to be the most complex. Take a look at Mage_Payment_Model_Method_Abstract and Mage_Payment_Model_Method_Cc and some of the built in payment methods that come with Magento. There is a wealth of information already in the codebase with functioning examples. With practice, testing, some research and good old fashion good code, it is really not that difficult to debug, or even create your own credit card payment method. Magento does not do all of the work for you, but it does enough that if you follow the conventions you should be able to quickly and reliably make it easy for people to give you money. What more could you ask for in life?