redberryproducts/laravel-bog-payment

This is my package bog-payment

v1.0.9 2025-01-27 14:31 UTC

Requires

• php: ^8.1|^8.2
• guzzlehttp/guzzle: ^7.9
• illuminate/contracts: ^10.0 || ^11.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^2.9 || v3.0.2
• laravel/pint: ^1.14
• nunomaduro/collision: ^7.10 || ^8.1
• orchestra/testbench: ^8.22 || ^9.0
• pestphp/pest: ^2.34 || ^3.5
• pestphp/pest-plugin-arch: ^2.7 || ^3.0
• pestphp/pest-plugin-laravel: ^2.3 || ^3.0
• phpstan/extension-installer: ^1.3 || ^1.4
• phpstan/phpstan-deprecation-rules: ^1.1 || ^2.0
• phpstan/phpstan-phpunit: ^1.3 || ^2.0
• spatie/laravel-ray: ^1.35

MIT

• Nika Jorjoliani

• laravel
• RedberryProducts
• bog-payment

README

The BOG Payment package provides seamless integration with the Bank of Georgia's payment gateway, enabling Laravel applications to process payments efficiently.

Demo

You can find a demo project here

Features

• Payment Processing: Initiate and manage transactions through the Bank of Georgia.
• Transaction Status: Retrieve and handle the status of payments.
• Secure Communication: Ensure secure data transmission with the payment gateway.

Installation

You can install the package via composer:

composer require redberryproducts/laravel-bog-payment

You can publish the config file with:

php artisan vendor:publish --tag="bog-payment-config"

Once published, the configuration file will be available at:

config/bog-payment.php

Environment Variables

Add the following variables to your .env file to configure the package:

BOG_SECRET=[your_client_secret]
BOG_CLIENT_ID=[your_client_id]
BOG_PUBLIC_KEY=[your_public_key] # Can be found at https://api.bog.ge/docs/payments/standard-process/callback

You can find up to date BOG_PUBLIC_KEY in the Bank of Georgia's API documentation.

You can also configure additional environment variables as needed. But this is the minimum that you need to implement.

Usage

Usage Example: Simple Payment Processing

To initiate a payment, use the Pay facade to set the order details and process the transaction:

use RedberryProducts\LaravelBogPayment\Facades\Pay;
use App\Models\Transaction;

// Step 1: Create a transaction record
$transaction = Transaction::create([
    'user_id'    => auth()->id(),
    'amount'     => $data['total_amount'],
    'status'     => 'pending', // Initial status
]);

// Step 2: Process the payment
$paymentDetails = Pay::orderId($transaction->id)
    ->redirectUrl(route('bog.v1.transaction.status', ['transaction_id' => $transaction->id]))
    ->amount($transaction->amount)
    ->process();

// Step 3: Update the transaction with payment details
$transaction->update([
    'transaction_id'   => $paymentDetails['id'],
]);

// Step 4: Redirect user to the payment gateway
return redirect($paymentDetails['redirect_url']);

here's an example of the response:

$paymentDetails = [
    'id' => 'test-id',
    'redirect_url' => 'https://example.com/redirect',
    'details_url' => 'https://example.com/details',
]

Save Card

Save card during payment

To save the card during the payment process, you can use the saveCard() method. This method will save the card details for future transactions.

When you want to save card during the payment, you need to do the following:

use RedberryProducts\LaravelBogPayment\Facades\Pay;

// SaveCard method will initiate another request that notifies bank to save card details
$response = Pay::orderId($external_order_id)
    ->redirectUrl(route('bog.v1.transaction.status', ['transaction_id' => $transaction->id]))
    ->amount($amount)
    ->saveCard()
    ->process();

// Example response
$response = [
    'id' => 'test-id',
    'redirect_url' => 'https://example.com/redirect',
    'details_url' => 'https://example.com/details',
];

When you receive the response, you can save the card details in your database, where id is the saved card(parent transaction) id that you would use for later transactions.

Pay using saved card

Once you have saved new payment method id in your database, you can initiate payments on saved cards like so:

use RedberryProducts\LaravelBogPayment\Facades\Card;

$response = Pay::orderId($external_order_id)
    ->amount($amount)
    ->chargeCard("test-id");

// Example response
$response = [
    'id' => 'test-id',
    'redirect_url' => 'https://example.com/redirect',
    'details_url' => 'https://example.com/details',
];

Functionality above will charge saved card without the user interaction.

Subscriptions

To register a subscription payment, you can use the Pay facade to set the order details and process the transaction:

use RedberryProducts\LaravelBogPayment\Facades\Pay;

