haithemdev/flouci-bundle

Ready-to-use Symfony Bundle for Flouci Payment Gateway. Optimized for multi-account and client-specific integrations with event-driven architecture.

v1.0.0 2026-04-03 12:03 UTC

Requires

• php: >=8.1
• symfony/framework-bundle: ^6.0|^7.0
• symfony/http-client: ^6.0|^7.0

Requires (Dev)

• phpunit/phpunit: ^10.0
• symfony/test-pack: ^1.0

MIT

• haithemdev

• symfony
• payment
• bundle
• gateway
• tunisia
• flouci

README

A robust Symfony bundle for integrating the Flouci Payment Gateway API v2. This bundle is designed for modern Symfony applications, offering support for multiple API accounts (static or dynamic), event-driven architecture, and built-in webhook handling.

Features

• ✅ Simple & Advanced Configuration: Single account or multiple account support.
• ✅ Dynamic Accounts: Create Flouci services on-the-fly for different clients (multi-tenancy).
• ✅ Event-Driven: Listen to FlouciEvents::PAYMENT_VERIFIED to handle post-payment logic.
• ✅ Built-in Webhook: Ready-to-use controller for payment notifications.
• ✅ Developer Friendly: Strong typing and custom exceptions for easy debugging.

Installation

composer require haithemdev/flouci-bundle

Configuration

Simple Mode (Standard)

# config/packages/flouci_symfony.yaml
flouci_symfony:
    app_token: '%env(FLOUCI_APP_TOKEN)%'
    app_secret: '%env(FLOUCI_APP_SECRET)%'

Advanced Mode (Multiple Accounts)

# config/packages/flouci_symfony.yaml
flouci_symfony:
    accounts:
        main:
            app_token: '...'
            app_secret: '...'
        business:
            app_token: '...'
            app_secret: '...'

Usage

1. Generating a Payment Link

use Flouci\SymfonyBundle\Service\FlouciServiceInterface;

public function checkout(FlouciServiceInterface $flouci)
{
    $result = $flouci->generatePaymentLink(
        10.500, // Amount in TND
        'order_123',
        'https://your-app.com/success',
        'https://your-app.com/fail'
    );

    return $this->redirect($result['link']);
}

2. Handling Payments (Events)

Create a listener to handle successful payments:

use Flouci\SymfonyBundle\Event\FlouciEvents;
use Flouci\SymfonyBundle\Event\PaymentVerifiedEvent;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;

#[AsEventListener(event: FlouciEvents::PAYMENT_VERIFIED)]
public function onPaymentVerified(PaymentVerifiedEvent $event): void
{
    $data = $event->getPaymentData();
    $orderId = $event->getTrackingId();
    
    if ($event->getStatus() === 'SUCCESS') {
        // Update your order in database
    }
}

3. Dynamic Client Accounts (No configuration needed)

If your API keys are stored in a database (per client):

use Flouci\SymfonyBundle\Service\FlouciManager;

public function pay(Client $client, FlouciManager $manager)
{
    // Automatically uses default if $client keys are null, or creates a new service if they exist.
    $flouci = $manager->getService($client->getToken(), $client->getSecret());
    
    $flouci->generatePaymentLink(...);
}

Built-in Webhook

This bundle includes a ready-to-use webhook route. Just point Flouci's webhook settings to: https://your-app.com/flouci/webhook/default

Testing

vendor/bin/phpunit

License

MIT