### Gateway Configuration Examples

Source: https://github.com/amidesfahani/filament-payment-manager/blob/v4/README.md

Examples of how to configure various payment gateways.

```APIDOC
## Gateway Configuration Examples

Examples of how to configure various payment gateways.

### Zarinpal

```php
[
    '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

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

### PayPal

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

### Stripe

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

--------------------------------

### Saman Bank Gateway Configuration Example

Source: https://github.com/amidesfahani/filament-payment-manager/blob/v4/README.md

Shows an example configuration for the Saman Bank payment gateway. Key settings include the merchant ID, password, callback URL, and currency. This setup is necessary for integrating with Saman Bank's payment processing services.

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

--------------------------------

### Stripe Gateway Configuration Example

Source: https://github.com/amidesfahani/filament-payment-manager/blob/v4/README.md

Provides an example configuration for the Stripe payment gateway. Essential details include the secret API key, currency, and URLs for success and cancellation redirects after payment processing. This setup enables Stripe as a payment method.

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

--------------------------------

### Install Filament Payment Manager Package

Source: https://context7.com/amidesfahani/filament-payment-manager/llms.txt

Commands to install the Filament Payment Manager package via Composer, publish its configuration, migrations, and views, and run the database migrations.

```bash
composer require amidesfahani/filament-payment-manager

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"

php artisan migrate
```

--------------------------------

### Create Multiple Payment Gateways via Admin Panel

Source: https://context7.com/amidesfahani/filament-payment-manager/llms.txt

Examples of creating multiple payment gateways, including PayPal and Stripe, through the Filament Admin Panel. Demonstrates setting different configurations and parameters for each gateway.

```php
// Example: Creating a PayPal gateway for international payments

/*
Name: PayPal International
Driver: paypal
Currency: USD
Is Active: Yes
Is Default: No
Sort Order: 10

Configuration:
clientId = your-paypal-client-id
clientSecret = your-paypal-client-secret
mode = sandbox

Callback URL: https://yourdomain.com/payment/paypal/callback
*/

// Example: Creating a Stripe gateway

/*
Name: Stripe Payments
Driver: stripe
Currency: usd
Is Active: Yes
Is Default: No
Sort Order: 20

Configuration:
secret = sk_test_xxxxxxxxxxxxx
success_url = https://yourdomain.com/payment/success
cancel_url = https://yourdomain.com/payment/cancel
*/
```

--------------------------------

### Complete Payment Controller Example - PHP

Source: https://context7.com/amidesfahani/filament-payment-manager/llms.txt

This PHP controller demonstrates how to initiate a payment using the PaymentManagerService and handle the verification callback. It integrates with Order and Transaction models and utilizes the Shetabit Multipay Invoice for payment details. Error handling and logging are included for robustness.

```php
// app/Http/Controllers/PaymentController.php
namespace App\Http\Controllers;

use App\Models\Order;
use App\Models\Transaction;
use Illuminate\Http\Request;
use AmidEsfahani\FilamentPaymentManager\Services\PaymentManagerService;
use Shetabit\Multipay\Invoice;

class PaymentController extends Controller
{
    public function initiate(Request $request, $orderId)
    {
        $order = Order::findOrFail($orderId);

        if ($order->isPaid()) {
            return redirect()->route('orders.show', $order->id)
                ->with('info', 'Order is already paid.');
        }

        $paymentManager = app(PaymentManagerService::class);

        $invoice = new Invoice();
        $invoice->amount($order->total_amount);
        $invoice->detail([
            'order_id' => $order->id,
            'customer_name' => $order->customer_name,
            'customer_email' => $order->customer_email,
        ]);

        try {
            $driver = $request->input('gateway', null); // Use default if not specified
            $payment = $paymentManager->createPayment($invoice->getAmount(), $driver);

            $transactionId = $payment->purchase($invoice, function($driver, $transactionId) use ($order) {
                Transaction::create([
                    'order_id' => $order->id,
                    'transaction_id' => $transactionId,
                    'driver' => $driver,
                    'amount' => $order->total_amount,
                    'status' => 'pending',
                ]);
            })->pay()->render();

        } catch (Exception $e) {
            \Log::error('Payment initiation failed', [
                'order_id' => $order->id,
                'error' => $e->getMessage(),
            ]);

            return redirect()->back()->with('error', 'Unable to process payment. Please contact support.');
        }
    }

    public function callback(Request $request)
    {
        $paymentManager = app(PaymentManagerService::class);

        try {
            $receipt = $paymentManager->verifyPayment();
            $referenceId = $receipt->getReferenceId();
            $driver = $receipt->getDriver();

            // Find transaction
            $transaction = Transaction::where('transaction_id', $request->input('Authority'))
                ->orWhere('transaction_id', $request->input('token'))
                ->firstOrFail();

            // Update transaction
            $transaction->update([
                'status' => 'completed',
                'reference_id' => $referenceId,
                'verified_at' => now(),
            ]);

            // Update order
            $order = $transaction->order;
            $order->update([
                'payment_status' => 'paid',
                'paid_at' => now(),
            ]);

            return redirect()->route('orders.success', $order->id)
                ->with('success', "Payment successful! Reference ID: {$referenceId}");

        } catch (Shetabit\Multipay\Exceptions\InvalidPaymentException $e) {
            \Log::error('Payment verification failed', [
                'error' => $e->getMessage(),
                'request' => $request->all(),
            ]);

            return redirect()->route('orders.failed')
                ->with('error', 'Payment verification failed. Please contact support if amount was deducted.');

        } catch (Exception $e) {
            \Log::error('Callback processing error', [
                'error' => $e->getMessage(),
            ]);

            return redirect()->route('orders.failed')
                ->with('error', 'An error occurred while processing your payment.');
        }
    }
}

```

--------------------------------

### Custom HTML Template Example

Source: https://github.com/amidesfahani/filament-payment-manager/blob/v4/README.md

Example of using a custom HTML template with placeholders for payment redirection.

```APIDOC
## Custom HTML Template

Use placeholders in your HTML:

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

--------------------------------

### Zarinpal Gateway Configuration Example

Source: https://github.com/amidesfahani/filament-payment-manager/blob/v4/README.md

Example configuration array for the Zarinpal payment gateway. Includes essential parameters such as merchant ID, callback URL, a description for the transaction, currency setting (Toman or Rial), and the operational mode (normal, sandbox, or zaringate).

```php
[
    '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
]
```

--------------------------------

### Create Zarinpal Gateway via Admin Panel

Source: https://context7.com/amidesfahani/filament-payment-manager/llms.txt

Instructions and example configuration for creating a Zarinpal payment gateway through the Filament Admin Panel. This includes setting the name, driver, currency, status, sort order, and specific Zarinpal configuration keys.

```php
// Navigate to Settings > Payment Gateways in Filament Admin Panel
// Click "Create" button and fill in the form:

/*
Name: Zarinpal Production
Driver: zarinpal (selected from dropdown)
Currency: T (Toman)
Is Active: Yes
Is Default: Yes
Sort Order: 0

Configuration (Key-Value pairs):
merchantId = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
mode = normal
description = Payment for order

Callback URL: https://yourdomain.com/payment/zarinpal/callback

Redirect Form Mode: default (use package's beautiful redirect form)

Description: Primary payment gateway for Iranian customers
*/

// After clicking "Save", the gateway is immediately available for use
// The PaymentManagerService automatically loads active gateways on instantiation
```

--------------------------------

### PayPal Gateway Configuration Example

Source: https://github.com/amidesfahani/filament-payment-manager/blob/v4/README.md

Illustrates the configuration parameters for integrating with PayPal. This includes client ID, client secret, callback URL, currency, and the operating mode (normal or sandbox). These settings are crucial for authenticating and processing payments through PayPal.

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

--------------------------------

### Custom Blade View Example

Source: https://github.com/amidesfahani/filament-payment-manager/blob/v4/README.md

Example of creating and using a custom Blade view for payment redirection.

```APIDOC
## Custom Blade View

Create your own Blade view:

```blade
{{-- 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`
```

--------------------------------

### Manual Gateway Loading Example

Source: https://github.com/amidesfahani/filament-payment-manager/blob/v4/README.md

Demonstrates how to manually load and register a payment gateway using the `PaymentManagerService` when auto-loading is disabled. It shows fetching a `PaymentGateway` model and then explicitly registering it with the service, allowing for programmatic control over gateway activation.

```php
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);
```

--------------------------------

### Manual Gateway Loading

Source: https://github.com/amidesfahani/filament-payment-manager/blob/v4/README.md

Example demonstrating how to manually load a payment gateway if auto-loading is disabled.

```APIDOC
## Manual Gateway Loading

