rhaima/larakonnect

Laravel package for Konnect.network payment gateway integration - Accept online payments in Tunisia (bank cards, e-DINAR, wallet)

v1.0.1 2025-12-20 00:32 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.0
• illuminate/http: ^10.0|^11.0|^12.0
• illuminate/routing: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0|^10.0
• phpunit/phpunit: ^10.0|^11.0

MIT

• Rhaima

• payment
• gateway
• laravel
• paiement
• fintech
• tunisia
• konnect
• e-dinar
• tunisie

README

A Laravel package for integrating Konnect.network payment gateway. Accept online payments in Tunisia via bank cards, e-DINAR, and Konnect wallet.

Features

• 🚀 Easy integration with Laravel 10, 11, and 12
• 💳 Support for bank cards, e-DINAR, and Konnect wallet
• 🔒 Secure payment processing with PCI-DSS compliance
• 📦 Eloquent model with polymorphic relations
• 🎯 Event-driven architecture for payment lifecycle
• 🛠 Artisan commands for installation and debugging
• 🧪 Sandbox mode for testing

Installation

composer require rhaima/larakonnect

Run the installation command:

php artisan larakonnect:install

This will:

• Publish the configuration file
• Publish and run migrations (optional)
• Add environment variables to your .env file

Configuration

Add your Konnect credentials to .env:

KONNECT_SANDBOX=true
KONNECT_API_KEY=your_wallet_id:your_api_secret
KONNECT_WALLET_ID=your_wallet_id

Get your credentials from:

• Sandbox: https://dashboard.sandbox.konnect.network
• Production: https://dashboard.konnect.network

Exclude Webhook from CSRF

Add the webhook route to your CSRF exceptions in app/Http/Middleware/VerifyCsrfToken.php:

protected $except = [
    'konnect/webhook',
];

Usage

Basic Usage with Facade

use Rhaima\LaraKonnect\Facades\LaraKonnect;

// Create a payment link (amount in TND)
$result = LaraKonnect::createPaymentLink(
    amountTND: 150.500,
    orderId: 'ORDER-2024-001',
    description: 'iPhone repair service',
    customer: [
        'first_name' => 'Mohamed',
        'last_name' => 'Rhaima',
        'email' => '[e-mail]',
        'phone' => '22123456',
    ]
);

if ($result->success) {
    return redirect($result->payUrl);
}

// Handle error
return back()->with('error', $result->error);

Advanced Usage

use Rhaima\LaraKonnect\Facades\LaraKonnect;
use Rhaima\LaraKonnect\Services\KonnectClient;

// Convert TND to millimes (1 TND = 1000 millimes)
$amountMillimes = KonnectClient::toMillimes(150.500); // 150500

// Initialize payment with full options
$result = LaraKonnect::initPayment($amountMillimes, 'ORDER-123', [
    'description' => 'Payment description',
    'acceptedPaymentMethods' => ['bank_card', 'e-DINAR'],
    'lifespan' => 30, // minutes
    'theme' => 'dark',
    'firstName' => 'Mohamed',
    'lastName' => 'Rhaima',
    'email' => '[e-mail]',
    'phoneNumber' => '22123456',
    'successUrl' => 'https://yoursite.com/payment/success',
    'failUrl' => 'https://yoursite.com/payment/fail',
]);

// Check payment status
$payment = LaraKonnect::getPayment($paymentRef);

if ($payment->isCompleted()) {
    // Payment successful
}

// Quick status check
if (LaraKonnect::isCompleted($paymentRef)) {
    // ...
}

Using the Model

use Rhaima\LaraKonnect\Models\KonnectPayment;

// Create and initiate payment with tracking
$result = KonnectPayment::createAndInitiate(
    amountTnd: 150.500,
    orderId: 'ORDER-123',
    payable: $order, // Your model (Order, Intervention, etc.)
    customerInfo: [
        'first_name' => 'Mohamed',
        'email' => '[e-mail]',
    ]
);

if ($result['success']) {
    return redirect($result['payUrl']);
}

// Query payments
$pendingPayments = KonnectPayment::pending()->get();
$completedPayments = KonnectPayment::completed()->get();
$orderPayments = KonnectPayment::forOrder('ORDER-123')->get();

Using the Trait

Add the trait to any model that can have payments:

use Rhaima\LaraKonnect\Traits\HasKonnectPayments;

class Intervention extends Model
{
    use HasKonnectPayments;

    // Optional: customize the order ID
    public function getKonnectOrderId(): string
    {
        return 'INT-' . $this->reference;
    }

    // Optional: auto-fill customer info
    public function getKonnectCustomerInfo(): array
    {
        return [
            'first_name' => $this->client->prenom,
            'last_name' => $this->client->nom,
            'phone' => $this->client->telephone,
        ];
    }
}

Then use it:

$intervention = Intervention::find(1);

// Initiate payment
$result = $intervention->initiateKonnectPayment(150.500);

// Check payment status
if ($intervention->isPaidViaKonnect()) {
    // Already paid
}

// Get payment history
$payments = $intervention->konnectPayments;
$latestPayment = $intervention->latestKonnectPayment;

Handling Events

Listen to payment events in your EventServiceProvider:

use Rhaima\LaraKonnect\Events\PaymentInitiated;
use Rhaima\LaraKonnect\Events\PaymentCompleted;
use Rhaima\LaraKonnect\Events\PaymentFailed;

protected $listen = [
    PaymentCompleted::class => [
        UpdateOrderStatus::class,
        SendPaymentConfirmation::class,
    ],
    PaymentFailed::class => [
        NotifyAdminOfFailedPayment::class,
    ],
];

Example listener:

class UpdateOrderStatus
{
    public function handle(PaymentCompleted $event): void
    {
        $order = Order::where('reference', $event->orderId)->first();
        
        if ($order) {
            $order->update([
                'payment_status' => 'paid',
                'paid_at' => now(),
            ]);
            
            // Send notification
            $order->client->notify(new PaymentReceived($order));
        }
    }
}

Available Methods

Facade Methods

Method	Description
createPaymentLink($amount, $orderId, $description?, $customer?)	Quick payment link creation
initPayment($amountMillimes, $orderId, $options?)	Full payment initialization
getPayment($paymentRef)	Get payment details
isCompleted($paymentRef)	Check if payment is completed
getStatus($paymentRef)	Get payment status enum
toMillimes($amountTND)	Convert TND to millimes
toTND($millimes)	Convert millimes to TND

Model Methods

Method	Description
createAndInitiate(...)	Create record and initiate payment
markAsCompleted()	Mark payment as completed
markAsFailed()	Mark payment as failed
refreshFromKonnect()	Sync status from Konnect API
isCompleted()	Check if completed
isPending()	Check if pending

Artisan Commands

# Install the package
php artisan larakonnect:install

# Check configuration status
php artisan larakonnect:status

# Check specific payment
php artisan larakonnect:status PAYMENT_REF

Testing

Use sandbox mode and test cards:

Card Type	Number	CVV
Visa	4000000000000002	Any 3 digits
Mastercard	5100000000000008	Any 3 digits

KONNECT_SANDBOX=true

Customization

Views

Publish and customize the views:

php artisan vendor:publish --tag=larakonnect-views

Views will be published to resources/views/vendor/larakonnect/.

Configuration

Publish the configuration:

php artisan vendor:publish --tag=larakonnect-config

Security

If you discover any security vulnerabilities, please email [e-mail].

Credits

• Rhaima
• All Contributors

License

The MIT License (MIT). Please see License File for more information.