Stephen Gray's dev blog » payment http://blog.s-gray.com e-commerce and integrations Sun, 17 Jan 2010 09:32:20 +0000 http://wordpress.org/?v=2.8.6 en hourly 1 Magento create a custom payment method http://blog.s-gray.com/2009/11/11/magento-create-a-custom-payment-method/ http://blog.s-gray.com/2009/11/11/magento-create-a-custom-payment-method/#comments Wed, 11 Nov 2009 09:42:18 +0000 Stephen http://colourgray.wordpress.com/?p=136 I’ve been doing some work with the Magento e-commerce platform lately and my task was to create a new payment method to use during the standard checkout process.

I’ve come to the conclusion that Magento is very annoying to develop for if you know nothing about the platform. Yes the platform is open source but they also have a commercial version, therefore it seems they have tried to make it hard for you to know the complete ins and outs of the system. I.E. if something seems like too much of a task to develop, a company would likely purchase the commercial version and get it developed by the platform developers rather than do it themselves.

You also have to remember that Magento is built on top of the Zend framework, so when you are developing for it documentation does not all reside on the Magento site, you will have to look into how the Zend framework works as well.

Finally, note that by default the Magento checkout process uses AJAX to submit the form, making this a very annoying module to debug. Thankfully Magento makes it easy to log values and throw exceptions which ‘pause’ the checkout process.

After much searching online, it seems that any available tutorials for custom payment methods either don’t work, are incomplete or worked in previous versions but are now updated. I developed this using version 1.3.2.2 of Magento.

I’m writing this tutorial with the intention of it being the definitive guide to creating a custom payment method.

Prerequisites
1. Creating the module
2. Configuration through the admin
4. Payment adapter model class

Prerequisites

There are a few things you need to note now to avoid confusion later down the line.

For your module, you need the main name and a simpler alias for it. I.E. if your module was called MyPaymentMethod, your alias could be mypayment. Keep the full name and the alias in mind. The full name will be used in class and folder names but the alias will be used when referencing the module anywhere else.

For this tutorial I will be using ModuleName for the full name, modulename for the module alias, and MyModules as the module namespace.

Magento names it’s classes after their path. I.E. you are going to have a class which handles all of this payment method logic, and it’s path will be something like app/code/local/MyModules/ModuleName/Model/PaymentLogic.php. It’s class name will be MyModules_ModuleName_Model_PaymentLogic. Remember this as it helps when trying to figure out where to find a referenced class etc.

Creating the module

OK so first we need to create the initial module and make sure Magento knows that it exists. Lets create the folder structure;

?View Code TEXT
1
2
3
4
5
6
7
8

app/
---- code/
-------- local/
------------ #1 MyModules
---------------- #2 ModuleName
-------------------- #3 Block
-------------------- #4 etc
-------------------- #5 Model

#1 In Magento terms, MyModules would be the module’s namespace. I.E. you’ll likely have one namespace for multiple modules. The namespace can be called anything but should be UpperCamelCase. If you take a look in app/code/core you will see a folder called Mage – this is the namespace for most of Magento’s core modules.

#2 This is your actual module name. This should be UpperCamelCase.

#3 This folder is used to contain block classes that are used in your module.

#4 This is where your module configuration will go.

#5 The class that handles all of your payment gateway logic will go here. This is also a good place to put any third party libraries or custom classes you may use.

config.xml

Create the file config.xml in app/code/local/MyModules/ModuleName/config. This file is the main module configuration file. For now, you want it to look like this;

?View Code XML
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

<?xml version="1.0" encoding="UTF-8"?>
<config>
 
    <!--
        register the full module name and it's
        version
    -->
    <modules>
        <MyModules_ModuleName>
            <version>0.1.0</version>
        </MyModules_ModuleName>
    </modules>
 
    <!--
        global module configuration
    -->
    <global>
 
        <!--
            register the module's model group
            note that we use the module's alias
            mentioned in the prerequisites
        -->
        <models>
            <modulename>
                <class>MyModules_ModuleName_Model</class>
            </modulename>
        </models>
 
        <!--
            set which resources the module will
            use when setting up, writing to the db
            and reading from the db. we're going
            to use the core connections.
        -->
        <resources>
            <modulename_setup>
                <setup>
                    <module>MyModules_ModuleName</module>
                </setup>
                <connection>
                    <use>core_setup</use>
                </connection>
            </modulename_setup>
            <modulename_write>
                <connection>
                    <use>core_write</use>
                </connection>
            </modulename_write>
            <modulename_read>
                <connection>
                    <use>core_read</use>
                </connection>
            </modulename_read>
        </resources>
    </global>
</config>

Now the module has it’s basic configuration but Magento doesn’t care because the module is not yet registered.

MyModules_All.xml

Create the file MyModules_All.xml in app/etc/modules. This is where we register the module. You want this file to look like this;

