feat: add mock payment plugin and callback service

[ginaxu1]

Closes #233

Screen.Recording.2026-03-24.at.13.53.10.mov

Summary

This PR introduces a secure, pluggable payment architecture to process gateway responses. Added the PaymentGateway interface to support multiple vendors (starting with GovPay) and a dedicated PaymentService to act as the domain orchestrator. Secure state transitions are guaranteed using an Outbound Fetch pattern, ensuring that task updates (IDLE → IN_PROGRESS → COMPLETED) only occur after direct server-to-server verification with the gateway provider.

Changes Made

backend/internal/task/plugin/gateway/ (Pluggable Architecture)

• Define PaymentGateway interface in interface.go, separating untrusted data extraction (ExtractReference) from secure verification (GetPaymentInfo).
• GovPay Adapter: implement GovPayProvider to encapsulate vendor-specific logic, including URL generation for the hosted checkout page and reference extraction from GovPay webhooks.
• Add a thread-safe Registry to manage multiple gateway instances, allowing the system to switch providers dynamically based on the transaction context.

backend/internal/payment/ (Domain Orchestration)

• Create a new PaymentService to house business logic previously residing in API handlers. It orchestrates the Outbound Fetch flow: receiving a raw webhook, extracting a reference, verifying it directly with the gateway's API, and updating the internal database
• The service uses GORM DB transactions (s.db.Transaction) to update statuses and prevent race conditions. Upon successful verification, it calls tm.ExecuteTask to transition the internal FSM state securely

backend/internal/task/api/payment.go (Transport Layer)

• Refactor PaymentHandler to be transport-only. It now purely extracts the {provider} from the URL path and delegates all processing to the PaymentService
• Add HandleTransactionInquiry to support synchronous GET requests from the LankaPay network, delegating the final JSON schema formatting to the specific gateway adapter

backend/internal/task/plugin/payment.go (FSM & Plugin)

• Payment FSM: implement the PaymentTask plugin with a finite state machine: IDLE ──(INITIATE_PAYMENT)──► IN_PROGRESS ──(PAYMENT_SUCCESS)──► COMPLETED.
• Session Persistence: implement robust session management using readSession and WriteToLocalStore to persist the gateway URL and transaction metadata in the task's local store
• Lazy Timeout Checking: add logic in GetRenderInfo to automatically transition tasks from IN_PROGRESS back to IDLE if a payment session exceeds its TTL, triggering a rotation of the payment session

backend/internal/app/bootstrap/ (System Wiring)

• Service Registration: wire PaymentService into the application container and inject the TaskManager to enable the service to drive task state changes
• Update WireManagers to register an upstream callback. This ensures that when the PaymentService completes a task, the WorkflowManager is automatically notified to progress the overall workflow

Portals (Trader App)

• Update Payment.tsx to handle the INITIATE_PAYMENT action. It now correctly receives and handles the gatewayUrl for redirection to external payment portals like GovPay
• URL Parameter Handling: implement a useEffect hook to detect the payment_error query parameter on return redirects, instantly alerting the user if an external transaction failed
• State Propagation: update TaskDetailScreen.tsx to pass an onTaskUpdated callback to the plugin renderer, allowing the UI to refresh seamlessly upon mock or local payment completions

[gemini-code-assist]

Code Review

This pull request introduces a new payment processing feature, including a PaymentConfig struct, a payment_transactions database table, and a PaymentHandler for processing payment callbacks and transaction inquiries. The backend now exposes programmatic ExecuteTask functionality and passes database and configuration to payment task plugins. The frontend integrates a mock payment screen and updates the Payment component to handle different payment methods and gateway redirections. Review feedback highlights several areas for improvement: the onTaskUpdated prop is no longer passed to the Payment component, which could lead to less smooth UI refreshes for instant card payments; the API key comparison in HandleTransactionInquiry should use a constant-time comparison to mitigate timing attacks; the "dummy" plugin instantiation for GetTransactionByReference could be refactored into a dedicated service for better decoupling; and the use of TaskID as ExecutionID in the payment_transactions table might not be granular enough to track individual payment attempts, especially in retry scenarios.

[gemini-code-assist]

Code Review

This pull request introduces a robust and extensible payment processing system, which is a significant feature. The use of a gateway interface and registry for different providers is excellent for future maintainability. The database-backed transaction handling with row-level locking in processPayment is well-implemented to ensure atomicity and prevent race conditions.

I've identified a couple of critical bugs related to database schema and state initialization that will cause runtime failures, and a medium-severity issue regarding hardcoded mock secrets. Please see the detailed comments for suggestions on how to address these points.

[ginaxu1]

nit: keep domain logic out of the HTTP handlers and TM

1. GovPay sends a webhook (or an inquiry GET request) to /api/v1/payments/lankapay/callback
2. api.PaymentHandler receives the HTTP request, extracts the {provider} and payload, and passes it to PaymentService.ProcessCallback()
3. PaymentService uses the Registry to find the correct gateway provider, verifies the payload, and extracts the ReferenceNo
4. PaymentService looks up the referenceNo in PaymentTransactionDB to find the associated TaskID
5. PaymentService calls tm.ExecuteTask(ctx, req) with the TaskID and the success/failure action

[gemini-code-assist]

Code Review

This pull request introduces a new payment processing system, integrating external payment gateways into the existing task management workflow. Key changes include adding a payment_transactions database table, new configuration for payment providers, and a payment.Service to manage callbacks and inquiries. The TaskManager and PaymentTask plugin were refactored to utilize a gateway.Registry and paymentRepository for persistent transaction management, moving away from local store history. The frontend Payment component was updated to support the new flow, including handling redirects to external gateways and passive polling for transaction status. Review comments highlight a critical inconsistency in payment status handling between the FSM and database, a missing validation for mandatory production payment secrets in the configuration, inconsistent environment variable naming for payment settings, and limited extensibility in the payment gateway selection logic.

[ginaxu1]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a well-designed and secure payment architecture. The separation of concerns into a PaymentService, gateway Registry, and task Plugin is excellent. The use of an "Outbound Fetch" pattern, database transactions with row locking, and robust state management in the PaymentTask plugin demonstrates strong attention to security and reliability. The frontend changes are also well-implemented, especially the polling mechanism on the payment return screen.

I have one main point of feedback:

1. A critical security stub in the GovPayProvider that bypasses payment verification. This must be addressed before production.

Overall, this is a very strong contribution. Addressing this point will make it ready for merging.

[gemini-code-assist]

The GetPaymentInfo function is currently a stub that always returns a success result. This completely bypasses the "Outbound Fetch" security pattern described in the pull request, where the backend should make a secure server-to-server call to the payment gateway to verify the transaction status. Without this verification, the system is vulnerable to fraudulent payment confirmations. While this is acceptable for initial development, it's critical to implement the actual verification logic before this code reaches production. Please ensure a ticket is created to track the implementation of the real verification API call or HMAC signature validation.