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' => 'client@example.com',
        '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' => 'client@example.com',
    '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' => 'client@example.com',
    ]
);

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

Model Methods

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:

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 mohamed.rhaima96@gmail.com.

Credits

• Rhaima
• All Contributors

License

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