If you disable auto-loading in config:

```php
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);
```
```

--------------------------------

### Install Filament Payment Manager

Source: https://github.com/amidesfahani/filament-payment-manager/blob/v4/README.md

Installs the Filament Payment Manager package using Composer. This is the first step to integrate payment gateway management into your Filament application.

```bash
composer require amidesfahani/filament-payment-manager
```

--------------------------------

### Sandbox Mode Configuration for Gateways

Source: https://github.com/amidesfahani/filament-payment-manager/blob/v4/README.md

Demonstrates how to enable sandbox mode for testing payment integrations without using real money. Examples are provided for Zarinpal and PayPal, showing the configuration key (`mode`) and its value (`sandbox`) to switch to test environments.

```php
// Zarinpal
'mode' => 'sandbox'

// PayPal
'mode' => 'sandbox'
```

--------------------------------

### Custom Redirect Form Service Example

Source: https://github.com/amidesfahani/filament-payment-manager/blob/v4/README.md

Example of using the `getRedirectForm` method to generate a custom redirect form.

```APIDOC
## Custom Redirect Form Service

```php
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);
```
```

--------------------------------

### Publish Configuration and Migrations

Source: https://github.com/amidesfahani/filament-payment-manager/blob/v4/README.md

Publishes the package's configuration files, migration files, and view files to your Laravel project. This allows for customization and database schema setup.

```bash
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"
```

--------------------------------

### Get Available Payment Gateways

Source: https://github.com/amidesfahani/filament-payment-manager/blob/v4/README.md

Retrieves information about configured payment gateways using the `PaymentManagerService`. This includes fetching all active gateways, the default gateway, or a specific gateway by its driver.

```php
$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');
```

--------------------------------

### Register Gateway with Runtime Configuration Override

Source: https://context7.com/amidesfahani/filament-payment-manager/llms.txt

This snippet demonstrates how to register a payment gateway with runtime configuration overrides. It shows how to fetch a gateway, get its configuration merged with defaults, modify specific configuration parameters like 'callbackUrl' or 'mode', and then either set these directly in Laravel's config or use the `registerGateway` method which handles this process internally. This is useful for dynamic configuration adjustments.

```php
use AmidEsfahani\FilamentPaymentManager\Models\PaymentGateway;
use Illuminate\Support\Facades\Config;

