Skip to content

Commit dcf6206

Browse files
ProgrammerHasanProgrammerHasan
committed
🚀: bkash payment
1 parent d3e2e83 commit dcf6206

7 files changed

Lines changed: 269 additions & 80 deletions

File tree

‎README.md‎

Lines changed: 251 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# bKash Laravel Package
1+
# BKash Payment Gateway for Laravel
22

33
Welcome to the **bKash Laravel Package**!
44
This package allows seamless integration with the bKash payment gateway in Laravel, making transactions quick and hassle-free.
@@ -8,20 +8,67 @@ Built-in automatic grantToken caching (1 hour) ensures full compliance with the
88

99
---
1010

11+
## ✨ Features
12+
- ⚡ **Clean and easy to integrate** with any Laravel project.
13+
- 🧪 Supports **sandbox and production mode** for Bkash payments.
14+
- 🔑 Supports **Auth & Capture** for tokenized payments.
15+
- ↩️ Supports **Refunds** and **Search Transactions**.
16+
- ⚙️ Built-in **automatic grantToken caching (1 hour)** to comply with bKash Tokenized API rules.
17+
- 💰 Enables creating, executing, and querying **payments** via Bkash API.
18+
- 📄 Provides **payment status verification** and transaction history.
19+
- 📝 Enables logging of Bkash payment activities in **sandbox mode only**.
20+
- 🛠️ Follows **Laravel conventions** for service providers and facades.
21+
- 🧩 Provides clean **helper methods** for easy integration into controllers and services.
22+
23+
## 🛠️ Requirements
24+
- 🐘 **PHP:** ^7.4 | ^8.0 | ^8.1 | ^8.2
25+
- ⚡ **Laravel (illuminate/support):** ~6 | ~7 | ~8 | ~9 | ^10 | ^11 | ^12
26+
- 🌐 **cURL enabled** in PHP
27+
- 🔑 **bKash Merchant Account** (sandbox or production)
28+
1129
## 📦 Installation
1230

1331
```bash
1432
composer require programmerhasan/bkash
1533
```
1634

17-
### vendor publish (config)
35+
### ⚙️ Vendor publish (config)
1836

1937
```bash
20-
php artisan vendor:publish --provider="ProgrammerHasan\Bkash\BkashServiceProvider"
38+
php artisan vendor:publish --provider="ProgrammerHasan\Bkash\BkashServiceProvider" --tag="config"
39+
```
40+
After publish config file setup your credential. you can see this in your config directory bkash.php file
2141
```
42+
<?php
2243
23-
### Set .env configuration
44+
return [
45+
/*
46+
|--------------------------------------------------------------------------
47+
| Enable or Disable bKash Log
48+
|--------------------------------------------------------------------------
49+
| Logging is only recommended in sandbox/testing mode.
50+
| In production, keep logging disabled to avoid exposing sensitive payment data.
51+
| Logs will be saved in the /storage/logs/laravel.log file.
52+
|
53+
| Usage:
54+
| - Sandbox: BKASH_SANDBOX=true → logs enabled
55+
| - Production: BKASH_SANDBOX=false → logs disabled
56+
*/
57+
"bkash_log_enabled" => env("BKASH_SANDBOX", false),
58+
59+
"bkash_sandbox" => env("BKASH_SANDBOX", false),
60+
"bkash_username" => env("BKASH_USERNAME"),
61+
"bkash_password" => env("BKASH_PASSWORD"),
62+
"bkash_app_key" => env("BKASH_APP_KEY"),
63+
"bkash_app_secret" => env("BKASH_APP_SECRET"),
64+
"bkash_base_url_sandbox" => "https://tokenized.sandbox.bka.sh/v1.2.0-beta/tokenized",
65+
"bkash_base_url_production" => "https://tokenized.Pay.bka.sh/v1.2.0-beta/tokenized",
66+
"bkash_callback_url" => env("BKASH_CALLBACK_URL", "http://127.0.0.1:8000/bkash/callback"),
67+
];
68+
```
2469

70+
### 📝 Set .env configuration
71+
Add your Bkash credentials and environment settings in the `.env` file:
2572
```bash
2673
BKASH_SANDBOX=true
2774
BKASH_USERNAME = ''
@@ -30,65 +77,106 @@ php artisan vendor:publish --provider="ProgrammerHasan\Bkash\BkashServiceProvide
3077
BKASH_APP_SECRET = ''
3178
BKASH_CALLBACK_URL='Your defined Callback URl //default Callback Url => http://127.0.0.1:8000/bkash/callback'
3279
```
80+
### 📝 Enable or Disable bKash Log
81+
You can turn bKash logging on or off. (Only sandbox/testing mode.)
3382

