README

A comprehensive Laravel package for integrating Nepali payment gateways (eSewa, Khalti, and ConnectIps) with optional database tracking and payment management.

Features

✅ Multiple Gateway Support

eSewa integration
Khalti integration
ConnectIps integration

✅ Database Integration (Optional)

Track payment history
Store gateway responses
Polymorphic payment associations
UUID support

✅ Event System

Payment lifecycle events
Custom event listeners

✅ Query Scopes & Helpers

Easy payment retrieval
Status filtering
Gateway filtering

Installation

Install the package via Composer:

composer require jaap-tech/laravel-nepali-payment

The package will auto-register the service provider.

Configuration

Publish the configuration file:

php artisan vendor:publish --tag=nepali-payment-config

This creates config/nepali-payment.php with the following structure:

return [
    'esewa' => [
        'product_code' => env('ESEWA_PRODUCT_CODE'),
        'secret_key'   => env('ESEWA_SECRET_KEY'),
        'success_url'   => env('ESEWA_SUCCESS_URL'),
        'failure_url'   => env('ESEWA_FAILURE_URL'),
    ],
    'khalti' => [
        'secret_key' => env('KHALTI_SECRET_KEY'),
        'environment' => strtolower(env('KHALTI_ENVIRONMENT', 'test')),
        'success_url'   => env('KHALTI_SUCCESS_URL'),
        'website_url'   => env('KHALTI_WEBSITE_URL'),
    ],
    'connectips' => [
        'merchant_id' => env('CONNECTIPS_MERCHANT_ID'),
        'app_id' => env('CONNECTIPS_APP_ID'),
        'app_name' => env('CONNECTIPS_APP_NAME'),
        'private_key_path' => env('CONNECTIPS_PRIVATE_KEY_PATH'),
        'password' => env('CONNECTIPS_PASSWORD'),
        'environment' => strtolower(env('CONNECTIPS_ENVIRONMENT', 'test')),
    ],
    'database' => [
        'enabled' => env('NEPALI_PAYMENT_DATABASE_ENABLED', false),
    ],
];

Environment Variables

Add these to your .env file:

eSewa:

ESEWA_PRODUCT_CODE=your_product_code
ESEWA_SECRET_KEY=your_secret_key
ESEWA_SUCCESS_URL=https://yourapp.com/payment/success # (optional)
ESEWA_FAILURE_URL=https://yourapp.com/payment/failure # (optional)

Khalti:

KHALTI_SECRET_KEY=your_secret_key
KHALTI_ENVIRONMENT=test  # or 'live'
KHALTI_SUCCESS_URL=https://yourapp.com/payment/success # (optional)
KHALTI_WEBSITE_URL=https://yourapp.com # (optional)

ConnectIps:

CONNECTIPS_MERCHANT_ID=your_merchant_id
CONNECTIPS_APP_ID=your_app_id
CONNECTIPS_APP_NAME=your_app_name
CONNECTIPS_PRIVATE_KEY_PATH=/path/to/private/key
CONNECTIPS_PASSWORD=your_password
CONNECTIPS_ENVIRONMENT=test  # or 'live'

Database Integration:

NEPALI_PAYMENT_DATABASE_ENABLED=true

Quick Start

Basic Payment Flow (Without Database)

use NepaliPayment;

// Initiate eSewa payment
$response = NepaliPayment::esewa()->payment([
    'amount' => 1000,
    'transaction_uuid' => 'unique-id-123', # optional, can be generated automatically
    'success_url' => route('payment.success'), # optional, can be set in config
    'failure_url' => route('payment.failure'), # optional, can be set in config
]);

// Redirect to payment gateway
$response->redirect();

With Database Integration

First, enable the database integration:

# 1. Publish migrations
php artisan vendor:publish --tag=nepali-payment-migrations

# 2. Run migrations
php artisan migrate

# 3. Enable in .env
NEPALI_PAYMENT_DATABASE_ENABLED=true

Now you can track payments:

use NepaliPayment;

// Initiate payment with gateway
$response = NepaliPayment::esewa()->payment([
    'amount' => 1000,
    'transaction_uuid' => 'unique-id-123', # optional, can be generated automatically
    'success_url' => route('payment.success'), # optional, can be set in config
    'failure_url' => route('payment.failure'), # optional, can be set in config
]);

// Record verification
$verification = NepaliPayment::esewa()->verify([
    'total_amount' => 1000,
    'transaction_uuid' => 'same-unique-id-123',
]);

