PayBridge DOCS
🚀 PayBridge 1.0 is live with 16 gateways including Bangla QR & Binance Pay!

🔐 Live Admin Control Panel

Manage all 16 payment gateways, live API keys, user-reported issues, and customer reviews.

Protected

Admin Authentication Required

Please enter your admin credentials to unlock the payment gateway management console and review system tickets.

Protected with SHA-256 cryptographic verification

PayBridge Developer & Merchant Hub

The enterprise-grade payment gateway aggregator for PHP & Laravel. Unify 16 local, global, and cryptocurrency gateways under a standardized API with a built-in No-Code Admin Control Panel.

PHP 8.2+ Universal Laravel 10 / 11 / 12 Bangla QR Interoperable Binance Pay & NOWPayments Bank-Grade Encryption

Why Choose PayBridge?

16 Built-In Gateways

bKash, Nagad, Rocket, Upay, Bangla QR, Binance Pay, NOWPayments, SSLCommerz, AamarPay, SurjoPay, Sonali Pay, PortPay, EPS, Stripe, and PayPal.

Universal PHP & Frameworks

Zero vendor lock-in! Works seamlessly in Raw PHP, WordPress, CodeIgniter, Symfony, and Laravel without forcing framework dependencies.

No-Code Admin Control Panel

Non-technical merchants can enable/disable gateways, update API keys, toggle sandbox modes, and set primary defaults without touching code.

National Bangla QR

Full compliance with Bangladesh Bank EMVCo standards and CRC-16 checksums for seamless multi-bank and MFS camera scanning.

Quick Architecture Tour

Option 1: Raw PHP / WordPress / CodeIgniter / Symfony

Raw PHP Standalone Usage (PayBridge::make)
require_once 'vendor/autoload.php';

use PayBridge\Payment\PayBridge;

// 1. Initialize any of the 16 gateways
$gateway = PayBridge::make('bkash_tokenize', [
    'app_key'      => 'your_bkash_app_key',
    'app_secret'   => 'your_bkash_app_secret',
    'username'     => 'your_bkash_username',
    'password'     => 'your_bkash_password',
    'sandbox'      => true,
    'callback_url' => 'https://example.com/callback.php',
]);

// 2. Initiate payment
$response = $gateway->pay([
    'amount'         => 1200.00,
    'transaction_id' => 'INV_' . time(),
    'currency'       => 'BDT',
]);

if ($response['success']) {
    header('Location: ' . $response['redirect_url']);
    exit;
}

Option 2: Laravel Applications (Payment Facade)

Laravel Controller (Auto-resolves default gateway & DB credentials)
use PayBridge\Payment\Facades\Payment;

// Automatically uses your default active gateway (from Admin Panel or .env)
$response = Payment::driver()->pay([
    'amount'         => 1500.00,
    'transaction_id' => 'ORD-2026-99',
]);

if ($response['success']) {
    return redirect()->away($response['redirect_url']);
}

🚀 Installation & Getting Started

Follow these quick steps to install PayBridge into your Raw PHP project or Laravel application.

Step 1: Install Composer Package

Terminal
composer require codepagol/pay-bridge

Option A: Setup in Raw PHP / WordPress / Any Framework

No migrations or service providers needed! Simply include the Composer autoloader and call PayBridge::make($gateway, $config):

PHP Script
require_once 'vendor/autoload.php';

use PayBridge\Payment\PayBridge;

$sslcommerz = PayBridge::make('sslcommerz', [
    'store_id'       => 'your_store_id',
    'store_password' => 'your_password',
    'sandbox'        => true,
]);

$response = $sslcommerz->pay(['amount' => 500, 'transaction_id' => uniqid()]);

Option B: Setup in Laravel (with Admin Control Panel)

In Laravel 10/11/12, the package is auto-discovered. Run these commands to publish configuration and create the database settings table:

Terminal
# 1. Publish config
php artisan vendor:publish --tag=payment-config

# 2. Run migrations
php artisan migrate

# 3. (Optional) Publish admin views
php artisan vendor:publish --tag=payment-views

Access the Laravel Admin Dashboard

Visit http://your-domain.test/admin/payment-gateways to manage all 16 gateways, API keys, and sandbox modes.

Authentication Requirement

The admin panel is protected by default with ['web', 'auth'] middleware in config/payment.php. Log into your Laravel application before accessing the URL.

💳 16 Supported Gateways Reference

PayBridge unifies local MFS, national QR, international cards, aggregators, and cryptocurrencies. Select any gateway below to view credentials and code examples.

🖥️ No-Code Admin Control Panel Guide

Empower non-technical merchants and store owners to configure payments independently without developer assistance.

Key Dashboard Features

Instant Active Toggle

Enable or disable any gateway with one click. Inactive gateways disappear from your store's customer checkout immediately.

Sandbox / Live Switch

