Relay Mono Connector Payunity Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Relay API Gateway Dependency: The bundle is designed as a PayUnity connector for Relay’s mono-bundle, implying tight coupling with Relay’s API gateway architecture. If the system already uses Relay (or a similar API gateway pattern), this could integrate cleanly. However, if the stack lacks Relay, this becomes a non-starter without significant refactoring.
• Mono-Bundle Pattern: The "mono-bundle" suggests a modular, single-responsibility design for payment connectors. If the team follows a similar pattern (e.g., Symfony bundles for payment gateways), this could slot in neatly.
• PayUnity-Specific Logic: The bundle abstracts PayUnity’s API interactions (payments, webhooks, refunds, etc.). If PayUnity is a critical dependency, this reduces custom integration effort. If not, the bundle is obsolete due to PayUnity’s shutdown.

Integration Feasibility

• Symfony/Laravel Compatibility:
  • The bundle is Symfony-based (given the Bundle suffix and Relay’s Symfony roots), but Laravel can use it via Symfony’s Bridge (symfony/flex, symfony/console).
  • Feasibility: Medium. Laravel’s service container and event system may require adapters (e.g., wrapping Symfony’s ContainerAware services).
• Relay API Gateway:
  • If Relay is not used, the bundle’s core logic (PayUnity API calls) could be extracted and rewritten for Laravel’s HTTP client (Guzzle, Illuminate\Http). However, this defeats the purpose of using the bundle.
  • If Relay is used, integration is straightforward but limited to Relay’s ecosystem.

Technical Risk

• Deprecated Dependency: PayUnity’s shutdown makes this bundle high-risk for future-proofing. Any new project should avoid it unless:
  • PayUnity is a mandatory legacy provider.
  • The team plans to fork and maintain it (e.g., rewriting for Stripe/PayPal).
• Lack of Maintenance:
  • No stars, dependents, or updates since PayUnity’s shutdown.
  • No active community → Bug fixes, security patches, or feature requests will require internal effort.
• Testing & Documentation:
  • Basic tests exist (CI badge shows passing), but no end-to-end tests or mock PayUnity API responses.
  • Documentation is minimal (README + basic docs). Onboarding will require reverse-engineering the bundle’s logic.
• License (AGPL-3.0):
  • Copyleft risk: If the project is proprietary, AGPL may force open-sourcing the entire codebase. Mitigation: Fork under MIT or negotiate with Digital Blueprint.

Key Questions

1. Is Relay API Gateway already in use?
   • If no, is the team willing to adopt Relay, or should this logic be rewritten natively?
2. Is PayUnity a mandatory provider?
   • If no, should the team migrate to a supported alternative (e.g., Stripe, PayPal)?
3. What’s the migration path if PayUnity shuts down?
   • Does the team have a Plan B for payment processing?
4. Can the bundle be forked and maintained?
   • If yes, what resources (time, dev effort) are allocated for upkeep?
5. How will this integrate with Laravel’s event system?
   • Relay’s event model may differ from Laravel’s Events/Listeners. Will adapters be needed?
6. Are there compliance/legal concerns with AGPL?
   • If the project is proprietary, how will AGPL compliance be handled?

Integration Approach

Stack Fit

• Symfony vs. Laravel:
  • The bundle is Symfony-native, but Laravel can host it via:
    • Symfony’s HttpKernel (for API routes).
    • Service container bridging (e.g., Symfony\Bridge\Laravel\ServiceProvider).
  • Recommended: Use Laravel’s illuminate/support to wrap Symfony services (e.g., ContainerInterface → Laravel’s Container).
• Relay Dependency:
  • If Relay is not used, the bundle’s core logic (PayUnity API calls) can be extracted and rewritten using:
    • Laravel’s Http client (Guzzle under the hood).
    • Laravel’s Events for webhooks.
    • Laravel’s Service Providers for configuration.
  • Tradeoff: Loses Relay’s features (e.g., request/response transformation, retries).

Migration Path

Compatibility

• PHP Version: Check composer.json for required PHP version (likely 8.0+).
• Laravel Version: Ensure compatibility with Laravel’s service container (e.g., Illuminate\Contracts\Container\Container).
• Database: No direct DB dependencies, but PayUnity webhooks may require a database for storage (e.g., payments table).
• Webhooks: The bundle likely handles PayUnity webhooks. Laravel’s Route::post('/payunity/webhook') can be used, but signature verification must match PayUnity’s specs.

Sequencing

1. Assess Dependency Fit:
   • Confirm Relay usage. If not, decide between:
     • Rewriting logic natively.
     • Adopting Relay (high effort).
2. Fork & Adapt:
   • If using the bundle, fork it to:
     • Replace PayUnity API calls with a strategy pattern (easy to swap later).
     • Add Laravel-specific bindings (e.g., App\Providers\PayUnityServiceProvider).
3. Test Integration:
   • Mock PayUnity API responses (use VCR or Pest).
   • Test webhook handling (e.g., php artisan payunity:webhook-test).
4. Deploy & Monitor:
   • Start with a feature flag for PayUnity payments.
   • Monitor for PayUnity API deprecations (if still operational).

Operational Impact

Maintenance

• Short-Term:
  • Low effort if Relay is used and PayUnity is stable.
  • High effort if PayUnity APIs change or Relay updates break compatibility.
• Long-Term:
  • Unsustainable due to PayUnity’s shutdown. Plan for:
    • Forking and rewriting for a new provider.
    • Deprecation timeline (e.g., 6–12 months before PayUnity’s full shutdown).
• Dependencies:
  • Monitor composer.json for outdated Symfony/Laravel packages.
  • Security: AGPL may require auditing for vulnerabilities.

Support

• No Vendor Support:
  • Issues must be resolved internally or via community (nonexistent).
  • Workaround: Create an internal GitHub repo for patches.
• Error Handling:
  • PayUnity API failures may require custom retries (Laravel’s Retry package).
  • Logging: Ensure monolog is configured for PayUnity-related errors.
• Documentation Gaps:
  • Internal docs must cover:
    • Webhook signature verification.
    • Payment flow (e.g., "How to handle failed PayUnity transactions?").
    • Migration steps if PayUnity shuts down.

Scaling

• Performance:
  • PayUnity API calls may introduce latency. Consider:
    • Caching (e.g., Illuminate\Cache) for rate-limited endpoints.
    • Async processing (Laravel Queues) for webhooks.
  • Load testing: Simulate high-volume PayUnity webhooks.
• Database:
  • Webhook storage may grow. Optimize with:
    • Partitioning (e.g., by year/month).
    • Archiving old webhook logs.
• Concurrency:
  • If Relay is used, it may handle concurrency. If not, ensure Laravel’s queue workers are scaled.

Failure Modes