?View Code XML
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<?xml version="1.0"?>
<config>
    <modules>
        <MyModules_ModuleName>
            <active>true</active>
 
            <!--
                for now we're telling the system that
                this module is just local, it's not a core
                or community module and resides in
                app/code/local.
            -->
            <codePool>local</codePool>
        </MyModules_ModuleName>
    </modules>
</config>

The module is now registered and Magento knows about it. But what can you do with it? Well, this is a payment method module, so we need to register it as a usable payment method. We also need to be able to set what fields are configured in the administration section that can be used when authenticating with the payment gateway etc.

Configuration through the admin

system.xml

Create the file system.xml in app/code/local/MyModules/ModuleName/etc. Here we will tell Magento to have a new section in the payment methods configuration area for configuring this module. We also set what fields we want there. For every field, we have an element like this;

?View Code XML
1
2
3
4
5
6
7
8
9

<field_name translate="label">
    <label>Field name</label>
    <frontend_type>field type</frontend_type>
    <source_model>field source model class</source_model>
    <sort_order>1</sort_order>
    <show_in_default>1</show_in_default>
    <show_in_website>1</show_in_website>
    <show_in_store>0</show_in_store>
</field_name>

As you will see below. To start with, have the file looking like this;

?View Code XML
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

<?xml version="1.0"?>
<config>
    <sections>
 
        <!--
            here we're telling the system we
            we want to add a new config section
            in the payment method area
        -->
        <payment>
            <groups>
                <modulename translate="label" module="paygate">
 
                    <!--
                        human readable module name
                        which appears as the name of the
                        payment method in the admin section
                    -->
                    <label>My Payment Module</label>
 
                    <!--
                        set where this method should appear
                        in comparison to the other methods
                        within the admin
                    -->
                    <sort_order>670</sort_order>
                    <show_in_default>1</show_in_default>
                    <show_in_website>1</show_in_website>
                    <show_in_store>0</show_in_store>
                    <fields>
 
                        <!--
                            you need this field if you want the user to
                            be able to disable/enable this payment
                            method. leave this out if you don't want
                            this to be optional
                        -->
                        <active translate="label">
                            <label>Enabled</label>
                            <frontend_type>select</frontend_type>
 
                            <!--
                                we want to use the standard Magento
                                yes/no select options
                            -->
                            <source_model>adminhtml/system_config_source_yesno</source_model>
                            <sort_order>1</sort_order>
                            <show_in_default>1</show_in_default>
                            <show_in_website>1</show_in_website>
                            <show_in_store>0</show_in_store>
                        </active>
 
                        <!--
                            the below two fields are an example
                            of fields you may need if integrating with
                            a payment gateway's API. you will see how
                            to retrieve these values in your code later
                        -->
                        <api_key translate="label">
                            <label>API Key</label>
                            <frontend_type>text</frontend_type>
                            <sort_order>2</sort_order>
                            <show_in_default>1</show_in_default>
                            <show_in_website>1</show_in_website>
                            <show_in_store>0</show_in_store>
                        </api_key>
                        <api_secret translate="label">
                            <label>API Secret</label>
                            <frontend_type>text</frontend_type>
                            <sort_order>3</sort_order>
                            <show_in_default>1</show_in_default>
                            <show_in_website>1</show_in_website>
                            <show_in_store>0</show_in_store>
                        </api_secret>
 
                        <!--
                            having this field here allows the user
                            to set whether we want payments to be
                            authorised or authorised AND captured
                            if you don't want the user to choose you
                            can leave this field out
                        -->
                        <payment_action translate="label">
                            <label>Payment Action</label>
                            <frontend_type>select</frontend_type>
 
                            <!--
                                we're using the source from the paygate
                                module as it has the options we want. this
                                is safe because the paygate module is a core
                                Magento module and therefore will be there
                                with any default install. if it makes you feel
                                safer you can create your own field source model
                                but that isn't covered in this tutorial
                            -->
                            <source_model>paygate/authorizenet_source_paymentAction</source_model>
                            <sort_order>4</sort_order>
                            <show_in_default>1</show_in_default>
                            <show_in_website>1</show_in_website>
                            <show_in_store>0</show_in_store>
                        </payment_action>
 
                        <!--
                            what do you want the status to be of
                            new orders made using this payment
                            method?
                        -->
                        <order_status translate="label">
                            <label>New order status</label>
                            <frontend_type>select</frontend_type>
                            <source_model>adminhtml/system_config_source_order_status_processing</source_model>
                            <sort_order>5</sort_order>
                            <show_in_default>1</show_in_default>
                            <show_in_website>1</show_in_website>
                            <show_in_store>0</show_in_store>
                        </order_status>
 
                        <!--
                            this field lets the user choose the
                            name of the payment method as it
                            appears to the normal user on your site
                        ->
                        <title translate="label">
                            <label>Title</label>
                            <frontend_type>text</frontend_type>
                            <sort_order>6</sort_order>
                            <show_in_default>1</show_in_default>
                            <show_in_website>1</show_in_website>
                            <show_in_store>0</show_in_store>
                        </title>
                    </fields>
                </modulename>
            </groups>
        </payment>
    </sections>
