UniPay BD — Unified Bangladesh Payment Gateway for Laravel

The ultimate unified Laravel payment gateway package for Bangladeshi Mobile Financial Services (MFS) & Payment Gateways.

📌 Table of Contents

• Overview
• Supported Payment Gateways
• Key Features
• Requirements
• Installation
• Configuration
• Quick Start & Usage
  • 1. Initiate Payment
  • 2. Handle Payment Callbacks & Webhooks
  • 3. Listen to Payment Events
  • 4. Process Refunds
  • 5. Query Payment Status
• Extending with Custom Drivers
• Exception & Error Handling
• Testing
• Security
• License

🚀 Overview

UniPay BD (unipay/unipay-bd) provides a seamless, developer-friendly driver-based payment integration for Laravel applications operating in Bangladesh.

Inspired by Laravel's native driver pattern (FilesystemManager, CacheManager), UniPay allows developers to integrate bKash, Nagad, Rocket, Upay, CellFin, SSLCommerz, and Shurjopay using a single, normalized API syntax.

Instead of writing fragmented, gateway-specific API logic for each payment provider, UniPay BD normalizes all request payloads and response structures (PaymentResponse) across all Bangladeshi payment gateways.

💳 Supported Payment Gateways

UniPay BD natively supports 7 Bangladeshi payment providers:

✨ Key Features

• 🎯 Unified Manager Architecture: Easily switch payment drivers on the fly using Payment::driver('bkash'), Payment::driver('nagad'), etc.
• 📦 Normalized DTO Responses: Unified PaymentResponse object guarantees identical property access (status, paymentId, transactionId, amount, redirectUrl, rawResponse).
• 🔄 Automated Callback & Webhook System: Built-in callback engine at /unipay/callback/{gateway} handles payment redirects and webhooks automatically.
• 🔔 Native Laravel Events: Fires PaymentSucceeded, PaymentFailed, and PaymentRefunded events for decoupled application logic.
• 🔐 Enterprise RSA & Token Security: In-memory token caching for bKash and PKCS1 RSA encryption for Nagad merchant onboarding.
• 📊 Transaction Logging: Automatic logging of payment requests, status updates, and raw gateway JSON payloads to your database.
• 🛠️ Artisan Installation CLI: Publish configs and database migrations with php artisan unipay:install.

⚙️ Requirements

• PHP: ^8.1 || ^8.2 || ^8.3
• Laravel: ^10.0 || ^11.0
• PHP Extensions: ext-json, ext-openssl, ext-curl

📦 Installation

Install the package via Composer:

Run the Artisan installer to publish the configuration file and database migrations:

🔧 Configuration

Add your payment gateway credentials to your application's .env file:

💻 Quick Start & Usage

1. Initiate Payment

To start a checkout process, build a PaymentRequest and call Payment::createPayment():

2. Handle Payment Callbacks & Webhooks

UniPay automatically registers a unified callback route at /unipay/callback/{gateway}.

When a customer completes payment, the MFS provider redirects back to this endpoint. UniPay automatically executes status verification and dispatches Laravel events.

3. Listen to Payment Events

Decouple your order processing logic by listening to UniPay events in App\Providers\EventServiceProvider.php:

Inside your event listener class:

4. Process Refunds

To issue a full or partial refund to a customer:

5. Query Payment Status

Query any transaction status explicitly at any time:

🛠️ Extending with Custom Drivers

You can easily register custom gateway drivers using Payment::extend():

⚠️ Exception & Error Handling

UniPay provides a clean exception hierarchy:

• Unipay\BD\Exceptions\UnipayException: Base exception class.
• Unipay\BD\Exceptions\InvalidGatewayException: Thrown when requesting an unsupported gateway.
• Unipay\BD\Exceptions\BkashApiException: Thrown when bKash API returns invalid credentials or auth errors.
• Unipay\BD\Exceptions\NagadEncryptionException: Thrown when OpenSSL RSA keys or signatures fail.
• Unipay\BD\Exceptions\PaymentVerificationFailedException: Thrown on failed payment checksums.

🧪 Testing

UniPay BD includes a full Pest & PHPUnit test suite with 100% mocked HTTP responses and OpenSSL key pair generation.

Run the test suite:

Expected output:

🔒 Security

If you discover any security-related issues, please email [email protected] instead of using the public issue tracker.

📄 License

UniPay BD is open-sourced software licensed under the MIT License.

Crafted with ❤️ for the Bangladeshi Developer Community.