// Get gateway
$gateway = PaymentGateway::where('driver', 'zarinpal')->first();

// Get config with defaults merged
$config = $gateway->getConfigWithDefaults();

// Override specific config at runtime
$config['callbackUrl'] = 'https://special-callback.com/payment';
$config['mode'] = 'sandbox';

// Set directly to Laravel config
Config::set("payment.drivers.{$gateway->driver}", $config);

// Or use registerGateway method which does the same
$paymentManager = app(PaymentManagerService::class);
$paymentManager->registerGateway($gateway);

```

--------------------------------

### Get All Available Payment Drivers (PHP)

Source: https://context7.com/amidesfahani/filament-payment-manager/llms.txt

Retrieves a list of all available payment drivers supported by the Shetabit Multipay package. The function returns an associative array where keys are the driver identifiers and values are their display names. This can be used to dynamically populate lists or select options for payment methods.

```php
use AmidEsfahani\FilamentPaymentManager\Services\DriverService;

// Get all available payment drivers from Shetabit Multipay
$drivers = DriverService::getAvailableDrivers();

// Returns array: ['driver_name' => 'Display Name']
// Example output:
// [
//     'zarinpal' => 'Zarinpal',
//     'saman' => 'Saman',
//     'paypal' => 'Paypal',
//     'stripe' => 'Stripe',
//     'parsian' => 'Parsian',
//     'sadad' => 'Sadad',
//     'mellat' => 'Mellat',
//     'pasargad' => 'Pasargad',
//     'irankish' => 'Irankish',
//     'zibal' => 'Zibal',
//     'payping' => 'Payping',
//     // ... and more
// ]

foreach ($drivers as $key => $name) {
    echo "{$key}: {$name}\n";
}
```

--------------------------------

### Custom Redirect Form Service Example

Source: https://github.com/amidesfahani/filament-payment-manager/blob/v4/README.md

Illustrates the usage of the `getRedirectForm` method from the `PaymentManagerService` to generate a custom HTML redirect form. This method takes gateway details, target action URL, HTTP method, and input parameters to construct the form dynamically, returning the HTML response.

```php
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);
```

--------------------------------

### Get Default Configuration for a Specific Payment Driver (PHP)

Source: https://context7.com/amidesfahani/filament-payment-manager/llms.txt

Fetches the default configuration values for a given payment driver from the package's configuration file. This is useful for understanding the required settings for each driver, such as merchant IDs, callback URLs, or API modes. It returns an array of default settings or an empty array if the driver is not found.

```php
use AmidEsfahani\FilamentPaymentManager\Services\DriverService;

// Get default configuration for a specific driver
$zarinpalDefaults = DriverService::getDriverDefaultConfig('zarinpal');

// Returns array from Shetabit's payment.php config file
// Example output for zarinpal:
// [
//     'merchantId' => '',
//     'callbackUrl' => 'http://yoursite.com/path/to',
//     'mode' => 'normal', // normal, sandbox, zaringate
//     'description' => 'payment in '.config('app.name'),
// ]

$paypalDefaults = DriverService::getDriverDefaultConfig('paypal');
// [
//     'clientId' => '',
//     'clientSecret' => '',
//     'mode' => 'normal', // normal, sandbox
//     'currency' => 'USD',
// ]

// Returns empty array if driver not found
$unknown = DriverService::getDriverDefaultConfig('nonexistent');
// []
```

--------------------------------

### Get All Available Currency Codes (PHP)

Source: https://context7.com/amidesfahani/filament-payment-manager/llms.txt

Retrieves a comprehensive list of all available ISO currency codes. This function utilizes the moneyphp/money library to provide a standardized set of currency identifiers. The returned array is alphabetically sorted and can be used to populate currency selection fields in forms.

```php
use AmidEsfahani\FilamentPaymentManager\Services\DriverService;

