Laravel Bkash Laravel Package

Product Decisions This Supports

• Market entry / payment method expansion (Bangladesh): bKash is the dominant mobile financial service in Bangladesh. This package is the shortest path to adding bKash Tokenized Checkout v1.2.0 to a Laravel app, supporting a "launch in Bangladesh" roadmap item without an in-house integration project.
• Build vs. buy vs. adopt: Shifts the decision from "build a bKash client" (weeks of token lifecycle, retries, error-code mapping) to "adopt and harden an MIT wrapper." The buy/adopt signal is strongest when bKash is one of several gateways and you want a thin adapter, not a strategic platform.
• Retention / repeat-purchase features: Agreement management enables tokenized checkout — saved agreements, one-click repeat purchases, subscription-like flows. This is a roadmap dependency for any recurring billing, loyalty, or reorder feature aimed at BD customers.
• Support and finance-ops roadmap: Refund, refund-status, query, and transaction-search APIs are the primitives for a customer-support refund console, reconciliation reports, and dispute workflows. Their presence lets these be scoped as product features rather than backend blockers.
• Checkout flow decisions (regular vs. tokenized): Both flows are supported, allowing PMs to choose per segment (guest checkout vs. returning customer) without re-architecting.
• Order state machine and analytics: Events (PaymentCompleted, PaymentFailed, AgreementCreated) plus DB transaction logging hook directly into order lifecycle, funnel analytics, and failure-rate dashboards.
• Risk posture / vendor strategy: With 1 GitHub star, 0 dependents, and a single maintainer, adoption should be framed as "internalize an OSS component," not "depend on a vendor." That drives a fork-and-own decision plus a contingency plan (direct API client or aggregator fallback behind the same interface).

When to Consider This Package

Consider it when:

• You are on Laravel 8+ / PHP 8+, targeting Bangladeshi customers paying via bKash, and you have (or are obtaining) a bKash merchant account with app key, app secret, username, and password.
• You need tokenized checkout/agreements (repeat payments, saved instruments), not just a single redirect payment.
• You need the full lifecycle — create/execute/query/refund/search plus agreement create/execute/query/cancel — and don't want to hand-roll token caching, retry/backoff, and bKash error-code mapping.
• Your team is small and Laravel-idiomatic, and benefits from publishable config, migrations for transaction logs, a facade, and events rather than a bespoke SDK.
• You are willing to own the code: review it, pin a version, wrap it behind your own PaymentGateway interface, and add contract tests against the sandbox.

Look elsewhere when:

• You need vendor SLAs, guaranteed support, or security review artifacts. This is single-maintainer OSS with minimal adoption; a payment-critical path carries real operational risk.
• You are not on Laravel, or you prefer a single aggregator (SSLCommerz, aamarPay, Portwallet, etc.) that already covers bKash plus Nagad/cards/other methods under one contract — fewer integrations to maintain.
• You need capabilities the package does not claim: multi-currency, advanced fraud/risk scoring, additional authentication beyond bKash's own flow, or callback signature verification — the README's callback example simply executes a payment, so idempotency, replay protection, and verification are on you.
• Your compliance posture forbids unvetted third-party dependencies in the payment path without formal review and an internal fork.
• You have high volume or strict uptime needs that justify a first-party client or commercial support.

Adoption gates I'd require before shipping: pinned version with changelog review; secrets in a vault (not plaintext .env in prod); sandbox end-to-end tests for create → execute → query → refund; idempotency on callback execution; structured logging and alerting on failure codes; and a named internal owner with a documented fallback plan.

How to Pitch It (Stakeholders)

For executives: bKash is the dominant mobile money rail in Bangladesh, and this MIT-licensed Laravel package gives us a working integration for bKash Tokenized Checkout v1.2.0 — payments, agreements for repeat purchases, refunds, and transaction search — in days instead of a multi-week build. The trade-off is maturity: it is a single-maintainer open-source project with negligible adoption, so we should treat it as a component we internalize (fork, pin, test, monitor), not a vendor we depend on. Net effect: it de-risks the schedule of entering Bangladesh and shifts risk to engineering ownership, which we control.

For engineering leads: It follows Laravel conventions — publishable config and migrations, a Bkash facade, typed response objects (isSuccess(), getPaymentId(), getTrxId()), events for order-state transitions, and built-in token caching with retry/timeout settings. What it does not provide: idempotent callback handling, reconciliation jobs, alerting, or any abstraction over bKash. Plan to wrap it in our own gateway interface, add sandbox-driven contract tests in CI, enforce idempotency keys on execute/refund, and keep a fallback (direct API or aggregator) behind the same interface.

For finance and support ops: Refund and refund-status endpoints plus transaction search mean we can ship a support tool for refunds and reconciliation without new backend work — but only after we validate status semantics and logging. Ask for a short runbook and an audit trail before go-live.