Laravel Fib Integration Laravel Package

Getting Started

rawahamid/laravel-fib-integration is a thin Laravel wrapper around First Iraqi Bank's (FIB) payment gateway API — auth token handling, payment creation, status checks, refunds, and callback verification. It is a service-provider + config + facade package, not a headless SDK, so most of your day-to-day work happens in config/fib.php and a small handful of injected services.

1. Install and publish:

   composer require rawahamid/laravel-fib-integration
   php artisan vendor:publish --tag=fib-config
   

2. Look at the published config first. Every key you need is in config/fib.php — environment selector, base URLs, client/app credentials, callback route. Read it before reading the source; it is the package's real API surface.
3. Set credentials in .env (names as published — typically FIB_CLIENT_ID / FIB_CLIENT_SECRET, plus the environment key):

   FIB_ENV=dev
   FIB_CLIENT_ID=...
   FIB_CLIENT_SECRET=...
   

4. First use case: create a payment and redirect. Resolve the payment service from the container and hand it an amount + callback URL:

   use Rawahamid\FibIntegration\Facades\Fib; // verify exact namespace after install
   
   $payment = Fib::createPayment([
       'amount'       => 25000,        // FIB expects minor units or IQD — check the config/docs
       'currency'     => 'IQD',
       'callback_url' => route('fib.callback'),
       'description'  => 'Order #1042',
   ]);
   
   return redirect($payment['redirect_url']);
   

5. Wire the callback route and verify the transaction server-side before fulfilling an order. Never trust the redirect query string alone — always re-fetch status from FIB.

v1.0.3 note: this release adds a dev environment target. Since there is no prior assessment, treat v1.0.3 as your baseline: FIB_ENV now accepts a dev value in addition to the test/production values. Confirm the accepted strings by reading the environment resolver in the package source before shipping — the mapping is a string comparison, so a typo silently falls through to a default.

Implementation Patterns

Environment switching. Keep FIB_ENV per-environment in .env (dev locally, production in prod) and never branch on it in application code. The package resolves base URLs from the environment value, so your payment code stays identical across environments.

Bind to the contract, not the facade. If the package ships an interface/contract, type-hint that in your services and inject it. Facades are convenient in controllers but make unit tests heavier; container binding plus Fib::fake()-style swapping (if available) or a mock of the contract keeps your checkout flow testable.

Wrap it in your own payment service. Don't scatter Fib::createPayment() calls across controllers. Build one FibPaymentService that owns: amount conversion, idempotency key generation, your orders table writes, and error translation. This is the single highest-leverage thing you can do — it isolates you from package-level churn (like the v1.0.3 env change) and gives you one place to fix when FIB changes response shapes.

Two-phase order flow. Persist a pending order with your internal reference before calling FIB, store the returned FIB payment/transaction ID on it, then transition to paid only inside the callback handler after a server-side status verification. Use a DB transaction plus lockForUpdate() on the order row so a duplicated callback can't double-fulfil.

Callback handling. Register the callback route outside auth middleware (FIB won't carry a session), and:

• validate the payload against what you stored (amount, currency, reference),
• treat callbacks as at-least-once delivery — make the handler idempotent,
• return a 200 quickly and push fulfilment to a queued job rather than doing work inline.

Token handling. FIB uses OAuth-style client credentials. Let the package manage the token, but be aware it may cache it in Laravel's cache store. In multi-node deployments make sure the cache driver is shared (Redis/DB, not array/file) or every node will re-authenticate.

Testing with dev. The new dev environment is the right target for integration tests against FIB's sandbox. Point a dedicated FIB_ENV=dev + sandbox credentials at your CI job, and keep a separate phpunit.xml env block so tests never read your local .env.

Gotchas and Tips

• FIB_ENV is a string match, not an enum. After v1.0.3 the accepted values are dev, plus the existing test/production strings. A typo (development, DEV, local) may silently fall back to a default base URL — meaning you can point "sandbox" credentials at production or vice versa. Add a config assertion on boot (abort_unless(in_array(config('fib.environment'), [...]), ...)) in non-production, and log the resolved base URL once at startup.
• php artisan config:cache is the classic trap. Config is read once; changing .env in a deployed environment does nothing until you re-run config:cache. If credentials "aren't updating," this is almost always why.
• Amount units. Payment gateways are inconsistent about major vs. minor units and about decimal handling. Check what FIB expects and convert in exactly one place. Floating-point math on money is a recurring bug here — use integer IQD (FIB's currency has no practical minor unit) or a money library.
• No webhook signature helper is guaranteed. Verify callbacks by re-querying the payment status from FIB using the stored transaction ID rather than trusting a signed body. This is slower but safe, and it means a forged callback can at most trigger a status check.
• Timeouts and retries. Set an explicit HTTP timeout in config and wrap payment creation in a try/catch; a timeout on createPayment is ambiguous — the payment may exist. Reconcile with a status lookup by your idempotency/reference value before retrying, or you will create duplicate charges.
• Log the raw response on failure only. FIB error payloads are the fastest path to debugging (invalid credentials, expired token, malformed amount), but don't log full request bodies containing card or personal data at info level.
• Extension point: the service provider typically binds a single client class. If you need custom behaviour (retry policy, custom HTTP client, extra headers), extend that class and rebind it in your own AppServiceProvider via $this->app->bind(...) — cleaner than forking the package.
• Pin the version. This package is at 1.0.x with a small maintainer footprint and frequent small releases (v1.0.3 is an env-config addition). Use a caret constraint but read the changelog on each bump: minor patches here can change runtime behaviour, as the dev addition demonstrates.
• Check the dev base URL is actually sandbox. Before relying on it, log the outbound request URL once and confirm against FIB's documentation. A dev label that resolves to production endpoints is the worst possible failure mode for a payments package — validate it with a deliberately invalid card before you onboard real traffic.