# bKash Module

https://docs.wisecp.com/de/bkash-module

Configure bKash to accept wallet payments on its payment page and track the resulting invoices in WISECP.

## Reaching the Screen

Go to **Settings → Financial → Payment Gateways → All Modules** and click **bKash**: `{admin}/modules/payment?module=bKash`

## What Is on the Screen

The form contains merchant credentials, a sandbox switch and shared gateway settings. Clients leave WISECP to enter their wallet number, OTP and PIN on bKash.

This module uses one-time checkout. It offers no saved wallet agreement, card storage, automatic payment, subscription, installment, separate capture or automatic refund. bKash's other products do not add these capabilities to this module.

## Before You Configure It

Apply through [bKash Online Business](https://www.bkash.com/en/business). Complete the merchant documents and agreement requested by your account manager. Request Checkout (URL based) access and separate sandbox/live integration credentials.

Use HTTPS and TLS 1.2 or newer. Payments must reach bKash in BDT. The current module sends the checkout's amount and currency without applying the shared conversion setting; use BDT invoices and confirm the received currency in sandbox. Confirm the approved website and endpoint version with bKash. This form has no custom API-address field.

## Fields

- **Username**: Required; empty by default. The integration username supplied by bKash for the selected environment.
- **Password**: Required; empty by default. The corresponding merchant API password; never enter a customer's wallet PIN.
- **App Key**: Required; empty by default. The application key supplied with those credentials.
- **App Secret**: Required; empty by default. The application secret belonging to the same App Key.
- **Fee**: Optional; empty by default. This field does not change the module's payment amount. Use the shared Commission Rate (%) setting for a surcharge.
- **Sandbox**: Off by default. Enable for sandbox credentials; disable for live credentials and real payments.

**Status** enables the module. Commission, conversion, amount limits and country lists belong to [Payment Modules](https://docs.wisecp.com/en/payment-modules). **Callback URL**, **Success URL** and **Failed URL** are generated addresses.

## Tasks

### Configure the Merchant Account

1. Obtain Username, Password, App Key and App Secret from bKash's integration team. These are issued during onboarding; this WISECP form cannot generate them.
2. On a separate test system, enter the sandbox set in the bKash form. Enable **Status** and **Sandbox**.
3. Click **Save Changes**. Prepare a BDT test invoice; the shared conversion setting does not convert this module's payment request.
4. Open **Payment Gateways → Initial → Enabled Module Selection**, select bKash and click **Save Changes**. The method becomes available within its configured limits.

### Check the Payment Return

The module sends **Callback URL** to bKash when creating each payment. If bKash requests your return address during approval, copy this complete value from WISECP.

No separate webhook/IPN registration or signing-secret field is used. The browser return supplies the payment ID; WISECP asks bKash to execute it. Payment completion requires a successful response with **Completed** status.

### Test and Switch to Live

1. Open an unpaid test invoice as its client. Select bKash and click **Pay Now**.
2. Use the sandbox wallet details supplied by bKash on its hosted page. Test success, cancellation and interrupted return separately.
3. Compare the bKash transaction ID, amount and BDT currency with the WISECP invoice and its payment record. Saving settings alone is not a connection test.
4. After merchant approval and successful tests, replace all four credentials with the live set. Clear **Sandbox** and click **Save Changes**; subsequent payments use real funds.

### Record a Refund

1. Arrange the refund through the process approved for your bKash merchant account. Give its operator the original transaction ID and confirm the returned amount.
2. For a completed full refund, open the WISECP invoice: `{admin}/invoices/detail?id={invoice}`.
3. Under **Summary → Change Status**, choose **Refunded → Add as expense** and click **Update Status**.
4. WISECP records the refund without sending funds. Keep the provider reference; track a partial refund separately at its actual amount.

## Things to Watch

> **Resolve an Uncertain Payment First**
> 
> The module has no automatic Query Payment recovery after an unanswered Execute request. A lost return can leave the invoice unpaid. Ask bKash to confirm the transaction before requesting another payment or releasing a service.

> **Repeated Attempts Can Reach Provider Limits**
> 
> The current module requests a fresh access token at payment creation and return. If bKash reports token limits, stop repeating the payment and contact your integration team. An error page does not prove that no funds moved.

## Required Privileges

Settings require **Modules → Payment Gateways** (`MODULES_PAYMENT_SETTINGS`). Invoice changes require **Billing → Edit** (`INVOICES_OPERATION`). bKash must authorize the merchant integration and any refund operator separately.

## Related Articles

- [Payment Modules](https://docs.wisecp.com/en/payment-modules)
- [Invoice Detail Overview](https://docs.wisecp.com/en/invoice-detail-overview)
- [bKash Onboarding and Sandbox](https://developer.bka.sh/docs/product-overview)
- [bKash Checkout and Payment Recovery](https://developer.bka.sh/docs/checkout-url-process-overview)