Payum Nganluong Laravel Package

Technical Evaluation

Architecture Fit

• Payum Integration: The package leverages Payum, a flexible payment abstraction layer for PHP, which aligns well with Laravel’s modular and extensible architecture. Payum’s event-driven design ensures compatibility with Laravel’s service container and dependency injection.
• Gateway-Specific Logic: The Nganluong gateway (Vietnamese payment provider) abstracts provider-specific API calls, reducing custom implementation effort for payment processing.
• Deprecation Note: Since the package is deprecated in favor of ekipower/nganluong, a direct migration path exists, but the TPM must assess whether the newer package offers critical improvements (e.g., bug fixes, feature parity, or Laravel-specific optimizations).

Integration Feasibility

• Laravel Compatibility: Payum is framework-agnostic but integrates seamlessly with Laravel via service providers, facades, or manual bootstrapping. The payum/payum package (v3+) is recommended for Laravel 8+ due to its improved PSR-15 middleware support.
• Configuration Overhead: Minimal—requires Payum’s core setup (e.g., PayumBundle or standalone Payum) plus Nganluong-specific configurations (API keys, endpoints).
• Testing Complexity: Mocking payment gateways in Laravel’s testing suite (e.g., using payum/payum-bundle's test utilities) is straightforward but may require stubbing Nganluong’s API responses.

Technical Risk

• Deprecation Risk: The package is deprecated; reliance on it may introduce long-term maintenance risks. The TPM should:
  • Verify if ekipower/nganluong (the successor) resolves critical issues (e.g., Laravel 10 compatibility, security patches).
  • Plan for a time-bound migration to the newer package.
• Payum Version Lock: Ensure the package’s Payum version (likely v2) aligns with Laravel’s ecosystem. Payum v3+ is recommended for modern Laravel apps.
• Error Handling: Nganluong-specific errors (e.g., API rate limits, Vietnamese bank-specific failures) may require custom exception handling in Laravel’s middleware or service layer.
• Webhook/Callback Support: If Nganluong uses asynchronous callbacks, Laravel’s Http middleware or queue workers (e.g., Illuminate\Queue) will be needed to process responses.

Key Questions

1. Why Deprecated?

   • Are there unresolved bugs, security vulnerabilities, or missing features in ekipower/payum-nganluong that ekipower/nganluong addresses?
   • Does the newer package support Laravel’s latest LTS version?

2. Business Criticality

   • Is Nganluong a mandatory payment provider for the product, or is it a secondary option?
   • What’s the downtime risk if the package fails during a transaction?

3. Team Expertise

   • Does the team have experience with Payum or similar payment abstractions? If not, budget for ramp-up time.
   • Are there existing Laravel payment services (e.g., Stripe, PayPal) that could serve as a fallback?

4. Compliance & Localization

   • Does Nganluong require specific Vietnamese compliance (e.g., VAT handling, bank redirects)? How does this interact with Laravel’s localization features?
   • Are there multi-currency or multi-gateway requirements that this package doesn’t support?

5. Monitoring & Observability

   • How will payment failures (e.g., Nganluong API timeouts) be logged? Laravel’s Monolog or third-party tools (e.g., Sentry)?
   • Are there real-time transaction status needs that require webhook integration?

Integration Approach

Stack Fit

• Laravel Core: The package integrates via Payum’s service container, making it compatible with Laravel’s service providers, facades, or manual DI.
• Payum Bundle: For Laravel 8+, use payum/payum-bundle (v3+) for built-in routing, configuration, and testing utilities.
• Alternatives:
  • Standalone Payum: For Laravel <8 or custom setups, use payum/payum (v3+) with manual service registration.
  • Laravel Cashier: If Nganluong is a primary provider, evaluate if Cashier’s extensibility can wrap Payum (though this is non-trivial).

Migration Path

1. Assess Deprecation Impact:
   • Fork the package temporarily if ekipower/nganluong lacks critical features.
   • Use composer’s replace in composer.json to transition to the new package:

     "repositories": [
       { "type": "vcs", "url": "https://github.com/ekipower/nganluong" }
     ],
     "require": {
       "ekipower/nganluong": "^1.0"
     },
     "replace": {
       "ekipower/payum-nganluong": "ekipower/nganluong"
     }
     

2. Payum Version Alignment:
   • If the new package uses Payum v3+, update Laravel’s Payum integration:

     composer require payum/payum-bundle:^3.0
     

3. Configuration Migration:
   • Replace ekipower/payum-nganluong service definitions with ekipower/nganluong in Laravel’s config/services.php or Payum’s YAML/array config.
   • Example (PayumBundle v3):

     # config/packages/payum.yaml
     services:
         payum.nganluong:
             class: Ekipower\Nganluong\NganluongGateway
             arguments:
                 - '@payum.core_api'
                 - { apiKey: '%env(NGANLUONG_API_KEY)%' }
     

4. Testing:
   • Use Payum’s PayumTest utilities to mock Nganluong responses:

     use Payum\Core\Bridge\Symfony\Tests\PayumTest;
     
     public function testNganluongPayment()
     {
         $this->client->followRedirects(false);
         $capture = PayumTest::getCapture();
         // ... test logic
     }
     

Compatibility

• Laravel Versions:
  • Payum v3+ requires PHP 8.0+ and Laravel 8+. For older Laravel, use Payum v2 (higher risk).
• Database/ORM:
  • No direct ORM dependencies, but transaction statuses may need a payments table. Use Laravel’s migrations:

    Schema::create('payments', function (Blueprint $table) {
        $table->id();
        $table->string('gateway'); // e.g., 'nganluong'
        $table->json('details');
        $table->timestamps();
    });
    

• Queue Workers:
  • If Nganluong uses async callbacks, configure Laravel’s queue system:

    // config/queue.php
    'connections' => [
        'database' => [
            'driver' => 'database',
            'table' => 'payment_jobs',
            // ...
        ],
    ];
    

Sequencing

1. Phase 1: Proof of Concept (PoC)
   • Set up Payum + Nganluong in a sandbox environment.
   • Test:
     • API key authentication.
     • Redirect flows (if Nganluong uses bank redirects).
     • Webhook handling (if applicable).
2. Phase 2: Core Integration
   • Integrate with Laravel’s payment service layer (e.g., app/Services/PaymentService.php).
   • Add middleware for:
     • Rate limiting (e.g., throttle).
     • Error translation (e.g., Vietnamese error messages).
3. Phase 3: Observability
   • Log payment events to Laravel’s logs/payments.log.
   • Add Sentry or Laravel Debugbar integration for transaction tracing.
4. Phase 4: Fallback & Monitoring
   • Implement a circuit breaker (e.g., spatie/fractal) for Nganluong failures.
   • Set up health checks (e.g., laravel-health) to monitor gateway availability.

Operational Impact

Maintenance

• Dependency Updates:
  • Monitor ekipower/nganluong for updates. Since it’s MIT-licensed, forks may be necessary if the package stagnates.
  • Payum’s core updates may require Laravel config adjustments (e.g., middleware changes in v3).
• Security Patches:
  • Nganluong API changes (e.g., new security protocols) may require package updates. Plan for quarterly security audits.
• Configuration Drift:
  • API keys, endpoints, and timeouts should be environment-specific (use Laravel’s .env).

Support

• Vendor Lock-in:
  • Ngan