Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto
  • ¿Algo no está bien?
#4,456 1 comentario 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 2 días

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
25/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Estancado
Stack tecnológico
mysql, php
Área
api, backend, payments

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

enhancement

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.

Lenguaje dominante
PHP
Estrellas
4.4k
Forks
2.6k
Merge medio
3 d 8 h
PR fusionados (30 d)
29

Preparar el entorno

  • Incluye un Dockerfile o un archivo de Docker Compose
  • Sin plantilla de pull request
  • Sin guía de contribución

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de opensourcepos/opensourcepos

Todos los issues de opensourcepos/opensourcepos

Issues similares

Más issues de PHP

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.