Filament Transbank Webpay Laravel Package

Technical Evaluation

Architecture fit johnrivera7/filament-transbank-webpay is a Filament panel plugin wrapping Transbank Webpay (Chilean card acquiring) into the admin UI. Architecturally this is a thin adapter over a hosted-redirect payment flow: the package owns the Filament UI surface (payment initiation actions, transaction listing/state widgets), the Laravel glue (config publishing, service bindings, migrations for transaction records), and delegates the actual charge to Transbank's SDK/API. That is a conventional and low-coupling shape — it does not require forking our domain model, and it should sit alongside existing order/invoice tables rather than replacing them. The critical architectural question is ownership of the payment record: if the package ships its own transactions table, we need an explicit mapping to our order aggregate and a rule for which system is authoritative.

Integration feasibility Integration is a single Composer require plus Filament plugin registration and credential configuration. The 1.0.2 release widens the framework constraint to illuminate/contracts ^13.0 and documents Laravel 11 / 12 / 13 compatibility, which puts it in line with a modern Laravel estate. Effort is dominated not by code but by merchant onboarding with Transbank (commerce creation, environment credentials, sandbox vs production) and by reconciliation design — typically days of engineering against weeks of commercial/ops lead time.

Technical risk

• Version-matrix ambiguity: the release notes state Laravel compatibility but say nothing about Filament major versions (v3 vs v4). Filament plugins are tightly coupled to the panel major; this is the single highest-impact unknown and must be confirmed before committing.
• Bus factor: single-author package (johnrivera7/*) with a 1.0.x line. Acceptable for an admin-side convenience layer, risky if it becomes the only path for revenue collection.
• PCI scope: a hosted redirect flow keeps us in SAQ A/A-EP territory, but only if we never touch PAN data. Any package feature that renders card fields in the Filament panel would materially change our compliance posture — verify.
• Financial correctness surface: refunds/voids, idempotency keys, and webhook/callback signature verification are not mentioned; absence of these in the notes is not proof of absence in the code, but they drive most of the real risk.
• Pinning: ^1.0 floats across the whole 1.x line; acceptable only with a lockfile and a review gate on minor bumps.

Key questions

1. Which Filament majors are supported, and is that constraint encoded in composer.json?
2. Minimum PHP version, and does Laravel 13 support come at the cost of dropping any currently supported version?
3. Does it verify Transbank callback/webhook authenticity, and is the confirmation step server-side and idempotent?
4. Are refund, void, and partial-refund operations exposed, or is it charge-only?
5. Does it persist transactions itself, and can that be disabled in favour of our own ledger?
6. Is there a sandbox/integration environment story, and are there automated tests against it?
7. License, security contact, and release cadence for 1.x.

Integration Approach

Stack fit Laravel 11–13 + Filament admin panel, CLP-denominated checkout, Transbank Webpay as the acquirer. The package is a natural fit if our checkout is initiated from, or surfaced in, the Filament panel; it is a worse fit if our storefront is a separate customer-facing application and only back-office refunds live in Filament — in that case we are adopting a plugin for a narrow slice of functionality and should weigh a direct SDK integration instead.

Migration path Greenfield is the clean route: stand it up behind a feature flag on a low-traffic payment method first. If replacing an existing custom Webpay integration, run dual-write/parallel-run: new integration handles a small traffic percentage, both write to the same ledger, finance reconciles daily. Do not cut over until a full settlement cycle (including a refund and a failed payment) has reconciled cleanly.

Compatibility The 1.0.2 change is additive — a widened illuminate/contracts constraint plus documentation — so it is a low-risk patch by SemVer. The gating checks are Filament version, PHP version, and whether the transitive Transbank SDK is pinned to a version with a current API surface. Confirm our lockfile resolves cleanly on both the oldest (11) and newest (13) ends of our estate before assuming the compatibility claim is uniform.

Sequencing

1. Spike: install in a throwaway Laravel 13 + Filament app, confirm panel version support and end-to-end sandbox charge.
2. Design review: transaction-record ownership, ledger mapping, idempotency, callback endpoint exposure.
3. Security/compliance review: confirm no PAN handling, confirm signature verification, confirm credential storage in secrets manager.
4. Staging certification: full sandbox matrix — success, decline, timeout, user-abandon, refund, duplicate callback replay.
5. Production pilot: single payment method, low traffic, daily reconciliation with finance.
6. General availability, then re-evaluate scope of 1.x upgrades.

Operational Impact

Maintenance Low ongoing code maintenance (it is a thin adapter), but non-zero upgrade tax: Filament majors move quickly, and plugin support tends to lag. Budget an evaluation each Filament major and each Laravel major. Pin to ~1.0.0-style constraints with a lockfile and require a PR review + changelog read on every bump; treat minor releases as reviewable rather than auto-merged.

Support Community/single-maintainer support means our escalation path for a payment-path defect is our own engineers, not the vendor. Transbank's own documentation and merchant support (Spanish-language, Chilean business hours) cover the gateway side. Decide up front whether the package is on the critical path (charge initiation) or adjacent (admin refunds) — that determines whether we need a maintained internal fork and a named owner.

Scaling The redirect flow is stateless and scales with our web tier; the plugin itself is not a throughput bottleneck. Real scaling concerns are (a) database growth of transaction/callback records — plan retention and archival, (b) reconciliation job throughput at month-end, and (c) outbound dependency on Transbank latency and availability, which needs a queue + retry + dead-letter path rather than synchronous calls in the request cycle.

Failure modes

• Callback lost or delayed → payment captured but order state stale; needs a polling/manual-reconcile job, not just webhooks.
• Duplicate or replayed callback → double fulfilment or double refund; requires idempotency keyed on Transbank token/authorization code.
• Double charge on user retry after a timeout; needs a pre-charge check against existing authorizations.
• Token/session expiry mid-checkout leaving orphaned pending records.
• Refund mismatch between our ledger and the acquirer's settlement file; finance detects late, disputes are expensive in CLP.
• Silent breakage on a Filament major upgrade — plugin loads but action wiring changes; caught only by the staging matrix, so keep it in CI.

Ramp-up Engineering ramp is a day or two for a Filament-fluent developer. The longer ramp is organizational: finance/ops must learn the reconciliation workflow and the settlement file format, and support staff need a runbook for "customer says they were charged but the order didn't confirm." Assign an internal owner for the integration before GA — an unowned payment dependency is the most likely way this becomes an incident.