DEV Community: Micah Andrew F. Bule

WooCommerce Hosted Payment Plugin Development

Micah Andrew F. Bule — Mon, 09 Jan 2023 15:49:45 +0000

WooCommerce is a very popular e-commerce platform not just because it's easy to set up on top of any WordPress instance, it is also FREE. However, imagine setting up your digital shop, finishing up configuring your product catalog and inventory, only to find out that your local payment service providers do not offer direct integrations with WooCommerce and international payment service providers just isn't viable due to certain reasons such as exorbitant fees or geographical restrictions.

If it so happened that you also know how to develop WordPress plugins, then this guide is perfect for you.

What this guide is and what is it not

Different payment service providers offer different types of payment solutions. This guide is written specifically for Hosted Checkout or Redirect-based workflows and how to integrate it with WooCommerce.

For an example of a hosted checkout experience, you can refer to Stripe Checkout and several implementations of it by different plugin authors.

While you can probably lift and apply most of the concepts and some of the code snippets from this guide to other types of payment solutions, this implementation is not a one-size-fits-all approach. Expect not the best of practices for developing plugins for the sake of simplicity, and that there can be better implementations out there aside from this one.

Our objective is to have a functional payment plugin at the end of this guide. We will try to cover and support other common features such as real-time order status updates based on payment status, voiding and refunding, as well as manual captures in upcoming posts.

Definition of Terms

Before we start writing any code, it's better to define some terms that will be used throughout this guide for clarity.

WordPress Core - refers to the primary process that executes every time you navigate throughout a WordPress application, whether it is a web page or the administration dashboard. Remember that WordPress is just a PHP application after all, executed by the web server for every request it will receive.
Hooks - are basically callback functions that extend the WordPress Core.
Action Hooks - are callback functions that introduce side-effects to the WordPress Core. Side effects are workflows triggered after certain events during the execution of the WordPress Core. Side effects can be in the form of interactions with the database or showing certain views or information to the user on certain processes or workflows. Action hooks may accept parameters but do not provide any return value to the process or function that called it.
Filter Hooks - are callback functions primarily used for transforming data within certain workflows during the execution of the WordPress Core. This is usually used for transforming data before being processed by WordPress Core or before being rendered as part of the UI that the user will see. Filter hooks may accept parameters and requires a return value to the process or function that called it.
Payment Gateway - throughout this guide, we will refer to this as the actual integration point between your payment service provider and WooCommerce. Technically, this is where the logic of your payment plugin will be written and/or configured.

Start Writing Code

While it's not the best practice, the whole plugin in this guide will be written in just one file, index.php, for the sake of simplicity.

After the plugin header, first we want to write the following code:

if (!defined('ABSPATH')) {
    exit;
}

What this snippet does is to check the existence of a constant named ABSPATH. This is a global constant that WordPress usually sets in wp-config.php. If there is no value, the script just terminates. This is to prevent the plugin file to be accessed directly via browser should it be exposed directly from the file system. While it's totally optional, this is a good way to ensure that attackers cannot abuse your plugin directly.

Next, we define a callback function for the plugins_loaded action hook for registering our custom payment method to WooCommerce, then call the action hook immediately after.

function wc_my_custom_gateway_init() {

}

add_action('plugins_loaded', 'wc_my_custom_gateway_init');

Plugin Initalization

It is important to note that WooCommerce payment plugins are heavily dependent on the WooCommerce plugin itself, hence it needs to be loaded first before any payment plugin can be registered. In this sense, the following code snippets should be located within the callback function above to avoid errors.

Next, we define our payment gateway class and extend the WC_Payment_Gateway parent class from WooCommerce. We will focus on this class later on, so we can leave it empty for now.

class WC_My_Custom_Gateway extends WC_Payment_Gateway {

}

Note that the class name of your payment gateway can be anything you want. However, it is best practice to make it as unique as possible to avoid conflicts with other WordPress plugins.

After declaring our payment gateway class, we want to declare a function to register our payment gateway to WooCommerce and call it with the woocommerce_payment_gateways filter hook.

function add_my_custom_gateway($methods) {
    $methods[] = 'WC_My_Custom_Gateway';
    return $methods;
}

add_filter('woocommerce_payment_gateways', 'add_my_custom_gateway');

After writing all that, you should have the an index.php file with full content below:

<?php
/**
 * PHP version 7
 * Plugin Name: WooCommerce Custom Payment Gateway
 * Description: A sample WooCommerce custom payment gateway plugin
 * Author: Mico
 * Author URI: https://meeco.dev
 * Version: 1.0.0
 * Requires at least: 5.3.2
 * Tested up to: 6.0.2
 */