// Get all ISO currency codes
$currencies = DriverService::currencies();

// Returns array of ISO currency codes from moneyphp/money library
// Format: ['USD' => 'USD', 'EUR' => 'EUR', ...]
// Alphabetically sorted

// Example usage in a form select:
$currencyOptions = DriverService::currencies();
// [
//     'AED' => 'AED',
//     'AFN' => 'AFN',
//     'ALL' => 'ALL',
//     // ...
//     'USD' => 'USD',
//     'EUR' => 'EUR',
//     'GBP' => 'GBP',
//     // ... 150+ currencies
// ]
```

--------------------------------

### Get All Active Payment Gateways - PHP

Source: https://context7.com/amidesfahani/filament-payment-manager/llms.txt

Retrieves a list of all currently active payment gateways configured in the system. The output includes details like name, driver, currency, and default status for each gateway. This function is useful for displaying available payment options to users. Dependencies include `PaymentManagerService`.

```php
use AmidEsfahani\FilamentPaymentManager\Services\PaymentManagerService;

// Get all active gateways
$paymentManager = app(PaymentManagerService::class);
$gateways = $paymentManager->getActiveGateways();

// Display gateways in checkout page
foreach ($gateways as $gateway) {
    echo "Name: {$gateway->name}\n";
    echo "Driver: {$gateway->driver}\n";
    echo "Currency: {$gateway->currency}\n";
    echo "Is Default: " . ($gateway->is_default ? 'Yes' : 'No') . "\n";
    echo "---\n";
}

// Example output:
// Name: Zarinpal Production
// Driver: zarinpal
// Currency: T
// Is Default: Yes
// ---
// Name: PayPal International
// Driver: paypal
// Currency: USD
// Is Default: No
```

--------------------------------

### Get Default Payment Gateway - PHP

Source: https://context7.com/amidesfahani/filament-payment-manager/llms.txt

Fetches the currently configured default payment gateway. If a default gateway is set, it outputs its name and driver; otherwise, it indicates that no default gateway is configured. This is useful for simplifying payment processing by always using the preferred gateway. Dependencies include `PaymentManagerService`.

```php
use AmidEsfahani\FilamentPaymentManager\Services\PaymentManagerService;

// Get the default payment gateway
$paymentManager = app(PaymentManagerService::class);
$defaultGateway = $paymentManager->getDefaultGateway();

if ($defaultGateway) {
    echo "Default Gateway: {$defaultGateway->name}";
    echo "Driver: {$defaultGateway->driver}";
} else {
    echo "No default gateway configured";
}
```

--------------------------------

### Get Payment Gateway by Driver Name - PHP

Source: https://context7.com/amidesfahani/filament-payment-manager/llms.txt

Retrieves a specific payment gateway configuration using its driver name (e.g., 'zarinpal'). If found and active, it displays the gateway's name, callback URL, configuration details, and active status. This is useful for accessing the settings of a particular payment provider. Dependencies include `PaymentManagerService`.

```php
use AmidEsfahani\FilamentPaymentManager\Services\PaymentManagerService;

// Get specific gateway by driver name
$paymentManager = app(PaymentManagerService::class);
$gateway = $paymentManager->getGatewayByDriver('zarinpal');

if ($gateway) {
    echo "Gateway Name: {$gateway->name}\n";
    echo "Callback URL: {$gateway->callback_url}\n";
    echo "Configuration: " . json_encode($gateway->config) . "\n";
    echo "Active: " . ($gateway->is_active ? 'Yes' : 'No') . "\n";
} else {
    echo "Zarinpal gateway not found or not active";
}
```

--------------------------------

### Basic Payment Flow with Service

Source: https://github.com/amidesfahani/filament-payment-manager/blob/v4/README.md

Demonstrates initiating a payment using the `PaymentManagerService`. It shows how to create an invoice and then proceed with payment, optionally specifying a gateway.

```php
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
}
```

--------------------------------

### Querying PaymentGateway Models in PHP

Source: https://context7.com/amidesfahani/filament-payment-manager/llms.txt

Demonstrates how to query the PaymentGateway model using Eloquent scopes like 'active', 'default', and 'withTrashed'. It also shows how to retrieve a specific gateway by driver and retrieve its configuration, including merging with default settings. Gateways can also be ordered by 'sort_order'.

```php
use AmidEsfahani\FilamentPaymentManager\Models\PaymentGateway;

// Query active gateways
$activeGateways = PaymentGateway::active()->get();

// Query default gateway
$defaultGateway = PaymentGateway::default()->active()->first();

// Get specific gateway
$zarinpal = PaymentGateway::where('driver', 'zarinpal')
    ->where('is_active', true)
    ->first();

// Get gateway with config merged with defaults
if ($zarinpal) {
    $config = $zarinpal->getConfigWithDefaults();
    // Returns merged array of driver defaults + database config
}

