Custom Payment Plugin

[TOC]

Overview

OS Calendar's payment system is extensible. You can create custom payment plugins to integrate any payment gateway not included in the default package. Custom plugins follow the same structure as the built-in plugins.

Plugin File Structure

A payment plugin consists of two files packaged in a .zip archive:

os_myplugin.xml    ← Plugin metadata and configuration parameters
os_myplugin.php    ← Payment processing logic

XML File Structure (os_myplugin.xml)

<?xml version="1.0" encoding="UTF-8"?>
<install version="1.0" type="oscplugin" group="payment">
    <name>os_myplugin</name>
    <title>My Payment Gateway</title>
    <author>Your Name</author>
    <creationDate>2025-01-01</creationDate>
    <copyright>Copyright 2025 Your Company</copyright>
    <license>GNU/GPL</license>
    <authorEmail>you@example.com</authorEmail>
    <authorUrl>www.example.com</authorUrl>
    <version>1.0</version>
    <description>My custom payment plugin for OS Calendar.</description>
    <config>
        <fields name="params">
            <fieldset name="basic">
                <field name="api_key" type="text" size="40"
                    label="API Key"
                    description="Enter your API key." default=""/>
                <field name="mode" type="list"
                    label="Mode"
                    description="Test or Live mode.">
                    <option value="0">Test</option>
                    <option value="1">Live</option>
                </field>
            </fieldset>
        </fields>
    </config>
    <files>
        <filename>os_myplugin.php</filename>
    </files>
</install>

PHP File Structure (os_myplugin.php)

Each payment plugin is a PHP class that extends the os_payment base class:

<?php
// No direct access.
defined('_JEXEC') or die;

class os_myplugin extends os_payment
{
    /**
     * Constructor — initialise payment gateway parameters.
     *
     * @param object $config  Plugin configuration parameters
     */
    public function __construct($config)
    {
        // Call parent constructor
        parent::__construct($config);

        // Retrieve plugin parameters
        $this->api_key = $config->get('api_key', '');
        $this->mode    = $config->get('mode', '0');
    }

    /**
     * Process payment — redirect or render the payment form.
     *
     * @param array $data  Order data (order_id, amount, customer info, etc.)
     */
    public function processPayment($data)
    {
        // Build the request to the payment gateway API
        // Redirect the customer to the gateway or render an inline form
    }

    /**
     * Verify payment — called when the gateway posts back a notification.
     */
    public function verifyPayment()
    {
        // Verify the IPN / webhook from the payment gateway
        // Update the OS Calendar order status accordingly
    }
}

Installing a Custom Plugin

1. Create the two files (os_myplugin.xml and os_myplugin.php).
2. Zip them together into os_myplugin.zip.
3. In the Joomla back-end, go to Components → OS Calendar → Manage Payment Plugins.
4. Use the Upload & Install section to upload and install the zip file.
5. After installation, publish and configure the plugin.

Available Order Data ($data array)

The processPayment($data) method receives an array with the following keys:

Tip: Study the built-in os_paypal.php source code in components/com_oscalendar/plugins/ as a reference implementation when building your own payment plugin.