Laravel Freekassa Laravel Package

Getting Started

• Install the version matching your framework: composer require maksa988/laravel-freekassa:^4.0 on Laravel 8, or ^3.0 if you are still on Laravel 7 (v4.x explicitly drops/does not target 7.x — see the release note).
• Publish the package config: php artisan vendor:publish --provider="Maksa988\FreeKassa\FreeKassaServiceProvider" (tag is typically config). This creates config/freekassa.php.
• Populate the three credentials from your FreeKassa merchant cabinet: merchant ID, secret word 1 (used to sign the outgoing payment form) and secret word 2 (used to verify incoming notifications). Put them in .env, not in the config file, and reference them via env() in the config.
• Look first at: config/freekassa.php (keys and endpoint URLs), the package's main service class / facade, and its bundled routes file (the notification callback). Those three files tell you almost everything the package does.
• First use case: build a payment for an order and redirect the user to FreeKassa, then expose the notification endpoint so the gateway can confirm payment. Start with a single hard-coded test order and a real sandbox/low-value payment before wiring it into your checkout.

Implementation Patterns

• Outgoing payment (redirect flow). Resolve the package service from the container (or via its facade) in a controller/service, pass merchant order ID, amount, currency, description, and an optional success/failure return URL, then redirect the user to the URL the package returns. Keep order creation in a transaction and persist the payment attempt before redirecting, so the callback has something to reconcile against.
• Notification/IPN handler. Register the callback as a dedicated, unauthenticated route (the package ships one; you can also point FreeKassa at your own controller). In the handler: (1) recompute the signature from the incoming fields using secret word 2, (2) reject on mismatch, (3) load your order by MERCHANT_ORDER_ID, (4) verify the amount matches what you expected, (5) mark paid idempotently, (6) return the exact success body FreeKassa expects (plain YES).
• Reconciliation over trust. Treat the notification as a trigger, not a source of truth: after a valid callback, optionally re-query the gateway or your ledger before fulfilling. Fulfilment (emails, entitlements, stock decrement) belongs in a queued job or event listener, not inline in the callback.
• State machine on your order. Track pending → paid → failed/refunded on your own model. Record the gateway's transaction ID and the raw payload alongside it — this is the single most valuable debugging artifact.
• Testing. Unit-test signature generation/verification with known fixtures, and feature-test the callback route by POSTing a signed payload and asserting the YES response and order transition. Fake the outbound redirect URL so CI never hits FreeKassa.
• Config/env split. Keep the package config committed with env() fallbacks; keep real secrets only in .env / your secret manager. Add a freekassa log channel or a dedicated logger for payloads.

Gotchas and Tips

• Version pinning is the big one. v4.0.0 is the Laravel 8 line. If you are on Laravel 7, Composer will either fail to resolve or you will silently get an incompatible major — pin ^3.0 deliberately and document it. Upgrade to v4 as part of the Laravel 8 bump, not independently.
• Two secrets, easily swapped. Secret word 1 signs the request; secret word 2 validates the notification. Using the wrong one produces a permanently "invalid signature" callback with no other symptom.
• Signature formatting. These hashes are MD5 over a colon-joined string and are case-sensitive; compare with lowercase and use hash_equals() rather than ===. Amount formatting must match exactly between request and callback (decimal separator, no thousands separators) or verification fails.
• CSRF and auth will break the callback. Exclude the notification URI from VerifyCsrfToken, and make sure no auth middleware or maintenance-mode gate blocks it. The endpoint must be publicly reachable over HTTPS.
• Idempotency. FreeKassa (like most aggregators) retries notifications. Deduplicate on merchant order ID + gateway transaction ID and make the handler safe to run twice; returning YES on an already-processed order is correct and expected.
• Response body matters. Returning a redirect, JSON, or a 500 on success will make the gateway keep retrying. Return the literal expected string with a 200.
• Currency/amount. Amounts are typically RUB with two decimals; sending a float that stringifies as 1.0E+3 or 100 instead of 100.00 will be rejected. Format explicitly with number_format($amount, 2, '.', '').
• Failure visibility. Add structured logging of the raw request, computed vs. received signature, and the resolved order — callback bugs are otherwise invisible because the gateway only shows "notification failed."
• Extension points. If the package's built-in controller is too rigid, bypass it: keep the package for URL/signature helpers and write your own controller + route. Override the config's endpoint URLs only for testing against a sandbox.
• Verify against small live amounts first. The sandbox behaviour of Russian payment aggregators is often incomplete; a 10 RUB live transaction catches signature and amount-format issues that mocks never will.