// Get all gateways ordered by sort_order
$sortedGateways = PaymentGateway::orderBy('sort_order')->get();

// Get gateway with trashed (soft deleted)
$allIncludingDeleted = PaymentGateway::withTrashed()->get();
```

--------------------------------

### Set Environment Variables for Payment Manager

Source: https://context7.com/amidesfahani/filament-payment-manager/llms.txt

Environment variables to configure the payment callback URL, default currency, automatic gateway loading, and logging for the payment manager.

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

--------------------------------

### Basic Payment Flow with Default Gateway in PHP

Source: https://context7.com/amidesfahani/filament-payment-manager/llms.txt

Initiates a payment using the default configured gateway. It creates an invoice, purchases the payment, records transaction details in the database, and redirects the user to the payment gateway. Error handling for payment creation is included.

```php
use AmidEsfahani\FilamentPaymentManager\Services\PaymentManagerService;
use Shetabit\Multipay\Invoice;

// Create payment with default gateway
$paymentManager = app(PaymentManagerService::class);

$invoice = new Invoice();
$invoice->amount(50000); // 50,000 Toman
$invoice->detail(['order_id' => 12345]);

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

    // Purchase and get transaction ID
    $transactionId = $payment->purchase($invoice, function($driver, $transactionId) {
        // Store transaction details in database
        \DB::table('transactions')->insert([
            'transaction_id' => $transactionId,
            'amount' => 50000,
            'driver' => $driver,
            'status' => 'pending',
            'created_at' => now(),
        ]);
    })->pay()->render();

    // User is redirected to payment gateway

} catch (\Exception $e) {
    // Handle payment creation error
    \Log::error('Payment creation failed: ' . $e->getMessage());
    return redirect()->back()->with('error', 'Unable to initiate payment. Please try again.');
}
```

--------------------------------

### Configure Filament Payment Manager

Source: https://context7.com/amidesfahani/filament-payment-manager/llms.txt

Configuration array for the Filament Payment Manager, defining default callback URLs, currency, gateway drivers, and logging settings.

```php
// config/filament-payment-manager.php
return [
    'default_callback_url' => env('PAYMENT_CALLBACK_URL', url('/payment/callback')),
    'auto_load_gateways' => env('PAYMENT_AUTO_LOAD_GATEWAYS', true),
    'default_currency' => env('PAYMENT_DEFAULT_CURRENCY', 'T'),

    'driver_defaults' => [
        'zarinpal' => [
            'mode' => 'normal',
            'currency' => 'T',
        ],
        'paypal' => [
            'mode' => 'normal',
            'currency' => 'USD',
        ],
        'stripe' => [
            'currency' => 'usd',
        ],
    ],

    'enable_logging' => env('PAYMENT_ENABLE_LOGGING', false),
    'table_name' => 'payment_gateways',
];
```

--------------------------------

### Using Sandbox Mode

Source: https://github.com/amidesfahani/filament-payment-manager/blob/v4/README.md

Information on enabling sandbox mode for testing with supported gateways.

```APIDOC
## Sandbox Mode

Many gateways support sandbox mode:

```php
// Zarinpal
'mode' => 'sandbox'

// PayPal
'mode' => 'sandbox'
```
```

--------------------------------

### Testing with Local Gateway

Source: https://github.com/amidesfahani/filament-payment-manager/blob/v4/README.md

Instructions on using the built-in local gateway for testing payment flows.

```APIDOC
## Using Local Gateway

The package includes a local test gateway:

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

--------------------------------

### Troubleshooting: Currency Issues

Source: https://github.com/amidesfahani/filament-payment-manager/blob/v4/README.md

Explanation of currency handling, particularly for Iranian gateways.

```APIDOC
## Troubleshooting: 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.
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/amidesfahani/filament-payment-manager/blob/v4/README.md

Sets up essential environment variables for the Filament Payment Manager. These variables control aspects like the payment callback URL, default currency, and logging behavior.

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

--------------------------------

### Access and Modify Gateway Configurations

Source: https://context7.com/amidesfahani/filament-payment-manager/llms.txt

This section details how to programmatically create and update payment gateway configurations using the `PaymentGateway` model. It shows the structure for creating a new gateway with its name, driver, currency, active status, default status, configuration array, callback URL, and sort order. It also illustrates how to update an existing gateway's configuration by merging new settings with existing ones, and how to access the complete configuration merged with default values from the config file.

```php
use AmidEsfahani\FilamentPaymentManager\Models\PaymentGateway;

// Create new gateway programmatically
$gateway = PaymentGateway::create([
    'name' => 'Zarinpal Test',
    'driver' => 'zarinpal',
    'currency' => 'T',
    'is_active' => true,
    'is_default' => true,
    'config' => [
        'merchantId' => 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
        'mode' => 'sandbox',
        'description' => 'Test payment',
    ],
    'callback_url' => 'https://example.com/payment/callback',
    'sort_order' => 0,
]);

