Laravel bKash Payment Gateway

A complete and easy-to-use bKash Payment Gateway integration package for Laravel.

This package provides a clean Laravel-friendly interface for integrating the bKash Tokenized Checkout API, including payment creation, execution, query, refund, and payment verification.

Features

• bKash Tokenized Checkout integration
• Sandbox and production environment support
• Create payment
• Execute payment
• Query payment
• Search transaction
• Refund payment
• Payment verification
• Laravel service provider integration
• Laravel configuration support
• Environment-based credentials
• Simple and clean API
• Easy integration with existing Laravel applications

Requirements

• PHP 7.4 or higher
• Laravel 5.x or higher
• Composer
• A valid bKash merchant account
• bKash API credentials

Make sure your Laravel application and PHP version are compatible with the version of this package you are installing.

Installation

Install the package using Composer:

composer require syedmahamudul/laravel-bkash

Laravel package discovery automatically registers the package service provider.

After installation, publish the package configuration:

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

This will publish the configuration file:

config/bkash.php

Configuration

Add your bKash credentials to the .env file.

Sandbox

BKASH_BASE_URL=https://tokenized.sandbox.bka.sh/v1.2.0-beta
BKASH_APP_KEY=your_app_key
BKASH_APP_SECRET=your_app_secret
BKASH_USERNAME=your_username
BKASH_PASSWORD=your_password

Production

For production, use the production bKash API URL and your production credentials.

BKASH_BASE_URL=your_production_base_url
BKASH_APP_KEY=your_production_app_key
BKASH_APP_SECRET=your_production_app_secret
BKASH_USERNAME=your_production_username
BKASH_PASSWORD=your_production_password

Never commit your bKash credentials to GitHub or any public repository.

Basic Usage

You can use the package through the provided bKash service.

Example:

use SyedMahamudul\Bkash\Bkash;

$response = Bkash::createPayment([
    'amount' => 100,
    'invoice' => 'INV-10001',
    'intent' => 'sale',
]);

The returned response contains the information provided by the bKash API.

Create Payment

Create a new bKash payment:

$response = Bkash::createPayment([
    'amount' => 100,
    'invoice' => 'INV-10001',
    'intent' => 'sale',
]);

You can then use the payment information returned by bKash to redirect the customer to the checkout process.

Execute Payment

After the customer completes the bKash checkout, execute the payment using the payment ID:

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

Example:

if ($response['transactionStatus'] === 'Completed') {
    // Payment successful
}

Always verify the payment response before marking an order as paid.

Query Payment

You can query an existing payment:

$response = Bkash::queryPayment($paymentId);

This can be useful when you need to verify the current status of a transaction.

Search Transaction

Search for a transaction using the bKash transaction ID:

$response = Bkash::searchTransaction($trxId);

Example:

$response = Bkash::searchTransaction('TRX123456');

Refund Payment

Refund a successful payment:

$response = Bkash::refundPayment(
    $paymentId,
    100,
    'Customer requested refund'
);

The refund reason can be dynamic:

$reason = 'Customer requested refund';

$response = Bkash::refundPayment(
    $paymentId,
    $amount,
    $reason
);

If no reason is supplied, the package uses:

Customer requested refund

as the default reason.

Payment Verification

For production applications, payment verification should be performed before updating the order status.

A typical workflow is:

Create Payment
      ↓
Customer Checkout
      ↓
Execute Payment
      ↓
Verify Payment
      ↓
Update Order
      ↓
Store Transaction

Example:

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

if (
    isset($response['transactionStatus']) &&
    $response['transactionStatus'] === 'Completed'
) {
    // Update order as paid
}

Laravel Controller Example

A simple controller implementation may look like:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use SyedMahamudul\Bkash\Bkash;;

class PaymentController extends Controller
{
    public function create()
    {
        $response = Bkash::createPayment([
            'amount' => 500,
            'invoice' => 'ORDER-' . time(),
            'intent' => 'sale',
        ]);

        return response()->json($response);
    }

