[Architecture]: Payment provider plugin system for external gateway integrations

Start by reading the existing plugin system in the plugin-system-fresh branch and the payment flow in Sales.php; the issue also points to locale_helper.php:243 and the proposed Payments/Webhook controller. The work spans payment abstractions, events, database migrations, webhooks, payment-type migration, and view hooks, so first establish which architecture decisions are accepted. Done would mean implementing the agreed phases and verifying compatibility with the existing sales workflow.

Overview

This issue proposes a Payment Provider Plugin System architecture to enable seamless integration with external payment gateways like SumUp and PayPal (Zettle). This builds on the existing plugin system in the plugin-system-fresh branch and addresses multiple feature requests for payment processing enhancements.

Related Issues

• #4346 - SumUp integration
• #4322 - PayPal In Store (POS/Zettle) Integration
• #3232 - Configurable payment types with custom options
• #3789 - Third-party integration standard architecture
• #3790 - Payment type stored as translated string breaks reports
• #2275 - Customer balance and payment tracking

Problem Statement

Currently, OSPOS has:

1. Hardcoded payment types in locale_helper.php:243 (Cash, Debit, Credit, Due, Check, UPI)
2. No payment processing hooks - events fire after sale completion, not during payment
3. No payment provider abstraction - no way to register external payment gateways
4. No webhook infrastructure - no endpoints to receive payment callbacks
5. Localized payment_type strings in DB - causes issues with multilingual installs (#3790)

Proposed Architecture

1. PaymentProviderInterface

A new interface that payment plugins implement:

interface PaymentProviderInterface
{
    public function getProviderId(): string;
    public function getProviderName(): string;
    public function initiatePayment(float $amount, array $options): array;
    public function processCallback(array $data): array;
    public function getPaymentStatus(string $transactionId): string;
    public function refund(string $transactionId, float $amount): bool;
    public function getPaymentTypes(): array;  // Returns payment type options
    public function getIcon(): ?string;
    public function getConfigView(): ?string;
}

2. PaymentPluginBase Class

Abstract class extending BasePlugin implementing common payment provider logic:

abstract class PaymentPluginBase extends BasePlugin implements PaymentProviderInterface
{
    protected function logTransaction(string $transactionId, string $status, array $metadata = []): void;
    protected function getTransaction(string $transactionId): ?array;
    protected function validateCallbackSignature(array $data): bool;
}

3. New Events

Add payment-specific events in Sales.php:

Event	Location	Purpose
payment_options	get_payment_options()	Allow plugins to register dynamic payment types
payment_initiated	postAddPayment()	Before payment is added to sale
payment_completed	After successful payment	After payment processed
payment_failed	On payment failure	Handle failed transactions
sale_completed	Sale finalization	After sale record saved

4. Webhook Controller

New controller for external payment callbacks:

/app/Controllers/Payments/Webhook.php
Route: POST /payments/webhook/{provider_name}

5. Database Schema

Transaction tracking table:

CREATE TABLE ospos_payment_transactions (
    id INT AUTO_INCREMENT PRIMARY KEY,
    provider_id VARCHAR(50) NOT NULL,
    sale_id INT NULL,
    transaction_id VARCHAR(255) NOT NULL,
    amount DECIMAL(15,2) NOT NULL,
    currency VARCHAR(3) DEFAULT 'USD',
    status ENUM('pending','authorized','completed','failed','refunded') DEFAULT 'pending',
    metadata JSON,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_provider (provider_id),
    INDEX idx_sale (sale_id),
    INDEX idx_transaction (transaction_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

6. Payment Type Refactor

Refactor payment_type storage (#3790) from translated strings to provider-prefixed constants:

Current	Proposed
lang('Sales.credit') → "Credit Card"	provider:sumup:card
lang('Sales.cash') → "Cash"	builtin:cash
lang('Sales.debit') → "Debit"	builtin:debit

7. View Hook Points

Standard injection points for payment plugins:

Hook	Location	Purpose
view:payment_buttons	Register checkout UI	Payment method selection UI
view:receipt_payment_details	Receipt view	Show transaction details
view:sale_complete_actions	Post-sale screen	Refund/void buttons
view:payment_provider_config	Settings	Provider configuration UI

Shared Components (SumUp & PayPal)

Both integrations would share:

Component	Description
PaymentProviderInterface	Common contract
Transaction table	Shared tracking
Webhook controller	Unified callback handling
Settings storage	Via ospos_plugin_config
Icon system	Standardized payment icons
Status management	Common state machine
Receipt injection	Standard receipt format

SumUp-Specific

• Card reader terminal integration via SumUp API
• Real-time transaction status polling
• Terminal display integration
• Refund processing

PayPal-Specific

• PayPal/Zettle card reader integration
• QR code payment display
• Invoicing integration
• Multi-currency support

Implementation Phases

Phase 1: Foundation

• Create PaymentProviderInterface and PaymentPluginBase
• Add payment events to Sales.php
• Modify get_payment_options() to trigger payment_options event
• Create ospos_payment_transactions migration

Phase 2: Webhook Infrastructure

• Create Payments/Webhook controller
• Add routes for webhook endpoints
• Implement signature validation framework

Phase 3: Payment Type Refactor

• Migrate payment_type column to use provider-prefixed format
• Create migration to convert existing data
• Update all payment_type references

Phase 4: View System

• Add plugin_content() hook points in views
• Create payment button partials
• Add receipt injection helpers

Phase 5: Plugin Templates

• Create SumUp plugin stub
• Create PayPal plugin stub
• Documentation and examples

Benefits

1. Extensibility: Any payment gateway can be integrated as a plugin
2. Multilingual Support: Payment types no longer break across languages
3. Separation of Concerns: Payment logic isolated from core
4. Maintainability: Each provider maintains its own code
5. Reusability: Shared infrastructure for all payment plugins

Technical Considerations

• Must work with existing sales workflow (suspended sales, returns, etc.)
• Need to handle offline/delayed payment scenarios
• Currency handling for international providers
• Security implications for payment data storage
• PCI compliance considerations (token-based, no card data storage)

Questions for Discussion

1. Should payment provider plugins support both "pre-sale" (pay first, then complete sale) and "post-sale" (sale pending, pay via webhook) flows?
2. How should we handle the transition from string-based payment types to the new format?
3. Should we create a payment provider marketplace/registry?

---

Related to the plugin system in plugin-system-fresh branch.