mdiqbal/laravel-payments

Laravel Payments Package

A comprehensive Laravel package for integrating multiple payment gateways into your application. This package provides a unified interface for processing payments through various payment providers including Stripe, PayPal, Razorpay, Paystack, and many more.

Table of Contents

• Features
• Supported Gateways
• Installation
• Upgrading to 3.x
• Configuration
• Basic Usage
• Gateway reference
• Testing
• Contributing
• License

Features

• Unified Interface: Single API for all payment gateways
• Multiple Gateways: Support for 21 payment gateways
• Secure: Built with security best practices
• Flexible: Easy to extend with new gateways
• Laravel Ready: Built specifically for Laravel
• Webhook Support: Built-in webhook handling
• Error Handling: Comprehensive error management
• Test Friendly: Full testing support

Supported Gateways

Installation

1. Install the package via Composer:

composer require mdiqbal/laravel-payments:^3.0

2. Publish the configuration file:

php artisan vendor:publish --provider="Mdiqbal\LaravelPayments\PaymentsServiceProvider"

3. Add your payment gateway credentials to your .env file:

# Example for Stripe
STRIPE_MODE=sandbox  # sandbox | live
STRIPE_SANDBOX_SECRET=your_sandbox_secret_key
STRIPE_SANDBOX_KEY=your_sandbox_publishable_key
STRIPE_LIVE_SECRET=your_live_secret_key
STRIPE_LIVE_KEY=your_live_publishable_key
STRIPE_WEBHOOK_SECRET=your_webhook_secret

# Example for PayPal
PAYPAL_MODE=sandbox
PAYPAL_SANDBOX_CLIENT_ID=your_sandbox_client_id
PAYPAL_SANDBOX_CLIENT_SECRET=your_sandbox_client_secret
PAYPAL_LIVE_CLIENT_ID=your_live_client_id
PAYPAL_LIVE_CLIENT_SECRET=your_live_client_secret

# Example for Mercado Pago
MERCADOPAGO_MODE=sandbox
MERCADOPAGO_SANDBOX_ACCESS_TOKEN=your_sandbox_access_token
MERCADOPAGO_LIVE_ACCESS_TOKEN=your_live_access_token
MERCADOPAGO_COUNTRY=MX
MERCADOPAGO_WEBHOOK_SECRET=your_webhook_secret

Upgrading to 3.x

Version 3.0 fixes the issues found in the QA pass over all 21 gateways (see QA_REPORT.md and CHANGELOG.md). To update an existing project:

# 1. Update the package
composer require mdiqbal/laravel-payments:^3.0

# 2. Remove the gateway SDKs 2.x pulled in (3.0 no longer needs them).
#    Skip any your own code still uses.
composer remove srmklive/paypal flutterwavedev/flutterwave-v3 raziul/sslcommerz-laravel \
    mollie/laravel-mollie sabitahmad/laravel-bkash loveycom/cashfree yogeshgupta/phonepe-laravel \
    njoguamos/laravel-pesapal midtrans/midtrans-php myfatoorah/laravel-package zfhassaan/easypaisa

# 3. Re-publish the config (back up config/payments.php first if you changed it)
php artisan vendor:publish --provider="Mdiqbal\LaravelPayments\PaymentsServiceProvider" --tag=config --force

# 4. Clear cached config
php artisan config:clear

If you only want bug fixes inside the 3.x line later, composer update mdiqbal/laravel-payments is enough.

Breaking changes to check in your code:

• Credentials must be in the sandbox / live blocks of config/payments.php; missing ones now throw PaymentException instead of falling back to fake "mock" responses.
• {GATEWAY}_MODE must be sandbox or live (test/production are accepted as aliases).
• Webhooks are signature-checked. Add the new .env keys for the gateways you use: STRIPE_WEBHOOK_SECRET, PAYPAL_WEBHOOK_SECRET (the PayPal Webhook ID), RAZORPAY_WEBHOOK_SECRET, FLUTTERWAVE_SECRET_HASH, SKRILL_*_SECRET_WORD, EASYPAISA_*_ACCOUNT_NUM, PHONEPE_*_MERCHANT_ID / PHONEPE_*_SALT_KEY / PHONEPE_*_SALT_INDEX (the old PhonePe names still work).
• Use Payment::pay($gateway, $request) / Payment::verify($gateway, $payload); see the Gateway reference for the payload each gateway's verify() expects.
• Check $response->matchesAmount($order->total, $order->currency) before marking an order paid.
• Gateway-specific helpers that returned fake data (e.g. SSLCommerz createSubscription(), Flutterwave payment-link and transfer helpers) were removed.
• senangPay, PayFast, Skrill, Telr and Easypaisa report supportsRefund() === false.

Configuration

The package configuration file is located at config/payments.php. Here you can configure all supported gateways:

return [
    'default' => env('PAYMENT_DEFAULT_GATEWAY', 'stripe'),

    'gateways' => [
        'stripe' => [
            'mode' => env('STRIPE_MODE', 'sandbox'),
            'sandbox' => [
                'secret_key' => env('STRIPE_SANDBOX_SECRET'),
                'api_key' => env('STRIPE_SANDBOX_KEY'),
            ],
            'live' => [
                'secret_key' => env('STRIPE_LIVE_SECRET'),
                'api_key' => env('STRIPE_LIVE_KEY'),
            ],
            'webhook_secret' => env('STRIPE_WEBHOOK_SECRET'),
        ],

        'paypal' => [
            'mode' => env('PAYPAL_MODE', 'sandbox'),
            'sandbox' => [
                'client_id' => env('PAYPAL_SANDBOX_CLIENT_ID'),
                'client_secret' => env('PAYPAL_SANDBOX_CLIENT_SECRET'),
            ],
            'live' => [
                'client_id' => env('PAYPAL_LIVE_CLIENT_ID'),
                'client_secret' => env('PAYPAL_LIVE_CLIENT_SECRET'),
            ],
            'webhook_id' => env('PAYPAL_WEBHOOK_ID'),
        ],

        // ... other gateways
    ],
];

Basic Usage

1. Start a payment

use Mdiqbal\LaravelPayments\Facades\Payment;
use Mdiqbal\LaravelPayments\DTO\PaymentRequest;

$request = new PaymentRequest(
    amount: 1500.00,
    currency: 'BDT',
    description: 'Order #1001',
    orderId: (string) $order->id,          // your reference (tran_id / tx_ref / m_payment_id ...)
    email: $user->email,
    customer: ['name' => $user->name, 'phone' => $user->phone],
    returnUrl: route('payment.return', 'sslcommerz'),
    cancelUrl: route('payment.cancel'),
    notifyUrl: url('/payments/webhook/sslcommerz'), // IPN / webhook (package route)
);

$response = Payment::pay('sslcommerz', $request);   // throws PaymentException on failure

// Store the gateway transaction id with the order: you need it for verify()/refund()
$order->update(['gateway_txn' => $response->transactionId]);

if ($response->requiresRedirect()) {
    // Some gateways need a form POST instead of a GET redirect:
    // $response->getData('redirect_method') === 'POST' with $response->getData('form_params')
    return redirect()->away($response->redirectUrl);
}

// Stripe (client_secret) and Cashfree (payment_session_id) return data for their JS SDKs

2. Verify when the customer returns

verify() never trusts the callback data alone: it checks the gateway signature and/or re-reads the transaction from the provider's API.

public function return(Request $request, string $gateway)
{
    $result = Payment::verify($gateway, $request->all());

    // Always compare the confirmed amount with your order before fulfilling it
    if ($result->success && $result->matchesAmount($order->total, $order->currency)) {
        $order->markPaid($result->transactionId);
    }
}

3. Webhooks / IPN

The package registers POST /payments/webhook/{gateway}. Each gateway verifies its own signature header against the raw request body (configure the secrets below), then Mdiqbal\LaravelPayments\Events\WebhookHandled is dispatched:

Event::listen(WebhookHandled::class, function (WebhookHandled $event) {
    if ($event->response->success) {
        // look up the order by $event->response->transactionId and check matchesAmount()
    }
});

Exclude the route from CSRF if you use the web middleware group. Responses: 200 accepted, 400 rejected/not paid, 401 bad signature.

4. Refunds

if (Payment::supportsRefund('stripe')) {
    Payment::refund('stripe', $paymentIntentId, 50.00);   // 0 = full refund where supported
}

Gateway reference

Credentials always live in the sandbox / live block of config/payments.php; missing credentials throw a PaymentException (there are no silent mock fallbacks). Test every gateway you enable against its sandbox before going live.

Testing

Running Tests

# Run all tests
composer test

# Run specific test
composer test -- --filter StripePaymentTest

# Generate coverage report
composer test -- --coverage

Test Configuration

Set test mode in your .env.testing file:

PAYMENT_DEFAULT_GATEWAY=stripe
STRIPE_MODE=sandbox  # sandbox | live
STRIPE_SANDBOX_SECRET=sk_test_xxxxxxxxxxxxxx
STRIPE_SANDBOX_KEY=pk_test_xxxxxxxxxxxxxx

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

1. Clone the repository
2. Install dependencies: composer install
3. Run tests: composer test

License

This package is open-sourced software licensed under the MIT license.

Support

• 📧 Email: support@laravel-payments.com
• 🐛 Issues: GitHub Issues
• 📖 Documentation: Full Documentation
• 💬 Discord: Join our Discord

Security

If you discover any security related issues, please email security@laravel-payments.com instead of using the issue tracker.