/**
 * This prevents direct access to the file; remember that WordPress
 * is just another PHP application served by a webserver, hence file
 * access through a browser is possible and can be abused by attackers.
 */
if (!defined('ABSPATH')) {
    exit;
}

/**
 * Action hook callback to initialize your payment plugin
 */
function wc_my_custom_gateway_init() {
    /**
     * Your payment gateway class
     */
    class WC_My_Custom_Gateway extends WC_Payment_Gateway {

    }

    /**
     * Filter hook callback to register your custom payment gateway to
     * valid WooCommerce Payment Gateways
     */
    function add_my_custom_gateway($methods) {
        $methods[] = 'WC_My_Custom_Gateway';
        return $methods;
    }

    add_filter('woocommerce_payment_gateways', 'add_my_custom_gateway');
}

/**
 * Make sure to load your plugin after all other plugins are loaded
 * to make sure WooCommerce has already loaded so you can register
 * your payment plugin.
 */
add_action('plugins_loaded', 'wc_my_custom_gateway_init');

Ideally, you can extract certain parts of the plugin to separate PHP files and just include it in index.php using the include_once directive. For example, you can move the payment gateway class to its own file instead of just declaring it within the plugins_loaded action hook callback function.

Building the Payment Gateway Class

Extending the WC_Payment_Gateway class allows us to configure the behavior of our payment plugin. The first thing we need to do is define a public __construct() function and fill out the following properties we are extending from the parent class.

class WC_My_Custom_Gateway extends WC_Payment_Gateway {
    public function __construct() {
        $this->id = 'my_custom_gateway';
        $this->method_title = 'My Custom Payment Gateway';
        $this->method_description = 'Pay easily with my custom gateway';
        $this->title = 'Your Payment Gateway';
    }
}

id [required] - unique gateway ID. Ideally no spaces nor special characters, and uses snake-case for readability.
method_title [required] - the value for this is what is used to display the payment method in the payment method settings of WooCommerce.
method_description [required] - the value for this is shown on the actual payment method settings page itself, describing what the payment method is.
title [optional] - shown as part of the method_title in the payment method

If there are no errors, you should be able to see the following in its respective URLs:

/wp-admin/admin.php?page=wc-settings&tab=checkout

/wp-admin/admin.php?page=wc-settings&tab=checkout&section=my_custom_gateway

Adding Settings for your Plugin

Integrating with your chosen payment service probably requires your plugin users to input their credentials such as API keys, callback URLs, or other hosted checkout customizations. For this example, let's assume that we need to have the following fields for configuration:

Merchant ID
Mode Dropdown Toggle
Sandbox Public API Key
Sandbox Secret API Key
Live Public API Key
Live Secret API Key

For the mode field, it's best to use the radio group or checkbox as the value can normally be represented with two radio options or a boolean, respectively. We will just show the capability of the settings page to render a dropdown field for this guide.

Extending the WC_Payment_Gateway allows us to leverage the WordPress Settings API and enables us to create our own settings page. In your payment gateway class, you can do the following:

class WC_My_Custom_Gateway extends WC_Payment_Gateway {
    public function __construct() {
        $this->id = 'my_custom_gateway';
        $this->method_title = 'My Custom Payment Gateway';
        $this->method_description = 'Pay easily with my custom gateway';
        $this->title = 'Your Payment Gateway';

        $this->init_form_fields();
        $this->init_settings();

        add_action(
            'woocommerce_update_options_payment_gateways_' . $this->id,
            array($this, 'process_admin_options'),
        );
    }

    public function init_form_fields()
    {
        $this->form_fields = array(
            'enabled' => array(
                'title' => 'Enable/Disable',
                'label' => 'Enable/Disable the Custom Gateway',
                'type' => 'checkbox',
                'default' => 'no',
            ),
            'merchant_id' => array(
                'title' => 'Merchant ID',
                'type' => 'text',
                'description' => 'Your merchant ID',
            ),
            'mode' => array(
                'title' => 'Mode',
                'type' => 'select',
                'options' => array(
                    'sandbox' => 'Sandbox',
                    'production' => 'Production',
                ),
                'description' => 'Toggle between sandbox and production mode',
                'default' => 'sandbox',
            ),
            'production_public_key' => array(
                'title' => 'Production Public Key',
                'type' => 'text',
            ),
            'production_secret_key' => array(
                'title' => 'Production Secret Key',
                'type' => 'password',
            ),
            'sandbox_public_key' => array(
                'title' => 'Sandbox Public Key',
                'type' => 'text',
            ),
            'sandbox_secret_key' => array(
                'title' => 'Sandbox Secret Key',
                'type' => 'password',
            ),
        );
    }
}

