30 April 2015

How does Magento’s payment processing work?

Magento is one of the biggest and most popular e-commerce platforms available. Due to its immense popularity with both individual and enterprise customers, it’s one of the most requested platforms for payment gateway integration. This blog is based on Magento’s Community Edition v1.9.

What is Magento?

Magento is a highly customisable e-commerce platform and content management system that is primarily used to build online storefronts and web sites for selling merchandise. Common e-commerce features, such as shopping carts and inventory management, are available in Magento.

Magento is written using the PHP programming language, and leverages elements of the Zend framework and the model-view-controller architecture. Magento runs on the MySQL relational database, and Magento schemes and tables are included in the Magento installation package.

Object-oriented programming concepts are inherent in the Magento design, allowing for maximum flexibility and extensibility of the software components that results in the ability to design and implement customised web sites.

Transaction types

Each online payment, be it with a debit or a credit card, requires your data to be passed through a payment gateway. In this payment gateway, a couple of options have been preselected. The most important option is the initial transaction type. In general, there are three transaction types used to process your payment data:

  • Authorise – a transaction type in which you request a certain amount from the cardholder’s account to be put on hold. The money is not immediately transferred to your own account, but the selected amount is put on hold for potential future collection. The most frequent use of this transaction type can be found with merchants shipping physical goods. Many companies prefer to reserve the amount from the customer, then check their inventory and if shipping is possible then finally proceed to send the physical goods to the customer. This way, they avoid dealing with refunds and returns in general if, for example, the ordered product turns out to be out of stock or that they can’t ship this product for some reason.
  • Capture – a transaction type that does not require customer data, it simply transfers an authorised amount to your account. You can’t change the amount or the initial parameters; you can only collect the previously authorised amount. Used frequently with physical retailers in conjunction with a previous authorisation.
  • Sale – this transaction type is a combination of the abovementioned Authorise & Capture transaction types. It is most popular with non-physical or digital goods and services. With more and more electronic goods being sold over the Internet, this transaction type is becoming more popular. When you purchase a song, for example, it’s available to you immediately (after successful payment), which means there’s no point in going through the process of authorising and then capturing a few minutes later.

It’s worth noting that there also are other transaction types that are suitable for other workflows. For example, a subscription service would prefer to bill their customers monthly instead of requesting credit card details every time their customers renew their subscription.

Magento’s basic structure

Before we begin, we make the assumption that you’re familiar with the Magento structure and architecture. If not, please click here for more information.

Below you will find a basic overview of Magento’s order workflow. The scope spans from the first visit by the customer to the successful completion of the order. It’s important to note that this diagram does not represent every possible outcome or exception. For example, asynchronous (3D-Secure) payments are not represented in this diagram.

Magento's Payment Workflow

Magento comes with a few minimal generic classes for handling payments:

  • Mage_Payment_Model_Method_Abstract
    – abstract class, used as a base for every payment method, provides generic functionality for payment methods like credit cards, cheques, cash on delivery, etc. It provides dummy functions for you to override in order to implement your own custom structure. It defines the variables you need to change in order to “tell” Magento, what functionalities your module has. For example, whether it supports Authorisation or Capture, whether you can refund with your module, etc.
  • Mage_Payment_Model_Method_Cc
    – extendable class, providing useful functions for a credit card (Cc) based payment method. It has basic functionality like assigning the customer data to internal variables, providing credit card validation (type support, luhn check, expiration check) and access to Magento’s 3D-Secure client for Centinel.
  • Mage_Payment_Model_Method_Ccsave
    – this is a super-set of the Mage_Payment_Model_Method_Cc class, suitable when you want to save the customer data in your database. Normally you wouldn’t need this as payment gateways are flexible enough to prevent the headaches that come with managing saved user credit card data to your database.

Where does the payment process begin?

The Magento workflow begins with the user entering their credentials on the checkout page. Once they enter their billing/shipping address, they have to choose the payment method they want to proceed with. In order to have your payment method displayed on the list of available methods, you have to meet the following conditions:


The behaviour and structure behind this validation is ultimately left up to your payment model. You can choose to use the default behaviour or override the

method within your
, thus changing the validation structure completely. If the customer selects your payment method and enters their data, the entered data will be validated against the following default conditions:


The behaviour and structure behind this validation is ultimately left up to your payment model. You can choose to use the default behaviour or override the

methods within your
, thus changing the validation structure completely.

How is the actual payment initiated?

We are now at the verification stage. We made basic checks to ensure that we can process the requested payment and the customer is now presented with a basic overview of his order. This is their last chance to cancel. Once the customer confirms the payment, a new instance of

is created, which in short does the following:

  • it removes all nominal items;
  • it does one last verification of the billing/shipping addresses;
  • it creates a new
    Mage_Core_Model_Resource_Transaction instance
  • it adds the following objects to the newly created instance
  • Once this is all set up, every added object is being called to save its data and the order is placed.

    By placing the order,

    is invoked, which in turn collects all the data for this order. It asks your model for the transaction type you would like to perform (via
    and then calls its internal methods to setup the parameters and initialise variables before calling the
    methods of your
    respectively (Based on the configuration of your module, you might be able to Authorise/Capture only a portion of the requested price (due to insufficient funds), i.e. partial Authorisations and Captures.).

    If an error is detected at some point, an exception is communicated and this notifies Magento that something went wrong. Depending on the

    class and where the exception occurred, different structures will be applied to recover from this error.

    At this point, if everything went as expected, a new transaction is created and notifications are sent to the customer. The newly created order is in your Admin Panel and it’s waiting for an update by you or by external notifications.

    You can check our eMerchantPay Payment Gateway Module at Github. If you are interested in applying for a test account, contact our Sales team at sales@emerchantpay.com.