34-
### Generate the Controller
83+
Logs will be saved in the /storage/logs/laravel.log file.
3584

3685
```bash
37-
php artisan make:controller Payment/BkashPaymentController
86+
"bkash_log_enabled" => env("BKASH_SANDBOX", false),
3887
```
3988

40-
### Enable or Disable bKash Log
41-
You can turn bKash logging on or off. (Only sandbox/testing mode.)
89+
## 🚀 Usage
4290

43-
Logs will be saved in the /storage/logs/laravel.log file.
91+
### Publish a controller
4492

4593
```bash
46-
"bkash_log_enabled" => env("BKASH_SANDBOX", false),
94+
php artisan vendor:publish --provider="ProgrammerHasan\Bkash\BkashServiceProvider" --tag="controllers"
95+
```
96+
### You can override the routes
4797
```
98+
Route::group(['middleware' => ['web']], static function () {
99+
// Payment routes for bKash
100+
Route::get('/bkash/payment', [BkashPaymentController::class, 'index']);
101+
Route::get('/bkash/create-payment', [BkashPaymentController::class, 'createPayment'])->name('bkash.payment.create');
102+
Route::get('/bkash/callback', [BkashPaymentController::class, 'callBack'])->name('bkash.payment.callback');
48103
49-
## [Checkout (URL Based)](https://developer.bka.sh/docs/checkout-url-process-overview)
104+
Route::get("bkash/failed", [BkashPaymentController::class, 'failed'])->name('bkash.payment.fail');
105+
Route::get("bkash/success", [BkashPaymentController::class, 'success'])->name('bkash.payment.success');
50106
51-
### 1. Create Payment
107+
// Search payment
108+
Route::get('/bkash/search/{trxID}', [BkashPaymentController::class, 'searchTnx'])->name('bkash.payment.search');
52109
110+
// Refund payment routes
111+
Route::get('/bkash/refund', [BkashPaymentController::class, 'refund'])->name('bkash.payment.refund');
112+
Route::get('/bkash/refund/status', [BkashPaymentController::class, 'refundStatus'])->name('bkash.payment.refund.status');
113+
});
53114
```
54-
<?php
55115

56-
namespace App\Http\Controllers\Payment;
116+
### Use route('bkash.payment.create') in blade
117+
118+
```
119+
<form action="{{ route('bkash.payment.create') }}" method="POST">
120+
@csrf
121+
<button type="submit">Pay with bkash</button>
122+
</form>
123+
```
57124

58-
use App\Http\Controllers\Controller;
59-
use Illuminate\Http\Request;
60-
use ProgrammerHasan\Bkash\Facade\CheckoutUrl;
125+
## [Checkout (URL Based)](https://developer.bka.sh/docs/checkout-url-process-overview)
61126

62-
class BkashPaymentController extends Controller
127+
### 1. Create Payment
128+
129+
```
130+
public function createPayment(Request $request)
63131
{
64-
public function createPayment(Request $request)
65-
{
66-
$request->validate([
67-
'payment_uid' => 'required',
68-
'amount' => 'required',
69-
'invoice_no' => 'required',
70-
]);
71-
72-
$data = [
73-
'payerReference' => $request->get('payment_uid'), // your payments table uid
74-
'amount' => $request->get('amount'),
75-
'merchantInvoiceNumber' => $request->get('invoice_no'),
76-
'callbackURL' => $request->get('bkash_callback_url'), // optional
77-
];
78-
79-
$response = (array) BkashPayment::create($data);
80-
81-
if (isset($response['bkashURL'])) return redirect()->away($response['bkashURL']);
82-
else return redirect()->back()->with('error-alert2', $response['statusMessage']);
83-
}
132+
$request->validate([
133+
'payment_uid' => 'required',
134+
'amount' => 'required',
135+
'invoice_no' => 'required',
136+
]);
137+
138+
$data = [
139+
'payerReference' => $request->get('payment_uid'), // your payments table uid
140+
'amount' => $request->get('amount'),
141+
'merchantInvoiceNumber' => $request->get('invoice_no'),
142+
'callbackURL' => $request->get('bkash_callback_url'), // optional
143+
];
144+
145+
$response = (array) BkashPayment::create($data);
146+
147+
if (isset($response['bkashURL'])) return redirect()->away($response['bkashURL']);
148+
else return redirect()->back()->with('error-alert2', $response['statusMessage']);
84149
}
85150
```
151+
### Create payment response
152+
```
153+
array[
154+
"statusCode" => "0000"
155+
"statusMessage" => "Successful"
156+
"paymentID" => "Your payment id"
157+
"bkashURL" => "https://sandbox.payment.bkash.com/redirect/tokenized/?paymentID=your_payment_id&hash=your_hash"
158+
"callbackURL" => "base_url/bkash/callback"
159+
"successCallbackURL" => "base_url/bkash/callback?paymentID=your_payment_id&status=success"
160+
"failureCallbackURL" => "base_url/bkash/callback?paymentID=your_payment_id&status=failure"
161+
"cancelledCallbackURL" => "base_url/bkash/callback?paymentID=your_payment_id&status=cancel"
162+
"amount" => "100"
163+
"intent" => "sale"
164+
"currency" => "BDT"
165+
"paymentCreateTime" => "2025-07-22T02:16:57:784 GMT+0600"
166+
"transactionStatus" => "Initiated"
167+
"merchantInvoiceNumber" => "merchant_invoice_no"
168+
]
169+
```
86170