First, declare a public method called init_form_fields() within your payment gateway class. Inside this public method, we will assign an array to the class property form_fields. This array will contain key-value pairs with each option key paired with another array value containing its configuration including but not limited to the title, type of the field, description, and even the default value. For all the available values and configurations per field type, check out the WooCommerce Settings API documentation.

Then, add the $this->init_form_fields() and $this->init_settings() call at the bottom part of the constructor. This will basically initialize all the values of the defined fields after the plugin has been registered.

Lastly, call the woocommerce_update_options_payment_gateways_{gateway_id} action hook with the method process_admin_options for the gateway to be able to save the settings.

At this point, if you don't encounter any errors, you will have the following screen below, complete with the functionality to save any data that you need to integrate with your payment service provider.

/wp-admin/admin.php?page=wc-settings&tab=checkout&section=my_custom_gateway

Also, if you enable your payment gateway at this point, you should be able to see it as a payment method option in the actual checkout page.

/checkout

You need to fix your permalinks to navigate to /checkout, otherwise you'll be seeing something similar to ?page=X where X is the page ID.

Process the Actual Payment

For this section, we will set certain assumptions for the payment service provider, including data for endpoints, payload, and workflow.

Assume that we need to send the payload below as a POST request to the /checkout endpoint of the payment service provider's public API to create a checkout.

{
    "first_name": "{customer_first_name}",
    "last_name": "{customer_last_name}",
    "total_amount": "{order_total_amount}",
    "redirect_url": "{redirect_url}",
}

Assume that we will receive the payload below after creating a checkout. This usually contains the hosted checkout URL where the customers can process their payments.

{
    "checkout_id": "chkout_fa21af237u3",
    "checkout_url": "https://your-payment-service-provider.com/hosted-checkout?id=chkout_fa21af237u3",
}

Assume that requests need to have an Authorization header with the base64-encoded secret key as value.

Now that we have the assumptions above, you can add make the following changes to your code:

class WC_My_Custom_Gateway extends WC_Payment_Gateway {
    protected $mode;
    protected $secret_key;

    public function __construct() {
        $this->id = 'my_custom_gateway';
        $this->method_title = 'My Custom Payment Gateway';
        $this->method_description = 'Pay easily with my custom gateway';
        $this->title = 'Your Payment Gateway';

        $this->init_form_fields();
        $this->init_settings();

        add_action(
            'woocommerce_update_options_payment_gateways_' . $this->id,
            array($this, 'process_admin_options'),
        );

        /**
         * This is a pretty nifty trick to set public/secret keys on your
         * gateway instance if you implement mode as a dropdown instead of
         * checkbox or radio group
         */
        $this->mode = $this->get_option('mode');
        $this->secret_key = $this->get_option($this->mode . '_secret_key');
    }

    /**
     * ASSUME THE FORM FIELDS SETTINGS IS HERE
     */

    public function process_payment($order_id)
    {
        /** Get the actual order object via ID */
        $order = wc_get_order($order_id);

        $payload = json_encode(
            array(
                'first_name' => $order->get_billing_first_name(),
                'last_name' => $order->get_billing_last_name(),
                /** get_total() returns a string value so you need to convert */
                'total_amount' => floatval($order->get_total()),
                'redirect_url' => $order->get_checkout_order_received_url(),
            )
        );

        $request_args = array(
            'body' => $payload,
            'method' => 'POST',
            'headers' => array(
                'Authorization' => 'Basic ' . base64_encode($this->secret_key . ':'),
                'Content-Type' => 'application/json'
            )
        );

        $response = wp_remote_post('https://your-payment-service-provider.com/checkout', $request_args);

        $body = json_decode($response['body'], true);

        $order->add_meta_data($this->id . '_checkout_id', $body['checkout_id']);

        return array(
            'result' => 'success',
            'redirect' => $body['checkout_url'],
        );
    }
}

In the code above, the first thing we did was to add two protected properties in our payment gateway class: mode and secret_key. We also assigned values to them at the end of the __construct() function, retrieving their corresponding values from the settings page we created earlier.

Next, we defined a public function called process_payment, taking in one parameter, order_id. This is extended from the parent WC_Payment_Gateway class and this is where the actual integration normally happens. For hosted checkout workflows, this is where you usually construct the payload with all the customer and transaction details that will populate your hosted checkout page.

