Php Sdk V2 Laravel Package

Technical Evaluation

Architecture Fit

• Modularity: The SDK retains its clean, object-oriented abstraction over Mangopay's REST API, which aligns with Laravel's service-oriented architecture. v5.1.0 adds ApiExtendedPreauthorizations (exposed as $api->ExtendedPreauthorizations) as a deliberate mirror of the existing deposits API, so the mental model, method surface (Create(), Get(), Update(), GetAllForUser(), GetAllForCard(), GetTransactions()), and error behaviour are consistent with what the team already knows.
• PSR Compliance: Unchanged — PSR-4 autoloading and PSR-3 logging continue to integrate cleanly with Laravel's container and Monolog.
• Polymorphic Responses (new): Get(), Update(), and GetAllForUser() return either a PayPalExtendedPreauthorization or an ExtendedPreauthorization depending on how the preauthorization was created. This is an implicit type-dispatch that Laravel services must handle explicitly (instance checks or a mapped DTO), otherwise downstream code will hit type errors that surface only for PayPal-originated records.
• Enum Surface (new): ExtendedPreauthorizationStatus (CREATED, SUCCEEDED, FAILED) is a bounded, PHP 8.1-friendly enum that maps cleanly to Eloquent enum casts, unlike the older DepositStatus class-constant pattern.
• Event Taxonomy Expansion (new): Eight extended-preauthorization event types and ten settlement event types were added to EventType. This is a webhook-contract change, not an SDK-call change — the risk sits in the Laravel webhook consumer, not in the package.
• Domain-Specific: Still fintech-specialised; the team should continue wrapping SDK calls in Laravel services/repositories rather than letting entity objects leak into controllers or jobs.

Integration Feasibility

• Laravel Compatibility: Unchanged — Composer-based install, service-provider registration, and container binding all work as before. v5.1.0 is additive at the API level; nothing the existing integration calls has been removed.
• Service Container: The existing MangopayServiceProvider binding remains valid. No new configuration keys are required, though the team may want a feature flag (e.g. services.mangopay.preauthorization_mode) to gate the deposits → extended-preauthorization cutover per environment.
• Deprecation, Not Removal: ApiDeposits, DepositStatus, Transaction::$DepositId, and ApiPayIns::CreatePayInDepositPreauthorizedWithoutComplement() all still function but are marked for removal in a future major version. This is a scheduled migration, not an emergency.
• New Capability Available Immediately: ApiPayIns::CreatePayInExtendedPreauthorized() opens the extended-preauthorized PayIn flow (full capture) without requiring a deposit object first — a genuine product capability, not just a rename.
• SCA Hook: ProfilingAttemptReference on UserNaturalSca and UserLegalSca is an optional field that lets the platform pass its own profiling/KYC attempt reference into Mangopay, improving reconciliation between internal onboarding records and vendor-side SCA checks.
• Technical Risk:
  • Deprecation Horizon: Medium. No removal date is published, but a future major will drop ApiDeposits and Transaction::$DepositId. Any persisted deposit_id column, report, or reconciliation job becomes technical debt with an unknown expiry.
  • Dual Code Paths: Teams running deposits and extended preauthorizations side by side during migration will maintain two service classes, two sets of tests, and two webhook handlers — a real but bounded cost.
  • Polymorphic Handling: Low-to-medium. The PayPal/standard dispatch is easy to get wrong and will only fail on PayPal traffic, which is typically a minority of test cases.
  • Unknown Event Types: Low but sharp. Consumers that throw or 500 on unrecognised EventType values will now fail on 18 new constants the moment Mangopay starts emitting them.
  • mTLS Complexity: Unchanged — PHP ≥8.1 and cURL ≥7.71.0 for Base64-encoded certificate support; filesystem fallback still introduces secrets-management overhead.
  • Temporary File Management: Unchanged — TemporaryFolder still needs a Laravel filesystem abstraction and periodic cleanup.

Key Questions

1. Deprecation Ownership: Who owns the deposits → extended-preauthorizations migration, and what is the target date relative to our next major Laravel upgrade? Is there a Mangopay-published removal timeline we can anchor to?
2. Data Model: Do we persist Transaction::$DepositId anywhere (columns, ledgers, exports)? Renaming to ExtendedPreauthorizationId needs a schema migration and a reconciliation-window plan, not just a code change.
3. Polymorphism: How will our service layer normalise PayPalExtendedPreauthorization vs ExtendedPreauthorization — a mapped internal DTO, or an interface check at the boundary?
4. Webhook Resilience: Does our consumer already ignore unknown EventType values gracefully? If not, that change should ship before Mangopay begins emitting extended-preauthorization and settlement events.
5. Settlement Events: Are the ten new SETTLEMENT_* events in scope for this quarter's reconciliation work, or explicitly deferred? Scope creep here is easy to absorb silently.
6. SCA Reconciliation: Is ProfilingAttemptReference something we can populate from existing KYC records, or does it require a new identifier?
7. Authentication & Performance: Unchanged from prior assessment — credential sourcing (.env vs config/services.php vs secrets manager), mTLS certificate custody, rate-limit monitoring against Mangopay's ~1000 req/min, and idempotency-key handling on retries all remain open.

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Service Layer: Keep wrapping SDK calls in Laravel services. Add app/Services/MangopayExtendedPreauthorizationService alongside the existing deposit service during the transition, then retire the deposit service once traffic is fully cut over.
  • Repositories / Eloquent: Map ExtendedPreauthorization and PayPalExtendedPreauthorization into local models. Cast ExtendedPreauthorizationStatus via Eloquent's enum cast (PHP 8.1 backed enum) rather than string comparison.
  • Normalisation Layer: Introduce a thin internal DTO or interface (e.g. App\Support\Mangopay\Preauthorization) that both SDK entity types collapse into, so controllers and jobs never branch on vendor class names.
  • Webhook Routing: Replace ad-hoc switch statements over EventType with a lookup table (config/mangopay-events.php or an enum-keyed handler map) that resolves to a job class and has an explicit default that logs and acknowledges.
  • Testing: Mock SDK responses with PHPUnit/PestPHP as before. Add fixtures for PayPal-originated preauthorizations, each new ExtendedPreauthorizationStatus, and every new EventType constant — these are the paths most likely to be untested.
