Transbank Laravel Package

Getting Started

• Install the package:

  composer require laragear/transbank
  

• Publish the config and migrations, then migrate:

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

  If the tags differ in your version, use php artisan vendor:publish and select the Laragear\Transbank provider.
• Set credentials in .env:

  TRANBANK_ENVIRONMENT=integration
  TRANBANK_COMMERCE_CODE=your-commerce-code
  TRANBANK_API_KEY=your-api-key
  

  Use the integration credentials from Transbank while developing; production credentials are separate.
• First use case: Webpay Plus one-off payment.

  use Laragear\Transbank\Facades\Transbank;
  
  $response = Transbank::webpay()->create(
      buyOrder: 'order-'.Str::uuid(),
      sessionId: $request->session()->getId(),
      amount: 19990,
      returnUrl: route('transbank.webpay.return'),
  );
  
  return redirect()->away($response->url);
  

  On return, the package return route commits the token, or your controller calls Transbank::webpay()->commit($request->input('token_ws')). Inspect the resulting transaction with isSuccessful() and persist the link to your own order.
• Look first at config/transbank.php, the Transbank facade, Laragear\Transbank\Models\Transaction, package events, and the published routes/controllers.
• v4.1.3 adds Laravel Boost compatibility. That is tooling support for AI-assisted Laravel development, not a runtime feature; install/use Boost if you want the package guidelines available to your assistant.

Implementation Patterns

• Use one facade entry per product: Transbank::webpay(), Transbank::webpayMall(), Transbank::oneclick(), and Transbank::patpass() where available. Keep product-specific code in small action classes rather than controllers.
• Create the payment before redirecting, but persist your own order and the returned token/URL first. After commit, attach the Transbank transaction to your order through an event listener or explicit service call.
• Prefer event-driven side effects: listen for completed, failed, and cancelled transaction events, plus Oneclick inscription events. Queue listeners that send emails, update inventory, or call external services so a listener failure cannot break the browser return flow.
• Oneclick follows a two-step pattern: start the inscription and redirect the user, finish the inscription on return and store the username, then charge later with charge($username, $buyOrder, $amount). Treat the stored username as a payment credential reference, not as a secret.
• Refunds should go through the package service or transaction model and be persisted with the refund response. Keep partial and full refunds separate in your domain model.
• Wrap Transbank calls in try/catch for connection/HTTP exceptions and gateway errors. Log the buy order, environment, and status, but never log API keys, tokens, or full cardholder data.
• Testing: use Transbank::fake() if the package version provides it; otherwise use Laravel’s Http::fake() because the package uses the Laravel HTTP client. Assert outgoing URLs and methods, and generate unique buy orders per test.
• Laravel Boost: if your team uses Boost, let it read the package guidelines and still validate generated code against the installed version and config/transbank.php. Do not add Boost as a production dependency solely for this package.

Gotchas and Tips

• token_ws is present on a successful Webpay return. Cancellations/aborts may return TBK_TOKEN or related fields instead; handle that path before calling commit().
• Commit is single-use. Do not blindly retry a commit after a timeout; reconcile the transaction status first or you can create confusing failures after the customer has already paid.
• Webpay Plus amounts are integer CLP values. Do not pass floats or decimal-formatted amounts.
• The return URL must be absolute and publicly reachable. In production it should be HTTPS. Local development usually needs a tunnel such as Ngrok or Expose because Transbank posts back to the browser.
• Integration and production credentials are not interchangeable. After changing TRANBANK_ENVIRONMENT or credentials, clear cached config with php artisan config:clear.
• v4.1.3 forces the outgoing HTTP method to uppercase. This is not a breaking runtime change, but tests or custom fakes that assert lowercase HTTP methods may need updating.
• Exceptions thrown from synchronous event listeners after a successful payment can break the user redirect. Queue listeners and catch failures around redirect logic.
• Duplicate buyOrder values and retried Oneclick charges can be rejected or cause double-charge risk. Enforce uniqueness in your application and make retries idempotent at the order level.
• Publish migrations before running them, and avoid editing vendor migrations. If you customize table names or models, update the config and clear caches.
• Laravel Boost compatibility is developer-tooling only. It does not change payment behavior, routes, or credentials; treat AI-generated guidance as a starting point and verify against the installed package version.