In our example, we retrieved all the details we need from the WooCommerce Order object, from customer name to total transaction amount and constructed the JSON payload. After that, we constructed the request arguments, including the Base64 encoded secret key for the authorization header.

Lastly, we sent the request to the public API of the payment service provider using the indicated endpoint and wp_remote_post() function from WordPress. Assuming it was a successful attempt, all we need to is to decode the JSON response payload, associate the checkout ID to the order metadata – which is critical if you want to resolve order statuses in real-time with payment statuses, then returned an array with the result and redirect keys, the latter set to whatever the value of the checkout URL from the response payload is.

This only follows the happy path for transacting. You need to also handle errors coming in from the payment service provider's public API.

Ideally, you want to create an API library that you want to instantiate in your payment gateway class so you can abstract the construction of the request payload and headers, as well as the call to the actual public API endpoints of the payment service provider.

Final step

If you're integrating with an actual payment service provider, all that's needed now is to test. If you have followed everything so far, you should be able to place an order in your e-commerce website using your custom payment gateway as the payment method, get redirect to the hosted checkout page, process your payment, and get redirected back to your e-commerce website.

What's Next?

At this point, there are several other features that you probably need/want to develop to have a better workflow:

If your payment service provider's public API offers registration a notification mechanism for payment statuses – usually in the form of webhooks – you may want to implement handling webhooks using the WooCommerce API Callback or even WordPress Custom Endpoints, instead of just pinging back other API endpoints to check the payment status.
If your payment service provider supports voiding and refunding, you probably want to implent the process_refund() method from the WC_Payment_Gateway parent class.
Manual capture is a bit more tricky as this requires extending the admin dashboard user interface to provide for the manual capture functionality. I am reserving this to explain in detail for another technical post.

WordPress + Warden

Micah Andrew F. Bule — Wed, 04 Jan 2023 15:17:02 +0000

Developing anything on top of WordPress can be a bit tricky, especially if you don't know where to start. Whether it be building an actual website using the CMS platform, or developing plugins and themes for it, it's almost always needed for you to have a local instance on your machine to test things out.

The Old-Fashioned Way

xampp client

Back in the days when you can just spin up a web server using XAMPP, I can just download a copy of WordPress, put it in the default root directory of my local Apache instance, setup the database and configure WordPress to connect, then I should be good to go. For most occasions, this would suffice. However, due to the nature of WordPress as a very robust, flexible, and dynamic content management system, having particularly the ability to extend it using plugins, complexities arise when you have different plugins that may or may not be compatible with each other or the WordPress version you have installed. Then there's the issue of working on a specific project together with other members of a team, having different machines and your own configurations.

Containers

Photo by https://unsplash.com/@eilisgarvey

Then came containerization.

While I can probably explain it in my own words, it's probably best to focus on my next topic, so here's a Yoast blog I followed when I started using Docker to create WordPress instances on my local machine about a year ago.

The primary idea is to compose your development environment – primarily your web server which would house your WordPress application, and its database – using containers. You can think of containers as "packaged environments" that can run the same way on any operating system. This way, it doesn't matter if you personally have multiple different development machines, or multiple team members using different machines collaborating on your work. You can simply configure what your environments should be for different scenarios, and just share the same configuration between said machines, then just spin up the same environment for everyone. It also has an added bonus that you can now spin up multiple environments on the same machine, say for different WordPress versions that you need to test.

Automate all the way

Warden is like XAMPP but on steroids as it leverages containerization technology.

It's basically an automation tool to configure different platform environments using containers for the platform's components. For example, the latest Magento requires more than just a web server and database but also ElasticSearch for searching, Varnish as a reverse proxy, and RabbitMQ for queueing – among others. With Warden, all you need to do is create a directory for your Magento instance, run a command to create the configuration file for your Magento environment, then execute a command to build the environment. What Warden does is create containers for each of the services mentioned above, and tie them all together so they all know how to talk to each other within your container's network.

The idea is pretty much the same for setting up WordPress.

Step 1: Create a directory for your WordPress instance

$ mkdir -p /path/to/your/wordpress-instance

Pretty much self-explanatory.

Step 2: Initialize your WordPress instance directory

Assuming you've already installed Warden and ran it for the first time without any hitch, you can directly go to your WordPress directory and execute the following:

$ warden env-init my_wordpress_instance wordpress