87-
### 2. ADD callback function
171+
### 2. Add callback function
88172

89173
```
90174
public function callback(Request $request)
91175
{
176+
// Callback request params
177+
// paymentID=your_payment_id&status=success&apiVersion=1.2.0-beta
178+
// using paymentID find the account number for sending params
179+
92180
$status = $request->input('status');
93181
$paymentId = $request->input('paymentID');
94182
@@ -118,44 +206,117 @@ public function callback(Request $request)
118206
}
119207
}
120208
```
121-
122-
### 3. ADD routes in Web.php
209+
### Execute payment response
123210

124211
```
125-
Route::group(['middleware' => ['web']], static function () {
126-
// Payment routes for bKash
127-
Route::get('/bkash/payment', [BkashPaymentController::class, 'index']);
128-
Route::get('/bkash/create-payment', [BkashPaymentController::class, 'createPayment'])->name('bkash.payment.create');
129-
Route::get('/bkash/callback', [BkashPaymentController::class, 'callBack'])->name('bkash.payment.callback');
130-
131-
Route::get("bkash/failed", [BkashPaymentController::class, 'failed'])->name('bkash.payment.fail');
132-
Route::get("bkash/success", [BkashPaymentController::class, 'success'])->name('bkash.payment.success');
133-
134-
// Search payment
135-
Route::get('/bkash/search/{trxID}', [BkashPaymentController::class, 'searchTnx'])->name('bkash.payment.search');
136-
137-
// Refund payment routes
138-
Route::get('/bkash/refund', [BkashPaymentController::class, 'refund'])->name('bkash.payment.refund');
139-
Route::get('/bkash/refund/status', [BkashPaymentController::class, 'refundStatus'])->name('bkash.payment.refund.status');
140-
});
212+
{
213+
"statusCode":"0000",
214+
"statusMessage":"Successful",
215+
"paymentID":"your_payment_id",
216+
"payerReference":"your_ref_id",
217+
"customerMsisdn":"customer_msi",
218+
"trxID":"your_tnx_id",
219+
"amount":"100",
220+
"transactionStatus":"Completed",
221+
"paymentExecuteTime":"2023-01-23T02:04:05:736 GMT+0600",
222+
"currency":"BDT",
223+
"intent":"sale"
224+
}
141225
```
142226

143-
### 4. Use route('bkash.pay') in blade
227+
### Query payment response
144228