Test credentials safely without affecting production transactions. Switch each gateway individually between Sandbox and Live.

Encrypted Password Masking

App Secrets and Passwords are automatically masked and encrypted using Laravel's AES-256 database casts.

Role & Permission Security

Integrates seamlessly with Spatie Laravel Permission (role:admin) or custom Laravel Gates.

Configuring Route Roles in config/payment.php

config/payment.php
'admin' => [
    'enabled' => true,
    'prefix' => 'admin/payment-gateways',
    'middleware' => [
        'web',
        'auth',
        'role:admin|super-admin', // Restrict to authorized store admins
    ],
],

🛒 Customer Checkout & Multi-Gateway UI

Learn how to render all active payment options dynamically on your store's checkout page.

1. Checkout Controller Example

app/Http/Controllers/CheckoutController.php
use PayBridge\Facades\PayBridge;
use PayBridge\Models\PaymentGatewaySetting;

public function showCheckout()
{
    // Fetch only gateways currently activated by the merchant in Admin Panel
    $activeGateways = PaymentGatewaySetting::where('is_active', true)->get();

    return view('checkout.index', [
        'gateways' => $activeGateways,
        'orderTotal' => 1250.00,
    ]);
}

2. Dynamic Payment Selector (Blade View)

resources/views/checkout/index.blade.php
<form action="{{ route('checkout.process') }}" method="POST">
    @csrf
    <h3>Select Payment Method:</h3>
    <div class="payment-options">
        @foreach($gateways as $gw)
            <label class="gateway-option">
                <input type="radio" name="gateway" value="{{ $gw->driver }}" required>
                <span>{{ $gw->display_name }}</span>
            </label>
        @endforeach
    </div>
    <button type="submit" class="btn-pay">Pay {{ number_format($orderTotal, 2) }} BDT</button>
</form>

🔒 Financial Security & Best Practices

Payment systems require strict safety controls. PayBridge implements multi-layered protections against tampering and race conditions.

Critical Rule: Never Trust Callback URL Amounts!

Always verify transaction status directly with the gateway server and cross-reference the verified amount and currency against your internal database record.

Double-Spend & Concurrency Protection

Database Transaction with lockForUpdate()
use Illuminate\Support\Facades\DB;

DB::transaction(function () use ($verifiedResult) {
    // Lock row to prevent simultaneous webhook execution
    $order = Order::where('transaction_id', $verifiedResult->getTransactionId())
        ->lockForUpdate()
        ->firstOrFail();

    // Idempotency: skip if already fulfilled
    if ($order->status === 'PAID') {
        return;
    }

    $order->update([
        'status' => 'PAID',
        'paid_at' => now(),
    ]);

    event(new OrderFulfilled($order));
});

❓ Troubleshooting & Common Errors

Find instant solutions to the most common problems encountered during gateway setup.

1. 🛑 419 Page Expired or CSRF Token Mismatch on Webhook / Callback

Cause: Laravel blocks external POST webhooks because gateways do not have your CSRF token.

Fix: Exclude payment routes in Laravel 11 (bootstrap/app.php):

$middleware->validateCsrfTokens(except: ['payment/callback/*', 'payment/webhook/*']);
2. 🛑 403 Forbidden or Redirected to /login on /admin/payment-gateways

Cause: The admin panel requires authentication by default to protect API keys.

Fix: Log in first, or check user role in config/payment.php under 'admin' => ['middleware' => ['web', 'auth']].

3. 🛑 cURL error 60: SSL certificate problem (Localhost / Laragon)

Cause: PHP cURL cannot find your local Windows certificate authority bundle.

Fix: Download cacert.pem from curl.se and configure curl.cainfo = "C:/laragon/bin/php/cacert.pem" in php.ini.

4. 🛑 bKash: "Invalid Grant" or "Token Expired"

Cause: Sandbox/Live switch mismatch, trailing whitespace in App Secret, or unwhitelisted outbound IP.

Fix: Verify the sandbox toggle matches your keys and contact bKash Merchant Operations to whitelist your server IP.

5. 🛑 Bangla QR: Bank/MFS App says "Invalid QR Code"

Cause: Unregistered merchant ID or missing Tag 26/27 acquiring bank sub-tags.

Fix: PayBridge automatically calculates the CRC-16 checksum (Tag 63). Ensure your live merchant ID is issued by an acquiring bank connected to Bangladesh Bank NPSB switch.

⭐ Merchant & Developer Reviews

See what businesses and engineers say about PayBridge.

4.9
★★★★★
Based on verified integrations

🐛 Issue Reporting & Support Center

If you encounter a bug, gateway response failure, or need custom integration advice, report it directly here.

Online Support & Issue Ticket Desk

Submit a technical problem or gateway response error directly to our support dashboard.

Direct Merchant Assistance

Need assistance with live credential onboarding or bank integration approvals? Contact our team.

Email Support Desk