    public function execute(Request $request)
    {
        $paymentId = $request->paymentID;

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

        return response()->json($response);
    }
}

Routes

Example Laravel routes:

use App\Http\Controllers\PaymentController;
use Illuminate\Support\Facades\Route;

Route::get('/payment/create', [
    PaymentController::class,
    'create'
]);

Route::get('/payment/execute', [
    PaymentController::class,
    'execute'
]);

Adjust the routes according to your application's payment workflow.

Configuration File

After publishing the configuration, you can manage the package settings from:

config/bkash.php

The configuration is designed to keep API credentials and environment-specific settings outside your application code.

Environment

The package supports separate environments for testing and production.

Sandbox

Use the bKash sandbox environment while developing and testing your integration.

Production

After completing testing and receiving your production credentials, update the environment configuration with the production bKash API settings.

Do not use sandbox credentials in production.

Error Handling

Wrap payment operations in exception handling when appropriate:

try {
    $response = Bkash::createPayment([
        'amount' => 100,
        'invoice' => 'INV-10001',
        'intent' => 'sale',
    ]);

    return response()->json($response);

} catch (\Throwable $e) {
    return response()->json([
        'message' => $e->getMessage(),
    ], 500);
}

For production applications, it is recommended to log payment errors and avoid exposing sensitive API information to customers.

Recommended Payment Flow

A recommended Laravel integration flow is:

1. Create an Order

Create the order in your database with a pending payment status.

2. Create bKash Payment

Send the order amount and invoice information to bKash.

3. Redirect Customer

Redirect the customer to the bKash checkout URL.

4. Execute Payment

After checkout, execute the payment using the returned payment ID.

5. Verify Payment

Verify the transaction before marking the order as paid.

6. Store Transaction

Save the bKash payment ID, transaction ID, amount, and payment status in your database.

7. Handle Refunds

Use the refund API when an eligible order needs to be refunded.

Example Order Status Flow

pending
   ↓
payment initiated
   ↓
customer checkout
   ↓
payment completed
   ↓
payment verified
   ↓
order paid

If payment fails:

pending
   ↓
payment initiated
   ↓
payment failed

Security Recommendations

For production applications:

• Never expose your bKash App Secret.
• Store credentials in .env.
• Never commit .env to Git.
• Validate payment amounts on the server.
• Verify payment status before updating an order.
• Store transaction IDs for reconciliation.
• Do not trust payment status received directly from the browser.
• Log API errors without exposing credentials.
• Use HTTPS in production.

Supported Versions

The package is designed for broad Laravel compatibility.

Exact compatibility depends on the package version and the dependencies declared in composer.json.

Testing

Clone the repository:

git clone https://github.com/syedmahamudul/laravel-bkash.git

Install dependencies:

composer install

Run the test suite:

composer test

If your project uses PHPUnit directly:

vendor/bin/phpunit

Contributing

Contributions are welcome.

To contribute:

git clone https://github.com/syedmahamudul/laravel-bkash.git

cd laravel-bkash

composer install

Create a new branch:

git checkout -b feature/your-feature

Make your changes, add tests where appropriate, and submit a pull request.

Issues

If you find a bug or have a feature request, please open an issue on GitHub.

GitHub repository:

https://github.com/syedmahamudul/laravel-bkash

Changelog

See the CHANGELOG.md file for information about changes between releases.

License

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

Author

Mahmudul Hasan

GitHub:

https://github.com/syedmahamudul/

Acknowledgements

This package was created to make integrating the bKash payment gateway with Laravel applications easier and more developer-friendly.

Special thanks to the Laravel and PHP communities for the tools and standards that make modern payment integrations possible.

Package

Package: syedmahamudul/laravel-bkash

Repository: https://github.com/syedmahamudul/laravel-bkash

License: MIT

Type: Laravel Payment Gateway Package