diff --git a/README.md b/README.md
index c82a771..4191370 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,44 @@
-# PipraPay — Payment Automation Platform
+# [PipraPay](https://piprapay.com) - Payment Automation Platform
-PipraPay is a **self-hosted payment automation platform** by QubePlug Bangladesh.
-You host it on your own server, define your own workflow, install custom plugins or themes — and stay in control. It’s free forever for users, with no monthly fees. ([piprapay.com](https://piprapay.com/))
+PipraPay is a self-hosted payment automation platform by QubePlug Bangladesh.
+Host it on your own server, define your workflow, install plugins and themes, and stay in control. It’s free to use with no monthly fees. Visit https://piprapay.com/ for more info.
+
+---
+
+## Table of Contents
+
+- Documentation
+- Features
+- Installation
+- License & Brand Protection
+- Trademark Policy
+- Contributing
+- Community & Support
+
+---
+
+## 📖 Documentation
+
+- Developer guides live in `docs/`:
+ - Payment Gateway Plugins: [docs/Payment-Gateway-Plugins-Developer-Guide.md](docs/Payment-Gateway-Plugins-Developer-Guide.md)
+ - Module Plugins: [docs/PipraPay-Module-Plugin-Developer-Guide.md](docs/PipraPay-Module-Plugin-Developer-Guide.md)
+
+- PipraPay Plugins & Integrations Directory
+ - Plugin Directory: [docs/Plugin-Directory.md](docs/Plugin-Directory.md)
+- Browse all docs: [docs/](docs/)
+- API docs: [piprapay.readme.io](https://piprapay.readme.io)
---
## 🚀 Features
-- Self-hosted: deploy it on your server, no dependency on third-party services. ([piprapay.com](https://piprapay.com/))
-- Plugin-based architecture: add payment gateways, modules, or tools; just like WordPress. ([piprapay.com](https://piprapay.com/))
-- Theme support for admin dashboard branding. ([piprapay.com](https://piprapay.com/))
-- Multiple gateways supported (Stripe, bKash, Nagad, etc.) via plugins. ([piprapay.com](https://piprapay.com/))
-- Auto transaction verification to reduce manual work. ([piprapay.com](https://piprapay.com/))
-- Unlimited transactions — scale as much as your server allows. ([piprapay.com](https://piprapay.com/))
-- Integration with platforms like WooCommerce, WHMCS, WordPress. ([piprapay.com](https://piprapay.com/))
+- Self-hosted: deploy on your own server with no third‑party lock‑in.
+- Plugin-based architecture for gateways, modules, and tools.
+- Theme support for admin dashboard branding.
+- Multiple gateways (Stripe, bKash, Nagad, etc.) via plugins.
+- Automatic transaction verification to reduce manual work.
+- Scales to unlimited transactions (within your server capacity).
+- Integrations with platforms like WooCommerce, WHMCS, and WordPress.
---
@@ -23,38 +48,38 @@ You host it on your own server, define your own workflow, install custom plugins
```bash
git clone https://github.com/PipraPay/PipraPay-Open-Source-Web.git
```
-2. Setup server with PHP, database, web server (Apache/Nginx).
-3. Upload source files to your server.
-4. Install dependencies (if any).
-5. Configure database credentials, domain, etc.
-6. Access admin panel, install plugins, set up gateways.
+2. Prepare your environment: PHP, a database, and a web server (Apache/Nginx).
+3. Upload or place the source files on your server.
+4. Install dependencies (if any) as per your setup.
+5. Configure database credentials, domain, and environment settings.
+6. Access the admin panel, install plugins, and configure gateways.
---
## 📚 License & Brand Protection
-- Code is licensed under **GNU Affero General Public License v3.0 (AGPL-3.0)**. You are free to use, modify.
+- Code is licensed under the GNU Affero General Public License v3.0 (AGPL‑3.0). See [LICENSE](LICENSE).
---
## 🛡️ Trademark Policy
-The **PipraPay name, logo, and brand identity** are trademarks of QubePlug Bangladesh.
+The PipraPay name, logo, and brand identity are trademarks of QubePlug Bangladesh.
-### What you CAN do:
+### ✅ What you can do
- Use PipraPay as provided, including branding.
-- Build and share plugins, modules, themes.
+- Build and share plugins, modules, and themes.
- Contribute back to this repository.
-### What you CANNOT do:
-- Rebrand the system (e.g. rename it to another product).
-- Remove or replace “PipraPay” name/logo/brand in a modified version and present it as your own brand.
+### ❌ What you cannot do
+- Rebrand the system (e.g., rename it to another product).
+- Remove or replace the PipraPay name/logo/brand in a modified version and present it as your own brand.
---
## 🤝 Contributing
-We welcome contributions from the community! To contribute:
+We welcome contributions from the community. To contribute:
1. Fork this repository.
2. Create a new branch:
@@ -63,20 +88,223 @@ We welcome contributions from the community! To contribute:
```
3. Make your changes.
4. Commit with a clear message.
-5. Push to your fork.
-6. Open a Pull Request explaining your changes.
+5. Push to your fork and open a Pull Request describing your changes.
+
+---
+
+## ❓ Common Issues & Solutions
+
+
+⏳ Pending payment is not auto-verifying
+
+**Possible Cause:**
+The cron job responsible for verifying payments is not running.
+
+**Solution:**
+1. Log in to the PipraPay **Admin Panel**.
+2. Navigate to **System Settings > Cron Job**.
+3. Copy the provided command.
+4. Set the cron job in your hosting control panel to run every **10 minutes**.
+
+
---
-## ⚡ Summary
+
+🔌 PipraPay tool app is not connecting
+
+**Possible Cause:**
+The base URL or webhook URL is not properly configured.
-PipraPay = control, freedom, extensibility.
-Open source where it matters. Brand protected. Build your payment workflows, scale your business, without giving up ownership.
+**Solution:**
+1. First, add your **base URL** (e.g., `https://example.com` or `https://pay.example.com`).
+2. After setting the base URL, add the **full webhook URL**.
+
+
---
-## 📬 Community & Support
+
+💳 No payment methods showing in the Admin Panel
+
+**Possible Cause:**
+The payment method plugins are not activated.
+
+**Solution:**
+1. Go to **Admin Panel > Plugin > Installed Plugins**.
+2. Activate the required **payment method plugins**.
+
+
+
+---
+
+
+🛒 Payment methods not showing on the checkout page
+
+**Possible Causes:**
+- Minimum and maximum payment amounts are not configured.
+- The payment method is disabled.
+
+**Solution:**
+1. Set the **minimum and maximum amount** for the payment method.
+2. Verify the **status**:
+ - If it is **disabled**, switch it to **enabled**.
+
+
+
+---
+
+
+💱 Currency mismatch (e.g., 1000 BDT showing as $1000 USD)
+
+**Possible Cause:**
+Currency exchange rates are not set correctly.
+
+**Solution:**
+1. In the **Admin Panel**, go to **System Settings > Currency Settings**.
+2. Update the currency rate.
+ - Example: `1 BDT = 0.0082 USD` (not `1 BDT = 1 USD`).
+
+
+
+---
+
+
+🔄 Website does not redirect after successful payment
+
+**Possible Cause:**
+Auto-redirect option is not enabled.
+
+**Solution:**
+1. Go to **Admin Panel > Appearance > Customize**.
+2. Enable the **Auto Redirect** option.
+
+
+
+---
+
+
+🔑 Forgot Admin Panel password
+
+**Solution:**
+1. Log in to your **hosting control panel**.
+2. Open the directory where **PipraPay files** are located.
+3. Edit the file `pp_config.php`.
+4. Change:
+ ```php
+ $password_reset = 'off';
+ ```
+ to
+ ```php
+ $password_reset = 'on';
+ ```
+5. Go to the **PipraPay Admin Login page** and click **Reset Password**.
+6. Set your new password.
+7. Re-edit `pp_config.php` and set:
+ ```php
+ $password_reset = 'off';
+ ```
+
+⚠️ **Important:** Always revert `$password_reset` to `'off'` after resetting for security reasons.
+
+
+
+---
+
+
+🌐 Payment API returning errors
+
+**Possible Cause:**
+Incorrect API credentials or endpoint configuration.
+
+**Solution:**
+1. Verify your **API key** and **secret** from the Admin Panel.
+2. Ensure the API endpoint matches your environment (**sandbox** vs **production**).
+3. Test using a REST client (e.g., Postman).
+
+
+
+---
+
+
+📦 Checkout page not loading properly
+
+**Possible Cause:**
+JavaScript conflicts or missing plugin files.
+
+**Solution:**
+1. Clear your **browser cache**.
+2. Recheck plugin installation in the Admin Panel.
+3. Disable conflicting plugins or themes temporarily.
+
+
+
+---
+
+
+🖥️ Hosting errors (500 Internal Server Error)
+
+**Possible Cause:**
+Server misconfiguration or insufficient resources.
+
+**Solution:**
+1. Check your server **error logs**.
+2. Increase **memory limit** and **max execution time** in PHP settings.
+3. Restart your web server (Apache/Nginx).
+
+
+
+---
+
+
+🔐 SSL certificate issues
+
+**Possible Cause:**
+Expired or misconfigured SSL certificate.
+
+**Solution:**
+1. Renew your SSL certificate with your hosting provider.
+2. Update the certificate path in your server configuration.
+3. Test the SSL status using online tools like **SSL Labs**.
+
+
+
+---
+
+
+📧 Customers not receiving email notifications
+
+**Possible Cause:**
+Email server or SMTP configuration is incorrect.
+
+**Solution:**
+1. Go to **Admin Panel > Plugins > Installed Plugin > SMTP Mailer Pro**.
+2. Go to **Admin Panel > Modules > SMTP Mailer Pro > Configure SMTP with valid credentials**.
+3. Test the email function using the built-in test tool.
+
+
+
+---
+
+
+⚙️ Database connection failed
+
+**Possible Cause:**
+Invalid database credentials or server downtime.
+
+**Solution:**
+1. Verify database credentials in `pp_config.php`.
+2. Check database server status.
+3. Ensure correct **host, port, username, and password** are set.
+
+
+
+---
+
+## 🤷♂️ Community & Support
+
+- Website: https://piprapay.com/
+- Documentation: [docs/](docs/)
+- License: [LICENSE](LICENSE)
+- Issues & bug reports: https://github.com/PipraPay/PipraPay-Open-Source-Web/issues
-- Documentation: [readme.io / PipraPay docs]
-- Issues & Bug Reports: GitHub Issues page
-- For help with using or customizing: Community forum or contact QubePlug
diff --git a/docs/Payment-Gateway-Plugins-Developer-Guide.md b/docs/Payment-Gateway-Plugins-Developer-Guide.md
new file mode 100644
index 0000000..05fc34e
--- /dev/null
+++ b/docs/Payment-Gateway-Plugins-Developer-Guide.md
@@ -0,0 +1,333 @@
+# PipraPay Payment Gateway Plugins — Developer Guide
+
+> **Version:** v1.0
+> **Author:** [Fattain Naime](https://facebook.com/fattain.naime)
+> **Summary:** A well‑detailed payment gateway developer documentation for PipraPay.
+
+---
+
+## Contents
+1. [Architecture Overview](#1-architecture-overview)
+2. [Database & Settings](#2-database--settings)
+3. [Plugin Anatomy & Files](#3-plugin-anatomy--files)
+4. [Runtime Contracts](#4-runtime-contracts)
+5. [Core Helper APIs](#5-core-helper-apis)
+6. [Payment Flows (Manual vs API)](#6-payment-flows)
+7. [Step‑by‑Step: Build a New Gateway](#7-step-by-step-build-a-new-gateway)
+8. [Boilerplates & Templates](#8-boilerplates--templates)
+9. [Hooks & Webhooks](#9-hooks--webhooks)
+10. [Security & UX](#10-security--ux)
+11. [Go‑Live Checklist](#11-go-live-checklist)
+12. [Examples](#12-examples)
+13. [FAQ](#13-faq)
+
+---
+
+## 1) Architecture Overview
+
+Every payment method is an isolated plugin located under:
+
+```text
+pp-content/plugins/payment-gateway/
+```
+
+> **How PipraPay loads plugins**
+> Active plugins are recorded in the `plugins` table. At runtime, PipraPay autoloads each gateway’s PHP class file and calls your
+> `__admin_page()` and `__checkout_page($payment_id)` functions when needed.
+
+---
+
+## 2) Database & Settings
+
+Gateways are registered in `__PREFIX__plugins` with core columns:
+
+- `plugin_name` — display name
+- `plugin_slug` — unique slug (e.g., `stripe-checkout`)
+- `plugin_dir` — usually `payment-gateway`
+- `plugin_array` — JSON of saved settings (credentials, fees, limits, mode)
+- `status` — `active` / `inactive`
+
+> The Admin UI writes settings into `plugin_array`. Use `pp_get_plugin_setting($slug)` to read them at checkout time.
+
+---
+
+## 3) Plugin Anatomy & Files
+
+```
+/
+├─ meta.json
+├─ -class.php
+├─ views/
+│ ├─ admin-ui.php # Admin: configure gateway
+│ └─ checkout-ui.php # Checkout: pay flow UI + action
+├─ assets/
+│ └─ icon.png # 128×128 recommended
+└─ readme.txt # Description / changelog
+```
+
+### `meta.json`
+
+```json
+{
+ "type": "payment-gateway",
+ "slug": "your-gateway",
+ "name": "Your Gateway",
+ "mrdr": "payment-gateway"
+}
+```
+
+### `-class.php`
+
+```php
+ 'Your Gateway',
+ 'Version' => '1.0.0',
+ 'Author' => 'Your Name'
+];
+
+function your_gateway_admin_page() {
+ $viewFile = __DIR__ . '/views/admin-ui.php';
+ if (file_exists($viewFile)) { include $viewFile; }
+ else { echo "Admin UI not found.
"; }
+}
+
+function your_gateway_checkout_page($payment_id) {
+ $viewFile = __DIR__ . '/views/checkout-ui.php';
+ if (file_exists($viewFile)) { include $viewFile; }
+ else { echo "Checkout UI not found.
"; }
+}
+```
+
+### `views/admin-ui.php`
+
+```php
+
+
+
+```
+
+### `views/checkout-ui.php`
+
+```php
+
+```
+
+---
+
+## 4) Runtime Contracts
+
+- Folder name == **slug** (kebab-case).
+- Main file name must be `-class.php`.
+- Admin function: `_admin_page()`
+- Checkout function: `_checkout_page($payment_id)`
+- AJAX POST target often appends `?method=` to `pp_get_paymentlink($payment_id)`.
+
+> **Tip:** Keep `slug` stable. PipraPay uses it to find settings, routes, and function bindings.
+
+---
+
+## 5) Core Helper APIs
+
+Frequently used helpers provided by PipraPay core (observed in real plugins):
+
+- `pp_get_settings()` — global site/app settings (branding, currency, etc.)
+- `pp_get_plugin_info($slug)`
+- `pp_get_plugin_setting($slug)`
+- `pp_get_transation($payment_id)`
+- `pp_get_faq()`, `pp_get_support_links()`
+- `pp_get_paymentlink($payment_id)`
+- `pp_set_transaction_byslip($payment_id, $slug, $display_name, $_FILES['payment_slip'], $status)`
+- Utilities: `convertToDefault()`, `safeNumber()`
+
+---
+
+## 6) Payment Flows
+
+### A) Manual / Slip Upload
+
+```php
+ $ok ? "true" : "false",
+ "message" => $ok ? "Initialize Payment Slip" : "Failed to upload payment slip"
+ ]);
+ exit();
+}
+```
+Use for bank transfers or providers without instant API capture.
+
+### B) Redirect / API (e.g., bKash)
+
+```php
+request('POST', $base_url.'/v1.2.0-beta/tokenized/checkout/token/grant', [
+ 'body' => json_encode(['app_key' => $app_key, 'app_secret' => $app_secret]),
+ 'headers' => [
+ 'accept' => 'application/json',
+ 'content-type' => 'application/json',
+ 'password' => $password,
+ 'username' => $username,
+ ],
+]);
+$id_token = json_decode($resp->getBody())->id_token;
+// then create payment, redirect to PSP URL
+```
+
+---
+
+## 7) Step‑by‑Step: Build a New Gateway
+
+1. Create folder `pp-content/plugins/payment-gateway/your-gateway`
+2. Add `meta.json` and `readme.txt`
+3. Implement `your-gateway-class.php` (admin/checkout loaders)
+4. Build `views/admin-ui.php` (credentials, fees, limits, status)
+5. Build `views/checkout-ui.php` (manual slip OR API/redirect)
+6. (Optional) add `assets/` and `functions.php`
+7. Enable plugin in Admin & test sandbox → live
+
+---
+
+## 8) Boilerplates & Templates
+
+### Folder Layout
+
+```
+your-gateway/
+├─ meta.json
+├─ your-gateway-class.php
+├─ views/
+│ ├─ admin-ui.php
+│ └─ checkout-ui.php
+├─ assets/
+│ └─ icon.png
+└─ readme.txt
+```
+
+### Admin Form (AJAX)
+
+```html
+
+```
+
+---
+
+## 9) Hooks & Webhooks
+
+Lightweight action system similar to WordPress:
+
+```php
+// Register a callback
+add_action('pp_transaction_ipn', 'your_gateway_handle_ipn');
+
+function your_gateway_handle_ipn($transaction_id) {
+ // verify provider webhook, update transaction state, notify customer, etc.
+}
+```
+
+Common core hooks:
+
+- `pp_transaction_ipn` — payment notification received
+- `pp_invoice_ipn` — invoice status updated
+
+---
+
+## 10) Security & UX
+
+- Never echo secrets; mask inputs and store in settings only
+- Validate/escape output (e.g., `htmlspecialchars(...)`)
+- Use HTTPS; verify PSP signatures and webhook authenticity
+- Keep amounts on server as source of truth
+- Offer sandbox/live mode toggle where supported
+- Clear customer messaging and error handling
+- Log key events (avoid storing PCI data)
+
+---
+
+## 11) Go‑Live Checklist
+
+- [x] Slug = folder name (kebab‑case) & file names match
+- [x] `meta.json` complete
+- [x] Admin & checkout functions exported
+- [x] Admin form saves & rehydrates values
+- [x] Amount + fee computation correct
+- [x] Manual flow: slip upload → status `pending`
+- [x] API flow: sandbox tested, credentials validated
+- [x] Icon present; readme has changelog
+
+---
+
+## 12) Examples
+
+### Stripe Checkout
+- `stripe-checkout-class.php` with `stripe_checkout_admin_page()` & `stripe_checkout_checkout_page()`
+- Admin: secret key + webhook secret
+- Checkout: Stripe.js or hosted Checkout Session
+
+### PayPal Checkout
+- `paypal-checkout-class.php` with `paypal_checkout_admin_page()` & `paypal_checkout_checkout_page()`
+- Admin: client ID + secret
+- Checkout: PayPal SDK smart buttons
+
+> Also see local “manual/slip” gateways and wallet APIs (e.g., bKash) for real-life patterns.
+
+---
+
+## 13) FAQ
+
+### What file names are mandatory?
+Folder = *slug*, main PHP = `-class.php`, `meta.json`, and both view files.
+
+### Where are settings stored?
+In `__PREFIX__plugins.plugin_array` as JSON. Use `pp_get_plugin_setting($slug)` to read.
+
+### How do I compute total payable amount?
+```php
+$base = convertToDefault(amount, fromCurrency, $settings['currency']);
+$fee = fixed_charge + ($base * percent_charge / 100);
+$payable = $base + $fee;
+```
+
+---
+
+© PipraPay — Payment Gateway Developer Documentation
diff --git a/docs/PipraPay-Module-Plugin-Developer-Guide.md b/docs/PipraPay-Module-Plugin-Developer-Guide.md
new file mode 100644
index 0000000..f25637a
--- /dev/null
+++ b/docs/PipraPay-Module-Plugin-Developer-Guide.md
@@ -0,0 +1,195 @@
+# PipraPay Module Plugin Developer Guide
+
+* **Version**: v1.0
+* **Author**: [Fattain Naime](https://iamnaime.info.bd)
+* **Summary**: PipraPay exposes a lightweight plugin system that allows you to extend the core gateway with module plugins. Modules run alongside payment gateways and can listen to lifecycle hooks, schedule background work, expose admin UI, and react to transaction or invoice changes. This document explains how the system works and how to build, package, and maintain a new module plugin.
+
+## Files and Directory Layout
+Module plugins live under `pp-content/plugins/modules//`. A typical module contains:
+
+```
+pp-content/plugins/modules//
++-- meta.json # Required manifest used when importing from ZIP
++-- -class.php # Required entry point that populates $plugin_meta and loads helpers
++-- functions.php # Optional; registers hooks with add_action()
++-- views/ # Optional admin UI or partial templates
++-- assets/icon.png # 256x256 icon surfaced in the admin panel
++-- other PHP/JS/CSS files # Any module-specific code (IPN endpoints, utilities, etc.)
+```
+
+### `meta.json`
+The importer expects the following keys:
+
+```json
+{
+ "type": "plugins",
+ "slug": "my-module",
+ "name": "My Module",
+ "mrdr": "modules"
+}
+```
+
+* `type` must be `plugins`.
+* `slug` becomes the directory name and database identifier.
+* `mrdr` is the plugin directory root (`modules` for module plugins).
+
+### `-class.php`
+Each plugin must expose `$plugin_meta` (used for the admin listing) and may load additional files:
+
+```php
+if (!defined('pp_allowed_access')) {
+ die('Direct access not allowed');
+}
+
+$plugin_meta = [
+ 'Plugin Name' => 'My Module',
+ 'Description' => 'What your plugin does.',
+ 'Version' => '1.0.0',
+ 'Author' => 'Acme Devs'
+];
+
+$funcFile = __DIR__ . '/functions.php';
+if (file_exists($funcFile)) {
+ require_once $funcFile;
+}
+
+function my_module_admin_page() {
+ $viewFile = __DIR__ . '/views/admin-ui.php';
+ if (file_exists($viewFile)) {
+ include $viewFile;
+ } else {
+ echo "Admin UI not found.
";
+ }
+}
+```
+
+`parsePluginHeader()` reads `$plugin_meta`, so keep the keys consistent with the sample above.
+
+### `functions.php`
+Place all hook registrations and module business logic inside this file. Always guard against direct access with the `pp_allowed_access` constant. Use `add_action()` to subscribe to hooks (details below). Split complex logic into smaller functions or dedicated classes when helpful.
+
+## How PipraPay Loads Module Plugins
+1. **Import (optional).** Uploading a ZIP through *Admin -> Add New* uses the importer defined in `pp-include/pp-model.php` to unpack into `pp-content/plugins////` and validate `meta.json`.
+2. **Activation.** The admin panel toggles plugin records via the `pp_plugins` table. When you activate a module, PipraPay stores the slug, marks it `active`, and remembers the directory.
+3. **Execution.** Whenever `pp_trigger_hook()` runs, it finds all active plugins, includes their `functions.php`, and then executes callbacks that were registered with `add_action()` (or matching `_` functions). This happens at runtime for each hook invocation, so make sure hook registration is idempotent.
+4. **Admin view loading.** When you open a module inside the admin navigation the system loads `pp-include/pp-resource/plugin-loader.php`, requires `-class.php`, and calls `_admin_page()`.
+
+## Hook System
+The hook API lives in `pp-include/pp-controller.php`:
+
+* `add_action($hook, $callback)` - registers a callback for a hook.
+* `do_action($hook, ...$args)` - runs all callbacks for a hook.
+* `pp_trigger_hook($hook, ...$args)` - loads every active plugin, requires its `functions.php`, then delegates to `do_action()`. After firing registered callbacks, PipraPay also looks for a function named `_` and calls it as a fallback.
+
+Hooks have no priority or argument count enforcement, so write callbacks that can accept optional parameters (`function foo($arg = null)` or `function foo(...$args)`).
+
+## Hook Reference
+| Hook | Trigger location | Arguments | Typical use |
+|------|------------------|-----------|-------------|
+| `pp_cron` | `index.php?cron` | none | Schedule tasks, auto-update checks, queue processing. |
+| `pp_admin_initialize` | Early in `admin/index.php` | none | Inject admin guards (2FA), load extra assets, enforce restrictions. |
+| `pp_transaction_ipn` | Multiple transaction updates (manual approval, cron auto-verify, slip upload) | `$transactionId` | Send notifications, push webhooks, reconcile ledgers. |
+| `pp_invoice_ipn` | Invoice status changes (IPN handler, bulk updates, manual edits) | `$invoiceId` | Notify customers, send receipts, sync accounting. |
+| `pp_invoice_initialize` | After invoice theme render (`invoice/index.php`) | none | Inject custom JavaScript, tracking pixels, or preload data when a public invoice is opened. |
+| `pp_payment_initialize` | After checkout theme render (`payment/index.php`) | none | Adjust checkout UI, preload payment metadata, fire analytics. |
+| `pp_payment_link_initialize` | When a payment link page is shown (`payment-link/index.php`) | none | Inject custom scripts or banner content for payment links. |
+
+> Tip: `pp_transaction_ipn` and `pp_invoice_ipn` are invoked frequently; keep handlers lightweight and fail-safe so they never block the core workflow.
+
+## Working with Plugin Settings
+Use the helper functions in `pp-include/pp-controller.php`:
+
+* `pp_get_plugin_setting($slug)` - returns the JSON blob stored for your plugin.
+* `pp_set_plugin_setting($slug, $array)` - persists new settings to the `plugins` table.
+* `pp_get_plugin_info($slug)` - metadata such as display name and directory.
+
+The admin panel expects AJAX forms to submit with `action=plugin_update-submit` and `plugin_slug=`. After activation you can render a settings form in `views/admin-ui.php` similar to the SMTP module. When posted, the core handler stores all remaining fields as JSON.
+
+## Accessing Platform Data
+Useful helpers available to modules include:
+
+* `pp_get_site_url()` - base URL with the current host.
+* `pp_get_settings()` - global settings row (currency, API keys, etc.).
+* `pp_get_transation($id)` - fetches a payment transaction by PipraPay ID (or accepts a custom SQL fragment).
+* `pp_get_invoice($invoiceId)` / `pp_get_invoice_items($invoiceId)` - fetch invoice header and line items.
+* `pp_get_payment_link($linkId)` and related item fetchers.
+* `pp_verify_transaction()` - cross-checks a transaction against SMS gateway data.
+* `pp_set_transaction_byid()` / `pp_set_transaction_byslip()` - mark transactions as completed, refunded, or slip-verified (these fire `pp_transaction_ipn`).
+
+Inspect `pp-include/pp-controller.php` for many more helpers (customer lookup, file utilities, etc.).
+
+## Building a New Module Plugin
+1. **Choose a slug.** Stick to lowercase letters, numbers, and dashes (`my-new-module`).
+2. **Create the directory.** `pp-content/plugins/modules/my-new-module/`.
+3. **Add `meta.json`.** Follow the schema shown above.
+4. **Create `my-new-module-class.php`.** Populate `$plugin_meta`, require `functions.php`, and define `my_new_module_admin_page()` if you need admin UI.
+5. **Create `functions.php`.** Guard with the `pp_allowed_access` constant, register hooks via `add_action()`, and implement callback logic. Retrieve data using the helper functions listed earlier.
+6. **(Optional) Add `views/admin-ui.php`.** Include a form that posts with `action=plugin_update-submit` and saves settings through AJAX.
+7. **Add an icon.** Place a PNG at `assets/icon.png` so the module is recognizable in the admin menu.
+8. **Activate the plugin.** In the admin panel go to *More -> Modules*, click your plugin, and press *Activate*. The first activation creates a database record if one does not already exist.
+9. **Test hooks.** Trigger the relevant flows (new transaction, invoice payment, cron job) to ensure your callbacks run.
+
+## Example: Minimal IPN Handler
+```php
+ $data['pp_id'],
+ 'amount' => $data['transaction_amount'],
+ 'currency' => $data['transaction_currency'],
+ 'status' => $data['transaction_status'],
+ ];
+
+ $ch = curl_init('https://example.com/webhook');
+ curl_setopt_array($ch, [
+ CURLOPT_POST => true,
+ CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
+ CURLOPT_POSTFIELDS => json_encode($payload),
+ CURLOPT_RETURNTRANSFER => true,
+ CURLOPT_TIMEOUT => 8,
+ ]);
+ curl_exec($ch);
+ curl_close($ch);
+}
+```
+
+## Best Practices
+* **Stay idempotent.** Hooks like `pp_transaction_ipn` can fire multiple times. Track delivery state in your own storage if repeating work is problematic.
+* **Avoid long blocking calls.** Offload slow work to queues or keep timeouts low so you never stall payment processing.
+* **Validate input.** Use `escape_string()`, `filter_var()`, or built-in sanitizers before storing data supplied by users.
+* **Respect `pp_allowed_access`.** Never execute plugin code when the core constant is missing.
+* **Graceful failures.** Catch exceptions, return early when settings are incomplete, and write to PHP error logs instead of echoing raw errors.
+* **Secure endpoints.** If you expose additional public PHP files (for example, an IPN endpoint), validate tokens or signatures before executing logic.
+* **Use settings APIs.** Store configuration via `pp_set_plugin_setting()` instead of writing your own files so backups and migrations capture everything.
+
+## Debugging Tips
+* Enable PHP error logging (`pp-config.php`) and tail the log while developing.
+* Temporarily add `error_log()` calls inside your callbacks to confirm hook order and payloads.
+* Use the built-in bulk actions (Send IPN) inside the admin *Transactions* grid to manually re-fire `pp_transaction_ipn` during testing.
+
+## Packaging & Distribution
+* Ship modules as ZIP files that contain the plugin folder at the root. The importer understands both `my-module/` (folder) and flat archives.
+* Ensure all files are UTF-8 (ASCII-safe) and avoid BOM markers.
+* Include a short `readme.txt` if you want to surface installation notes inside the admin UI.
+
+Following these guidelines keeps your module plugins consistent with the bundled examples (SMTP mailer, webhook dispatch, Telegram notifications, etc.) and ensures they interoperate cleanly with core PipraPay updates.
+
+
+
+
+---
+
+© [PipraPay](https://piprapay.com) — Module Plugin Developer Documentation
\ No newline at end of file
diff --git a/docs/Plugin-Directory.md b/docs/Plugin-Directory.md
new file mode 100644
index 0000000..6720720
--- /dev/null
+++ b/docs/Plugin-Directory.md
@@ -0,0 +1,65 @@
+# PipraPay Plugins & Integrations Directory
+
+A curated list of official and community-created plugins and integrations related to PipraPay. To add or update an entry, open a Pull Request.
+
+- Back to README: [../README.md](../README.md)
+
+---
+
+## Official PipraPay Plugins/SDK/Module/Library for Third-Party Applications
+
+| Name | Type | Author |
+| --- | --- | --- |
+| [PipraPay Payment Gateway for FOSSBilling](https://github.com/PipraPay/fossbilling-piprapay-gateway) | Gateway | [PipraPay](https://github.com/PipraPay) |
+| [PipraPay Payment Gateway for BoxBilling](https://github.com/PipraPay/boxbilling-piprapay-gateway) | Gateway | [PipraPay](https://github.com/PipraPay) |
+| [PipraPay Clientexec Integration](https://github.com/PipraPay/clientexec-piprapay-gateway) | Integration | [PipraPay](https://github.com/PipraPay) |
+| [PipraPay WISECP Integration](https://github.com/PipraPay/wisecp-piprapay-gateway) | Integration | [PipraPay](https://github.com/PipraPay) |
+| [PipraPay SDK for CodeIgniter 3](https://github.com/PipraPay/codeigniter3-sdk-piprapay-gateway) | SDK | [PipraPay](https://github.com/PipraPay) |
+| [PipraPay PHP Library](https://github.com/PipraPay/php-library-piprapay-gateway) | Library | [PipraPay](https://github.com/PipraPay) |
+| [PipraPay Laravel SDK](https://github.com/PipraPay/laravel-sdk-piprapay-gateway) | SDK | [PipraPay](https://github.com/PipraPay) |
+| [PipraPay Payment Module for SMMCrowd](https://github.com/PipraPay/smmcrowd-piprapay-gateway) | Module | [PipraPay](https://github.com/PipraPay) |
+| [PipraPay Payment Module for SMM Matrix](https://github.com/PipraPay/smmmatrix-piprapay-gateway) | Module | [PipraPay](https://github.com/PipraPay) |
+| [Smart SMM Panel v4 - PipraPay Module](https://github.com/PipraPay/smart-smm-panel-v4-piprapay-gateway) | Module | [PipraPay](https://github.com/PipraPay) |
+| [PipraPay Active e-Commerce Integration](https://github.com/PipraPay/active-ecommerce-piprapay-gateway) | Integration | [PipraPay](https://github.com/PipraPay) |
+| [PipraPay Android SDK](https://github.com/PipraPay/android-sdk-piprapay-gateway) | SDK | [PipraPay](https://github.com/PipraPay) |
+| [EDD PipraPay Gateway](https://github.com/PipraPay/easydigitaldownload-piprapay-gateway) | Gateway | [PipraPay](https://github.com/PipraPay) |
+| [Modified SMM Panel PipraPay Gateway](https://github.com/PipraPay/modifiedsmmpanel-piprapay-gateway) | Gateway | [PipraPay](https://github.com/PipraPay) |
+| [PipraPay Gateway for WooCommerce](https://github.com/PipraPay/woocommerce-piprapay-gateway) | Gateway | [PipraPay](https://github.com/PipraPay) |
+| [Onest LMS Module for PipraPay](https://github.com/PipraPay/onest-lms-piprapay-gateway) | Module | [PipraPay](https://github.com/PipraPay) |
+| [PipraPay Blesta Integration](https://github.com/PipraPay/blesta-piprapay-gateway) | Integration | [PipraPay](https://github.com/PipraPay) |
+| [PipraPay Payment Module for PerfexCRM](https://github.com/PipraPay/perfexcrm-piprapay-gateway) | Module | [PipraPay](https://github.com/PipraPay) |
+| [PipraPay Payment Gateway for WHMCS](https://github.com/PipraPay/whmcs-piprapay-gateway) | Gateway | [PipraPay](https://github.com/PipraPay) |
+
+---
+
+## Community-Developed Plugins for Third-Party Applications
+
+| Name | Type | Author |
+| --- | --- | --- |
+| [PipraPay Gateway for WooCommerce](https://github.com/bdetopup/woocommerce-piprapay-gateway) | Gateway | [Asif Arman Saikot](https://github.com/bdetopup) |
+
+---
+
+## Community-Developed Payment Gateway Plugins for PipraPay
+
+| Name | Type | Author |
+| --- | --- | --- |
+| No entries listed yet | - | - |
+
+---
+
+## Community-Developed Module Plugins for PipraPay
+
+| Name | Type | Author |
+| --- | --- | --- |
+| [SMS Notification for PipraPay](https://github.com/fattain-naime/Custom-SMS-Gateway-for-PipraPay) | Module | [Fattain Naime](https://iamnaime.info.me) |
+| [Currency Rate Auto Update for PipraPay](https://github.com/fattain-naime/currency-rate-auto-update) | Module | [Fattain Naime](https://iamnaime.info.me) |
+| [Telegram Bot Notification Pro for PipraPay](https://github.com/refatbd/PipraPay-bot-notification-pro) | Module | [Refat Rahman](https://github.com/refatbd) |
+| [Transactions Import From Uddoktapay for PipraPay](https://github.com/NabilNewaz/transactions-import-uddoktapay-for-piprapay) | Module | [Nabil Newaz](https://github.com/NabilNewaz) |
+| [Advance Analytics for PipraPay](https://github.com/NabilNewaz/advance-analytics-for-piprapay) | Module | [Nabil Newaz](https://github.com/NabilNewaz) |
+| [Initialize Failed Analytics for PipraPay](https://github.com/NabilNewaz/initialize-failed-transactions-for-piprapay) | Module | [Nabil Newaz](https://github.com/NabilNewaz) |
+| [Customizable Payment Link Generator for PipraPay](https://github.com/refatbd/customizable-payment-link-generator) | Module | [Refat Rahman](https://github.com/refatbd) |
+
+---
+
+If you maintain a plugin or integration that should be listed here, please submit a Pull Request with the Plugin name, plugin Description, plugin URL, and author details.