// SaveCard method will initiate another request that notifies bank to save card details
$response = Pay::orderId($external_order_id)
    ->redirectUrl(route('bog.v1.transaction.status', ['transaction_id' => $transaction->id]))
    ->amount($amount)
    ->subscribe();

// Save the parent transaction id in your database
$parentTransactionId = $response['id']; 

// Charge saved subscription at any time that you need
$response = Pay::orderId($external_order_id)
    ->chargeSubscription($parentTransactionId);

This will charge the saved subscription without the user interaction.

Building the payload

Although the package provides a convenient way to initiate payments, you can also build the payment payload manually using the provided traits.

The BuildsPayment trait helps you build the payload for payments quickly by providing the following methods

Here's how you do it:

getPayload(): // Retrieves the current payload array.

orderId($externalOrderId): // Sets the external order ID for the payment.

callbackUrl($callbackUrl): // Sets a custom callback URL for the payment process.

redirectUrl($statusUrl): // Sets both success and fail URLs to the same value for redirection after the payment.

redirectUrls($failUrl, $successUrl): // Sets separate fail and success URLs for redirection after the payment.

saveCard(): // Sets the save card flag to true for the payment.

amount($totalAmount, $currency = 'GEL', $basket = []): // Defines the total amount, currency, and optionally, the basket details for the payment.

// These methods allow for easy customization of the payment payload to suit various payment requirements.

Set Buyer

You can set the buyer details for the payment by using the setBuyer() method. This method accepts an array of buyer details, including the buyer's full_name, masked_email, and masked_phone.

here's the example of how you can set the buyer details:

use RedberryProducts\LaravelBogPayment\Facades\Pay;

$buyer = [
    'full_name' => 'John Doe',
    'masked_email' => 'john**@gmail.com',
    'masked_phone' => '59512****10',
];
    
$paymentDetails = Pay::orderId($transaction->id)
            ->redirectUrl(route('bog.v1.transaction.status', ['transaction_id' => $transaction->id]))
            ->amount($data['total_amount'])
            ->buyer($buyer) // Set new buyer details
            ->process();

// Optionally you can set buyer details separately

$paymentDetails = Pay::orderId($transaction->id)
            ->redirectUrl(route('bog.v1.transaction.status', ['transaction_id' => $transaction->id]))
            ->amount($data['total_amount'])
            ->buyerName($buyer['full_name']) // Set new buyer full name
            ->buyerEmail($buyer['masked_email']) // Set new buyer masked email
            ->buyerPhone($buyer['masked_phone']) // Set new buyer masked phone
            ->process();

Callback Handling

The package handles callback behavior automatically. When a payment is processed, it will send a POST request to your callback URL with the payment details. The package then verifies the request's signature to ensure its authenticity and fires the RedberryProducts\LaravelBogPayment\Events\TransactionStatusUpdated event, which contains all relevant payment details.

To utilize this functionality, register an event listener in your application to capture and respond to the transaction status updates as needed.

Example: Registering a Listener for Transaction Status Updates Add the following code to your event listener:

namespace App\Listeners;

use RedberryProducts\LaravelBogPayment\Events\TransactionStatusUpdated;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;

class HandleTransactionStatusUpdate implements ShouldQueue
{
use InteractsWithQueue;

    /**
     * Handle the event.
     *
     * @param  RedberryProducts\LaravelBogPayment\\Events\TransactionStatusUpdated  $event
     * @return void
     */
    public function handle(array $event)
    {
        // Implement your logic here
    }

Setting Up the Event Listener

Setting Up the Event Listener To handle transaction status updates efficiently, you need to register an event listener that listens for the TransactionStatusUpdated event triggered by the package.

1. Generating the Listener Automatically You can generate the event listener using the Artisan command:

   php artisan make:listener HandleTransactionStatusUpdate --event=RedberryProducts\LaravelBogPayment\\Events\TransactionStatusUpdated

   This command will create a listener class at app/Listeners/HandleTransactionStatusUpdate.php, which you can customize to handle the event logic.

This approach provides flexibility by allowing dynamic event registrations at runtime without modifying the EventServiceProvider.

For more details on event handling in Laravel, refer to the official documentation.

Handling Transaction Status

The package provides a convenient way to retrieve the status of a transaction using the Transaction Facade's get() method. This method sends a GET request to the Bank of Georgia payment API to retrieve the transaction status.

Here's how you can use it:

use RedberryProducts\LaravelBogPayment\Facades\Transaction;

$transactionDetails = Transaction::get($order_id); // Returns array of transaction details

See example of the response Official Documentation

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Nika Jorjoliani
• All Contributors

License

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