Ti Ext Payregister Laravel Package

Technical Evaluation

Architecture Fit

The ti-ext-payregister package (v4.4.0) retains its strong alignment with Laravel's service provider pattern, event-driven workflows, and queue-based async processing. The v4.1.2 Stripe webhook hardening (mandatory signing secret) remains in force and is now joined by a breaking Square SDK migration that shifts the integration from a builder-based pattern to sub-client instantiation—this is architecturally cleaner long-term but requires code-level adapter changes on the consuming side.

Key Strengths (Updated):

• Enforced Security (Stripe): Mandatory Stripe webhook secrets still prevent replay attacks and unauthorized event processing.
• Modernized Square Client: Migration to ~47.0 SDK replaces legacy SquareClientBuilder with a sub-client structure (payments, customers, cards, refunds) — closer to idiomatic Laravel DI and easier to mock in tests.
• Type-Safety in Amount Formatting: Refund, order, and tip amounts are now cast to float before number_format, eliminating deprecation warnings and type errors on string inputs — reduces silent failures in invoice/refund flows.
• Decoupled Gateway Design: Unchanged — Stripe, Mollie, Square, and other providers remain encapsulated behind the gateway contract.
• Offsite Mode: Still reduces PCI scope.

Updated Misalignment:

• Square Breaking Change: Any custom listener, observer, or direct SDK usage built against SquareClientBuilder will fail on upgrade. Must refactor to the new sub-client API.
• Stripe Webhook Secret Dependency (carried forward): Still a breaking constraint for multi-tenant / shared webhook endpoints.
• TastyIgniter-Specific: Assumes ti-ext-* module system; vanilla Laravel still needs adapter layers.
• Frontend UX: Offsite redirects remain incompatible with SPA/instant-checkout flows.

Integration Feasibility

• Laravel Compatibility:
  • PHP 8.1+ required (unchanged).
  • Stripe SDK v12+ still enforced for webhook validation.
  • Square SDK ~47.0 now required — verify composer.json lockstep with the package constraint.
  • No database schema changes in this release.
• Gateway-Specific Setup:
  • Stripe: Mandatory STRIPE_WEBHOOK_SECRET (unchanged from v4.1.2).
  • Square:
    • Breaking: Direct instantiation of Square\Client or SquareClientBuilder in custom code must migrate to SquareClient with sub-clients.
    • Action: Audit any custom refund/order/tip code calling old API classes. Replace with $client->refunds->refund(...), $client->payments->create(...), etc.
    • Action: Verify Square account credentials still resolve in v47 SDK (access token + environment config unchanged in shape, but SDK validation is stricter).
  • Mollie: Unchanged (Omnipay-based).
  • Authorize.Net/PayPal: Unchanged.
• Webhook Handling: No webhook change in v4.4.0 — v4.1.2's mandatory Stripe secret validation remains authoritative.
• Amount Formatting Fix: Audit any code that already casts these amounts or relies on the previous string-based behavior (e.g., locale-specific formatting, integer-only tip logic) — the float cast may subtly change rounding for amounts stored as numeric strings.

Feasibility Risks (Updated):

Technical Risk

Key Questions for TPM (Updated)

1. Square Migration (NEW):

   • Does any custom code instantiate SquareClientBuilder or individual Square API classes directly? If yes, it must be refactored before upgrading.
   • How are refund/tip/order amounts currently stored — as strings or floats? Confirm the new cast doesn't alter accounting output.
   • Is there a Square sandbox test plan covering refunds, tips, and multi-currency formatting?

2. Security & Compliance (Stripe):

   • How are Stripe webhook secrets currently managed? (Manual .env edits? Version-controlled?)
   • Are there multi-tenant or shared webhook endpoints that conflict with the mandatory secret requirement?

3. Infrastructure:

   • Is the webhook endpoint behind a WAF? (Cloudflare, AWS ALB)
   • Can the team implement a circuit breaker for Stripe webhook failures without downtime?

4. Provider Strategy:

   • Will other gateways evolve similar breaking SDK migrations (Square is now the first non-Stripe to break)? Establish a gateway SDK lifecycle policy.
   • Is the team prepared to rotate Stripe secrets every 6 months?

5. Migration Impact:

   • Are there existing custom Square listeners or jobs that need refactoring to sub-client calls?
   • How will the team test Square v47 and Stripe webhook validation in staging vs. production?
   • Is there a rollback plan if either the Square SDK upgrade or Stripe validation breaks existing integrations?

6. Operational Impact:

   • Who monitors webhook and Square API failures post-deployment? (Sentry, Laravel Horizon)
   • What is the rollback window if v4.4.0's Square migration causes reconciliation errors?

