Cashier Core Laravel Package

Technical Evaluation

Architecture fit

• cashier-core 2.5.0 remains a Laravel-native, driver-based payment package, and Xoala follows the existing connection-driver configuration pattern.
• The release introduces a meaningful architectural expansion: the package now serves its own hosted-checkout interstitial via a new route group, Blade view, and publishable views. This is the first non-webhook route and first package-owned UI surface.
• Xoala is scoped narrowly: supports() reports charge and webhook; refund, capture, authorize, and void throw. It is suitable only for deposit-style flows unless refunds are handled outside the package.
• The checkout route is guarded by signed URLs and throttle:cashier-checkout, with no web middleware, session, or CSRF token. That is intentional but should be treated as a security-review item.
• The route group and checkout page remain under the existing cashier-core.routes.enabled / Cashier::ignoreRoutes() guard, which preserves a coherent disable switch.

Integration feasibility

• Feasible for an existing Laravel app already using cashier-core: add a xoala connection, set required env values, optionally publish views for branding, and ensure package routes are enabled.
• No breaking changes are reported. Existing connections and routes are untouched, and the new route group only registers when routes are enabled.
• The main integration dependency is correct account configuration: member_id, secure_key, base_url, and especially totype, which is account-specific and part of the request checksum.
• The host application must support the package-served checkout page in deployment: route caching, signed URLs, throttling, trusted proxy/IP handling, and view publishing need validation.

Technical risk

• The new checkout bridge increases the package’s HTTP surface. Signed URLs and throttling reduce risk, but the absence of web middleware/CSRF means the flow should be reviewed against replay, link expiry, and transaction-state assumptions.
• totype misconfiguration fails opaquely at the hosted page. The provider refuses to resolve without it, but a wrong value is a poor-operability failure mode.
• Xoala capability limits are a product risk: if the business expects refunds or authorization flows inside the package, this driver will not meet that need.
• Vendor documentation is weak enough that the gateway contract was vendored under .claude/skills/xoala/. That improves internal reference but raises supportability and onboarding concerns.
• Checksum recomputation from the transaction row at render time is sensible because the checksum is not persisted, but it makes the checkout page dependent on persisted transaction integrity.

Key questions

• Is deposit-only support acceptable for the target merchant/use case, and what is the operational refund process?
• What is the signed checkout link TTL, and is replay or reuse handled by the gateway?
• Are callbacks idempotent, and what does “sync” mean in this driver: status reconciliation, scheduled sync, or manual operation?
• Is the cashier-checkout rate limiter registered by the package or expected from the host? How are trusted proxies configured for per-IP throttling?
• Which Laravel/PHP versions are in the supported test matrix for 2.5.0?
• If views are published, how will future package view changes be tracked and merged?
• Has security reviewed the no-session/no-CSRF signed route and the data exposed in the auto-submitting form?

Integration Approach

Stack fit

• Good fit for Laravel applications already using cashier-core and needing another deposit/payment driver without adding a separate SDK integration.
• Requires the host app to accept a package-owned checkout route and optional Blade view. Apps that disable package routes via Cashier::ignoreRoutes() will also disable Xoala checkout.
• The Xoala driver is a limited-capability addition, best treated as a deposit channel rather than a full payment lifecycle integration.

Migration path

• Upgrade cashier-core to 2.5.0; no breaking changes are reported.
• Add Xoala configuration and environment variables. Start with the sandbox base URL.
• Publish cashier-core-views only if branding or copy changes are required; otherwise use package defaults.
• Verify route registration, signed URL generation, throttle behavior, and transaction persistence before enabling production credentials.
• Keep existing drivers unchanged; Xoala should be introduced as an additive connection.

Compatibility

• Confirm Laravel/PHP version support and route-cache behavior in the target app.
• Validate signed middleware configuration, app URL/proxy settings, and named throttle limiter availability.
• Ensure deployment pipelines run route/config cache clears after enabling the new route group.
• Confirm the host app can receive Xoala callbacks and reconcile them with transaction state.

Sequencing

1. Upgrade package and run existing test suite.
2. Add Xoala sandbox config, including totype.
3. Enable package routes and verify the checkout route resolves.
4. Publish views if branding is required, then test form render and auto-submit.
5. Complete a sandbox deposit, callback, and sync/reconciliation test.
6. Run security and operations review of signed-link and throttling behavior.
7. Promote production credentials and monitor first transactions.

Operational Impact

Maintenance

• Adds a new operational surface: a package-served checkout route, Blade view, view-publish tag, and Xoala-specific configuration.
• If views are published, the host owns branding drift and must track upstream view changes.
• The vendored Xoala contract under .claude/skills/xoala/ should be maintained as internal documentation, not treated as a substitute for vendor support.
• The dev-2.x branch alias fix is useful for teams tracking development branches but has low production impact.

Support

• Support teams need a runbook for opaque Xoala hosted-page failures, especially totype, member_id, secure_key, and base_url issues.
• Because charge() performs no HTTP, gateway reachability and configuration errors are deferred to the browser checkout step. Support must distinguish package/route failures from gateway-hosted-page failures.
• Refund/capture/authorize/void exceptions should be documented as unsupported through this driver.

Scaling

• The checkout page is stateless and sessionless, which is favorable for horizontal scaling.
• It still consumes application capacity per checkout render and depends on transaction-row reads. Capacity planning should include checkout page traffic, not just API/webhook traffic.
• Per-IP throttling at 30/min can affect users behind shared NAT/proxies; trusted proxy configuration should be verified.

Failure modes

• Wrong totype or credentials: opaque failure at the hosted page.
• Expired or invalid signed link: checkout cannot render; user needs a restart path.
• Route disabled or route cache stale: checkout route missing.
• Throttle limit hit: 429 during checkout.
• Published view drift or branding error: broken interstitial.
• Callback loss/duplication or sync gaps: transaction state mismatch requiring reconciliation.
• Unsupported refund/capture/authorize/void: business process exception.
• Missing or inconsistent transaction row at render time: checksum/render failure.

Ramp-up

• Moderate. The driver configuration itself is straightforward, but the new hosted-checkout route, signed-link security model, Blade view publishing, and opaque Xoala failure behavior require cross-team review.
• Engineering, security, and support should align on sandbox validation, callback reconciliation, and production runbooks before broad rollout.