README

A modern, developer-friendly Laravel integration for the Fastaar Payment Gateway — accept bKash & Nagad payments in Bangladesh.

Features

• Facade & Dependency Injection: Access Fastaar functionality via Fastaar facade or inject FastaarClient.
• Automatic Configuration: Built-in support for environment variables.
• Webhook Middleware: Secure webhook routes automatically using signature validation.
• Modern PHP Features: Strict type checking, built on PHP 8.1+.

Installation

Add the package via Composer:

composer require fastaar/fastaar-laravel

Repository Configuration (If installed prior to Packagist publishing)

If you are installing this package from a custom VCS repository, define it in your project's composer.json first:

"repositories": [
    {
        "type": "vcs",
        "url": "https://github.com/fastaar/fastaar-laravel.git"
    }
],

Configuration

Publish the config file:

php artisan vendor:publish --provider="Fastaar\Laravel\FastaarServiceProvider" --tag="fastaar-config"

This will create a config/fastaar.php configuration file. You can configure Fastaar credentials in your .env file:

FASTAAR_API_KEY=fk_live_your_api_key_here
FASTAAR_WEBHOOK_SECRET=wh_secret_your_secret_here
FASTAAR_TIMEOUT_SECONDS=15

For test environments, use a test key (e.g., fk_test_...). Payments auto-complete on the test checkout page without processing real money.

Usage

1. Create a Payment & Redirect

Initialize payments using the Fastaar Facade. The same invoice_id is idempotent, meaning you can retry requests without double-charging.

use Fastaar\Laravel\Facades\Fastaar;

public function checkout()
{
    try {
        $payment = Fastaar::createPayment([
            'amount' => 1250, // Amount in BDT
            'invoice_id' => 'ORDER-42', // Your order reference
            'success_url' => route('checkout.success'), // Customer returns here on success
            'cancel_url' => route('checkout.cancel'), // Customer returns here on cancellation
        ]);

        return redirect()->away($payment['checkout_url']);
    } catch (\Fastaar\FastaarException $e) {
        return back()->withErrors(['message' => $e->getMessage()]);
    }
}

2. Check Payment Status

Retrieve a payment using the payment reference ID or look up by your custom invoice reference ID.

use Fastaar\Laravel\Facades\Fastaar;

// Retrieve by payment ID
$payment = Fastaar::getPayment('01jxyz...');

// Look up by your internal invoice/order reference
$payment = Fastaar::findByInvoiceId('ORDER-42');

if ($payment && $payment['status'] === 'completed') {
    // Order is successfully paid
}

3. List Payments

Fetch a list of payments filtered by status or invoice ID, newest first:

use Fastaar\Laravel\Facades\Fastaar;

$payments = Fastaar::listPayments([
    'status' => 'completed',
    'per_page' => 10,
]);

4. Handling Webhooks

To secure your webhooks, register the signature verification middleware on your route:

use Fastaar\Laravel\Http\Middleware\VerifyWebhookSignature;

Route::post('/webhooks/fastaar', function (Illuminate\Http\Request $request) {
    $event = $request->json()->all();

    if ($event['event'] === 'payment.completed') {
        $orderId = $event['data']['invoice_id'];
        $paymentId = $event['data']['id'];

        // Mark order as paid idempotently using $paymentId as the unique transaction key
    }

    return response('Webhook Handled', 200);
})->middleware(VerifyWebhookSignature::class);

Note

Make sure to exclude your webhook route from CSRF protection by adding it to your application's bootstrap/app.php (Laravel 11) or VerifyCsrfToken middleware (Laravel 9/10).

Testing

Run tests with Pest PHP:

./vendor/bin/pest

Verify styling and formatting rules:

./vendor/bin/pint --test

Run static analysis using PHPStan:

./vendor/bin/phpstan analyse