145229
```
146-
<form action="{{ route('bkash.payment.create') }}" method="POST">
147-
@csrf
148-
<button type="submit">Pay with bkash</button>
149-
</form>
230+
{
231+
"paymentID":"your_payment_id",
232+
"mode":"0011",
233+
"paymentCreateTime":"2023-01-23T02:01:06:713 GMT+0600",
234+
"paymentExecuteTime":"2023-01-23T02:04:05:736 GMT+0600",
235+
"amount":"100",
236+
"currency":"BDT",
237+
"intent":"sale",
238+
"merchantInvoice":"merchant_inv_no",
239+
"trxID":"tnx_no",
240+
"transactionStatus":"Completed",
241+
"verificationStatus":"Complete",
242+
"statusCode":"0000",
243+
"statusMessage":"Successful",
244+
"payerReference":"pay_ref"
245+
}
246+
```
247+
### 3. Search Transaction
248+
```
249+
public function searchTnx($trxID)
250+
{
251+
return BkashPayment::searchTransaction($trxID);
252+
}
253+
```
254+
### Response
255+
```
256+
{
257+
"trxID":"tnx_no",
258+
"initiationTime":"2023-01-23T12:06:05:000 GMT+0600",
259+
"completedTime":"2023-01-23T12:06:05:000 GMT+0600",
260+
"transactionType":"bKash Tokenized Checkout via API",
261+
"customerMsisdn":"customer_msi",
262+
"transactionStatus":"Completed",
263+
"amount":"20",
264+
"currency":"BDT",
265+
"organizationShortCode":"og_short_code",
266+
"statusCode":"0000",
267+
"statusMessage":"Successful"
268+
}
150269
```
151270

152-
### For refund Transaction
271+
### 4. Refund Transaction
153272

154273
```
155-
public function refund(Request $request)
156-
{
157-
return BkashPayment::refund(paymentID,$trxID,$amountToRefund);
158-
}
274+
public function refund(Request $request)
275+
{
276+
$paymentID = 'Your payment id';
277+
$trxID = 'your transaction no';
278+
$amount = 5;
279+
$reason = 'this is test reason';
280+
$sku = 'abc';
281+
return BkashPayment::refund($paymentID, $trxID, $amount, $reason, $sku);
282+
}
283+
```
284+
### Response
285+
```
286+
{
287+
"statusCode":"0000",
288+
"statusMessage":"Successful",
289+
"originalTrxID":"or_tnx_no",
290+
"refundTrxID":"refund_tnx",
291+
"transactionStatus":"Completed",
292+
"amount":"5",
293+
"currency":"BDT",
294+
"charge":"0.00",
295+
"completedTime":"2023-01-23T15:53:29:120 GMT+0600"
296+
}
297+
```
298+
### 5. Refund status check
299+
```
300+
public function refundStatus(Request $request)
301+
{
302+
$paymentID = 'Your payment id';
303+
$trxID = 'your transaction no';
304+
return BkashPayment::refundStatus($paymentID, $trxID);
305+
}
306+
```
307+
### Response
308+
```
309+
{
310+
"statusCode":"0000",
311+
"statusMessage":"Successful",
312+
"originalTrxID":"ori_tx",
313+
"refundTrxID":"ref_tx",
314+
"transactionStatus":"Completed",
315+
"amount":"5",
316+
"currency":"BDT",
317+
"charge":"0.00",
318+
"completedTime":"2023-01-23T15:53:29:120 GMT+0600"
319+
}
159320
```
160321

161322
## [Auth & Capture (URL)](https://developer.bka.sh/docs/auth-capture-process-overview)
@@ -183,3 +344,26 @@ BkashPayment::capture($paymentID);
183344
```
184345
BkashPayment::void($paymentID);
185346
```
347+
348+
---
349+
350+
### Required APIs
351+
0. **Developer Portal** (detail Product, workflow, API information): https://developer.bka.sh/docs/checkout-process-overview
352+
1. **Grant Token :** https://developer.bka.sh/v1.2.0-beta/reference#gettokenusingpost
353+
2. **Create Payment :** https://developer.bka.sh/v1.2.0-beta/reference#createpaymentusingpost
354+
3. **Execute Payment :** https://developer.bka.sh/v1.2.0-beta/reference#executepaymentusingpost
355+
4. **Query Payment :** https://developer.bka.sh/v1.2.0-beta/reference#querypaymentusingget
356+
5. **Search Transaction Details :** https://developer.bka.sh/v1.2.0-beta/reference#searchtransactionusingget
357+
358+
### Tokenized Checkout (v2) Demo
359+
0. Bkash: https://merchantdemo.sandbox.bka.sh/
360+
1. Go to https://merchantdemo.sandbox.bka.sh/tokenized-checkout/version/v2
361+
2. **Wallet Number:** 01770618575
362+
3. **OTP:** 123456
363+
4. **Pin:** 12121
364+
365+
## License
366+
367+
This repository is licensed under the [MIT License](http://opensource.org/licenses/MIT).
368+
369+
Copyright 2025 [ProgrammerHasan](https://github.com/ProgrammerHasan).

0 commit comments

Comments
 (0)