MIGS payments in Joomla VirtueMart.
This is a follow-up post in response to Mike Soden's comment on my post Integrate MIGS 2-party payments in PHP - in which Mike asked for some help getting MIGS 2-party payments working in VirtueMart.
I took a quick look at some of the other attempts at MIGS integration into VirtueMart, but I wasn't convinced about their quality; they looked incomplete and sloppy. So, I decided to gut an existing one and roll my own.
I wrote this one using VirtueMart 1.1.4 stable running on Joomla 1.5.17. It will likely work for other versions of VirtueMart and/or Joomla, but I make no promises.
The VirtueMart MIGS payment method plugin code:
VirtueMart allows developers to add a new payment method in two steps:
Step one, by adding the classes to the following location:
[wwwroot]/administrator/components/com_virtuemart/classes/payment
And step 2, by adding and configuring the payment method in the VirtueMart admin component.
The first half of this post will talk about the payment class (and accompanying config file) that you need to paste into the above location. NOTE: You will also need to chmod the config file with write permission, as the VirtueMart admin component writes to this file from the configuration tab.
VirtueMart payment classes typically have two files:
- ps_migs.php
- ps_migs.cfg.php (cfg is an abbreviation for config)
The main file (and class) is called ps_migs. For what it's worth: the "ps_" naming convention is remnants of phpShop, which VirtueMart forked from back in the day.
The ps_migs.php file actually contains a few class definitions, including: ps_migs, Migs, MigsConfig and MigsHtml; this is just about keeping the code split into neat logical chunks, while still maintaining the VirtueMart convention of two files. You really needn't worry too much about this.
My ps_migs class takes inspiration from the other payment classes in the methods it contains, largely because I couldn't find appropriate documentation on what an ideal payment class should look like.
There are 5 methods relating to configuring the payment method. These should not be of too much interest to developers implementing the MIGS payment plugin into their own VirtueMart store, as they are all used by the VirtueMart admin component. Needless to say, they all work and together, allow you to configure your MIGS payment method.
There are 2 methods relating to actually processing payments. At this point, only the process_payment method has a proper implementation (as the projects I have been working on have not required payment capture and processing).
Since we already have such a strong basis for making payments using MIGS payment gateway from my previous post - we'll use the existing classes: Migs and MigsConfig. This is going to be a walk in the park!
The other file ps_migs.cfg.php, defines a series of constants. In our case, the ps_migs.cfg.php file contains four constants. The first two are your Merchant Id and your Access Code. The second two are response codes used in VirtueMart which really need not be changed from 'C' and 'X' respectively - as they indicate what status payments that succeeded or failed should receive.
define('vpc_AccessCode', '80#####7');
define('vpc_Merchant', 'TESTBBL9#####4');
define('MIGS_VERIFIED_STATUS', 'C');
define('MIGS_INVALID_STATUS', 'X');
These values can be edited via the VirtueMart admin component, more on this in the second half of the post.
NOTE: At this point you really should have some familiarity with my previous post Integrate MIGS 2-party payments in PHP - in which the Migs class is first introduced.
Ok, since the Migs class is already written to use the MigsConfig class to read it's values from, we're going to write a quick adapter method to populate the config from VirtueMart's defined constants into the MigsConfig class. This is the exact same technique I demonstrated in my previous post to extract config values from a Joomla admin component's parameters. Cool huh?
So, after creating an instance of the Migs class we populate the config from the VirtueMart ps_migs.cfg.php file.
// Bring in the Virtuemart config.
$configFilepath = CLASSPATH.'payment/'.$this->classname.'.cfg.php';
require_once($configFilepath);
// Use Migs helper class to package, process and un-package the payment.
$migs = new Migs();
$migs->config->readConfigFromVirtuemartFile($configFilepath);
The next step is getting the data we need from VirtueMart into an associative array, ready to pass in to the digitalOrder method of the Migs class.
// Get the data from Virtuemart into the format that MIGS expects.
$data = array(
'vpc_MerchTxnRef' => $orderNumber,
'vpc_OrderInfo' => $orderNumber,
'vpc_Amount' => (int)($amount*100), // Force amount into cents.
'vpc_CardNum' => $_SESSION['ccdata']['order_payment_number'],
'vpc_CardExp' => (substr($_SESSION['ccdata']['order_payment_expire_year'],2)) . ($_SESSION['ccdata']['order_payment_expire_month']),
'vpc_CardSecurityCode' => $_SESSION['ccdata']['credit_card_code']
);
Now, it's time to reap the benefits of good software development practices... reusability. Yep, it's the Migs class from my previous post, looking like a champ! These next two lines of code handle all the integration with the MIGS payment gateway.
$response = $migs->digitalOrder($data);
$errors = $migs->validateResponse($response);
Lastly, it's just a matter of handling the response - pushing the appropriate data we got back from the MIGS gateway into our VirtueMart data variable to be saved.
// Validate/Verify the response succeeded.
if (sizeof($errors) == 0) {
$d['order_payment_log'] = var_export($response, true);
$d['order_payment_trans_id'] = $response['vpc_TransactionNo'];
// Update the order status to 'C' as per the config.
$d['order_status'] = MIGS_VERIFIED_STATUS;
return true;
}
else {
// some code removed ...
}
Install the ps_migs files to the filesystem:
That's the first half taken care of - at this point we should have extracted the two ps_migs files and copied them into the [wwwroot]/administrator/components/com_virtuemart/classes/payment directory. You should also give the ps_migs.cfg.php file write permission if you intend on configuring your MIGS payment method from the VirtueMart admin component.
On to the second half of the post... In brief, we're going to log into Joomla and install/configure your brand-spanking-new MIGS payment method in the VirtueMart admin component.
Add and configure the MIGS payment method:
The following steps should help you through:
- Log into the Joomla admin, and head to the VirtueMart component.
- On the left hand side, click the Store link (in the accordion menu).
- Click Add Payment Method.
- Enter details along the lines of:
Active?: Checked
Payment Method Name: Credit Card (MIGS) *** NOTE: you can rename this as you please. ***
Code: MIGS
Payment class name: ps_migs
Payment method type: Use Payment Processor
Accepted Credit Card Types: Visa, MasterCard, American Express, Diners Club, etc.
[...]
The rest you can just leave as per their defaults (unless you know what you're doing).
- Save the new payment method and return into editing it by clicking it's name in the list.
- Click the Configuration tab and enter your MIGS Merchant Id and Access Code.
- Ensure the Verified Status Code is C and the Invalid Status Code is X.
- Save the configuration.
- [Optional] Set other payment methods to un-active if they are not needed.
- Give it a test - you're done! :D
NOTE: As I mentioned in my previous post, when testing: the payment amount is translated to cents and needs to be divisible by 100 to be valid. E.g. an amount of $23.00 would work, but $23.50 would return an error response (when using the test payment server).
If everything went correctly, you should be able to select an item from your store, add it to the cart, check out and see something similar in your VirtueMart store.
Download the MIGS VirtueMart payment method plugin:
Please note: This code is provided as is, use it at your own discretion.
That said, if you do notice anything that you think is potentially unsecure, or that you think could be improved upon - feel free to let me know.
I'd also be interested in hearing if you have success using this class in any of your own projects.
Professional quality MIGS implementations by Inlight Media.
If you've got to the end of this post and you're still unsure on how to integrate MIGS in to your VirtueMart, or your PHP site - you should give Inlight Media a call on (03) 9029 3582 or email info@inlight.com.au - Inlight Media are a Melbourne based web development agency who (amongst other things) are experts at PHP based MIGS integration.
