Filament Flow Laravel Package

Technical Evaluation

Architecture fit. Filament Flow v1.0.0 is a thin, opinionated integration layer between a Laravel application and Flow.cl (Chilean payment processor), packaged as a first-party-style Filament plugin. Architecturally it splits into four concerns: (1) a Filament settings page plus a reusable credentials schema, (2) an HMAC-SHA256 signer that produces Flow's s parameter, (3) FlowGateway as the API boundary (create, createEmail, getStatus, refund), and (4) a Blade checkout redirect view. This is a reasonable shape for a redirect-based (hosted checkout) integration — card data never touches the application, so PCI scope stays at SAQ-A-eligible, and the gateway class gives us a natural seam to wrap behind our own PaymentProvider interface for provider portability.

Integration feasibility. The happy path is short: configure credentials in the panel, call FlowGateway::create(), redirect to Flow with url?token=, and poll/receive status. Realistically this is a 1–2 sprint lift including sandbox certification, not the "install and go" the release notes imply, because the confirmation callback is not addressed. Flow posts a confirmation to a merchant-registered URL containing a token; the merchant must then call getStatus and acknowledge by HTTP 200. The package exposes getStatus, so the callback is buildable, but the absence of a route/controller means we own idempotency, replay protection, and the acknowledgement contract ourselves. That is the single largest scoping gap in v1.0.0.

Technical risk.

• Maturity: v1.0.0 is the first public release — no track record, unknown maintainer, no stated stability policy, tests/CI not mentioned.
• Signature correctness: HMAC-SHA256 over Flow's exact sorted-parameter concatenation is the classic failure mode; a mismatch surfaces as an unhelpful 400/401 at Flow with no local trace. We need to validate the signer against Flow's documented vectors in sandbox before committing.
• Version envelope: declaring Filament 4.x/5.x and Laravel 11–13 simultaneously is broad and partly forward-looking. We must confirm these constraints are tested, not merely declared, or Composer will happily resolve us into an untested combination.
• Missing surface area: no webhook handling, no transaction/order persistence or migrations, no subscriptions/recurring (Flow supports them), no explicit partial-refund semantics, no stated idempotency keys.
• Secrets handling: the settings page implies credentials in the database; encryption cast, multi-tenant partitioning, and env-vs-DB precedence are unverified.

Key questions.

1. Are Laravel 12/13 and Filament 5 constraints exercised in CI, and what is the supported-version policy?
2. Does the package ship a confirmation-webhook route or must we implement it? Any idempotency guidance?
3. Is refund full-only or partial, and what does it return on Flow error codes?
4. Where are credentials stored — encrypted DB column or config/env? Multi-tenant safe?
5. Is the checkout Blade view usable outside a Filament panel (non-panel or API-only app)?
6. License, maintainer backing, and disclosure process for security issues?
7. Is createEmail documented with the required Flow email-flow prerequisites, and does it fall back sensibly?
8. CLP zero-decimal handling — is amount coercion validated to integer?

Integration Approach

Stack fit. Good fit if we are on Filament 4 with a panel already in place: the settings page and credentials schema drop into the admin surface and remove the "edit .env for the payment gateway" operational smell. Laravel 11 + Filament 4 is the sweet spot. If we are not a Filament shop, roughly half the value evaporates — we get a gateway class, a signer, and a Blade view, which is a modest amount of code we could own directly.

Migration path. No prior Flow integration in our baseline, so this is greenfield rather than a migration. If a parallel effort exists using Flow's raw SDK or hand-rolled cURL, migrate incrementally: keep our existing Order/Payment models as the source of truth, adopt FlowGateway for create/getStatus/refund, and retire custom signing code only after sandbox parity. Do not let the package own persistence — it doesn't ship any.

Compatibility. Verify PHP version floor, Filament panel requirement for the settings page, and whether the checkout view is panel-coupled. Confirm the Flow API version pinned by developers.flow.cl docs matches the gateway's assumptions.

Sequencing.

1. Sandbox merchant account + credential provisioning; validate signer against known vectors.
2. Install, bind FlowGateway behind our own PaymentProvider interface (non-negotiable for exit risk).
3. Implement create → redirect flow end-to-end behind a feature flag.
4. Build the confirmation endpoint ourselves: token validation, getStatus, idempotent state transition, 200 acknowledgement, duplicate-safe.
5. Add scheduled reconciliation for orders stuck in pending via getStatus.
6. Add refunds (start with full refunds only).
7. Optional: ES/EN translation pass, admin UX for transaction history.

Operational Impact

Maintenance. Low code footprint, but a young package: budget for pinning a known-good version and a quarterly review of upstream releases. The broad version envelope raises the chance of transitive dependency churn on Filament majors. Owning the confirmation endpoint means we absorb Flow's contract changes regardless of what the package does.

Support. No stated support model; assume community/self-support. Internal runbook must cover: signature mismatch diagnosis, token expiry, sandbox vs production credential drift, and Flow error-code mapping. Finance/ops will need a manual reconciliation procedure for the first months.

Scaling. create and refund are synchronous outbound HTTP calls — they must not sit in user-facing request paths beyond a single redirect, and must carry timeouts plus a retry policy that is safe (no blind retries on create, which is not idempotent by default and can produce duplicate charges). Webhook volume is low; the real scaling concern is correctness under retries and out-of-order delivery, not throughput. Reconciliation via getStatus should be queued and rate-limited to respect Flow's limits.

Failure modes. Signature errors fail opaquely and are the most likely day-one incident. Missed or non-acknowledged confirmations leave orders in limbo — hence the scheduled reconciliation. Duplicate confirmations cause double-fulfilment without idempotency. Token expiry breaks slow user redirects. Refund semantics unknown → finance risk if partials are needed.

Ramp-up. One backend engineer comfortable with Filament and HTTP integrations: ~2–3 days to sandbox parity on the happy path, plus 3–5 days for confirmation handling, reconciliation, and hardening. The binding constraint is commercial, not technical — a Flow merchant account requires Chilean entity/bank details and approval lead time. Recommend a pilot behind a feature flag with a capped order value, gated on: signer validated, duplicate-webhook test passed, and a documented manual reconciliation runbook.