bKash: pay from the bKash wallet
Connect bKash Checkout (tokenized) so buyers pay from their bKash wallet. The four values you need, the API version, testing, refunds and common errors.
bKash is the wallet most buyers in Bangladesh already use. Once bKash has approved your Checkout account, connecting it takes a few minutes.
What it is#
bKash Checkout (tokenized) lets a buyer pay from their bKash wallet at your checkout: they enter their number, the code and PIN on the bKash page and return to your store. It suits shops whose buyers mostly pay by bKash.
What you need#
- A bKash merchant account with the payment gateway (Checkout) service approved by bKash. bKash gives you the credentials itself, separately for sandbox and live.
- Four values and one choice:
| Field in Jukto | What it is |
|---|---|
| App key | Identifies your app (secret) |
| App secret | Secret for your app (secret) |
| Username | The API username bKash gave you |
| Password | The API password bKash gave you (secret) |
| API version | v2 (current) or v1.2.0-beta (older merchant accounts). Leave empty for v2 |
Where to find your keys#
- 1
Ask bKash for the Checkout (tokenized) credentials
Ask your bKash relationship manager or merchant support. bKash issues them per merchant, one set for sandbox and one for live. They are not a self-service download.
- 2
Collect the four values
You receive an App key, an App secret, a Username and a Password. Copy each into the field with the same name in Jukto.
- 3
Choose the API version
Leave API version empty for v2. Choose v1.2.0-beta only if bKash set up your merchant account before 2024 and told you to use it.
- 4
Match the mode
Choose Sandbox (testing) or Live so that it matches the set of values you pasted.
What Jukto does#
- Keys. Saved encrypted for this website only. Jukto asks bKash for a token with them and keeps the token for a short time, scoped to your website.
- Payment. Jukto creates a bKash payment and sends the buyer to the bKash page. bKash pays in BDT only.
- Return. When the buyer returns, Jukto does not trust the address: it asks bKash to confirm the payment (execute and query) and compares the invoice and the amount.
- Nothing to register. There is no notification address to paste in the bKash panel for payments.
- Order. On success the payment shows Paid with the bKash transaction ID. If the buyer cancelled or the payment failed, the order stays unpaid and the payment is marked Cancelled or Failed.
- Refunds. You can refund from the order. bKash only allows refunds within a limited time and a limited number of partial refunds per payment, so check the bKash rules before you promise one.
Text version of the diagram
- Jukto creates the payment to Buyer pays on bKash
- Buyer pays on bKash to Buyer returns
- Buyer returns to Jukto asks bKash to confirm
- Jukto asks bKash to confirm to Completed, invoice and amount match?
- Completed, invoice and amount match? to Order marked paid (Yes)
- Completed, invoice and amount match? to Cancelled or failed: stays unpaid (No)
Test and turn on#
- 1
Open the provider
Go to Dashboard > Tools > Integrations, open the Payments group and choose bKash.
- 2
Choose the mode and fill the fields
Pick Sandbox (testing) or Live, fill App key, App secret, Username, Password, and API version if needed. Press Save.
- 3
Press Test connection
Jukto asks bKash for a token. You see "bKash sandbox granted a token" (or "live") when the four values are right.
- 4
Repeat with live values
After a sandbox pass, switch to Live, enter the live set, Save and test again.
- 5
Press Turn on
Make one small real order with your own bKash number, then check the Payments list. Press Check again if it stays waiting.
Common errors#
| What you see | What it means | What to do |
|---|---|---|
| Fill in: App key, App secret, Username, Password | A required field is empty | Fill all four and save |
| bKash refused the credentials: (bKash's message) | A value is wrong, or Sandbox values are used in Live | Check the set and the mode, and the API version |
| bKash did not return a token | bKash answered without a token | Test again; ask bKash if it repeats |
| bKash did not answer | bKash or the network was slow | Try again in a minute |
| bKash refused the payment | bKash did not accept the new payment | Read the message that follows; check that the amount is valid |
| bKash says Initiated | The buyer has not completed the payment | Wait, then press Check again |
| buyer returned with cancel / failure | The buyer cancelled or the payment failed | The order stays unpaid; the buyer can try again |
| the bKash transaction id is not saved yet; check the payment status first | A refund was tried before the payment was confirmed | Press Check again, then refund |
| bKash refused the refund | The refund was not accepted | Check the amount and bKash's refund time limit |
Next#
- Payments overview
- Nagad: the other big wallet.
- Integrations overview
Comments (0)
Anyone can comment. Please do not post phone numbers, passwords or customer details.