Filament Transbank Webpay Laravel Package

Getting Started

1. Install and pin the minor line. The 1.0.2 release adds Laravel 13 support (illuminate/contracts ^13.0) and documents the Laravel 11 / 12 / 13 matrix. There are no breaking changes in the 1.0.x line, so composer require johnrivera7/filament-transbank-webpay:^1.0 is the safe constraint — it will pull 1.0.2 while staying inside the patch range.
2. Confirm your version triangle before anything else. You now need three constraints to line up: your Laravel version (11/12/13), your Filament major, and this package. If you are on Laravel 13 you are almost certainly also on the newest Filament major — check the README matrix added in this release before debugging anything else, because a Filament major mismatch is the most common install failure for panel plugins.
3. Publish config and migrations, then read the published config file first — it is the single best map of the package's surface area (commerce code, API key, environment, return/callback route names).

   php artisan vendor:publish --tag="filament-transbank-webpay-config"
   php artisan vendor:publish --tag="filament-transbank-webpay-migrations"
   php artisan migrate
   

4. Set the Transbank credentials in .env, not in the config file. You need the commerce code, API key, and an environment switch (integration vs production). Use Transbank's published integration credentials for local work so you never touch live keys in development.
5. Register the plugin on your panel in the PanelProvider (->plugins([...])) — see the README for the exact plugin class name in this version.
6. First use case: a single-amount checkout. Add a Filament action or a dedicated checkout page that creates a Webpay Plus transaction, persists the order with its token, redirects the user to the returned Webpay URL, and then handles the POST return by committing the transaction and updating the order status. Get this one happy path working end-to-end in the integration environment before adding anything else — refunds, multiple products, or tenancy.

Implementation Patterns

• Two-phase flow, two records of truth. Webpay Plus is create → redirect → POST return → commit. Model it explicitly: write an orders/payments row (status = initiated, plus token, buy_order, session_id, amount) before redirecting. The return handler then transitions that row. Never rely on session state alone to know what the user was paying for.
• Keep the create/commit logic in a service, not in the Filament action. Filament actions are closures inside a Livewire component — hard to test and impossible to reuse from a queued job, an API endpoint, or an admin "retry" button. Wrap the package's transaction calls in something like App\Services\WebpayCheckout with create() and commit() methods and unit-test those.
• Return route must be public. The Webpay return is a browser POST from Transbank's servers-side redirect, not an authenticated request. Register it outside your auth middleware group, and look the order up by the returned token_ws, not by auth()->user(). If your app requires a logged-in user to view the result page, handle "user looks logged out" deliberately (see Gotchas).
• Guard against double-commit. A token is single-use. Wrap the commit in a DB transaction with a row lock (lockForUpdate() on the payment record) and short-circuit if the status is already committed. This protects against double-clicks, browser back-then-refresh, and Transbank retries.
• Store amounts as integers in CLP. Webpay Plus amounts for CLP have no decimals. Don't pass floats from a Filament TextInput or a formatted currency field — cast at the boundary and validate min:50 (Transbank's floor) to fail early rather than at the gateway.
• Filament action vs custom page. For a one-off purchase, a Action on a resource or a custom page is fine. For a real checkout with cart, customer data, and a result screen, build a custom Filament page (or a plain Blade route) and keep the panel for reconciliation — the panel is where you want an admin view of payment statuses, not where you want the customer's card flow to live.
• Local development needs a tunnel. Your return URL must be reachable over the public internet. Use expose, ngrok, or similar and set APP_URL to the tunnel host, or the redirect will silently land on a dead localhost URL and the commit will never fire.
• Idempotent status model. Define statuses up front — initiated, committed, authorized, failed, aborted — plus a raw_response JSON column. Transbank's response codes are more granular than "paid / not paid" and you will want them six months later during a finance reconciliation.
• Reconciliation in Filament. The highest day-to-day value of this package is the admin side: a resource listing payments with status badges, a filter for failed/abandoned orders, and an action to re-attempt commit for stragglers. Build that view early — it turns "customer says they paid" support tickets into a two-second lookup.

Gotchas and Tips

• CSRF on the return POST. Transbank posts back to your return_url without your session token. Depending on how the package registers its route you may need to exclude the return path from VerifyCsrfToken, or simply not use your own controller for it. If you see a 419 on return, this is why.
• Session loss on return. The POST back from Webpay can arrive without cookies (depends on browser SameSite and your session driver). Never assume auth()->check() inside the return handler. If you need the user context, embed a reference in session_id and re-authenticate or show a "your payment succeeded, please log in" screen.
• Environment leakage. The most expensive mistake in this package is shipping the integration environment config to production. Assert the environment in a boot check (abort_unless(config('...environment') === 'production', ...) in a production-only service provider) so a missing env var fails loudly instead of creating fake payments.
• Don't log the token. token_ws is a bearer-style credential for that transaction. Keep it out of Log::info, out of exception messages, and out of Filament's activity log if you have one enabled.
• Amount mismatch is your problem, not Transbank's. Webpay will happily report an amount that differs from what you stored if you compute it in two places. Compute once, store it, pass the stored value to both create and commit.
• Laravel 13 support is new in this patch. If you're upgrading a Laravel 11/12 app, nothing changes for you and 1.0.2 is a drop-in. If you're moving to Laravel 13, verify your Filament major supports it first — the package's illuminate/contracts ^13.0 constraint is necessary but not sufficient, since Filament itself gates the panel APIs. Also re-run composer update --with-all-dependencies rather than a plain require, otherwise Composer may keep you on the older contract and you'll wonder why the upgrade "didn't take."
• Extension points worth knowing: the published config file, the published migration/morph keys (so you can attach payments to your own models), and the package's views if they're publishable. Overriding the config's route names is usually easier than overriding the controllers — start there.
• Test matrix for CI: run your suite against the integration environment with Transbank's public test credentials, and mock the HTTP layer (via Http::fake()) for anything beyond the single happy-path smoke test. Live-credential tests in CI are a common source of leaked keys.