SBI ePay for Laravel

A modern, fluent, and strongly-typed SBI ePay (State Bank of India Payment Gateway) integration package for Laravel applications.

[!NOTE] Disclaimer: This is an independent, community-developed package and is not an official package from State Bank of India (SBI) or SBI ePay. It is neither endorsed by, affiliated with, nor maintained by State Bank of India.

Highlights

• ⚡ Fluent Payment Initiation: One-liner payment generation with auto-submitting redirect form or headless API responses for SPAs.
• 🔐 AES-128-CBC Encryption: Compliant with official SBI ePay specifications using PHP's native OpenSSL.
• 🛡️ Double Verification Support: Built-in server-to-server query verification to prevent client tampering and guarantee authentic bank status.
• 🏢 Multi-Merchant / Multi-Tenant Support: Seamlessly switch merchant credentials dynamically using SbiEpay::merchant($id, $key).
• 🔀 Environment Switching: Out-of-the-box configuration for test (UAT) and live (Production) gateways.
• 🧪 Production-Grade Quality: Strict types declared, PHPStan Level 7 compliant, 100% type coverage, and tested with Pest.

Requirements

• PHP: ^8.3 or ^8.4
• Laravel: ^11.0 or ^12.0
• PHP OpenSSL Extension enabled

Installation

Install the package into your Laravel application via Composer:

composer require satnam-singh/sbi-epay

Publish Configuration

Publish the sbi-epay.php configuration file:

php artisan vendor:publish --tag="sbi-epay-config"

Configuration

Add your SBI ePay merchant credentials to your .env file:

# Environment: 'test' for UAT sandbox, 'live' for production
SBI_EPAY_MODE=test

# SBI ePay Merchant Credentials
SBI_EPAY_MERCHANT_ID=1000003
SBI_EPAY_MERCHANT_KEY=your_16_byte_merchant_key

# Optional settings (sensible defaults provided)
SBI_EPAY_AGGREGATOR_ID=SBIEPAY
SBI_EPAY_OPERATING_MODE=2
SBI_EPAY_COUNTRY=IN
SBI_EPAY_CURRENCY=INR

# Optional URL overrides
# SBI_EPAY_PAYMENT_URL=https://test.epay.sbiuat.bank.in/secure/AggregatorHostedListener
# SBI_EPAY_VERIFICATION_URL=https://test.epay.sbiuat.bank.in/payagg/statusQuery/getStatusQuery

Important: Exclude Callback Route from CSRF Verification

SBI ePay returns customers back to your application by issuing a cross-site HTTP POST request containing encrypted payload data (encData). In Laravel 11 and 12, make sure to exclude your payment callback route from CSRF verification:

In bootstrap/app.php:

->withMiddleware(function (Middleware $middleware) {
    $middleware->validateCsrfTokens(except: [
        'payment/sbi/callback',
    ]);
})

Quick Usage

1. Initiating a Payment

In your controller, use the SbiEpay facade to create a payment request:

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use SbiEpay\SbiEpay\Facades\SbiEpay;
use SbiEpay\SbiEpay\DTOs\PaymentRequest;

class CheckoutController extends Controller
{
    public function initiatePayment()
    {
        $initiation = SbiEpay::initiate(new PaymentRequest(
            orderId: 'ORDER_' . uniqid(),
            amount: 1500.00,
            successUrl: route('payment.sbi.callback'),
            failUrl: route('payment.sbi.callback'),
            otherDetails: 'Order Payment #1024',
            customerEmail: '[email protected]',
            customerMobile: '9876543210',
        ));

        // Returns an auto-submitting POST view that redirects the user to SBI ePay
        return $initiation->redirect();
    }
}

For Headless / Inertia / Vue / React SPAs: Instead of $initiation->redirect(), retrieve the raw form parameters and submit them from your frontend:

return response()->json([
    'action' => $initiation->paymentUrl,
    'form_data' => $initiation->formData(),
]);

