Sbi Epay Laravel Package

Getting Started

satnamgills/sbi-epay-laravel wraps SBI ePay (State Bank of India payment gateway) for Laravel: payment initiation, redirect to the SBI hosted page, and server-side verification of the result.

Minimal path:

1. composer require satnamgills/sbi-epay-laravel — pin to ^1.0.10 (see Gotchas; earlier tags shipped stale endpoints).
2. Publish the config (php artisan vendor:publish --tag=... — check the README for the exact tag) and set merchant credentials plus the mode (test / live).
3. Start with the README's example payment and verification URLs — these were corrected in this release (commit 506e0a6), so the README is now the source of truth rather than any blog post or older snippet you may have copied.
4. First use case: build a checkout controller that creates a payment for an order, redirects the customer to SBI, and a callback controller that verifies the response server-side before marking the order paid.

Where to look first: the config file (mode + credentials), the service provider bindings (what's resolvable from the container), and the README's payment/verification examples.

Implementation Patterns

Mode is config, not code. The v1.0.10 fix is precisely about test vs live endpoints, so the package is designed to switch environment via configuration. Never branch on app()->environment() to pick URLs yourself — set the package mode and let it resolve the endpoint. Carry separate credential sets for test and live and select them with the same switch.

Two-step payment flow. Treat initiation and verification as distinct concerns:

• Initiation: build the request from the order, persist a local transaction record with your own reference before redirecting, then redirect.
• Verification: on callback, call the package's verification path against the gateway, compare amount and reference to your stored record, then transition the order state.

Idempotent order references. Generate the merchant reference once and store it. Callbacks can arrive more than once (browser redirect + server-to-server), so verification handling should be safe to run repeatedly — look up the transaction by reference and no-op if already settled.

Callback route hygiene. Register the callback outside auth middleware and exclude it from CSRF (VerifyCsrfToken::$except or the Laravel 11+ equivalent). Return a plain 200 quickly; do the verification and any slow work (emails, ledger writes) in a queued job where possible.

Testing. Fake the HTTP layer and assert the outgoing payload (amount, reference, mode-specific endpoint). For the callback, construct a representative gateway response fixture rather than hitting the sandbox in CI — the test endpoint's availability is outside your control.

Multi-merchant / multi-tenant. If you serve several merchants, resolve config per request rather than binding once at boot; check whether the package reads config at resolution time or at construction time before relying on runtime overrides.

Promotion path. Keep one code path and flip mode + credentials per environment. Smoke-test in test mode with the corrected endpoints from this release before switching live.

Gotchas and Tips

• Pin >=1.0.10. The headline fix (eb2a641) corrects payment and verification endpoints for both test and live modes. If you integrated against 1.0.9 or earlier, you may have "fixed" it locally by hardcoding URLs or overriding config — remove those workarounds after upgrading, or they will silently shadow the corrected values.
• Verify, don't trust the redirect. A customer landing on your success URL proves nothing. Always perform the server-side verification call and check the returned status, amount, and reference against your own record.
• Credential/mode mismatch is the top support ticket. Live keys against the test endpoint (or vice versa) produce opaque failures at SBI rather than clean errors. Log the resolved mode and endpoint at startup in non-production.
• Config caching. After changing credentials or mode, run php artisan config:clear (and config:cache in deploy). Stale cached config is the usual cause of "it works locally, not on the server."
• Amount formatting. Confirm the minor-unit/decimal convention the package expects and store amounts in a single canonical form; rounding drift between initiation and verification is a common source of amount-mismatch rejections.
• Payload encoding. Gateway responses are typically URL-encoded and hash-signed; decode before comparing, and compare against the raw response the package gives you rather than a re-serialized array.
• Log raw request/response bodies (masked credentials, masked card fields) into a dedicated channel. When verification fails, the raw payload is the only thing that tells you whether it's a signature issue, a mode issue, or a genuine decline.
• Extension points to check: publishable config, any bound HTTP client you can swap for a mock, and events fired around initiation/verification — hooking events is cleaner than wrapping the package's service class.
• Class/namespace names: the release notes only cover endpoints, so confirm the actual facade/service names from the README at install time rather than assuming; this package is small and its public surface has stayed narrow across patches.