where my_wordpress_instance is an identifier for your WordPress instance. No spaces, preferably snake-cased. This will create a .env file in the current working directory with default configurations for a WordPress instance.

Step 3: Download WordPress into the WordPress instance directory

You can just execute the following commands within the WP instance directory:

$ curl -O https://wordpress.org/latest.zip
$ unzip latest.zip
$ mv wordpress/* .
$ rm -r wordpress/ latest.zip

This should download the latest version of WordPress in a zipped file to your current working directory, unzip it, move the contents to the current working directory, and remove downloaded files and unnecessary folders.

Step 4: Run the WordPress environment on Warden

Just execute the following:

$ warden env up

This should set up all necessary containers, from web server to database, tie them all up as configured in your .env file.

Ideally, on first run, WordPress will let you configure the connection strings during set up, so just copy the values within the .env file and you'll be good to go.

As cherry on top, Warden does not just automate the container setup for you with the containers you need for your platform environment. It also provides several services out of the box to make your development way easier.

Traefik - handles all the networking needed within your Warden services so all containers can talk to each other
DNSMasq - handles DNS and DHCP locally, which is particularly useful in conjunction with ngrok to route requests; no more localhost:port, use your environment name instead
Portainer - handle container management; pretty useful even without using Warden in general to manage other containers for development using its GUI
Mailhog - is an email testing tool which you can configure with your environment if you want to test mailing functionality of your platform (ex. order confirmation and invoice sending for e-commerce functionalities)

For any developers out there who wants to take their WordPress development to the next level, Warden is definitely something worth trying.

WordPress Plugin Development Primer

Micah Andrew F. Bule — Wed, 04 Jan 2023 13:17:41 +0000

Photo by https://unsplash.com/@benkolde

What and Why?

WordPress has been around for about two decades now and is basically responsible for almost half of all websites on the internet at this point. While there are tons of available alternatives out there for content management systems, especially with the rise of headless CMS counterparts, it's quite certain that WordPress is not going to sunsetted anytime soon.

One of WordPress' killer feature by the time it took the internet is the Plugins ecosystem. Having the ability to extend and customize your content management system, making it more dynamic and robust, is one of the things that made WordPress so popular to a lot of digital users. From adding simple utility tools to your CMS to turning your website into an e-commerce shop, WordPress plugins got most of the existing use-cases covered. However, in case that the solution does not exist yet, it is worth mentioning that we, as web developers, can actually develop our own WordPress plugins.

The Plugin

The directory structure

sample-wordpress-plugin
 |-- index.php

index.php - this is our initial file and where we will call the action hook that would register our plugin to the WordPress Core so it would show up in the Plugins page.

Assuming you already have a local WordPress instance, you can proceed to create your own plugin directory under /your-wordpress-directory/wp-content/plugins. Otherwise, you can refer to my other blog post on how to setup a local WordPress instance using Warden. Moving forward this guide, assume all files are within the plugin directory in the path /your-wordpress-directory/wp-content/plugins/sample-wordpress-plugin.

The Initial File

<?php
/**
 * PHP version 7
 * Plugin Name: Sample WordPress Plugin
 * Description: A sample WordPress plugin
 * Author: Mico
 * Author URI: https://meeco.dev
 * Version: 1.0.0
 * Requires at least: 5.3.2
 * Tested up to: 6.0.2
 */

index.php

The comments at the start of the initial file is called the Plugin Header. The header is important as that is what determines the plugin details that would appear on the Plugins page in the WordPress dashboard (refer to image 1.a below). While the first few lines are pretty self-explanatory, there are some that we think it is best to define:

Author URI - while optional, it's better to put your own personal or company URL here for easier contact reference and free marketing.
Version - this is the plugin's current version, preferably using Semantic Versioning.
Requires at least - the minimum WordPress version that your plugin is compatible with. This is very important as any published plugins are regularly checked for compatibility across WordPress versions.
Tested up to - the latest version of WordPress that your plugin was tested to work with. Do note that this does not mean your plugin won't work on later versions of WordPress, this just means you tested your plugin's compatibility up to the value of this field.

For more details on what else you can put within this comment section, you can check the WordPress Header Requirements.

With just the header, and without any other issues, you should be able to see something like the image below.

A sample Plugins page in a WordPress admin dashboard

Next Steps

While the plugin literally does nothing right now other than merely registering itself in a WordPress instance's loaded plugins, as a developer, you can now start to decide what to do from here. Below are some additional guides based on this primer.

Create a payment plugin for WooCommerce
Create a custom shortcode plugin
Publish your plugin to WordPress Plugins public repository;