Payment Manager

• Features
• Supported Payment Gateways
• Installation
  • Step 1: Install via Composer
  • Step 2: Publish Configuration & Migrations
  • Step 3: Run Migrations
  • Step 4: Register Plugin
• Configuration
  • Environment Variables
  • Config File
• Usage
  • Creating a Payment Gateway
  • Using in Your Application
    • Basic Payment Flow
    • Verify Payment (in callback)
    • Get Available Gateways
  • Custom Redirect Forms
    • 1. Use Package Default (Recommended)
    • 2. Custom Blade View
    • 3. Custom HTML Template
• Gateway Configuration Examples
  • Zarinpal
  • Saman Bank
  • PayPal
  • Stripe
• Advanced Usage
  • Manual Gateway Loading
  • Custom Redirect Form Service
• API Reference
  • PaymentManagerService Methods
  • PaymentGateway Model
• Testing
  • Using Local Gateway
  • Sandbox Mode
• Troubleshooting
  • Gateway not working
  • Callback URL issues
  • Currency issues
• Contributing
• License
• Credits
• Support

A comprehensive Filament 4 plugin to manage Shetabit Payment gateways with a beautiful admin interface.

#Features

• ✅ Filament 4 Compatible - Built specifically for Filament 4
• 🎨 Beautiful UI - Modern, intuitive interface for managing payment gateways
• 🔌 Multiple Gateways - Support for 30+ payment providers
• ⚙️ Dynamic Configuration - Configure each gateway independently
• 🎯 Default Gateway - Set a default payment gateway
• 🔄 Custom Redirect Forms - Use custom views or HTML templates
• 📊 Gateway Management - Enable/disable, sort, and organize gateways
• 🔐 Secure - Built on top of trusted Shetabit Payment package

#Supported Payment Gateways

• Zarinpal, Saman, PayPal, Stripe
• Parsian, Sadad, Zibal, PayPing
• Behpardakht (Mellat), Pasargad, IranKish
• And 20+ more Iranian and international gateways

#Installation

#Step 1: Install via Composer

composer require amidesfahani/filament-payment-manager

#Step 2: Publish Configuration & Migrations

php artisan vendor:publish --tag="filament-payment-manager-config"
php artisan vendor:publish --tag="filament-payment-manager-migrations"
php artisan vendor:publish --tag="filament-payment-manager-views"

#Step 3: Run Migrations

php artisan migrate

#Step 4: Register Plugin

Add the plugin to your Filament panel in app/Providers/Filament/AdminPanelProvider.php:

use YourVendor\FilamentPaymentManager\FilamentPaymentManagerPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->plugins([
            FilamentPaymentManagerPlugin::make(),
        ]);
}

#Configuration

#Environment Variables

Add these to your .env file:

PAYMENT_CALLBACK_URL=https://yourdomain.com/payment/callback
PAYMENT_DEFAULT_CURRENCY=T
PAYMENT_AUTO_LOAD_GATEWAYS=true
PAYMENT_ENABLE_LOGGING=false

#Config File

The config file config/filament-payment-manager.php allows you to customize:

• Default callback URL
• Auto-loading gateways
• Default currency (T=Toman, R=Rial)
• Driver default configurations
• Logging settings

#Usage

#Creating a Payment Gateway

1. Navigate to Settings > Payment Gateways in your Filament panel
2. Click Create
3. Fill in the required fields:
   • Name: Display name for the gateway
   • Driver: Select payment provider
   • Configuration: Add required credentials (merchantId, password, etc.)
   • Callback URL: Optional custom callback URL
   • Active: Enable/disable the gateway
   • Default: Set as default gateway

#Using in Your Application

#Basic Payment Flow

use YourVendor\FilamentPaymentManager\Services\PaymentManagerService;
use Shetabit\Multipay\Invoice;

// Get the service
$paymentManager = app(PaymentManagerService::class);

// Create an invoice
$invoice = new Invoice();
$invoice->amount(10000); // Amount in Toman or Rial

// Create payment (uses default gateway)
$payment = $paymentManager->createPayment($invoice->getAmount());

// Or specify a gateway
$payment = $paymentManager->createPayment($invoice->getAmount(), 'zarinpal');

// Purchase and get transaction ID
try {
    $transactionId = $payment->purchase($invoice, function($driver, $transactionId) {
        // Store transaction ID in your database
    })->pay()->render();
    
} catch (\Exception $e) {
    // Handle error
}

#Verify Payment (in callback)

use YourVendor\FilamentPaymentManager\Services\PaymentManagerService;
use Shetabit\Payment\Facade\Payment;