• Migration Path:
  1. Phase 0 — Pin and Harden Webhooks: Pin mangopay4/php-sdk to ^5.1 and ship the "unknown event type is logged, not thrown" change before enabling anything new. This is the cheapest risk reduction available.
  2. Phase 1 — Webhook Event Adoption: Register handlers (or explicit no-op acknowledgements) for the extended-preauthorization and settlement event constants. Confirm Mangopay is not already emitting events we're silently dropping.
  3. Phase 2 — Greenfield Uses New APIs: Any new preauthorization flow goes straight to $api->ExtendedPreauthorizations and ApiPayIns::CreatePayInExtendedPreauthorized(). No new deposits code is written.
  4. Phase 3 — Backfill Migration: Port existing deposit flows one at a time behind a feature flag, starting with the lowest-volume merchant or use case. Add the Transaction::$DepositId → $ExtendedPreauthorizationId schema migration and run both fields in parallel through one reconciliation cycle.
  5. Phase 4 — Retire Deposits: Remove deposit service classes, config, and DB columns once parity is confirmed across a full settlement window.
• Compatibility:
  • PHP Version: SDK's PHP 8.1+ requirement aligns with Laravel 9+/10+ and is what makes the enum-based status handling viable.
  • Laravel Versions: No known conflicts with Laravel's HTTP client, queue, or scheduler systems.
  • Deprecations: All deprecated symbols remain functional in 5.1.0 — the integration will not break on upgrade, only on the subsequent major.
• Sequencing Notes: The webhook work (Phase 1) and the deposit migration (Phase 3) are independent and can run in parallel with different owners. The schema change for ExtendedPreauthorizationId should follow, not precede, the service-layer cutover, so the old column remains readable during rollback.

Operational Impact

Maintenance

• Dependency Updates: Pin to ^5.1 and monitor Mangopay's changelog for the major that removes deposits. Treat the deprecation list as a tracked backlog item with an owner, not a comment in code.
• Deprecation Sweep: Grep the codebase for ApiDeposits, Deposits->, DepositStatus, DepositId, and CreatePayInDepositPreauthorizedWithoutComplement and record every hit as a migration ticket. This is a finite, enumerable list — which makes the effort estimable.
• Configuration Drift: Centralise SDK config in config/services.php as before, adding a mode flag for the preauthorization cutover so the same codebase serves sandbox, staging, and production with different behaviour.
• Temporary Files: Continue scheduling php artisan mangopay:clean-temp; extended preauthorizations do not change the SDK's temp-folder usage.
• Event Contract Drift: Store the set of handled EventType values as configuration so adding a handler is a config change plus a job, not a code edit buried in a controller.

Support

• Error Handling: Extend App\Exceptions\Handler as before for ResponseException, and add explicit handling for type mismatches in polymorphic preauthorization responses so they surface as actionable alerts rather than generic 500s.
• Unknown Events: Log and acknowledge unrecognised EventType values with the raw payload retained for one cycle. This turns a potential outage into a backlog item.
• Support Channels: Mangopay's GitHub Issues remain the escalation path for SDK defects; the deprecation notices themselves are a vendor-roadmap question better raised through the account manager than the issue tracker.
• Observability Gaps: Add metrics for extended-preauthorization status transitions (CREATED → SUCCEEDED/FAILED) and for settlement events received per day, so a silently broken webhook route is visible without waiting for a merchant to report a missing payment.

Scaling

• Rate Limiting: Unchanged — throttle against Mangopay's ~1000 req/min ceiling with a cache-backed counter and hourly reset. Note that extended-preauthorization flows add calls per transaction (Create → Get → CreatePayInExtendedPreauthorized), so effective request volume per checkout rises modestly.
• Queue Workers: Offload preauthorization creation, status polling, and all webhook handling to Laravel queues. Settlement processing in particular is batch-shaped and should not run synchronously in a request cycle.
• Failure Modes:
  • Polymorphic Mismatch: A PayPalExtendedPreauthorization returned where only the standard type is handled — fails only on PayPal traffic, so it needs dedicated fixtures rather than hoping sandbox coverage catches it.
  • Unhandled Event Types: New constants arriving before handlers exist; mitigated by the log-and-acknowledge default.
  • Enum Drift: If Mangopay adds a fourth ExtendedPreauthorizationStatus value, a strict enum cast will throw. Decide now whether unknown statuses are logged-and-mapped or hard failures.
  • Mixed-Mode Reconciliation: During migration, deposits and extended preauthorizations coexist in reporting; any reconciliation job keyed on DepositId will silently under-count.
• Ramp-Up: The deposits → extended-preauthorizations rename is conceptually simple but touches schema, reporting, webhooks, and finance reconciliation simultaneously. Budget for a short internal walkthrough of the status lifecycle and the PayPal branch before Phase 3 starts, and route the first migrated flow through a single low-volume merchant.