Payment Plugin
Development Guide

Build custom payment integrations for the KobiZeka™ Hotel Management System. This guide covers the complete plugin architecture, from creating a simple offline payment method to building a full 3D Secure online payment gateway.

Introduction

The KobiZeka payment plugin system is designed to be modular and self-contained. Each plugin lives in its own directory under app/plugins/Payment/ and is automatically discovered by the PaymentPluginManager.

Plugins can be:

• Offline — Pay at hotel, bank transfer, cash on delivery
• Online — Credit card gateways (iyzico, PayTR, Stripe, etc.)

The system supports:

• Auto-discovery — just drop a folder with Provider.php
• Built-in settings management — define fields, the admin UI is generated automatically
• Multi-language — each plugin ships its own translation files
• 3D Secure callbacks and webhook handling
• Refund support (optional)

Architecture

The payment system consists of three main components:

Plugin Lifecycle

1. Discovery — Manager scans app/plugins/Payment/*/Provider.php
2. Registration — New plugins are auto-registered in the payment_plugins table
3. Configuration — Admin enables plugin and fills in settings (API keys, etc.)
4. Checkout — Active plugins appear on the reservation confirmation page
5. Payment — Guest selects method → createPayment() → redirect/process
6. Callback — Gateway sends result → handleCallback() → transaction saved

Directory Structure

Quick Start

PaymentProviderInterface

Every plugin must implement this interface. Here is the complete contract:

// app/plugins/Payment/PaymentProviderInterface.php

namespace App\Plugins\Payment;

interface PaymentProviderInterface
{
    // ─── Identity ───
    public function getSlug(): string;         // Unique ID: 'my_gateway'
    public function getDisplayName(): string;  // 'My Gateway'
    public function getDescription(): string;  // Short description
    public function getIcon(): string;         // FontAwesome: 'fa-credit-card'
    public function getVersion(): string;      // '1.0.0'
    public function getAuthor(): string;       // 'Your Company'
    public function getType(): string;         // 'online' or 'offline'

    // ─── Configuration ───
    public function getSettingsFields(): array; // Admin settings form fields
    public function isConfigured(): bool;      // Are API keys set?

    // ─── Checkout ───
    public function renderCheckoutInfo(array $reservation): string;

    // ─── Payment ───
    public function createPayment(array $reservation, float $amount): array;
    public function handleCallback(array $data): array;

    // ─── Refunds ───
    public function supportsRefund(): bool;
    public function refund(string $transactionId, float $amount): array;
}

Method Reference

Provider.php

The main plugin class. Must implement PaymentProviderInterface and use PluginTranslationTrait for multi-language support.

YourPlugin/Provider.phpnamespace App\Plugins\Payment\MyGateway;

use App\Plugins\Payment\PaymentProviderInterface;
use App\Plugins\Payment\PluginTranslationTrait;

class Provider implements PaymentProviderInterface
{
    use PluginTranslationTrait;

    public function getSlug(): string       { return 'my_gateway'; }
    public function getDisplayName(): string{ return $this->__p('name'); }
    public function getDescription(): string{ return $this->__p('description'); }
    public function getIcon(): string       { return 'fa-credit-card'; }
    public function getVersion(): string    { return '1.0.0'; }
    public function getAuthor(): string     { return 'Your Company'; }
    public function getType(): string       { return 'online'; }

    // ... see full examples below
}

Settings Fields

The getSettingsFields() method returns an array of field definitions. The admin panel automatically generates a settings form from these fields.

public function getSettingsFields(): array
{
    return [
        [
            'key'      => 'api_key',          // Setting key (stored in DB)
            'label'    => $this->__p('api_key'),  // Label (translated)
            'type'     => 'text',              // text | textarea | select | checkbox
            'default'  => '',                  // Default value
            'required' => true,                // Show as required in UI
        ],
        [
            'key'      => 'secret_key',
            'label'    => $this->__p('secret_key'),
            'type'     => 'text',
            'default'  => '',
            'required' => true,
        ],
        [
            'key'      => 'sandbox',
            'label'    => 'Sandbox Mode',
            'type'     => 'checkbox',
            'default'  => '1',
            'required' => false,
        ],
    ];
}

Supported Field Types

Checkout Rendering

The renderCheckoutInfo() method returns HTML that is displayed on the reservation confirmation page when the guest selects this payment method.

public function renderCheckoutInfo(array $reservation): string
{
    $html = '<div style="padding:16px;background:#f8f9fa;border-radius:10px">';
    $html .= '<h4>' . e($this->__p('name')) . '</h4>';
    $html .= '<p>You will be redirected to our secure payment page.</p>';
    $html .= '</div>';
    return $html;
}

Payment Flow

Online Plugins

For online payment gateways, the flow is:

public function createPayment(array $reservation, float $amount): array
{
    // 1. Read your API settings
    $mgr = \App\Plugins\Payment\PaymentPluginManager::getInstance();
    $apiKey = $mgr->getPluginSetting($this->getSlug(), 'api_key', '');

    // 2. Build payment request to gateway API
    $callbackUrl = base_url('payment/callback/' . $this->getSlug());

    // 3. Call gateway API...
    // $response = $gateway->createPayment(...);

    // 4. Return redirect URL
    return [
        'redirect_url'    => $response['payment_page_url'],
        'transaction_id'  => $response['token'],
    ];
}

Callback Handling

public function handleCallback(array $data): array
{
    // $data contains POST/GET parameters from the gateway

    // Verify the payment with gateway API...

    return [
        'success'        => true,
        'transaction_id' => $data['token'],
        'amount'         => 250.00,
        'currency'       => 'TRY',
        'message'        => 'Payment successful',
    ];
}

Offline Plugins

Offline plugins have simpler implementations:

// No redirect needed
public function createPayment(array $reservation, float $amount): array
{
    return [];
}

// No callback to handle
public function handleCallback(array $data): array
{
    return ['success' => false, 'message' => 'N/A'];
}

Refunds

If your gateway supports programmatic refunds, implement the refund methods:

public function supportsRefund(): bool { return true; }

public function refund(string $transactionId, float $amount): array
{
    // Call gateway refund API...
    return [
        'success' => true,
        'message' => 'Refund processed',
        'refund_id' => 'ref_abc123',
    ];
}

PluginTranslationTrait

The translation trait provides each plugin with its own isolated translation system. No need to modify core language files.

How It Works

1. Trait detects the current admin locale via admin_locale()
2. Loads the matching lang/{locale}.php from the plugin's own directory
3. Falls back through: requested locale → en → tr
4. Automatically reloads when locale changes (no caching issues)

Language Files

Each language file returns a simple key-value array:

YourPlugin/lang/en.php<?php
return [
    'name'         => 'My Gateway',
    'description'  => 'Secure online payments via My Gateway.',
    'api_key'      => 'API Key',
    'secret_key'   => 'Secret Key',
    'sandbox_note' => 'Use sandbox URL for testing',
];

YourPlugin/lang/tr.php<?php
return [
    'name'         => 'Ödeme Geçidi',
    'description'  => 'My Gateway ile güvenli online ödeme.',
    'api_key'      => 'API Anahtarı',
    'secret_key'   => 'Gizli Anahtar',
    'sandbox_note' => 'Test için sandbox URL kullanın',
];

Using __p()

Call $this->__p('key') anywhere in your Provider class:

// In identity methods
public function getDisplayName(): string { return $this->__p('name'); }

// In settings field labels
['label' => $this->__p('api_key')]

// In checkout rendering
$html .= '<p>' . e($this->__p('checkout_instructions')) . '</p>';

Plugin Manager API

Access the plugin manager from anywhere via the singleton:

$mgr = \App\Plugins\Payment\PaymentPluginManager::getInstance();

Database Schema

payment_plugins

payment_transactions

Helper Functions

These global functions are available in your plugin:

Security Guidelines

• Never log API keys or secrets — Use getPluginSetting() at runtime, never hardcode
• Always verify callbacks — Check signatures, hashes, or call the gateway's verification API
• Escape all output — Use e() for any data rendered in HTML
• Use HTTPS only — Never allow HTTP callback URLs
• Validate amounts — Compare the callback amount with the reservation amount
• Store raw responses — Save gateway responses in raw_response for dispute resolution
• Handle errors gracefully — Wrap gateway calls in try/catch, log errors, show user-friendly messages
• Test with sandbox — Always provide a sandbox/test mode toggle in your settings

Example: Offline Plugin

A complete offline payment plugin (e.g., "Pay at Hotel"):

PayAtHotel/Provider.php<?php
namespace App\Plugins\Payment\PayAtHotel;

use App\Plugins\Payment\PaymentProviderInterface;
use App\Plugins\Payment\PluginTranslationTrait;

class Provider implements PaymentProviderInterface
{
    use PluginTranslationTrait;

    public function getSlug(): string        { return 'pay_at_hotel'; }
    public function getDisplayName(): string { return $this->__p('name'); }
    public function getDescription(): string { return $this->__p('description'); }
    public function getIcon(): string        { return 'fa-hotel'; }
    public function getVersion(): string     { return '1.0.0'; }
    public function getAuthor(): string      { return 'KobiZeka'; }
    public function getType(): string        { return 'offline'; }

    public function getSettingsFields(): array
    {
        return [
            ['key' => 'title', 'label' => $this->__p('title_label'),
             'type' => 'text', 'default' => 'pay_at_hotel', 'required' => false],
            ['key' => 'accepted_methods', 'label' => $this->__p('accepted_methods'),
             'type' => 'text', 'default' => 'Cash, Credit Card', 'required' => false],
        ];
    }

    public function isConfigured(): bool { return true; }

    public function renderCheckoutInfo(array $reservation): string
    {
        return '<div class="checkout-info">'
            . '<p>' . e($this->__p('description')) . '</p>'
            . '</div>';
    }

    public function createPayment(array $reservation, float $amount): array
    {
        return []; // No redirect for offline
    }

    public function handleCallback(array $data): array
    {
        return ['success' => false, 'message' => 'N/A'];
    }

    public function supportsRefund(): bool { return false; }
    public function refund(string $tid, float $amt): array { return ['success' => false]; }
}

Full Plugin Template

Copy this template to start building your own plugin:

KobiZeka™ Hotel Management System
Payment Plugin Development Guide v1.0

Need help? Contact developer@kobizeka.com