// Update gateway configuration
$gateway = PaymentGateway::find(1);
$gateway->update([
    'config' => array_merge($gateway->config ?? [], [
        'mode' => 'normal', // Switch from sandbox to production
        'merchantId' => 'new-merchant-id',
    ]),
]);

// Access config with defaults
$completeConfig = $gateway->getConfigWithDefaults();
// Merges driver defaults from config file with database config

```

--------------------------------

### Run Database Migrations

Source: https://github.com/amidesfahani/filament-payment-manager/blob/v4/README.md

Executes the database migrations published by the Filament Payment Manager package. This creates the necessary tables in your database for managing payment gateways.

```bash
php artisan migrate
```

--------------------------------

### Troubleshooting: Gateway Not Working

Source: https://github.com/amidesfahani/filament-payment-manager/blob/v4/README.md

Common steps to troubleshoot issues when a payment gateway is not functioning correctly.

```APIDOC
## 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
```

--------------------------------

### Testing with Local Gateway

Source: https://github.com/amidesfahani/filament-payment-manager/blob/v4/README.md

Instructions on using the built-in local test gateway for development and testing purposes. By configuring a gateway with the driver 'local' within Filament, developers can simulate payment flows without needing actual credentials or live gateway integrations.

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

--------------------------------

### Troubleshooting: Callback URL Issues

Source: https://github.com/amidesfahani/filament-payment-manager/blob/v4/README.md

Guidance on resolving problems related to payment gateway callback URLs.

```APIDOC
## Troubleshooting: 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
```

--------------------------------

### Process Payment with Error Handling (PHP)

Source: https://context7.com/amidesfahani/filament-payment-manager/llms.txt

Handles the process of creating and initiating a payment, including comprehensive error handling for various exceptions like ModelNotFoundException, InvalidPaymentException, and general exceptions. It logs errors and returns informative messages.

```php
use AmidEsfahani\FilamentPaymentManager\Services\PaymentManagerService;
use Shetabit\Multipay\Invoice;
use Shetabit\Multipay\Exceptions\InvalidPaymentException;
use Illuminate\Database\Eloquent\ModelNotFoundException;

public function processPayment($orderId)
{
    $paymentManager = app(PaymentManagerService::class);

    try {
        $order = Order::findOrFail($orderId);

        $invoice = new Invoice();
        $invoice->amount($order->total);

        $payment = $paymentManager->createPayment($invoice->getAmount());

        $transactionId = $payment->purchase($invoice)->pay()->render();

        return ['success' => true, 'transaction_id' => $transactionId];

    } catch (ModelNotFoundException $e) {
        // Gateway not found or not active
        \Log::error('Payment gateway not found', [
            'error' => $e->getMessage(),
            'order_id' => $orderId,
        ]);
        return ['success' => false, 'error' => 'Payment gateway not available'];

    } catch (InvalidPaymentException $e) {
        // Invalid payment parameters or gateway rejection
        \Log::error('Invalid payment', [
            'error' => $e->getMessage(),
            'order_id' => $orderId,
        ]);
        return ['success' => false, 'error' => 'Payment parameters invalid'];

    } catch (\Shetabit\Multipay\Exceptions\PurchaseFailedException $e) {
        // Gateway purchase request failed
        \Log::error('Purchase failed', [
            'error' => $e->getMessage(),
            'order_id' => $orderId,
        ]);
        return ['success' => false, 'error' => 'Unable to initiate payment'];

    } catch (\Exception $e) {
        // General error
        \Log::error('Payment processing error', [
            'error' => $e->getMessage(),
            'order_id' => $orderId,
            'trace' => $e->getTraceAsString(),
        ]);
        return ['success' => false, 'error' => 'Payment system error'];
    }
}
```

--------------------------------

### Programmatic Use of Custom Redirect Form in PHP

Source: https://context7.com/amidesfahani/filament-payment-manager/llms.txt

Shows how to programmatically generate the custom redirect form HTML using the Payment Manager Service in PHP. It illustrates fetching a payment gateway, calling the `getRedirectForm` method with specific action, method, and input data, and returning the rendered HTML response. The placeholders in the HTML are automatically replaced and inputs are escaped.

```php
use AmidEsfahani\FilamentPaymentManager\Models\PaymentGateway;
use AmidEsfahani\FilamentPaymentManager\Services\PaymentManagerService;

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

$html = $paymentManager->getRedirectForm(
    gateway: $gateway,
    action: 'https://payment.gateway.com/pay',
    method: 'POST',
    inputs: [
        'token' => 'abc123xyz',
        'amount' => 50000,
        'merchant_id' => 'test-merchant',
    ]
);

