> ## Documentation Index
> Fetch the complete documentation index at: https://ownpay.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> OwnPay is licensed under AGPL-3.0 and is completely free - no licensing fees.
> Production docs URL: https://ownpay.org/docs - append .md to any page URL for clean markdown.
> OwnPay requires PHP 8.3+, MySQL/MariaDB, and Redis.
> MCP server available at https://ownpay.org/docs/mcp for programmatic documentation queries.
> Use root-relative links (e.g. /quickstart) for internal navigation - do NOT include /docs prefix.
> Plugin development: consult /developer/plugin-types/ pages for correct interfaces and manifests.

# Plugin System: Build Gateway, Theme, and Addon Plugins

> Overview of OwnPay's plugin architecture, plugin types (gateway, theme, addon), packaging, installation, and how to build custom plugins.

Plugins extend OwnPay functionality without modifying core code. Instead of forking OwnPay, write a plugin to add payment gateways, create custom features, design custom themes, or integrate external services.

## Plugin types

### 1. Gateway plugins

Add new payment methods (Stripe, PayPal, bKash, bank transfer, crypto). Provides payment processing, settlement management, webhook handling, and refund logic.

### 2. Addon plugins

Add features like advanced reporting, subscription management, inventory sync, CRM integration, or email customization. Provides admin pages, API endpoints, scheduled jobs, and UI components.

### 3. Theme plugins

Customize the checkout experience with custom templates, CSS, JavaScript, and branding. Provides Twig templates, stylesheets, and asset management.

## Plugin lifecycle

```text theme={null}
1. Discovery
   v Plugin loader scans plugins/ directory
   
2. Registration
   v Plugin class loaded and registered
   
3. Configuration
   v Config files read and validated
   
4. Activation
   v Plugin hooks registered
   
5. Runtime
   v Plugin executes and responds to events
   
6. Deactivation
   v Plugin hooks unregistered
```

## Plugin structure

```text theme={null}
plugins/
+-- gateway-stripe/
    +-- config.json          # Plugin metadata
    +-- composer.json        # PHP dependencies
    +-- src/
    |   +-- StripeGateway.php
    |   +-- Hooks.php
    |   +-- Events.php
    +-- resources/
    |   +-- views/
    |       +-- settings.twig
    +-- migrations/
    |   +-- create_stripe_table.php
    +-- README.md
```

## Hooks system

**Pre-execution hooks** (modify behavior):

```php theme={null}
$amount = Hook::apply('payment.amount', $amount, $payment);
```

**Post-execution hooks** (react to events):

```php theme={null}
Hook::do('payment.completed', $payment);
```

Over 60 hooks available across OwnPay.

## Plugin API

```php theme={null}
// Access services
$paymentService = Plugin::service('payment');
$config = Plugin::config('stripe');
Plugin::log('Something happened', 'info');
$user = Plugin::user();

// Access database
$payments = Database::query("SELECT * FROM payments");

// Register routes
Route::post('my-plugin/action', 'MyController@action');

// Add admin pages
Menu::add('Dashboard', 'my-plugin', '/admin/my-plugin');
```

## Managing plugins

### Via admin panel

Go to **System > Plugins** to view, enable, or disable plugins.

### Via CLI

```bash theme={null}
php public/index.php plugin:list
php public/index.php plugin:enable my-plugin
php public/index.php plugin:disable my-plugin
php public/index.php plugin:test my-plugin
```

## Best practices

* Follow OwnPay coding standards
* Include tests and documentation
* Validate all input and escape output
* Use parameterized queries
* Respect the permission system
* Store secrets in config, never hardcoded
* Log important events
* Queue heavy tasks


## Related topics

- [Addon Plugin Development - Build General-Purpose Extensions](/docs/developer/plugin-types/addon-development.md)
- [Developer Quickstart - Build Your First Payment Integration](/docs/developer/quickstart.md)
- [System Health Check](/docs/api-reference/system-health-check.md)
- [Theme Plugin Development - Customize Checkout Appearance](/docs/developer/plugin-types/theme-development.md)
- [Plugin Capabilities - Declare Features and Permissions](/docs/developer/plugins/capabilities.md)