Adding a Custom Payment Method to Expresso Store in ExpressionEngine

During the discovery phase of a recent website project, we learned the client used "Sage" for their merchant account and payment processing. Planning on using ExpressionEngine, I looked up which Payment Gateways Expresso Store supported, and read "Sage Pay Direct" and "Sage Pay Server" - and (incorrectly) concluded that "Expresso Store supports Sage" and went on with the building of the website. A little while later, I was at the step to enable their merchant account and learned of my blunder. The client uses Sage Processing Solutions (a US service) and Expresso Store (via the Omnipay framework) supports "Sage Pay" - the UK company with the same parent... but not the same payment system. Very different architecture, very different methods of integration.

Thankfully, Expresso Store supports the adding on of your own custom Payment Method very easily, and we were able to keep the project on track with minimal effort.

Overview:

Expresso Store allows you to add a new payment method without touching their module. This lets you upgrade store without having to update your files, or re-integrate them in their module. Once you have added the payment method, configuration and management is done inside Expresso Store. The Omnipay framework supports standard purchase mechanisms, tokenized billing and recurring billing. More information about Omnipay can be found on their site

How is this accomplished?

• Step 1: Add a new extension, listening for the store_payment_gateways developer hook
• Step 2: At a minimum, add a "PurchaseRequest" and a "Response" handler in the extension
• Step 3: Enable the payment method, configure, test and test some more

As shared by the Expresso Store Developers in this StackExchange post, first we add the extension. This simply listens for Store to send the developer hook "store_payment_gateways" and returns the results of our custom payment gateway. The files for your custom payment method are then stored in your extension under the "Omnipay" folder. Here's an example extension function for adding our custom "Sage" payment method.

public function store_payment_gateways($gateways) { if (ee()->extensions->last_call) { $gateways = ee()->extensions->last_call; } // tell Store about our new payment gateway // (this must match the name of your gateway in the Omnipay directory) $gateways[] = 'Sage'; // tell PHP where to find the gateway classes // Store will automatically include your files when they are needed $composer = require(PATH_THIRD.'store/autoload.php'); $composer->add('Omnipay', __DIR__); return $gateways; } 

The simplest technique from here is to copy another payment method already in Expresso Store, and edit it to meet your needs. The configuration of your payment method is defined in the Gateway.php file. This is where you define the variables that will be necessary in configuring your gateway.

<?php namespace Omnipay\Sage; use Omnipay\Common\AbstractGateway; use Omnipay\Sage\Message\PurchaseRequest; /** * Sage Payment Gateway * GRAYBOX / Mark Middleton */ class Gateway extends AbstractGateway { public function getName() { return 'Sage Payment Solutions'; } public function getDefaultParameters() { return array( 'merchantId' => '', 'merchantKey' => '', 'testMode' => false, ); } public function getMerchantId() { return $this->getParameter('merchantId'); } public function setMerchantId($value) { return $this->setParameter('merchantId', $value); } public function getMerchantKey() { return $this->getParameter('merchantKey'); } public function setMerchantKey($value) { return $this->setParameter('merchantKey', $value); } public function purchase(array $parameters = array()) { return $this->createRequest('\Omnipay\Sage\Message\PurchaseRequest', $parameters); } } 

In addition to the Gateway file, you must at least create a PurchaseRequest.php and a Response.php to process the basic handlings of your payment method.

Additional files can be added to support different test modes, recurring billing, refunds, token charges and any other interactions you may have with your payment system.

Here is the file structure of our custom payment method.

Once you have added these files and updated your extension to add the listener for the developer hook, you will find your payment method in the Payment Methods settings area in Expresso Store

Enable the new payment method and click on the name to update the settings

Each of these settings is available in your payment method to process the interaction.

Many options are available, including interactions via REST, JSON, HTTP, SOAP or any PHP-supported technology you might need. The Omnipay framework is there to help support but generally stays out of the way of your specific implementation.Full documentation is found at the Omnipay page.