Skip to content

Releases

bKash Sync 2.0_1.0

bKash Sync 2.0_1.0 Latest
Latest

Choose a tag to compare

View all tags
@zenjahid zenjahid released this 28 May 01:32
v2.0
f95e3f8

Real-time bKash SMS transaction monitoring and sync with custom backend APIs.

What it does

bKash Sync captures every incoming bKash SMS on your Android phone, extracts the transaction details (amount, sender, TrxID, balance, timestamp), stores them locally, and syncs them to your own Cloudflare Workers + D1 backend. From there, you can query your database to verify payments on your website, trigger webhooks, or build dashboards — no bKash merchant account required.

Features

Real-time SMS Capture

  • Intercepts bKash SMS instantly via BroadcastReceiver with priority 999
  • Parses You have received Tk messages using regex to extract amount, sender number, TrxID, timestamp, and balance
  • Tracks which SIM slot received the transaction (SIM 1 / SIM 2)

Offline-First Architecture

  • All transactions stored in local Room (SQLite) database before any network sync
  • Three tables: transactions, outbox (sync queue), and sync_state
  • INSERT OR IGNORE on TrxID prevents duplicates at the database level

Background Sync (WorkManager + Foreground Service)

  • Batches up to 30 transactions per API request
  • Retries failed uploads with exponential backoff (max 8 attempts)
  • Persistent foreground notification shows live sync metrics (total, pending, sent, failed, last sync time)
  • Configurable sync interval (default 15 seconds)

Smart Delta-Sync

  • Bidirectional reconciliation between phone and server
  • POST /synctransaction sends all local TrxIDs to the server
  • Server returns missingOnServer (re-queued for upload) and missingOnClient (downloaded and inserted locally)
  • Both sides converge to identical dataset without full re-upload

Historical SMS Scanner

  • Imports existing bKash SMS from the device inbox on first setup
  • Periodically rescans inbox (last 50 SMS) to catch any missed messages
  • Auto-reconcile option runs Delta-Sync after each sweep

Encrypted Storage

  • API key encrypted with AES/CBC/PKCS5Padding in SharedPreferences
  • Prevents casual on-device inspection of credentials

Configurable

  • Adjustable sync interval
  • Dark/light mode with animated toggle
  • Manual sync, force resync, and database purge controls
  • Battery optimization status check and exemption guide

Cloudflare Workers Backend

  • Serverless TypeScript backend deployable in minutes
  • D1 (serverless SQLite) for zero-config persistent storage
  • Admin endpoints for issuing/revoking user API keys
  • CORS-enabled, Bearer token auth, INSERT OR IGNORE deduplication

API Endpoints

Endpoint Method Auth Description
/verify POST API Key Verify API key validity
/transactions POST API Key Upload batched transactions
/synctransaction POST API Key Smart Delta-Sync (bidirectional)
/user/transactions GET API Key Get user's transactions
/admin/keys POST Admin Key Issue/revoke user API keys
/admin/users GET Admin Key List all registered users
/admin/transactions GET Admin Key Get all transactions

How to Use

1. Deploy Your Backend

cd server/cloudflare-server
npm install
wrangler d1 create bkash-sync-db          # Copy the database ID into wrangler.toml
wrangler secret put ADMIN_API_KEY         # Set your master admin key
npm run db:deploy                         # Initialize database schema
npm run deploy                            # Deploy to Cloudflare

Your Worker will be live at https://bkash-sync-cloudflare-server.<your-subdomain>.workers.dev.

2. Issue an API Key for Your Device

Use the admin endpoint to create a key tied to your phone number:

curl -X POST https://your-worker.workers.dev/admin/keys \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "01XXXXXXXXX", "key": "your-device-api-key"}'

3. Get the App

You have two options:

Option A — Download the pre-built APK from the Releases page.

Option B — Build it yourself:

cd bkash-sync_app
./gradlew assembleRelease
# Output: app/build/outputs/apk/release/app-release.apk

Install the APK on your phone and grant all requested permissions:

  • SMS (RECEIVE_SMS, READ_SMS) — needed to intercept bKash messages
  • Notifications — for the persistent sync status notification
  • Battery optimization exemption — prevents Android from killing the background service

4. Configure the App

Open the app and tap the Settings tab:

  1. API Sync Endpoint — Enter your Worker URL (e.g. https://your-worker.workers.dev)
  2. Secure Sync API Key — Enter the device API key you issued in step 2
  3. User Phone Number — Enter the phone number tied to your API key
  4. Tap VERIFY & SAVE GATEWAY — the app will call /verify to confirm everything works

Once verified, the status badge at the top changes from PAUSED to ACTIVE and monitoring begins immediately.

5. Enable Smart Delta-Sync

In the Settings tab:

  • Sync Interval — How often the background scanner checks for new SMS (default 15 seconds, minimum 1 second)
  • Auto-Reconcile — Toggle this ON to run Smart Delta-Sync automatically after every sweep

With auto-reconcile enabled, the app will:

  • Compare all local TrxIDs with the server after each scan
  • Re-upload any transactions missing on the server
  • Download any transactions present on the server but missing on the phone

You can also trigger Delta-Sync manually from the Monitor tab by tapping Smart Delta-Sync Now.

6. Verify Payments from Your Website

Once transactions are synced, your website can verify payments by calling your Worker:

# Fetch all synced transactions for a phone number
curl -X GET "https://your-worker.workers.dev/user/transactions?phone_number=01XXXXXXXXX" \
  -H "Authorization: Bearer your-device-api-key"

Match the senderNumber, trxId, and amount from the response against what your customer submitted on your payment page.

7. Optional: Import Old SMS

Tap Import Old SMS on the Monitor tab to scan your device inbox for any bKash transactions that arrived before the app was installed.

Use Case

bKash Sync enables automated P2P (person-to-person) bKash payment verification:

  1. You create a payment page with a product price and your personal bKash number
  2. A customer sends money from their bKash to your number and gets a TrxID
  3. bKash Sync captures the SMS on your phone and syncs it to your backend
  4. The customer enters their phone number and TrxID on your payment page
  5. Your website queries your backend to match senderNumber + trxId + amount
  6. Payment verified — no manual SMS checking, no merchant account

Requirements

  • Android: API 24+ (Android 7.0)
  • Server: Node.js 18+, Cloudflare account, Wrangler CLI
  • Permissions: RECEIVE_SMS, READ_SMS, Internet, Notifications, Battery Optimization exemption

License

MIT — see LICENSE

Assets 3
Loading