sabitahmad/laravel-bkash

Unofficial Bkash Package for Laravel providing seamless integration with Bkash payment gateway.

v1.0.0 2025-04-02 00:45 UTC

Requires

• php: ^8.0
• illuminate/contracts: ^10.0||^11.0||^12.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• laravel/pint: ^1.14
• nunomaduro/collision: ^8.1.1||^7.10.0
• orchestra/testbench: ^10.0.0||^9.0.0||^8.22.0
• pestphp/pest: ^3.0
• pestphp/pest-plugin-arch: ^3.0
• pestphp/pest-plugin-laravel: ^3.0

MIT

• Sabit Ahmad

• laravel
• laravel-bkash
• SabitAhmad

README

A comprehensive solution for integrating bKash payments into Laravel applications.

Table of Contents

• Features
• Requirements
• Installation
• Configuration
• Response Handling
• License

Features

• Full bKash API v1.2.0 integration
• Sandbox & Production modes
• Token management with auto-refresh
• Payment, Refund, and Query operations
• Comprehensive exception handling
• Transaction logging with UI component
• Event-driven architecture
• Customizable responses
• Built-in Laravel HTTP Client

Requirements

• PHP 8.0+
• Laravel 9.x+
• Composer
• bKash Merchant Account

Installation

You can install the package via composer:

composer require sabitahmad/laravel-bkash

You can publish and run the migrations with:

php artisan vendor:publish --tag="laravel-bkash-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --tag="laravel-bkash-config"

This is the contents of the published config file:

return [
    'sandbox' => env('BKASH_SANDBOX', true),
    'log_transactions' => env('BKASH_LOG_TRANSACTIONS', true),
    'credentials' => [
        'app_key' => env('BKASH_APP_KEY'),
        'app_secret' => env('BKASH_APP_SECRET'),
        'username' => env('BKASH_USERNAME'),
        'password' => env('BKASH_PASSWORD'),
    ],
    'urls' => [
        'sandbox' => [
            'token' => 'https://checkout.sandbox.bka.sh/v1.2.0-beta/checkout/token/grant',
            // ... other endpoints
        ],
        'production' => [
            // Production endpoints
        ]
    ],
    'callback_url' => env('BKASH_CALLBACK_URL', '/bkash/callback'),
    'redirect_url' => env('BKASH_REDIRECT_URL', '/payment/redirect'),
];

Optionally, you can publish the views using

Configuration

Add the following environment variables to your .env file:

BKASH_SANDBOX=true
BKASH_APP_KEY=your_app_key
BKASH_APP_SECRET=your_app_secret
BKASH_USERNAME=your_username
BKASH_PASSWORD=your_password
BKASH_CALLBACK_URL=/bkash/callback
BKASH_REDIRECT_URL=/payment/redirect
BKASH_LOG_TRANSACTIONS=true

Usage

Create Payment

try {
    $payment = Bkash::createPayment(payerReference: 'CUST-001', amount: 100.50, invoiceNumber: 'INV-001'
);

    
    if ($payment->isSuccess()) {
        return redirect()->away($payment->getPaymentUrl());
    }
    
    throw new Exception('Payment initialization failed: ' . $payment->getErrorMessage());
    
} catch (BkashException $e) {
    // Handle exception
}

Execute Payment

$execution = Bkash::executePayment($paymentId);

if ($execution->getTransactionStatus() === 'Completed') {
    // Payment successful
    $trxId = $execution->getTrxId();
}

Handle Callback

Route::post('/bkash/callback', function (Request $request) {
    $payment = Bkash::executePayment($request->paymentID);
    
    if ($payment->isSuccess()) {
        event(new PaymentCompleted($payment));
        return redirect('/success');
    }
    
    return redirect('/failed');
});

Refund Payment

• Description: Processes a refund for a given payment.
• Parameters:
  • string $paymentId: Original transaction ID.
  • float $amount: Refund amount.
  • string $reason: Refund description.
• Returns: RefundResponse

Example

$refund = Bkash::refundPayment('TRX123456', 100.50, 'Duplicate payment');

Query Payment

• Description: Queries the status of a given payment.
• Parameters:
  • string $paymentId: Payment ID to query.
• Returns: QueryResponse

Example

$query = Bkash::queryPayment('TRX123456');

PaymentResponse Methods

Core Methods

Method	Returns	Description
isSuccess()	bool	Whether operation succeeded
getErrorMessage()	?string	Error message if failed

Create Payment Methods

Method	Returns	Description
getPaymentUrl()	?string	Redirect URL for payment

Execute Payment Methods

Method	Returns	Description
getTrxId()	?string	bKash transaction ID
getCustomerMsisdn()	?string	Customer phone number
getTransactionStatus()	?string	"Completed"/"Failed" etc
getPaymentExecuteTime()	?Carbon	Execution timestamp

Common Methods

Method	Returns	Description
getPaymentId()	?string	Payment ID
getAmount()	?float	Transaction amount
getInvoiceNumber()	?string	Merchant invoice number
getStatusCode()	?string	bKash status code
getStatusMessage()	?string	bKash status message

RefundResponse Methods

Method	Returns	Description
getRefundId()	?string	Unique refund ID
getOriginalPaymentId()	?string	Original transaction ID
getRefundAmount()	?float	Refunded amount
getTransactionStatus()	?string	Refund status
isSuccess()	bool	Whether refund succeeded

QueryResponse Methods

Method	Returns	Description
getTransactionStatus()	?string	Current payment status
getAmount()	?float	Original amount
getPaymentId()	?string	Payment ID
isSuccess()	bool	Whether query succeeded

Testing

composer test

Changelog

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

Credits

• Sabit Ahmad

License

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