</config>

Default configuration values

Before we go and test this, we should set some default values for the configuration fields we just created.

Open app/code/local/MyModules/ModuleName/etc/config.xml and add the following section;

?View Code XML
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

<config>
 
    ...
 
    <default>
        <payment>
            <modulename>
 
                <!--
                    is this payment method enabled?
                -->
                <active>0</active>
 
                <!--
                    this is where we tell the system what
                    class to use to handle all of the payment
                    logic. we call this class the payment
                    adapter model class. you can change the
                    paymentLogic bit to be what you want
                    but it has to be lowerCamelCase and
                    the class name will have to be changed later
                    on as you will see
                -->
                <model>modulename/paymentLogic</model>
 
                <order_status>pending</order_status>
                <title>Credit Card (My Payment Method)</title>
 
                <api_key>1234</api_key>
                <api_secret>1234</api_secret>
 
                <!--
                    this is the default set of allowed credit
                    card types. leave this as it is for now
                -->
                <cctypes>AE,VI,MC,DI,SS</cctypes>
 
                <!--
                    this should be authorize or authorize_capture
                    you can probably guess that authorize just
                    authorizes the payment but authorize_capture
                    processes it as well
                -->
                <payment_action>authorize_capture</payment_action>
 
                <!--
                    this field is used to say whether you only
                    want this method to be used for certain
                    countries but that is not covered by this
                    tutorial
                -->
                <allowspecific>0</allowspecific>
            </modulename>
        </payment>
    </default>
</config>

Of course, if you have any of the fields in the above file configurable as set in system.xml, the user set value will be used.

Test progress so far

OK so now if you log into the Magento administration and go to System -> Configuration -> Payment methods you should see your new payment method somewhere in that list.

If you enable it it should then also be available if you checkout on your site as normal. Don’t complete any orders using it yet as there will be problems because we haven’t finished! We still need to create the most important part, the class which will handle all of the logic.

If you don’t see your payment method, please make sure you have completed the above steps correctly. Check for any simple mistakes and try clearing the Magento cache as well. The basic rule is; if it doesn’t appear in the payment method list in the administration section, there’s a problem with system.xml. If it doesn’t appear as a usable payment method when checking out, there could be a problem with config.xml.

Payment adapter model class

Create the file PaymentLogic.php in app/code/local/MyModules/ModuleName/Model/. This is where we will put all of our payment gateway logic. First, the contents of the file;

?View Code PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

<?php
class CompanyName_NewModule_Model_PaymentLogic extends Mage_Payment_Model_Method_Cc
{
    /**
     * unique internal payment method identifier
     */
    protected $_code = 'newmodule';
 
    /**
     * this should probably be true if you're using this
     * method to take payments
     */
    protected $_isGateway               = true;
 
    /**
     * can this method authorise?
     */
    protected $_canAuthorize            = true;
 
    /**
     * can this method capture funds?
     */
    protected $_canCapture              = true;
 
    /**
     * can we capture only partial amounts?
     */
    protected $_canCapturePartial       = false;
 
    /**
     * can this method refund?
     */
    protected $_canRefund               = false;
 
    /**
     * can this method void transactions?
     */
    protected $_canVoid                 = true;
 
    /**
     * can admins use this payment method?
     */
    protected $_canUseInternal          = true;
 
    /**
     * show this method on the checkout page
     */
    protected $_canUseCheckout          = true;
 
    /**
     * available for multi shipping checkouts?
     */
    protected $_canUseForMultishipping  = true;
 
    /**
     * can this method save cc info for later use?
     */
    protected $_canSaveCc = false;
 
    /**
     * this method is called if we are just authorising
     * a transaction
     */
    public function authorize (Varien_Object $payment, $amount)
    {
 
    }
 
    /**
     * this method is called if we are authorising AND
     * capturing a transaction
     */
    public function capture (Varien_Object $payment, $amount)
    {
 
    }
 
    /**
     * called if refunding
     */
    public function refund (Varien_Object $payment, $amount)
    {
 
    }
 
    /**
     * called if voiding a payment
     */
    public function void (Varien_Object $payment)
    {
 
    }
}
?>

If the payment_action option of ‘Authorise’ has been selected, then only the authorize() method will be called and no payment can be taken automatically. If however the payment_action ‘Authorise and Capture’ was selected, then only the capture() method will be called and that method should probably authorise the payment before capturing the funds. A bit confusing and not explained anywhere but that’s how it works!

The Varien_Object $payment object holds all data to do with the transaction and also the order.

So that’s it! That’s the method I used to add a custom payment gateway to Magento. Please note: I don’t work with Magento anymore so if you have a complicated question which requires looking into Magento code, I probably won’t be able to answer it – but ask anyway just in case!

]]> http://blog.s-gray.com/2009/11/11/magento-create-a-custom-payment-method/feed/ 4