💳 Kapitalbank Laravel Payment Gateway

Laravel layihənizə Kapitalbank ödəniş sistemini 10 dəqiqəyə qoşun.

Bu paket Azərbaycanda ən böyük bank olan Kapitalbank-ın E-Commerce ödəniş sistemini Laravel layihənizə asan şəkildə inteqrasiya etməyə imkan verir. Heç bir mürəkkəb konfiqurasiya tələb olunmur - sadəcə quraşdırın və istifadə edin!

📋 Başlamazdan əvvəl nə lazımdır?

| Tələb | Minimum versiya | Necə yoxlamaq? | |-------|-----------------|----------------| | PHP | 8.2+ | Terminalda: php -v | | Laravel | 10, 11 və ya 12 | php artisan --version | | Composer | İstənilən | composer --version | | Kapitalbank E-Commerce hesabı | - | Bankdan almalısınız |

Kapitalbank E-Commerce hesabınız yoxdursa, əvvəlcə Kapitalbank-a müraciət edib merchant hesabı açın. Onlar sizə username və password verəcəklər.

🚀 Quraşdırma (Addım-addım)

Addım 1: Terminalı açın

Windows: Win + R basın, cmd yazın, Enter basın
Mac: Cmd + Space basın, Terminal yazın, Enter basın
Linux: Ctrl + Alt + T basın

Addım 2: Laravel layihənizin qovluğuna keçin

cd /path/to/your/laravel/project

Məsələn:

cd C:\xampp\htdocs\my-shop

və ya

cd /var/www/my-shop

Addım 3: Paketi yükləyin

Bu əmri terminalda yazın və Enter basın:

composer require azpayments/kapitalbank

⏳ Yükləmə bitənə qədər gözləyin. "Successfully" yazısı görünməlidir.

Addım 4: Config faylını yaradın

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

Bu əmr config/kapitalbank.php faylını yaradacaq.

Addım 5: `.env` faylını redaktə edin

Laravel layihənizin ana qovluğunda .env adlı fayl var. Bu faylı istənilən mətn redaktoru ilə açın (Notepad, VS Code, Sublime Text və s.)

Faylın sonuna bu sətirləri əlavə edin:

# Kapitalbank konfiqurasiyası
KAPITALBANK_MODE=test
KAPITALBANK_USERNAME=sizin_username_buraya
KAPITALBANK_PASSWORD=sizin_password_buraya
KAPITALBANK_CURRENCY=AZN
KAPITALBANK_LANGUAGE=az
KAPITALBANK_REDIRECT_URL=/payment/kapitalbank/callback
KAPITALBANK_SUCCESS_URL=/payment/success
KAPITALBANK_ERROR_URL=/payment/error
KAPITALBANK_LOG_ENABLED=true

⚠️ Vacib qeydlər:

sizin_username_buraya və sizin_password_buraya yerinə Kapitalbank-dan aldığınız əsl məlumatları yazın
Test mühiti üçün (pulsuz sınaq):

KAPITALBANK_MODE=test
KAPITALBANK_USERNAME=TerminalSys/kapital
KAPITALBANK_PASSWORD=kapital123

Production mühiti üçün (real ödənişlər):

KAPITALBANK_MODE=production
KAPITALBANK_USERNAME=your_real_username
KAPITALBANK_PASSWORD=your_real_password

Faylı yadda saxlayın (Ctrl + S).

Addım 6: Cache-i təmizləyin

Bu əmrləri ardıcıl yazın:

php artisan config:clear
php artisan cache:clear

✅ Quraşdırma tamamlandı! İndi istifadəyə keçək.

📖 İstifadə - Addım-addım tam nümunə

İndi sizə ödəniş səhifəsi yaratmağı öyrədəcəyəm. Hər addımı diqqətlə izləyin.

Addım 1: Controller yaradın

Terminalda bu əmri yazın:

php artisan make:controller PaymentController

Bu əmr app/Http/Controllers/PaymentController.php faylını yaradacaq.

Addım 2: Controller faylını redaktə edin

app/Http/Controllers/PaymentController.php faylını açın.

İçindəki bütün kodu silin və bu kodu yapışdırın:

<?php

