Fib Laravel Payment Sdk Laravel Package

Getting Started

Install and publish

composer require first-iragi-bank/fib-laravel-payment-sdk   # confirm exact vendor/name from the README
php artisan vendor:publish --provider="FIBC\LaravelPaymentSDK\FIBServiceProvider"

v1.9.0 widens the framework constraint to include Laravel 13, so composer update is the whole upgrade story for most apps — no code changes expected. It also flips TLS verification on by default (see Gotchas before you deploy).

Where to look first

1. config/fib.php — base URLs (sandbox vs production), credentials, and the HTTP client options block. This is the only file you should need to touch for a first run.
2. The service provider — it tells you whether the client is bound as a singleton (affects runtime credential swapping) and whether a facade alias exists.
3. The payments resource class — the method signatures are the real API docs; the changelog is not.

First use case: take one payment end-to-end

Set FIB_CLIENT_ID, FIB_CLIENT_SECRET, and the environment/base URL in .env, then create a payment for an existing order, persist the returned FIB payment ID, and redirect the customer to the returned URL (or render the QR payload). Verify the status server-side before marking the order paid. That single loop exercises auth, request signing, the client, and status reconciliation — everything else in the SDK is a variation on it.

Implementation Patterns

Wrap the SDK behind your own service. Don't call the SDK from controllers. Bind an interface (PaymentGateway) in a service provider and implement it with the SDK. This gives you one place to swap behaviour, one place to log, and something trivial to fake in tests when the package's own test doubles are thin.

final class FibGateway implements PaymentGateway
{
    public function __construct(private FibClient $client) {}

    public function createForOrder(Order $order): PaymentIntent
    {
        $response = $this->client->payments()->create([
            'amount'      => $order->total,          // confirm units: IQD has no minor unit
            'currency'    => 'IQD',
            'redirectUrl' => route('fib.callback'),
            'orderId'     => (string) $order->id,    // your idempotency handle
        ]);

        $order->payments()->create([
            'gateway_ref' => $response->paymentId,
            'status'      => 'pending',
        ]);

        return new PaymentIntent($response->paymentId, $response->redirectUrl);
    }
}

Persist before you redirect. Write the FIB payment ID against your order in the same transaction that creates it. If the user never comes back, the row is your only lead.

Reconcile with the status endpoint, not the redirect. Treat the return URL as a UX event. In the callback handler, re-fetch status from FIB by payment ID, compare the amount and currency to what you stored, then transition state in an idempotent handler keyed on the gateway reference. If the SDK exposes webhooks, treat them the same way — the payload is a hint, the status fetch is the truth.

Poll in a job, not in the request. For pending payments (QR flows especially), schedule a CheckPaymentStatus job with exponential backoff and a hard attempt cap. Keep the job ShouldBeUnique on the payment ID so a user refreshing the callback page doesn't spawn a dozen pollers.

Credentials per merchant. In a multi-tenant app, resolve credentials at call time rather than relying on a boot-time singleton. Either build the client from a factory per request, or config()->set() before resolution and make sure nothing has already resolved the singleton.

Testing. The SDK almost certainly rides on Laravel's HTTP client, so Http::fake() with fixture payloads for create/status/refund covers nearly all of your own logic. Assert on what you send (amount, currency, order ID) as well as what you do with the response — unit-mismatch bugs hide there.

Laravel 13. Bump and run your suite. The risk isn't the SDK, it's whatever else in your dependency graph hasn't caught up yet.

Gotchas and Tips

TLS verification is now enforced (v1.9.0) — treat this as a breaking change. It ships under a minor version number, but any host that was silently succeeding against an unverified certificate will start failing with cURL error 60: SSL certificate problem. That includes stale ca-certificates packages, minimal Docker base images, corporate MITM proxies, and any environment where someone had pointed the SDK at a host with a self-signed cert.

Fix it at the platform layer, in this order:

# Debian/Ubuntu
apt-get update && apt-get install -y ca-certificates && update-ca-certificates

; php.ini — point PHP at an explicit bundle if the system store isn't found
curl.cainfo = /etc/ssl/certs/ca-certificates.crt
openssl.cafile = /etc/ssl/certs/ca-certificates.crt

Only if a config toggle exists in config/fib.php should you consider disabling verification, and then only under APP_ENV=local. A payment client that skips certificate validation is a man-in-the-middle vulnerability with a settlement ledger attached — don't ship that to production to save a five-minute CA update. If you genuinely cannot fix the host, pin ^1.8 rather than disabling verification globally, and put the fix on a deadline.

Read the diff, not the changelog. One PR, two headline changes. Check whether the TLS flag is configurable or hard-coded, and whether any HTTP client options you had customised (timeouts, middleware, base URI) were renamed. If you had your own verify => false in a published config, the merged config may not pick it up.

Amount units. Confirm from the docs whether the API wants major units or minor units, and whether IQD is treated as zero-decimal. Getting this wrong by a factor of 100 is the single most common integration bug and it will pass every sandbox test you write with round numbers.

Don't auto-retry payment creation. A network timeout on create is ambiguous — the payment may exist. Retry with the same order/idempotency reference and reconcile by order ID, or you'll double-charge.

Redact secrets in logs. If you enable HTTP client logging or Guzzle middleware for tracing, filter the OAuth token request and the Authorization header. A debug log with a client secret in it is a breach waiting on a support ticket.

Config cache. php artisan config:cache in deploy pipelines will happily serve a stale base URL. Clear config after any .env change that touches FIB, and sanity-check sandbox vs production credentials — a mismatch here surfaces as a bare 401, which is easy to misread as a code problem.

Extension point worth knowing. The underlying HTTP client binding is usually the cleanest hook for adding retry-with-jitter, request IDs for tracing, and structured logging without forking the package. Find that binding before you write middleware around the SDK's public API.