---
title: 'Custom Payment Plugin'
url: 'https://docs.joomdonation.com/oscalendar/payment-plugins/custom-payment'
markdown: 'https://docs.joomdonation.com/oscalendar/payment-plugins/custom-payment.md'
date: '2026-04-24'
description: "[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 packa…"
taxonomy:
  category:
    - docs
---

[](#) [ edit this page](https://github.com/getgrav/grav-skeleton-rtfm-site/blob/develop/pages/05.payment-plugins/04.custom-payment/docs.md) 

# 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
<?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
<?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:

| Key | Description |
|---|---|
| `order_id` | The OS Calendar booking order ID |
| `total_amount` | Total amount to charge |
| `currency` | Currency code |
| `customer_name` | Customer's full name |
| `customer_email` | Customer's email address |
| `return_url` | URL to redirect to after successful payment |
| `cancel_url` | URL to redirect to if payment is cancelled |
| `notify_url` | URL for the payment gateway to send IPN/webhook notifications |

> > > > **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.

 [ ](https://docs.joomdonation.com/oscalendar/payment-plugins/offline) [](https://docs.joomdonation.com/oscalendar/payment-plugins/authorize-net)

---

## Navigation

- Parent: [Payment Plugins](https://docs.joomdonation.com/oscalendar/payment-plugins.md)
- Previous: [Offline / Bank Transfer](https://docs.joomdonation.com/oscalendar/payment-plugins/offline.md)
- Next: [Authorize.net](https://docs.joomdonation.com/oscalendar/payment-plugins/authorize-net.md)