Integration Approach

Stack Fit

The package remains optimized for Laravel, but v4.4.0 adds a second breaking surface (Square) to the previously introduced Stripe constraint:

• Service Providers: Unchanged — gateways register as Laravel services. Square now binds a SquareClient instance; verify scoping (singleton vs. transient) to avoid re-instantiating per request.
• Events/Listeners: Custom Stripe listeners must still validate secrets (from v4.1.2). New: custom Square listeners must use the new sub-client API.
• Queues: Unchanged — but failed Square jobs may spike during the SDK cutover; expect transient errors until the refactor is deployed.
• Middleware: Stripe webhook middleware still required (v4.1.2). No new middleware for Square.
• Blade/Middleware: Offsite redirect flows unchanged.

Compatibility Matrix (Updated):

Migration Path (Updated)

Phase 1: Prep & Security Hardening (1 Week) — carried forward

1. Stripe Secret Configuration: Same as v4.1.2 (mandatory STRIPE_WEBHOOK_SECRET, config/payregister.php update, Envoy automation).
2. Stripe Middleware: StripeWebhookMiddleware remains required.
3. NEW — Square SDK Audit:
   • Action: Grep codebase for SquareClientBuilder, Square\Apis\, Square\Api\.

     grep -rn "SquareClientBuilder\|Square\\\\Apis\|Square\\\\Api\\\\" app/ packages/
     

   • Action: Catalogue every hitsite — refunds, orders, customers, cards, tips.
   • Action: Map old call sites → new sub-client equivalents ($client->refunds->refund(...), etc.).

Phase 2: Square Refactor (1–2 Weeks)

1. Replace builder instantiation:
   • Old: new SquareClientBuilder()->build(new Configuration(...)).
   • New: new SquareClient(getenv('SQUARE_ACCESS_TOKEN'), ['environment' => ...]).
2. Replace per-resource API classes with $client->payments, $client->customers, $client->cards, $client->refunds.
3. Verify amount handling: Confirm float casts preserve accounting semantics for the currencies in use; add regression tests for refund/tip math.
4. Sandbox verification: Run full Square sandbox suite — payment, refund, partial refund, tip, card-on-file.

Phase 3: Rollout (1 Week)

1. Deploy middleware first (Stripe) — no-op if secrets present.
2. Deploy Square refactor behind a feature flag if possible; fall back to previous package version if reconciliation fails.
3. Monitor webhook failure rates, Square API error rates, and refund reconciliation for 72 hours.
4. Rollback gate: Document the exact composer.json pin to revert to prior version if v4.4.0 breaks production.

Operational Impact

Maintenance

• Additional gateway to track: Square SDK ~47.0 now has its own changelog cadence and deprecation cycle. TPM should subscribe the platform team to Square SDK release notes in addition to Stripe.
• Two SDK upgrade streams (Stripe v12+ and Square v47) increase maintenance surface. Consider a "gateway SDK upgrade" calendar aligned with quarterly Laravel upgrade windows.

Support

• Support playbook must now cover: (a) Stripe webhook secret rotation, (b) Square SDK breaking upgrades, (c) Square amount-formatting regressions (refund/tip discrepancies).
• First-line triage: add a diagnostic check for "is this a Stripe validation failure or a Square SDK mismatch?" — both manifest as failed jobs but require very different remediation.

Scaling

• Queue workers unchanged but now carry Square refund/order jobs through the same pipeline; scale workers proportionally to Square volume (refund-heavy merchants may need extra capacity).
• SquareClient should be bound as a singleton in the service provider to avoid per-request instantiation cost across many small API calls.

Failure Modes

1. Silent Square failure: Old SquareClientBuilder calls in custom code that compile but throw at runtime → refunds fail without obvious alerting. Mitigate with exception monitoring on Square gateway class.
2. Webhook crash (Stripe): Unchanged from v4.1.2 — missing/invalid secret throws, crashing the endpoint.
3. Amount drift: Float casting of previously-string amounts may produce off-by-cents discrepancies in reconciliation; requires finance/ops sign-off on test cases.
4. Mixed-version mismatch: If one environment is on v4.1.2 and another on v4.4.0, Square integration behavior diverges — enforce composer lock parity across environments.

Ramp-Up

• Onboarding materials must cover two gateway SDKs (Stripe + Square) rather than one primary. Estimate ~1–2 days of ramp-up per engineer to be productive on Square refunds/orders under the new sub-client API.
• Add a "gateway SDK upgrade" runbook to the ops playbook — the current one only documents Stripe secret rotation.
• Recommend a short internal tech talk / lunch-and-learn on the Square v47 migration to reduce future support load.