2. Handling the Payment Callback

When the transaction finishes, SBI ePay posts the encrypted status payload to your successUrl or failUrl. Decrypt and parse it with SbiEpay::handleCallback():

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use SbiEpay\SbiEpay\Facades\SbiEpay;

class CheckoutController extends Controller
{
    public function handleCallback(Request $request)
    {
        try {
            // Decrypt and parse the response
            $response = SbiEpay::handleCallback($request->input('encData'));

            if ($response->isSuccess()) {
                // Highly recommended: Perform server-to-server Double Verification
                $verification = SbiEpay::verify($response->orderId, $response->amount);

                if ($verification->isSuccess()) {
                    // Mark order as paid in your database
                    // $order = Order::where('order_id', $response->orderId)->first();
                    // $order->markAsPaid($response->sbiTransactionId);

                    return redirect()->route('order.success', [
                        'order_id' => $response->orderId,
                    ])->with('success', 'Payment completed successfully!');
                }
            }

            return redirect()->route('order.failed')->with('error', 'Payment verification failed.');

        } catch (\Exception $e) {
            return redirect()->route('order.failed')->with('error', $e->getMessage());
        }
    }
}

Available Methods on PaymentResponse:

$response->isSuccess();           // bool: true if status is SUCCESS
$response->isFailed();            // bool: true if status is FAIL/FAILED
$response->isPending();           // bool: true if status is PENDING/AWAITED
$response->orderId;               // string: your original order ID
$response->status;                // string: 'SUCCESS', 'FAIL', etc.
$response->amount;                // float: paid amount
$response->sbiTransactionId;      // ?string: SBI reference ID
$response->bankReferenceNo;       // ?string: Bank reference number
$response->bankName;              // ?string: Paying bank name (e.g. State Bank of India)
$response->transactionDate;       // ?string: Transaction timestamp
$response->merchantId;            // ?string: SBI merchant ID
$response->rawResponse;           // string: raw pipe-delimited decrypted string
$response->toArray();             // array<string, mixed>

3. Server-to-Server Double Verification

To eliminate any chance of client-side callback tampering, query SBI's Double Verification API directly from your server:

use SbiEpay\SbiEpay\Facades\SbiEpay;

$verification = SbiEpay::verify(
    orderId: 'ORDER_12345',
    amount: 1500.00
);

if ($verification->isSuccess()) {
    // Verified by SBI server
    $sbiRef = $verification->sbiTransactionId;
}

4. Dynamic Multi-Merchant Support

If your application processes payments for multiple branches, municipalities, or tenants with different merchant accounts:

$initiation = SbiEpay::merchant('MERCHANT_BRANCH_02', 'KEY_BRANCH_02')
    ->initiate($paymentRequest);

5. Direct Encryption & Decryption Helpers

You can also use the encryption engine standalone:

use SbiEpay\SbiEpay\Facades\SbiEpay;

// Encrypt string with configured merchant key
$cipherText = SbiEpay::encrypt('Hello World');

// Decrypt back to plaintext
$plainText = SbiEpay::decrypt($cipherText);

Testing

Run the package test suite:

composer test

Individual checks:

# Pest test suite
composer test:unit

# Type coverage (100%)
composer test:types

# PHPStan static analysis
composer analyse

# Laravel Pint code styling
composer lint:check

Changelog

Please see CHANGELOG.md for details on recent changes.

Contributing

Please see CONTRIBUTING.md and CODE_OF_CONDUCT.md for details.

Security

Please review our security policy on how to report security vulnerabilities.

Credits

• Satnam Singh (@satnamgills)
• All Contributors

Disclaimer

This package is an independent, custom-built open-source integration developed to assist Laravel developers integrating with the SBI ePay payment gateway. This project is not an official product of, nor is it endorsed, certified, or maintained by State Bank of India (SBI) or SBI ePay. All trademarks, service marks, and company names are the property of their respective owners.

License

The MIT License (MIT). Please see License File for more information.