bKash Tokenized Checkout & PayBill Integration

IMPLEMENTED

Official Reference: bKash Developer Documentation

ShebaFi ISP provides native, multi-tenant integration with two official bKash products:

1. bKash Tokenized Checkout (v1.2.0-beta): Embedded web checkout inside the Customer Self-Care Portal for online invoice settlement and instant subscription renewals.
2. bKash PayBill Biller API: Server-to-server utility billing allowing broadband subscribers to pay their monthly ISP bills directly inside the native bKash Mobile App under Pay Bill > Internet.

Architecture Overview

1. bKash Tokenized Checkout

Base URLs

• Sandbox Environment: https://tokenized.sandbox.bka.sh/v1.2.0-beta
• Production Environment: https://tokenized.pay.bka.sh/v1.2.0-beta

Step 1: Grant Token

ShebaFi automatically manages token acquisition and caches the bearer token in Redis for 3,500 seconds (tokens are valid for 1 hour).

• Endpoint: POST /tokenized/checkout/token/grant
• Headers:
  • username: Merchant API Username
  • password: Merchant API Password
• Body:

  {
    "app_key": "YOUR_APP_KEY",
    "app_secret": "YOUR_APP_SECRET"
  }

Step 2: Create Payment Session

Initiated by the customer portal when renewing a subscription or paying an outstanding bill:

• Internal Portal Endpoint: POST /api/v1/portal/payments/bkash/create/
• Outgoing bKash Call: POST /tokenized/checkout/create
• Payload:

  {
    "mode": "0011",
    "payerReference": "CUST-1001",
    "callbackURL": "https://isp.shebafi.net/portal",
    "amount": "800.00",
    "currency": "BDT",
    "intent": "sale",
    "merchantInvoiceNumber": "INV-2026-09-001"
  }

• Response:

  {
    "statusCode": "0000",
    "statusMessage": "Successful",
    "paymentID": "TR0011241098877",
    "bkashURL": "https://tokenized.sandbox.bka.sh/checkout/...",
    "amount": "800.00"
  }

Step 3: Execute Payment

Called when the customer authorizes the transaction:

• Internal Portal Endpoint: POST /api/v1/portal/payments/bkash/execute/
• Outgoing bKash Call: POST /tokenized/checkout/execute
• Payload:

  {
    "paymentID": "TR0011241098877"
  }

• Execution Effect:
  • Validates trxID uniqueness.
  • Generates immutable PaymentTransaction record.
  • Updates BillingAccount and records double-entry LedgerEntry.
  • Reconciles unpaid invoices using FIFO allocation.
  • Extends Customer.expiry_date by the package duration (default 30 days).
  • Enqueues NetworkSyncJob to unblock / enable the subscriber's PPPoE/Static profile on MikroTik.

2. bKash PayBill Biller API (Outbound Interface v1.4)

Official Reference: bKash API for Bill Payment Outbound Interface - Partner Integration Guide (Document version 1.4, Published January 30, 2024)

The bKash PayBill Outbound Interface allows bKash Pay Bill middleware to communicate directly with ShebaFi ERP to validate subscriber accounts, settle bill payments, and query transaction outcomes.

Architecture & Call Flow

Endpoint Routing & Supported URL Paths

ShebaFi supports both the official sample endpoints specified in the bKash guide and canonical RESTful aliases:

Payloads can be sent via multipart/form-data (using -F flags as shown in bKash cURL samples), application/x-www-form-urlencoded, or application/json.

2.1 Check Bill (1.1 Check Bill)

Invoked by bKash Pay Bill middleware to validate the subscriber and fetch outstanding dues.

Request Parameters

Response Parameters

cURL Sample

curl -L -X POST 'https://isp.shebafi.net/api/queryBill/' \
  -F 'UserName="bKash"' \
  -F 'Password="K38MO3"' \
  -F 'CustomerNo="CID-9878"' \
  -F 'BillMonth="092026"'

2.2 Bill Payment (1.2 Bill Payment)

Invoked by bKash Pay Bill middleware when a subscriber authorizes payment in the bKash App.

Request Parameters

Response Parameters

Processing Behavior

1. Idempotency: Duplicate calls with the same TrxId return ErrorCode: "200" immediately without double-crediting balances or repeating ledger entries.
2. Ledger & Accounting: Records a double-entry LedgerEntry under the customer's BillingAccount and allocates funds to unpaid Invoice records.
3. Line Restoration: Automatically updates Customer.status to ACTIVE, advances Customer.expiry_date, and enqueues a background NetworkSyncJob to unblock/enable the subscriber on the connected MikroTik BRAS.

cURL Sample

curl -L -X POST 'https://isp.shebafi.net/api/payBill/' \
  -F 'UserName="bKash"' \
  -F 'Password="K38MO3"' \
  -F 'CustomerNo="CID-9878"' \
  -F 'Amount="540.00"' \
  -F 'TrxId="5C8300HJ6V"' \
  -F 'UserMobileNumber="017111928374"' \
  -F 'PayTime="20260917123000"'

2.3 Transaction Search Query (1.3 Transaction Search Query)

Invoked by bKash middleware to verify whether a specific transaction was successfully recorded in ShebaFi ERP.

Request Parameters

Response Parameters

cURL Sample

curl -L -X POST 'https://isp.shebafi.net/api/searchTransaction/' \
  -F 'UserName="bKash"' \
  -F 'Password="K38MO3"' \
  -F 'TrxId="5C8300HJ6V"'

2.4 Error Code Specification

In compliance with Section 2 of the bKash Partner Integration Guide, ShebaFi returns the following standardized error codes and descriptions:

3. Multi-Tenant Gateway Configuration

Each tenant configures their own bKash Merchant credentials via PaymentGateway:

• app_key
• app_secret
• username
• password
• is_sandbox (Toggle between Sandbox and Live endpoints)
• sandbox_app_key, sandbox_app_secret, sandbox_username, sandbox_password

Credentials are encrypted in the database and never exposed in portal responses or API serializations.