README

Kashier Payment Gateway for Laravel

A Laravel package for integrating with the Kashier payment gateway in your Laravel applications.

Overview

This package provides a simple and elegant way to integrate Kashier payment processing into your Laravel applications. It handles payment requests, callbacks, and webhooks with minimal configuration.

Features

Easy integration with Kashier payment gateway
Support for multiple payment methods (cards, wallets, bank installments)
Secure payment processing with hash verification
Webhook handling for payment notifications
Response handling for payment callbacks
Event-driven architecture for custom payment processing logic

Installation

You can install the package via composer:

composer require asciisd/kashier

Configuration

Publish the configuration file:

php artisan vendor:publish --provider="Asciisd\\Kashier\\Providers\\KashierServiceProvider" --tag="config"

Then, set your Kashier credentials in your .env file:

KASHIER_MID=your-merchant-id
KASHIER_API_KEY=your-api-key
KASHIER_SECRET_KEY=your-secret-key
KASHIER_MODE=test # or live
KASHIER_CURRENCY=EGP # or any other supported currency
KASHIER_CALLBACK_URL=https://your-website.com/payment-complete # optional custom redirect URL

Usage

Basic Payment Processing

use Asciisd\Kashier\Facades\Kashier;

// Generate a payment URL
$paymentUrl = Kashier::buildPaymentUrl(
    amount: 100, // Amount in the smallest currency unit (e.g., piasters for EGP)
    orderId: 'order-123', // Your unique order ID
    attributes: [
        'customerName' => 'John Doe',
        'customerEmail' => 'john@example.com',
        'customerMobile' => '01234567890',
        // Additional attributes as needed
    ]
);

// Redirect the user to the payment URL
return redirect()->away($paymentUrl);

Customizing Payment Methods

use Asciisd\Kashier\Facades\Kashier;

// Allow only specific payment methods
$paymentUrl = Kashier::setAllowedMethods('card,wallet')
    ->buildPaymentUrl(100, 'order-123');

Handling Payment Responses

The package automatically handles payment responses at the /kashier/response endpoint. You can listen for the KashierResponseHandled event to process successful payments:

use Asciisd\Kashier\Events\KashierResponseHandled;
use Illuminate\Support\Facades\Event;

Event::listen(function (KashierResponseHandled $event) {
    $paymentData = $event->payload;
    
    // Process the payment data
    // $paymentData['paymentStatus'] contains the payment status
    // $paymentData['merchantOrderId'] contains your order ID
    // ...
});

Custom Redirect After Payment

By default, users are shown a receipt page after completing payment. If you prefer to redirect users to your own custom page, you can set the KASHIER_CALLBACK_URL in your .env file:

KASHIER_CALLBACK_URL=https://your-website.com/payment-complete

When this is configured, users will be redirected to your custom URL after payment processing, with all payment data included as query parameters. This allows you to create a completely custom post-payment experience.

Handling Webhooks

Kashier will send webhook notifications to the /kashier/webhook endpoint. You can listen for the KashierWebhookHandled event to process these notifications:

use Asciisd\Kashier\Events\KashierWebhookHandled;
use Illuminate\Support\Facades\Event;

Event::listen(function (KashierWebhookHandled $event) {
    $webhookData = $event->payload;
    
    // Process the webhook data
    // Update order status, send notifications, etc.
});

Retrieving Transaction Details

use Asciisd\Kashier\Facades\Kashier;

try {
    $transactionDetails = Kashier::getTransactionDetails('order-123');
    
    // Process transaction details
    // $transactionDetails['paymentStatus'] contains the payment status
    // ...
} catch (Exception $e) {
    // Handle error
}

Security

The package automatically verifies the signature of incoming webhook and response requests to ensure they are legitimate and have not been tampered with.

Events

KashierResponseHandled: Dispatched when a payment response is received
KashierWebhookHandled: Dispatched when a webhook notification is received

License

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

asciisd / kashier

Maintainers

Details