README

A robust and clean Laravel package for integrating Bank of Georgia (BOG) payment gateway into your application. Optimized for security, race-condition prevention, and ease of use.

🚀 Key Features

• ✅ Race-Condition Prevention: Atomic locking mechanism for payment callbacks.
• ✅ Clean Architecture: Thin controllers with dedicated Form Requests and Service layer logic.
• ✅ Full BOG API integration: OAuth2, Order creation, Status tracking.
• ✅ Card Management: Securely save cards for 1-click future payments.
• ✅ Automated Workflows: Automatic product status updates upon successful payment.
• ✅ Developer Friendly: Highly configurable models and comprehensive logging.

📋 Requirements

• PHP >= 8.1
• Laravel >= 9.0 (Supports Laravel 10, 11, and 12)
• BOG Payment API Credentials

📦 Installation

Install the package via Composer:

composer require tatogi/bog-payment-laravel

Publish the configuration and migrations:

php artisan vendor:publish --provider="Bog\Payment\BogPaymentServiceProvider"

Run the database migrations:

php artisan migrate

⚙️ Configuration

Add your BOG credentials to your .env file:

BOG_CLIENT_ID=your_client_id
BOG_CLIENT_SECRET=your_client_secret
BOG_CALLBACK_URL=https://your-domain.com/bog/callback

# Optional - Customize your models
# The package will automatically update these models on successful payments
BOG_USER_MODEL=App\Models\User
BOG_PRODUCT_MODEL=App\Models\Product

📖 Usage

Creating a Payment Order

The package handles all the heavy lifting, including database records and product linking.

use Bog\Payment\Services\BogPaymentService;
use Bog\Payment\Services\BogAuthService;

$auth = app(BogAuthService::class);
$paymentService = app(BogPaymentService::class);

$token = $auth->getAccessToken()['access_token'];

$payload = [
    'callback_url' => 'https://example.com/callback',
    'purchase_units' => [
        'total_amount' => 100.00,
        'currency' => 'GEL',
        'basket' => [
            [
                'product_id' => 'prod-123',
                'name' => 'Premium Item',
                'quantity' => 1,
                'unit_price' => 100.00,
            ]
        ]
    ],
    'redirect_urls' => [
        'success' => 'https://example.com/success',
        'fail' => 'https://example.com/fail',
    ],
    'save_card' => true, // Optional: request card saving
    'user_id' => auth()->id(),
];

$response = $paymentService->createOrder($token, $payload);
return redirect($response['_links']['redirect']['href']);

Callback Handling (Automated)

The package includes a built-in callback handler that uses Atomic Locks to prevent duplicate processing if BOG sends multiple hit requests.

1. Verifies status directly with BOG API (Source of Truth).
2. Updates bog_payments table.
3. Saves the card (if requested).
4. Marks products as "ordered" in your database.

🛣️ API Endpoints

🏗️ Architecture

• BogPaymentService: The core logic engine. Handles API communication and DB transactions.
• Form Requests: Validation is isolated for cleaner controllers.
• Atomic Locking: Uses Cache-based locks to ensure callbacks are processed exactly once.

🧪 Testing

The package is fully tested with PHPUnit.

vendor/bin/phpunit

👤 Author

Tato

• GitHub: @TatoGi
• Email: tato.laperashvili95@gmail.com

📄 License

This package is open-sourced software licensed under the MIT license.

Made with ❤️ for the Laravel community.