Database Models

Payment Model

The Payment model stores all payment records with full lifecycle tracking.

Scopes:

// Find payment by reference ID
PaymentTransaction::byReference('ref-123')->first();

// Filter by gateway
PaymentTransaction::byGateway('esewa')->get();

// Filter by status
PaymentTransaction::byStatus('completed')->get();

// Completed payments only
PaymentTransaction::completed()->get();

// Failed payments only
PaymentTransaction::failed()->get();

// Pending/processing payments
PaymentTransaction::pending()->get();

// Filter by payable type and ID
PaymentTransaction::forPayable('App\Models\User', $userId)->get();

Methods:

$payment = Payment::find($id);

// Check status
$payment->isCompleted();
$payment->isFailed();
$payment->isPending();

// Update status
$payment->markAsProcessing();
$payment->markAsCompleted();
$payment->markAsFailed('Reason for failure');
$payment->markAsCancelled();

// Relationships
$payment->payable;        // The associated model (User, Order, etc)

Helper Functions

Quick helpers for common operations:

// Check if database is enabled
nepali_payment_enabled();

// Find payments
nepali_payment_find('ref-123');                    // by reference

// Query payments
nepali_payment_get_by_status('completed')->paginate();
nepali_payment_get_by_gateway('khalti')->latest()->get();

Events

The package dispatches events at key lifecycle points:

use JaapTech\NepaliPayment\Events\{
    PaymentInitiatedEvent,
    PaymentProcessingEvent,
    PaymentCompletedEvent,
    PaymentFailedEvent,
};

// Listen to events in EventServiceProvider
protected $listen = [
    PaymentCompletedEvent::class => [
        \App\Listeners\SendPaymentConfirmation::class,
        \App\Listeners\UpdateUserBalance::class,
    ],
    PaymentFailedEvent::class => [
        \App\Listeners\NotifyPaymentFailure::class,
    ],
];

// Or listen inline
Event::listen(PaymentCompletedEvent::class, function ($event) {
    // $event->payment
});

Verify Configuration

Check if all gateway configurations are valid:

php artisan nepali-payment:check

Output example:

Checking Nepali Payment Gateway Configuration:
- esewa: ✅ configured
- khalti: ✅ configured
- connectips: ⚠️  missing keys: environment

Example: Complete Payment Flow

// PaymentController.php
<?php

namespace App\Http\Controllers;

use App\Models\Order;
use NepaliPayment;
use JaapTech\NepaliPayment\Models\PaymentTransaction;

class PaymentController extends Controller
{
    public function create(Order $order)
    {
        // Initiate payment with gateway
        $response = NepaliPayment::esewa()->payment([
            'amount' => $order->total,
            'transaction_uuid' => $payment->reference_id,
            'success_url' => route('payment.verify', $payment->id),
            'failure_url' => route('payment.failed', $payment->id),
        ]);

        return $response->redirect();
    }

    public function verify(PaymentTransaction $payment)
    {
        // Get gateway response
        $verification = NepaliPayment::esewa()->verify([
            'total_amount' => $payment->amount,
            'transaction_uuid' => $payment->reference_id,
        ]);

        if ($verification->isSuccess()) {
            NepaliPayment::completePayment(
                $payment,
                gatewayTransactionId: $payment->reference_id,
                responseData: $verification->toArray()
            );

            return redirect()->route('order.show', $payment->payable)
                ->with('success', 'Payment completed successfully!');
        } else {
            NepaliPayment::failPayment($payment, 'Gateway verification failed');

            return redirect()->route('payment.create', $payment->payable)
                ->with('error', 'Payment verification failed');
        }
    }

    public function failed(PaymentTransaction $payment)
    {
        NepaliPayment::failPayment($payment, 'User cancelled payment');
        
        return redirect()->route('payment.create', $payment->payable)
            ->with('error', 'Payment was cancelled');
    }
}

Troubleshooting

"Database integration is not enabled" error

Make sure NEPALI_PAYMENT_DATABASE_ENABLED=true in .env
Run migrations: php artisan migrate

"Missing config for nepali-payment" error

Check all required environment variables are set in .env
Run: php artisan nepali-payment:check

Payment not being saved to database

Verify database is enabled in config
Check database connection is working
Ensure migrations have been run

License

This package is licensed under the MIT License. See the LICENSE file for details.

Support

For issues, questions, or contributions, visit the GitHub repository.

jaap-tech / laravel-nepali-payment

Maintainers

Package info

Statistics

Security