I have had a fair bit of experience now with Payment Modules under osCommerce. I have used publicly available payment modules as well as writing my own (for Australian eSec/Securepay, Westpac Webadvantage and Mastercard Internet Gateway Services - MIGS).
I have to say that a lot of the modules aren’t correctly documented and often take the quickest approach to doing a problem, without considering future maintenance or implementing good industry practices. Overall the osCommerce package has, in my opinion, in general, become more of a nightmare than a solution for anything you want to do that slightly changes from the standard package they provide.
But instead of turning this into a “I am so over osCommerce” post I am going to discuss coding up a Payment Method that will suit the requirements of your client or your site.
The Payment Module
The payment module is a way of creating a custom hook point for handling payment by a specific means, such as accepting payment via PayPal or through an Online Credit Card Gateway. It is written flexible enough to cater for 98% of situations and has frameworked multilanguage support. A payment module is formed of two files, the Payment Module Language file as well as the Payment File Class.
The payment module language files are located in
“includes/languages/[english]/modules/payment” and should to correspond to the same name as your class file. It contains series of define(); calls to setup the various language requirements that you need.
The payment module class files are located in
“includes/modules/payment” and are typically named similar to “cc_via_whatever.php” or something more descriptive. This is the file that will handle our processing.
You will need to request from your payment gateway provider an integration guide. Any payment provider will be able to provide you this information and should provide sufficient support for you to diagnose the process.
The next step is to analyse the flow of the Payment Module Class. This is extremely important for you to understand as you will need to disect your payment integration into the correct functions of your Payment Class. Ensure that you protect your clients sensitive information and never rely on hidden form fields (!).
The order in which the payment module is executed occurs similar to below:
Constructor (function cc_via_whatever): Purpose is to initialise requirements of osCommerce. The variables that it wants you to configure include:
- $this->code = (same as your class file name prepend, eg, “cc_via_whatever”)
- $this->title = (Title of the payment module, EG “Payment Via Credit Card Facilities Online”, you will see this appear on your website frontend)
- $this->description = (a more verbose explaination of the payment module)
- $this->enabled = (This is very important to set true or false. I usually check to ensure all my Admin controlled variables are set before making this module enabled)
- $this->form_action_url = (Where to submit the form contents to once hit submit)
- $this->sort_order = (The sort order of this module in correspondance to others)
function update_status: Purpose it so check whether this payment module is available during runtime with an order.
Usually this method will analyse whether the payment module is valid within this clients zone. This is usually a generic call, so you can reference other example payment modules.
First Stage, Making Selection of the Payment Module
function javascript_validation: Purpose is to check the contents of the submitted payment details when this option is selected for payment.
This is usually fairly generic between the credit card modules, but you will need to ensure that your naming of your files remain the same as well.
function selection: Purpose is to provide a set of form information when the payment module is selected. The form information is used to render the form required fields, such as Credit Card number etc. The javascript validation provided in the above javascript_validation method will work off the field names setup here. If you are using a bank hosted integration model, or one that does not require user input of credit card you can return only the id and module. Check another payment module for the syntax.
function pre_confirmation_check: Purpose is to validate the details that have been submitted for the form that we created above. This needs to be very thorough. If you are using this payment method for the validation of a Credit Card you may like to make use of the validation class cc_validation.php bundled with osCommerce. Other payment modules will help you which its use. If the form fields don’t validate, this function will redirect the user back to the payment selection screen.
Second Stage, Confirming the order
function confirm: Purpose is to confirm to the user the details that will be used to process the order. Once again this is in an array format that defines keys that will be read in on the confirmation page.
function process_button: This allows us to place in hidden form fields into the confirmation page. These are provided to you by your payment gateway. You will need to carefully analyse which fields need to be placed here - as they are parsed through the request (only) to the next process:
Third Stage, Processing the payment
function before_process: This is where all of our actions go for processing the payment (prior to the order being saved). If you are using a Bank Hosted model this is called after the user has been to the bank and is returning. You will need to validate the request (eg, $_GET/$_POST) to ensure that the bank responded with the correct details. If you are submitting to the bank directly using CURL or similar, you will perform you actions here also to determine if the order should be continued to be processed, or to divert the user back to the payment details screen. This method doesn’t return a value, instead you will need to perform your validation and redirect if necessary. Otherwise allow the function to terminate and it will continue to process the order.
function after_process: This is called after the order has been saved. I don’t usually have a need for this method.
Misc Methods required for the payment module to integrate into osCommerce
function get_error: Create an associative array to house the error. Check syntax from existing payment module
function check: Checks whether the payment has been “installed” through the admin panel. You can determine this by checking for configuration_values which get inserted into the database when the user hits “install”.
function install: Installs the configuration keys into the database. This is where you define the fields to be collected from the adminsitrator user, such as Merchant ID’s etc.
function remove: Removes the configuration keys from the database, called when they hit “remove” in the backend.
function keys: Defines an array containing the configuration key keys that are used by the payment module.
For an example for one that I contributed to osCommerce for MIGS - ANZ, Bendigo use etc checkout the link to the payment module: MIGS Payment Module
I recommend for people to indicate on their module: Proper PHPDoc tags for functions, break up the method access into accessor style methods, try to leave a much notes for future developers (even yourself) such as “//” sections that indicate what you are doing etc. Also ensure to TODO notes where you have not completed a section of the integration, and also quote any documentation versions that you have used.
Lastly to complete the Payment Module you should include correct documentation that outlines how to install via FTP etc.
