README

sarojsardar/hamropay

A production-ready Laravel package for the HamroPay payment gateway.

Disclaimer: This is an unofficial community package and is not affiliated with or endorsed by HamroPatro Pvt. Ltd.

Features

• HMAC-SHA512 signed requests — all API calls are cryptographically signed
• Laravel events — PaymentInitiated and WebhookReceived for clean application hooks
• Auto-registered routes — configurable prefix, middleware, and toggle
• Config validation — throws on missing credentials at boot time, not at runtime
• Retry & timeout — configurable HTTP client options for production resilience
• Rate limiting — built-in throttle on initiate and transaction endpoints
• Fully tested — 16 tests, 45 assertions with Pest
• PHPStan level 8 — strict static analysis via Larastan
• Laravel Pint — enforced code style

Requirements

Installation

Install via Composer:

composer require sarojsardar/hamropay

Laravel auto-discovers the service provider — no manual registration needed.

Publish the config file:

php artisan vendor:publish --tag=hamropay-config

Configuration

Add the following to your .env file:

# API Endpoints
HAMROPAY_API_BASE_URL=https://uat-payclient.hamropatro.com
HAMROPAY_GATEWAY_URL=https://uat-checkout-pay.hamropatro.com

# Merchant Credentials (from HamroPay merchant portal)
HAMROPAY_MERCHANT_ID=your-merchant-id
HAMROPAY_CLIENT_ID=your-client-id
HAMROPAY_CLIENT_API_KEY=your-client-api-key
HAMROPAY_SECRET=your-secret
HAMROPAY_WEBHOOK_SECRET=your-webhook-secret

# Redirect URLs
HAMROPAY_SUCCESS_URL=https://yourapp.com/payment/success
HAMROPAY_FAILURE_URL=https://yourapp.com/payment/failed

# HTTP Options (optional)
HAMROPAY_VERIFY_SSL=true
HAMROPAY_TIMEOUT=30
HAMROPAY_RETRY=1
HAMROPAY_RETRY_DELAY=500

# Routes (optional)
HAMROPAY_ROUTES_ENABLED=true
HAMROPAY_ROUTES_PREFIX=api/hamropay

Quick Start

1. Initiate a Payment

use SarojSardar\HamroPay\Facades\HamroPay;

$result = HamroPay::initiate(
    amount: 1000,           // Amount in paisa (1000 = Rs. 10)
    remarks: 'Order #42',
);

// $result['gateway_url']     — POST form action URL
// $result['merchant_txn_id'] — your transaction reference
// $result['params']          — hidden fields to submit

2. Submit to Gateway (Blade)

<form method="POST" action="{{ $result['gateway_url'] }}">
    @foreach ($result['params'] as $key => $value)
        <input type="hidden" name="{{ $key }}" value="{{ $value }}">
    @endforeach
    <button type="submit">Pay with HamroPay</button>
</form>

3. Handle the Webhook

Listen to the WebhookReceived event in your AppServiceProvider:

use SarojSardar\HamroPay\Events\WebhookReceived;

Event::listen(WebhookReceived::class, function (WebhookReceived $event) {
    $payload = $event->payload;

    if ($payload['status'] === 'SUCCESS') {
        // Mark order as paid
    }
});

Usage

Via Dependency Injection (recommended)

use SarojSardar\HamroPay\Contracts\HamroPayClient;
use SarojSardar\HamroPay\Exceptions\HamroPayException;

class PaymentController extends Controller
{
    public function __construct(private readonly HamroPayClient $hamroPay) {}

    public function initiate(Request $request): JsonResponse
    {
        try {
            $result = $this->hamroPay->initiate(
                amount: $request->integer('amount'),
                remarks: "Order #{$request->input('order_id')}",
                products: $request->array('products'),
                metadata: $request->array('metadata'),
            );
        } catch (HamroPayException $e) {
            return response()->json(['error' => $e->getMessage()], 422);
        }

        return response()->json($result);
    }
}

Fetch Transaction Status

$txn = HamroPay::getTransaction($merchantTxnId);

// $txn['status']  — SUCCESS | FAILED | NOT_INITIATED
// $txn['amount']  — amount in paisa

Webhook Verification (manual)

$valid = HamroPay::verifyWebhookSignature(
    headerSig: $request->header('Signature'),
    merchantTxnId: $payload['merchantTxnId'],
    status: $payload['status'],
    amount: (float) $payload['amount'],
);

Or use handleWebhook() which verifies and fires the WebhookReceived event in one call:

if (! HamroPay::handleWebhook($request->header('Signature'), $request->all())) {
    abort(401, 'Invalid signature');
}

API Routes

The package auto-registers these routes under the api middleware group:

Customise Routes

// config/hamropay.php
'routes' => [
    'enabled'    => true,
    'prefix'     => 'payments/hamropay',
    'middleware' => ['api', 'auth:sanctum'],
],

Disable and Define Your Own

HAMROPAY_ROUTES_ENABLED=false

use SarojSardar\HamroPay\Http\Controllers\HamroPayController;

Route::middleware('api')->group(function () {
    Route::post('/pay/initiate',   [HamroPayController::class, 'initiate']);
    Route::post('/pay/status',     [HamroPayController::class, 'transaction']);
    Route::post('/pay/webhook',    [HamroPayController::class, 'webhook']);
});

Events

Error Handling

All API failures throw HamroPayException:

use SarojSardar\HamroPay\Exceptions\HamroPayException;

try {
    $result = HamroPay::initiate(1000);
} catch (HamroPayException $e) {
    $e->getMessage();   // Human-readable error
    $e->getCode();      // HTTP status code (for requestFailed)
    $e->context();      // ['status' => 400, 'body' => '...']
}

Testing

# Run tests
composer test

# Run with coverage (requires Xdebug or PCOV)
composer test:coverage

# Static analysis
composer analyse

# Code style
composer format

Faking in Application Tests

use Illuminate\Support\Facades\Http;

Http::fake([
    'uat-payclient.hamropatro.com/*' => Http::response([
        'sessionId' => 'fake-session-id',
    ]),
]);

$this->postJson('/api/hamropay/initiate', ['amount' => 1000])
     ->assertOk()
     ->assertJsonStructure(['gateway_url', 'merchant_txn_id', 'params']);

Security

• All outbound requests are signed with HMAC-SHA512
• Webhook signatures are verified with hash_equals() to prevent timing attacks
• SSL verification is enabled by default (HAMROPAY_VERIFY_SSL=true)
• Credentials are validated at service resolution time — misconfiguration fails fast

To report a security vulnerability, please email sarojsardar25@gmail.com instead of opening a public issue.

Contributing

Contributions are welcome. Please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Run tests (composer test) and static analysis (composer analyse)
4. Submit a pull request

Changelog

See CHANGELOG.md for release history.

License

The MIT License. See LICENSE for details.