README

An elegant, easy-to-use Laravel integration for ShadhinPayGateway. Fully compatible with Laravel 8, 9, 10, and 11, and PHP 7.4 through 8.x.

Installation

Install the package via Composer:

composer require xeronce/shadhinpay-gateway-laravel

Local Development / Testing

If you are developing or testing this package locally before publishing, add the package to your host Laravel project's composer.json using a path repository:

"repositories": [
    {
        "type": "path",
        "url": "path/to/shadhinpay-gateway-laravel",
        "options": {
            "symlink": true
        }
    }
],

Then run:

composer require xeronce/shadhinpay-gateway-laravel:@dev

Zero Configuration

Laravel's Package Auto-Discovery will automatically register the service provider and ShadhinPayGateway Facade.

If you wish to publish the configuration file, run:

php artisan vendor:publish --tag=shadhinpay-gateway-config

Configuration

Add the following environment variables to your .env file:

SHADHINPAY_GATEWAY_CLIENT_ID=your_client_id
SHADHINPAY_GATEWAY_BUSINESS_ID=your_business_id
SHADHINPAY_GATEWAY_API_KEY=your_x_api_key_access_key
SHADHINPAY_GATEWAY_WEBHOOK_SECRET=your_webhook_signing_secret_optional
SHADHINPAY_GATEWAY_BASE_URL=https://request.shadhinpay.com

Usage

1. Create a Payment

To initiate a payment and redirect the customer to ShadhinPayGateway's checkout:

use Xeronce\ShadhinpayGateway\Facades\ShadhinpayGateway;

$response = ShadhinpayGateway::pay([
    'amount'        => 500.00,
    'currency'      => 'BDT',
    'merchantTxnId' => 'TXN-' . time(),
    'callbackUrl'   => route('payment.callback'),
    'customerPhone' => '01700000000',
    'customerEmail' => 'customer@example.com',
    'description'   => 'Buying Premium Plan',
]);

if (isset($response['data']['paymentUrl'])) {
    return redirect($response['data']['paymentUrl']);
}

// Handle error
return back()->with('error', $response['message'] ?? 'Payment failed to initialize');

2. Verify a Payment

To verify the payment status using the paymentId returned from the checkout callback:

use Xeronce\ShadhinpayGateway\Facades\ShadhinpayGateway;

$paymentId = $request->query('paymentId');
$response = ShadhinpayGateway::verify($paymentId);

if (isset($response['data']['status']) && $response['data']['status'] === 'COMPLETED') {
    // Payment is successful
}

3. Refund a Payment

To request a refund for an existing payment:

use Xeronce\ShadhinpayGateway\Facades\ShadhinpayGateway;

$response = ShadhinpayGateway::refund($paymentId, [
    'amount' => 500.00,
    'reason' => 'Customer requested cancelation',
    'merchantRef' => 'REF-' . time()
]);

Webhooks

ShadhinPayGateway automatically dispatches webhooks to notify your application of payment status changes.

The package exposes a POST endpoint at: /ShadhinPayGateway/webhook

Important

Since webhook requests are sent from ShadhinPayGateway's servers, you must exempt the webhook route from CSRF protection.

For Laravel 8, 9, and 10: Add the route to $except in app/Http/Middleware/VerifyCsrfToken.php:

protected $except = [
    'ShadhinPayGateway/webhook',
];

For Laravel 11+: Add the route to the middleware configuration in bootstrap/app.php:

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

Webhook Event Listener

When a webhook is received, the package verifies the webhook signature (if ShadhinPayGateway_GATEWAY_SIGNING_SECRET is defined in .env) and fires a WebhookReceived event.

You can listen to this event in your EventServiceProvider:

use Xeronce\ShadhinpayGateway\Events\WebhookReceived;
use App\Listeners\HandleShadhinpayGatewayWebhook;

protected $listen = [
    WebhookReceived::class => [
        HandleShadhinpayGatewayWebhook::class,
    ],
];

And in your listener class HandleShadhinpayGatewayWebhook.php:

namespace App\Listeners;

use Xeronce\ShadhinpayGateway\Events\WebhookReceived;

class HandleShadhinpayGatewayWebhook
{
    public function handle(WebhookReceived $event)
    {
        $payload = $event->payload;
        $eventType = $payload['eventType'] ?? ''; // e.g. PAYMENT.COMPLETED

        if ($eventType === 'PAYMENT.COMPLETED') {
            $paymentData = $payload['data'];
            $paymentId = $paymentData['paymentId'];
            $merchantTxnId = $paymentData['merchantTxnId'];
            
            // Update your database order status
        }
    }
}

Security

If ShadhinPayGateway_GATEWAY_SIGNING_SECRET is set, all incoming webhooks are validated using HMAC-SHA256 replay-safe protection to prevent request spoofing.

License

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