public function callback(Request $request)
{
    $paymentManager = app(PaymentManagerService::class);
    
    try {
        $receipt = $paymentManager->verifyPayment();
        
        // Payment successful
        $referenceId = $receipt->getReferenceId();
        
        // Update your order status
        
        return redirect()->route('payment.success');
        
    } catch (\Exception $e) {
        // Payment failed
        return redirect()->route('payment.failed');
    }
}

#Get Available Gateways

$paymentManager = app(PaymentManagerService::class);

// Get all active gateways
$gateways = $paymentManager->getActiveGateways();

// Get default gateway
$defaultGateway = $paymentManager->getDefaultGateway();

// Get specific gateway by driver
$gateway = $paymentManager->getGatewayByDriver('zarinpal');

#Custom Redirect Forms

You have three options for redirect forms:

#1. Use Package Default (Recommended)

Beautiful, modern redirect form with countdown timer and animations.

#2. Custom Blade View

Create your own Blade view:

{{-- resources/views/payments/custom-redirect.blade.php --}}
<!DOCTYPE html>
<html>
<head>
    <title>Payment Redirect</title>
</head>
<body>
    <h1>Redirecting to payment...</h1>
    <form method="{{ $method }}" action="{{ $action }}" id="payment-form">
        @foreach($inputs as $name => $value)
            <input type="hidden" name="{{ $name }}" value="{{ $value }}">
        @endforeach
        <button type="submit">Continue</button>
    </form>
    <script>
        document.getElementById('payment-form').submit();
    </script>
</body>
</html>

Then set in gateway: payments.custom-redirect

#3. Custom HTML Template

Use placeholders in your HTML:

<form method="{method}" action="{action}">
    {inputs}
    <button>Pay Now</button>
</form>
<script>document.forms[0].submit();</script>

#Gateway Configuration Examples

#Zarinpal

[
    'merchantId' => 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
    'callbackUrl' => 'https://yourdomain.com/payment/callback',
    'description' => 'Payment for Order #123',
    'currency' => 'T', // T=Toman, R=Rial
    'mode' => 'normal', // normal, sandbox, zaringate
]

#Saman Bank

[
    'merchantId' => 'your-merchant-id',
    'password' => 'your-password',
    'callbackUrl' => 'https://yourdomain.com/payment/callback',
    'currency' => 'T',
]

#PayPal

[
    'clientId' => 'your-client-id',
    'clientSecret' => 'your-client-secret',
    'callbackUrl' => 'https://yourdomain.com/payment/callback',
    'currency' => 'USD',
    'mode' => 'normal', // normal or sandbox
]

#Stripe

[
    'secret' => 'sk_test_xxxxxxxxxxxxx',
    'currency' => 'usd',
    'success_url' => 'https://yourdomain.com/payment/success',
    'cancel_url' => 'https://yourdomain.com/payment/cancel',
]

#Advanced Usage

#Manual Gateway Loading

If you disable auto-loading in config:

use YourVendor\FilamentPaymentManager\Services\PaymentManagerService;
use YourVendor\FilamentPaymentManager\Models\PaymentGateway;

$paymentManager = app(PaymentManagerService::class);

// Load specific gateway
$gateway = PaymentGateway::where('driver', 'zarinpal')->first();
$paymentManager->registerGateway($gateway);

#Custom Redirect Form Service

use YourVendor\FilamentPaymentManager\Models\PaymentGateway;
use YourVendor\FilamentPaymentManager\Services\PaymentManagerService;

$gateway = PaymentGateway::find(1);
$paymentManager = app(PaymentManagerService::class);

$html = $paymentManager->getRedirectForm(
    $gateway,
    'https://payment.gateway.com/pay',
    'POST',
    ['token' => 'abc123', 'amount' => 10000]
);

return response($html);

#API Reference

#PaymentManagerService Methods

#PaymentGateway Model

#Testing

#Using Local Gateway

The package includes a local test gateway:

// In Filament, create a gateway with driver 'local'
// This allows you to test payment flow without real credentials

#Sandbox Mode

Many gateways support sandbox mode:

// Zarinpal
'mode' => 'sandbox'

// PayPal
'mode' => 'sandbox'

#Troubleshooting

#Gateway not working

1. Check if gateway is active in admin panel
2. Verify all required configuration fields are filled
3. Ensure callback URL is accessible
4. Check logs if logging is enabled

#Callback URL issues

Make sure your callback URL:

• Is publicly accessible (not localhost in production)
• Matches exactly what you configured in the gateway
• Uses HTTPS in production

#Currency issues

Iranian gateways typically require amounts in Rial, but you can use Toman by setting currency => 'T' in config. The package handles conversion automatically.

#Contributing

Contributions are welcome! Please submit pull requests or issues on GitHub.

#License

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

#Credits

• Built on Shetabit Payment
• Designed for Filament PHP

#Support

For issues and questions:

• GitHub Issues: [amidesfahani/filament-payment-manager]