Download the PHP package thejano/fib-payment-laravel without Composer

thejano/fib-payment-laravel

A Laravel package for integrating with the First Iraqi Bank (FIB) online-shop payment API. Supports payment creation, status checks, cancellation, refunds, and typed error handling via OAuth2 client-credentials authentication.

Features

• OAuth2 authentication (client-credentials grant, automatic per-request)
• Create a payment with configurable amount, description, and options
• Check payment status (PAID / UNPAID / DECLINED)
• Cancel a payment
• Refund a paid payment
• Receive status-change callbacks (webhooks) from FIB
• Retrieve a raw access token
• Typed exceptions (FibPaymentException) on any 4xx/5xx response
• First-class testability — facade or dependency-injected services, all driven by Laravel's Http client

Feature ↔ API coverage

Requirements

• PHP >= 8.1 (with the mbstring extension)
• Laravel >= 9.0 (illuminate/support and illuminate/http)
• FIB online-shop credentials (client ID + secret)

The CI suite runs against Laravel 11, 12, and 13 on PHP 8.3 and 8.4 (see .github/workflows/tests.yml).

Installation

Install the package via Composer:

Publish the config file:

Configuration

Add the following variables to your .env file:

Usage

All operations are accessed through the FibPayment facade.

Lifecycle: you create() a payment and present its QR code / app links to the customer. The payment starts as UNPAID; once the customer pays it becomes PAID, and FIB calls your callback URL. A payment can be cancel()ed while unpaid, or refund()ed after it is paid (within the refundable window). At any point you can poll status() for the authoritative state.

Create a Payment

Response structure:

Supported $options keys

Description is automatically trimmed to 50 characters (multibyte-safe).

Check Payment Status

Response structure:

Cancel a Payment

Refund a Payment

Only PAID payments within the configured refundable window can be refunded.

Retrieve an Access Token

Handling Status-Change Callbacks (Webhooks)

When a payment's status changes, FIB sends a POST request to your FIB_PAYMENT_CALLBACK_URL (or the per-payment callbackUrl option). The request body contains two fields:

This package does not register a route for you — you own the endpoint so you can apply your own middleware, validation, and queueing. The recommended pattern is to treat the callback as a trigger and re-fetch the authoritative status from FIB rather than trusting the payload:

Remember to add the callback path to the CSRF exception list (VerifyCsrfToken::$except in Laravel 9–10, or $middleware->validateCsrfTokens(except: [...]) in Laravel 11+).

Using the Services Directly (Dependency Injection)

The facade is a thin wrapper over two container-resolvable services. If you prefer constructor injection — for example, to keep classes explicit and easy to test in isolation — resolve PaymentService and AuthService directly:

PaymentService exposes the same create(), status(), cancel(), and refund() methods as the facade; AuthService::getAccessToken() returns the raw token. Both are bound through the container, so Laravel autowires them anywhere dependency injection is available.

Error Handling

All methods throw TheJano\FibPayment\Exceptions\FibPaymentException on any 4xx or 5xx response. Use getStatusCode() to retrieve the HTTP status and getResponseBody() to inspect the API error payload.

Error-handling caveats

Network failures: FibPaymentException is thrown when the FIB API returns a response (4xx/5xx). A low-level network failure (DNS error, connection timeout, etc.) surfaces instead as Laravel's Illuminate\Http\Client\ConnectionException, which callers should also catch if needed.

No token caching: The OAuth2 access token is never cached or stored. Every create, status, cancel, refund, or getToken call performs a fresh client-credentials authentication against FIB.

Instance caching: The FibPayment facade resolves a singleton whose AuthService and PaymentService objects are constructed once per process (config is read at construction time). This caches the service instances only — not the token. It is not designed to pick up runtime config changes within a long-lived worker such as Laravel Octane. Re-deploy or restart the worker to apply config changes.

Testing

Run the package's own suite:

The test suite uses Pest and Orchestra Testbench.

Testing your integration

Because every request goes through Laravel's Http client, you can fake FIB entirely in your own application's tests — no network calls, no credentials:

License

The thejano/fib-payment-laravel package is open-source software licensed under the MIT License.

fib-payment-laravel