Checkout: Redirect/Hosted Payment Gateway

This guide will help you to develop/integrate a redirect/hosted payment gateway into the WordPress Shopping Cart plugin using a 3rd party extension plugin structure.

A redirect/hosted payment gateway is a gateway where the customer leaves the merchant’s website with a form with hidden fields or a URL to go through to the gateway’s secure payment page where the actual transaction/charge is made. The customer is then returned back to the merchant’s website with an order confirmation.

Since this extension plugin for the Shopping Cart plugin is a WordPress plugin on its own, best is to go through the Writing a Plugin guide on the WordPress Codex to familiarise yourself with it if you don’t already know how to write a WordPress plugin specifically. It will take you through the steps of the files, the file header and the rest.

Now let’s get started with the actual coding of the extension plugin.

 

1. Activation Hook

The first thing you want to do is to write an activation hook which will be fired when this extension plugin is activated. It could be used to load initial options into the database and also check certain requirements such as the current Shopping Cart plugin version.

In the code above, at the very bottom it uses register_activation_hook() on the current file to register an activation hook with WordPress to fire the gateway_activation_hook() function.

This function checks that the Shopping Cart plugin is actually active and the current version of the Shopping Cart plugin to see that it is at least X.X (change this to a specific version number). The reason for checking the version of the Shopping Cart plugin is to ensure that it is up to date and contains all the functions and hooks that you need for your extension plugin to function properly.

If the version is fine, you can go ahead and load some default options/settings in your own way. It is probably best to do this using add_option() which is a WordPress function and can later be retrieved using the same handle with get_option().

All of this is pretty straightforward WordPress code and specific to WordPress up until now.

 

2. Extensions List

Let’s add the extension plugin to the extensions list of the Shopping Cart plugin so that it is aware of this new extension and it can know what its handle is, its folder name and core file name is and where it resides on the Internet.

In the code above, we’re simply hooking to the wpco_extensions_list filter hook of the Shopping Cart plugin which passes $extensions variable which is the current Array of extensions. You can now append to this Array with your own, unique key such as “gateway” above and then name, link, image, description, slug, plugin_name, plugin_file accordingly.

• name – The name of your extension plugin
• link – A link to your extension plugin online
• image – An absolute URL to a 75 by 75px icon/image
• description – A short description of your extension plugin
• slug – A unique slug for identification purposes
• plugin_name – Plugin name and folder name of the plugin
• plugin_file – Plugin file name inside the folder above

 

3. Payment Methods List

Under Checkout > Configuration in the Shopping Cart plugin there is a list of payment methods/gateways with checkboxes to activate the ones that you want to use. The next step of this extension plugin is to add your payment gateway to this list with its own checkbox.

Hook onto the wpco_pmethods_list action hook which fires at the bottom of the payment methods checkboxes list and passes through two parameters.

The first one is $active which is an Array of active payment methods by slug and the 2nd parameter is $cssclass either empty/blank or contains “alternative” to help you create a more legible list.

Then the output is simply a table row TR with a single column TD containing a checkbox which is part of paymentmethods[] input name range where the value is your extension plugin’s slug.

When the checkbox is checked and the settings are saved, this gateway will now show up on the billing page as a payment method for your customers to choose.

 

4. Settings Metabox

Next you need to put a box for settings under Checkout > Configuration > Payment Methods of the Shopping Cart plugin so that the merchant can fill in settings related to the gateway accordingly.

First you’ll hook onto wpco_pmethods_metaboxes action hook which is fired when the metaboxes are added for Checkout > Configuration > Payment Methods. This hook will call gateway_pmethods_metaboxes() with 3 parameters.

This function now executes the standard WordPress add_meta_box() function to add “gateway” (the slug of your extension plugin) with the title/heading “Gateway” and its content will come from the output of gateway_metabox_settings() function.

The last 3 parameters of the add_meta_box() function you don’t have to worry about as the first 2 comes from the arguments/parameters from the hook and the last one is always just “core“.

Then the gateway_metabox_settings() just includes a file named settings.php which you can create inside your extension plugin’s main folder checkout-gateway. This settings.php file will have some HTML code to output a form for the merchant to insert settings. The Shopping Cart plugin will handle the saving of these settings together with the rest of the settings and you’ll learn later on how to retrieve these settings to use.

 

5. Merchant Settings Form

The settings.php file is included as mentioned above. This settings.php file will include a table with several fields so that the merchant can enter settings and click “Save Settings” to save them as WordPress options.

Start each setting name with your extension plugin’s slug, then an underscore and then the setting name. This way you ensure that your settings don’t conflict with that of other extension plugins. For example a title setting will be gateway_title and a merchant ID setting will be gateway_merchantid. Those are the name attributes of the form fields.

Here is an example settings form.

You can insert any HTML input fields here as you wish. Text input fields, checkboxes, radio buttons, textareas, etc., to capture any data from the merchant that you might need for the payment gateway.

Any of these settings can later be retrieved using wpco_get_option() with the name attribute used in the form.

 

6. Payment HTML Form

Next, you need HTML for the actual payment form which will send the customer from your site to the secure payment gateway page accordingly. You will hook to the process_order_{$slug} action hook of the Shopping Cart plugin and output your form HTML.

You have to consult the integration documentation of the payment gateway/processor to know what fields you need to send through in the form as POST data to the gateway payment page.

Here is a sample for reference:

So the customer will go through checkout and after the billing step, this HTML form will output and automatically submit with all the necessary details for the gateway payment page. The customer will then make the payment on the payment page of the gateway/processor.

 

7. Activate and Test

Once your extension plugin is under wp-content/plugins/ in your WordPress installation with the required structure and plugin file header, you can go to Plugins in your WordPress dashboard and activate it.

Testing the integration will depend on the payment gateway itself. Some gateways require certain parameters to be passed through in the HTML form, some gateways require your account to be set to test mode on their side and some gateways require specific credit card numbers for testing purposes, etc.

Give it a test and see if it works!

 

8. Publish Your Extension

If you want to publish your extension under our WordPress plugin extensions section, you may contact us to have it published there so that we can sell and market it for you.