// Returns fully rendered HTML with placeholders replaced and inputs escaped
return response($html);
```

--------------------------------

### Gateway Model Events and Validation for Default/Soft Deletes

Source: https://context7.com/amidesfahani/filament-payment-manager/llms.txt

This code illustrates the behavior of the `PaymentGateway` model concerning its events and validation, specifically focusing on the 'default' gateway and soft delete functionality. When a new gateway is created or updated to be the default, the model automatically ensures only one gateway can be default at any time by deactivating the previously default one. It also demonstrates how to soft delete gateways and query for active gateways, soft-deleted gateways, or all gateways, including the ability to restore soft-deleted records.

```php
use AmidEsfahani\FilamentPaymentManager\Models\PaymentGateway;

// Create first default gateway
$gateway1 = PaymentGateway::create([
    'name' => 'Primary Gateway',
    'driver' => 'zarinpal',
    'currency' => 'T',
    'is_active' => true,
    'is_default' => true, // Set as default
    'config' => ['merchantId' => 'xxx'],
]);

// Create second gateway and set as default
$gateway2 = PaymentGateway::create([
    'name' => 'Secondary Gateway',
    'driver' => 'saman',
    'currency' => 'T',
    'is_active' => true,
    'is_default' => true, // Set as default
    'config' => ['merchantId' => 'yyy'],
]);

// The model's saving event automatically sets $gateway1->is_default to false
// Only one gateway can be default at a time

// Verify
$gateway1->refresh();
echo $gateway1->is_default; // false
echo $gateway2->is_default; // true

// Soft delete gateway
$gateway1->delete();

// Query excluding soft deleted
$activeGateways = PaymentGateway::active()->get();

// Query including soft deleted
$allGateways = PaymentGateway::withTrashed()->get();

// Restore soft deleted gateway
$gateway1->restore();

```

--------------------------------

### Verify Payment Callback with Error Handling (PHP)

Source: https://context7.com/amidesfahani/filament-payment-manager/llms.txt

Handles the verification of a payment callback, managing exceptions such as InvalidPaymentException and ModelNotFoundException. It logs warnings and errors and returns specific error messages for different failure scenarios.

```php
use AmidEsfahani\FilamentPaymentManager\Services\PaymentManagerService;

public function verifyCallback(Request $request)
{
    $paymentManager = app(PaymentManagerService::class);

    try {
        $receipt = $paymentManager->verifyPayment();
        $referenceId = $receipt->getReferenceId();

        // Success handling
        return [
            'success' => true,
            'reference_id' => $referenceId,
            'driver' => $receipt->getDriver(),
        ];

    } catch (\Shetabit\Multipay\Exceptions\InvalidPaymentException $e) {
        // Payment verification failed (wrong amount, expired, already verified)
        \Log::warning('Payment verification failed', [
            'error' => $e->getMessage(),
            'request_data' => $request->all(),
        ]);
        return [
            'success' => false,
            'error' => 'verification_failed',
            'message' => 'Payment could not be verified',
        ];

    } catch (\Illuminate\Database\Eloquent\ModelNotFoundException $e) {
        // Gateway not found
        \Log::error('Gateway not found during verification', [
            'error' => $e->getMessage(),
        ]);
        return [
            'success' => false,
            'error' => 'gateway_not_found',
            'message' => 'Payment gateway configuration missing',
        ];

    } catch (\Exception $e) {
        \Log::error('Verification system error', [
            'error' => $e->getMessage(),
            'trace' => $e->getTraceAsString(),
        ]);
        return [
            'success' => false,
            'error' => 'system_error',
            'message' => 'System error during verification',
        ];
    }
}
```

--------------------------------

### Specific Gateway Payment Flow in PHP

Source: https://context7.com/amidesfahani/filament-payment-manager/llms.txt

Enables users to select a payment method (gateway) for transactions. This flow creates an invoice with detailed information, initiates payment with the chosen gateway, records transaction specifics, and handles potential errors like unavailable gateways or general processing failures.

```php
use AmidEsfahani\FilamentPaymentManager\Services\PaymentManagerService;
use Shetabit\Multipay\Invoice;

// Create payment with specific driver
$paymentManager = app(PaymentManagerService::class);

// Let user choose payment method
$selectedDriver = request()->input('payment_method'); // 'zarinpal', 'paypal', 'stripe'

$invoice = new Invoice();
$invoice->amount(100000);
$invoice->detail([
    'order_id' => 98765,
    'customer_name' => 'John Doe',
    'customer_email' => 'john@example.com',
]);