namespace App\Http\Controllers;

use AZPayments\Kapitalbank\Facades\Kapitalbank;
use Illuminate\Http\Request;

class PaymentController extends Controller
{
    /**
     * Ödəniş formasını göstərir
     * İstifadəçi bu səhifədə məbləği daxil edəcək
     */
    public function checkout()
    {
        return view('payment.checkout');
    }

    /**
     * Ödənişi başladır və istifadəçini Kapitalbank səhifəsinə yönləndirir
     * Form göndərildikdə bu metod işə düşür
     */
    public function pay(Request $request)
    {
        // Daxil edilən məlumatları yoxlayırıq
        $request->validate([
            'amount' => 'required|numeric|min:0.1',
        ]);

        try {
            // Kapitalbank-da ödəniş yaradırıq
            $order = Kapitalbank::createOrder([
                'amount' => $request->amount,
                'description' => 'Sifariş ödənişi',
                'title' => 'Online Ödəniş',
            ]);

            // İstifadəçini Kapitalbank ödəniş səhifəsinə yönləndiririk
            // İstifadəçi bu səhifədə kart məlumatlarını daxil edəcək
            return $order->redirect();

        } catch (\Exception $e) {
            // Əgər xəta baş verdisə, istifadəçiyə bildiririk
            return back()->with('error', 'Xəta baş verdi: ' . $e->getMessage());
        }
    }

    /**
     * Kapitalbank-dan callback gəldikdə bu metod işə düşür
     * Ödəniş tamamlandıqdan sonra istifadəçi bura yönləndirilir
     */
    public function callback(Request $request)
    {
        try {
            // Callback məlumatlarını yoxlayırıq
            $result = Kapitalbank::verifyCallback($request->all());

            if ($result['is_successful']) {
                // ✅ Ödəniş uğurlu!
                // Burada sifarişi "ödənildi" statusuna keçirə bilərsiniz
                
                return redirect('/payment/success')->with([
                    'order_id' => $result['order_id'],
                    'message' => 'Ödəniş uğurla tamamlandı!'
                ]);
            }

            // ❌ Ödəniş uğursuz
            return redirect('/payment/error')->with([
                'order_id' => $result['order_id'],
                'message' => 'Ödəniş uğursuz oldu.'
            ]);

        } catch (\Exception $e) {
            return redirect('/payment/error')->with([
                'message' => 'Xəta: ' . $e->getMessage()
            ]);
        }
    }

    /**
     * Ödəniş uğurlu olduqda istifadəçi bu səhifəyə gəlir
     */
    public function success()
    {
        return view('payment.success', [
            'order_id' => session('order_id'),
            'message' => session('message', 'Ödəniş uğurla tamamlandı!')
        ]);
    }

    /**
     * Ödəniş uğursuz olduqda istifadəçi bu səhifəyə gəlir
     */
    public function error()
    {
        return view('payment.error', [
            'order_id' => session('order_id'),
            'message' => session('message', 'Ödəniş uğursuz oldu.')
        ]);
    }
}

Faylı yadda saxlayın (Ctrl + S).

Addım 3: Route-ları əlavə edin

routes/web.php faylını açın.

Faylın sonuna bu kodu əlavə edin:

use App\Http\Controllers\PaymentController;

// Ödəniş səhifəsi - istifadəçi məbləği daxil edir
Route::get('/checkout', [PaymentController::class, 'checkout'])->name('checkout');

// Ödənişi başlat - form göndərildikdə işə düşür
Route::post('/payment/pay', [PaymentController::class, 'pay'])->name('payment.pay');

// Callback - Kapitalbank ödənişdən sonra bura yönləndirir
Route::get('/payment/kapitalbank/callback', [PaymentController::class, 'callback'])->name('payment.callback');

// Uğurlu ödəniş səhifəsi
Route::get('/payment/success', [PaymentController::class, 'success'])->name('payment.success');

// Uğursuz ödəniş səhifəsi
Route::get('/payment/error', [PaymentController::class, 'error'])->name('payment.error');

Diqqət: Əgər faylın yuxarısında artıq use sətirləri varsa, use App\Http\Controllers\PaymentController; sətrini onların yanına əlavə edin.