try {
    // Create payment with specific gateway
    $payment = $paymentManager->createPayment($invoice->getAmount(), $selectedDriver);

    $transactionId = $payment->purchase($invoice, function($driver, $transactionId) use ($invoice) {
        // Save transaction with details
        \App\Models\Transaction::create([
            'transaction_id' => $transactionId,
            'driver' => $driver,
            'amount' => $invoice->getAmount(),
            'details' => $invoice->getDetails(),
            'status' => 'pending',
        ]);
    })->pay()->render();

} catch (\Illuminate\Database\Eloquent\ModelNotFoundException $e) {
    // Gateway not found or not active
    return redirect()->back()->with('error', 'Selected payment method is not available.');
} catch (\Exception $e) {
    \Log::error('Payment error: ' . $e->getMessage());
    return redirect()->back()->with('error', 'Payment processing failed.');
}
```

--------------------------------

### Custom HTML Redirect Form for Payment Gateways

Source: https://context7.com/amidesfahani/filament-payment-manager/llms.txt

Demonstrates how to create a custom HTML template for payment gateway redirects. This involves defining the HTML structure, including form fields and styling, and using placeholders that are automatically replaced by the Payment Manager Service. The form is designed to auto-submit after a specified delay.

```html
<!DOCTYPE html>
<html>
<head>
    <title>Payment Gateway</title>
    <style>
        body { background: #f0f0f0; font-family: sans-serif; }
        .form-container {
            max-width: 400px;
            margin: 100px auto;
            background: white;
            padding: 30px;
            border-radius: 8px;
            box-shadow: 0 2px 10px rgba(0,0,0,0.1);
        }
        button {
            background: #4CAF50;
            color: white;
            padding: 12px 30px;
            border: none;
            border-radius: 4px;
            cursor: pointer;
            font-size: 16px;
            width: 100%;
        }
        button:hover { background: #45a049; }
    </style>
</head>
<body>
    <div class="form-container">
        <h2>Complete Your Payment</h2>
        <p>You will be redirected to the secure payment gateway.</p>

        <form method="{method}" action="{action}" id="gateway-form">
            {inputs}
            <button type="submit">Proceed to Payment</button>
        </form>
    </div>

    <script>
        // Auto-submit after 3 seconds
        setTimeout(function() {
            document.getElementById('gateway-form').submit();
        }, 3000);
    </script>
</body>
</html>
```

--------------------------------

### Verify Payment with Default Gateway - PHP

Source: https://context7.com/amidesfahani/filament-payment-manager/llms.txt

Verifies a payment using the default configured gateway. It handles successful verification by updating the transaction status and redirecting the user, or catches exceptions for failed verifications. Dependencies include the `PaymentManagerService` and `Request` object.

```php
use AmidEsfahani\FilamentPaymentManager\Services\PaymentManagerService;

// In your callback route (e.g., /payment/callback)
public function callback(Request $request)
{
    $paymentManager = app(PaymentManagerService::class);

    try {
        // Verify payment with default gateway
        $receipt = $paymentManager->verifyPayment();

        // Get payment details
        $referenceId = $receipt->getReferenceId();
        $driver = $receipt->getDriver();

        // Update transaction status
        $transaction = \DB::table('transactions')
            ->where('transaction_id', $request->input('Authority'))
            ->first();

        if ($transaction) {
            \DB::table('transactions')
                ->where('id', $transaction->id)
                ->update([
                    'status' => 'completed',
                    'reference_id' => $referenceId,
                    'verified_at' => now(),
                ]);
        }

        return redirect()->route('payment.success')
            ->with('success', "Payment successful! Reference: {$referenceId}");

    } catch (\Shetabit\Multipay\Exceptions\InvalidPaymentException $e) {
        // Payment verification failed
        return redirect()->route('payment.failed')
            ->with('error', 'Payment verification failed: ' . $e->getMessage());

    } catch (\Exception $e) {
        \Log::error('Payment callback error: ' . $e->getMessage());
        return redirect()->route('payment.failed')
            ->with('error', 'An error occurred during payment verification.');
    }
}
```

--------------------------------

### Register Filament Payment Manager Plugin

Source: https://context7.com/amidesfahani/filament-payment-manager/llms.txt

Code to register the Filament Payment Manager plugin within your Filament admin panel provider.

```php
// app/Providers/Filament/AdminPanelProvider.php
use AmidEsfahani\FilamentPaymentManager\FilamentPaymentManagerPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->id('admin')
        ->path('admin')
        ->plugins([
            FilamentPaymentManagerPlugin::make(),
        ]);
}
```

--------------------------------

### PaymentGateway Model Properties

Source: https://github.com/amidesfahani/filament-payment-manager/blob/v4/README.md

This section outlines the properties available in the PaymentGateway Eloquent model.

```APIDOC
## PaymentGateway Model Properties

This section outlines the properties available in the PaymentGateway Eloquent model.

### Properties

- **`name`** (string) - Gateway display name.
- **`driver`** (string) - Payment driver name (e.g., 'zarinpal', 'stripe').
- **`is_active`** (boolean) - Indicates if the gateway is currently active.
- **`is_default`** (boolean) - Indicates if this is the default payment gateway.
- **`config`** (array) - Configuration options specific to the gateway.
- **`callback_url`** (string) - A custom callback URL for the gateway.
- **`redirect_form_view`** (string) - Path to a custom Blade view for the redirect form.
- **`redirect_form_html`** (string) - Custom HTML content for the redirect form.
- **`sort_order`** (integer) - The display order for the gateway.
- **`description`** (string) - Internal notes or description for the gateway.
```