Faylı yadda saxlayın.

Addım 4: View qovluğunu yaradın

Terminalda:

Windows üçün:

mkdir resources\views\payment

Mac/Linux üçün:

mkdir -p resources/views/payment

Addım 5: Checkout səhifəsini yaradın

resources/views/payment/checkout.blade.php adlı yeni fayl yaradın.

Bu kodu faylın içinə yapışdırın:

<!DOCTYPE html>
<html lang="az">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Ödəniş Et - Kapitalbank</title>
    <style>
        * {
            margin: 0;
            padding: 0;
            box-sizing: border-box;
        }
        
        body {
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
            background: linear-gradient(135deg, #1e3c72 0%, #2a5298 100%);
            min-height: 100vh;
            display: flex;
            justify-content: center;
            align-items: center;
            padding: 20px;
        }
        
        .payment-container {
            background: white;
            padding: 40px;
            border-radius: 20px;
            box-shadow: 0 20px 60px rgba(0, 0, 0, 0.3);
            width: 100%;
            max-width: 420px;
        }
        
        .payment-header {
            text-align: center;
            margin-bottom: 30px;
        }
        
        .payment-header h1 {
            color: #1e3c72;
            font-size: 28px;
            margin-bottom: 10px;
        }
        
        .payment-header p {
            color: #666;
            font-size: 14px;
        }
        
        .error-message {
            background: #fee2e2;
            border: 1px solid #ef4444;
            color: #dc2626;
            padding: 12px 16px;
            border-radius: 8px;
            margin-bottom: 20px;
            font-size: 14px;
        }
        
        .form-group {
            margin-bottom: 24px;
        }
        
        .form-group label {
            display: block;
            margin-bottom: 8px;
            font-weight: 600;
            color: #374151;
            font-size: 14px;
        }
        
        .form-group input {
            width: 100%;
            padding: 16px;
            border: 2px solid #e5e7eb;
            border-radius: 12px;
            font-size: 18px;
            transition: border-color 0.3s;
        }
        
        .form-group input:focus {
            outline: none;
            border-color: #1e3c72;
        }
        
        .pay-button {
            width: 100%;
            padding: 18px;
            background: linear-gradient(135deg, #1e3c72 0%, #2a5298 100%);
            color: white;
            border: none;
            border-radius: 12px;
            font-size: 18px;
            font-weight: 600;
            cursor: pointer;
            transition: transform 0.2s, box-shadow 0.2s;
        }
        
        .pay-button:hover {
            transform: translateY(-2px);
            box-shadow: 0 10px 20px rgba(30, 60, 114, 0.3);
        }
        
        .security-note {
            text-align: center;
            margin-top: 24px;
            color: #6b7280;
            font-size: 12px;
        }

        .bank-logo {
            text-align: center;
            margin-bottom: 20px;
        }

        .bank-logo img {
            height: 40px;
        }
    </style>
</head>
<body>
    <div class="payment-container">
        <div class="bank-logo">
            <img src="https://www.kapitalbank.az/assets/images/logo.svg" alt="Kapitalbank">
        </div>

        <div class="payment-header">
            <h1>💳 Ödəniş Et</h1>
            <p>Təhlükəsiz ödəniş sistemi</p>
        </div>

        @if(session('error'))
            <div class="error-message">
                {{ session('error') }}
            </div>
        @endif

        <form action="{{ route('payment.pay') }}" method="POST">
            @csrf
            
            <div class="form-group">
                <label for="amount">Ödəniş məbləği (AZN)</label>
                <input 
                    type="number" 
                    id="amount" 
                    name="amount" 
                    step="0.01" 
                    min="0.1"
                    max="10000"
                    placeholder="0.00"
                    required
                    autofocus
                >
            </div>

            <button type="submit" class="pay-button">
                🔒 Ödənişə keç
            </button>
        </form>

        <p class="security-note">
            🔐 Ödənişiniz Kapitalbank tərəfindən qorunur
        </p>
    </div>
</body>
</html>

Addım 6: Uğurlu ödəniş səhifəsini yaradın

resources/views/payment/success.blade.php adlı yeni fayl yaradın:

<!DOCTYPE html>
<html lang="az">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Ödəniş Uğurlu</title>
    <style>
        * { margin: 0; padding: 0; box-sizing: border-box; }
        
        body {
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
            background: linear-gradient(135deg, #11998e 0%, #38ef7d 100%);
            min-height: 100vh;
            display: flex;
            justify-content: center;
            align-items: center;
            padding: 20px;
        }
        
        .container {
            background: white;
            padding: 50px 40px;
            border-radius: 20px;
            box-shadow: 0 20px 60px rgba(0, 0, 0, 0.2);
            text-align: center;
            max-width: 420px;
        }
        
        .icon {
            font-size: 80px;
            margin-bottom: 20px;
        }
        
        h1 {
            color: #11998e;
            font-size: 28px;
            margin-bottom: 12px;
        }
        
        .message {
            color: #6b7280;
            font-size: 16px;
            margin-bottom: 24px;
        }
        
        .order-info {
            background: #f3f4f6;
            padding: 16px;
            border-radius: 12px;
            margin-bottom: 24px;
        }
        
        .btn {
            display: inline-block;
            padding: 14px 32px;
            background: linear-gradient(135deg, #11998e 0%, #38ef7d 100%);
            color: white;
            border-radius: 10px;
            text-decoration: none;
            font-weight: 600;
        }
        
        .btn:hover {
            transform: translateY(-2px);
            box-shadow: 0 10px 20px rgba(17, 153, 142, 0.3);
        }
    </style>
</head>
<body>
    <div class="container">
        <div class="icon">✅</div>
        <h1>Ödəniş Uğurlu!</h1>
        <p class="message">{{ $message }}</p>
        
        @if($order_id)
            <div class="order-info">
                <p>Sifariş ID: <strong>{{ $order_id }}</strong></p>
            </div>
        @endif
        
        <a href="/" class="btn">Ana səhifəyə qayıt</a>
    </div>
</body>
</html>

Addım 7: Uğursuz ödəniş səhifəsini yaradın

resources/views/payment/error.blade.php adlı yeni fayl yaradın:

<!DOCTYPE html>
<html lang="az">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Ödəniş Uğursuz</title>
    <style>
        * { margin: 0; padding: 0; box-sizing: border-box; }
        
        body {
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
            background: linear-gradient(135deg, #eb3349 0%, #f45c43 100%);
            min-height: 100vh;
            display: flex;
            justify-content: center;
            align-items: center;
            padding: 20px;
        }
        
        .container {
            background: white;
            padding: 50px 40px;
            border-radius: 20px;
            box-shadow: 0 20px 60px rgba(0, 0, 0, 0.2);
            text-align: center;
            max-width: 420px;
        }
        
        .icon {
            font-size: 80px;
            margin-bottom: 20px;
        }
        
        h1 {
            color: #eb3349;
            font-size: 28px;
            margin-bottom: 12px;
        }
        
        .message {
            color: #6b7280;
            font-size: 16px;
            margin-bottom: 24px;
        }
        
        .buttons {
            display: flex;
            gap: 12px;
            justify-content: center;
        }
        
        .btn {
            padding: 14px 28px;
            border-radius: 10px;
            text-decoration: none;
            font-weight: 600;
        }
        
        .btn-primary {
            background: linear-gradient(135deg, #1e3c72 0%, #2a5298 100%);
            color: white;
        }
        
        .btn-secondary {
            background: #f3f4f6;
            color: #374151;
        }
    </style>
</head>
<body>
    <div class="container">
        <div class="icon">❌</div>
        <h1>Ödəniş Uğursuz</h1>
        <p class="message">{{ $message }}</p>
        
        <div class="buttons">
            <a href="/checkout" class="btn btn-primary">Yenidən cəhd et</a>
            <a href="/" class="btn btn-secondary">Ana səhifə</a>
        </div>
    </div>
</body>
</html>

Addım 8: Test edin! 🎉

Terminalda serveri işə salın:

php artisan serve

Brauzerdə açın:

http://127.0.0.1:8000/checkout

Test kartları ilə sınayın:

| Kart növü | Nömrə | Tarix | CVV | |-----------|-------|-------|-----| | Visa | 4169741330151778 | 06/25 | 119 | | Mastercard | 5239151747183468 | 11/24 | 292 |

🎯 Digər ödəniş növləri

🏨 Hotel üçün PreAuth (Bloklama)

Müştəri gəlir, pulu blokla. Çıxanda real məbləği çək:

// 1. Rezervasiya zamanı - 500 AZN bloklayırıq
$order = Kapitalbank::createPreAuthOrder([
    'amount' => 500.00,
    'description' => 'Hotel rezervasiyası',
]);
return $order->redirect();

// 2. Müştəri çıxanda - real məbləği çək
Kapitalbank::completePreAuth($orderId, 450.00);

📅 Taksit ödənişi

// 1200 AZN-i 6 aya böl
$order = Kapitalbank::createInstallmentOrder([
    'amount' => 1200.00,
    'description' => 'iPhone 15 Pro',
], 6); // 6 aylıq taksit

return $order->redirect();

💸 Pulu geri qaytar (Refund)

// Tam geri qaytar
Kapitalbank::refund($orderId);

// Qismən qaytar
Kapitalbank::refund($orderId, 50.00);

↩️ Əməliyyatı ləğv et (Reversal)

// Eyni gün ərzində ləğv et
Kapitalbank::reversal($orderId, 'Full');

🔔 Event Listener - Ödəniş olduqda avtomatik kod işlət

Ödəniş uğurlu olduqda email göndərmək, sifarişi yeniləmək istəyirsinizsə:

Addım 1: Listener yaradın

php artisan make:listener HandleKapitalbankPayment

Addım 2: Listener kodunu yazın

app/Listeners/HandleKapitalbankPayment.php:

<?php

namespace App\Listeners;

use AZPayments\Kapitalbank\Events\PaymentSuccessful;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Mail;

class HandleKapitalbankPayment
{
    public function handle(PaymentSuccessful $event)
    {
        $orderId = $event->orderId;
        $amount = $event->getAmount();
        $cardMask = $event->getCardMask(); // **** **** **** 1778
        
        // Log yaz
        Log::info("Ödəniş alındı: {$orderId}, Məbləğ: {$amount} AZN");
        
        // Sifarişi yenilə
        // Order::where('id', $orderId)->update(['status' => 'paid']);
        
        // Email göndər
        // Mail::to($customer->email)->send(new PaymentReceived($order));
    }
}

Addım 3: Event-i qeydiyyatdan keçir

app/Providers/AppServiceProvider.php:

use AZPayments\Kapitalbank\Events\PaymentSuccessful;
use App\Listeners\HandleKapitalbankPayment;
use Illuminate\Support\Facades\Event;

public function boot(): void
{
    Event::listen(PaymentSuccessful::class, HandleKapitalbankPayment::class);
}

❓ Tez-tez verilən suallar

"Class not found" xətası alıram

composer dump-autoload
php artisan config:clear

401 Unauthorized xətası

Username və ya password səhvdir. .env faylını yoxlayın.

Test kartı işləmir

KAPITALBANK_MODE=test olduğuna əmin olun
Test kartının tarixinə baxın

Callback işləmir (localhost)

Localhost-da callback işləmir. ngrok istifadə edin:

ngrok http 8000

Sonra Kapitalbank-a ngrok URL-ini verin.

📊 Ödəniş statusları

| Status | Mənası | |--------|--------| | Preparing | Gözləyir ⏳ | | FullyPaid | Ödənilib ✅ | | Declined | Rədd edilib 🚫 | | Reversed | Ləğv edilib ↩️ | | Refunded | Geri qaytarılıb 💸 |

📞 Dəstək

Problem yarandıqda:

GitHub-da issue açın: github.com/ElgunHeydarli/kapitalbank-laravel/issues
Xətanın tam mətnini əlavə edin
Laravel versiyanızı qeyd edin

📄 Lisenziya

MIT License - istədiyiniz layihədə pulsuz istifadə edin.

👨‍💻 Müəllif

Elgun Heydarli

Email: [email protected]
GitHub: @ElgunHeydarli

⭐ Bəyəndinizsə GitHub-da Star verməyi unutmayın!