# Payment Configuration Module - Dependencies & Installation Guide

## Overview

This document provides information about the dependencies required for the Payment Configuration Module and instructions for integrating it into your existing SSHIA Laravel System.

---

## Required Dependencies

### PHP Extensions
The module requires the following PHP extensions (typically included in PHP 8.2+):

| Extension | Purpose | Required |
|-----------|---------|----------|
| `openssl` | Encryption of API credentials | Yes |
| `curl` | HTTP requests to MTN MoMo API | Yes |
| `json` | JSON encoding/decoding | Yes |
| `mbstring` | String manipulation | Yes |

### Laravel Packages
The module uses the following Laravel packages (already included in SSHIA Laravel System):

| Package | Version | Purpose |
|---------|---------|---------|
| `laravel/framework` | 12.x | Core framework |
| `spatie/laravel-permission` | 6.24+ | Role and permission management |
| `guzzlehttp/guzzle` | 7.x | HTTP client (used by Laravel HTTP facade) |

### Frontend Dependencies
The views use the following frontend dependencies (already included in SSHIA Laravel System):

| Package | Version | Purpose |
|---------|---------|---------|
| `tailwindcss` | 4.x | CSS framework |
| `alpinejs` | 3.x | JavaScript interactivity |
| `flowbite` | 4.x | UI components |
| `@fortawesome/fontawesome-free` | 7.x | Icons |

---

## No Additional Installation Required

**Good news!** This module uses only the dependencies already included in the SSHIA Laravel System. No additional npm or composer packages need to be installed.

---

## Integration Steps

### Step 1: Copy Files to Your Project

Copy the following directories and files to your Laravel project:

```
payment-module/
├── app/
│   ├── Http/Controllers/PaymentConfigurationController.php → app/Http/Controllers/
│   ├── Models/
│   │   ├── PaymentConfiguration.php → app/Models/
│   │   └── PaymentLog.php → app/Models/
│   └── Services/
│       ├── ConfigurationService.php → app/Services/
│       ├── PaymentProvider.php → app/Services/
│       └── PaymentService.php → app/Services/
├── database/
│   ├── migrations/
│   │   ├── 2024_01_15_000001_create_payment_configurations_table.php → database/migrations/
│   │   └── 2024_01_15_000002_create_payment_logs_table.php → database/migrations/
│   └── seeders/
│       └── PaymentConfigurationPermissionSeeder.php → database/seeders/
├── routes/
│   └── payment.php → routes/
└── resources/views/config/payment/
    ├── index.blade.php → resources/views/config/payment/
    ├── form.blade.php → resources/views/config/payment/
    ├── test.blade.php → resources/views/config/payment/
    ├── logs.blade.php → resources/views/config/payment/
    └── documentation.blade.php → resources/views/config/payment/
```

### Step 2: Update Routes File

Add the payment routes to your main `routes/web.php` file:

```php
// Add this line to routes/web.php
require __DIR__ . '/payment.php';
```

Or include the routes directly:

```php
// In routes/web.php
Route::middleware(['auth', 'role:Super Manager'])->prefix('config/payment')->name('config.payment.')->group(function () {
    // Import routes from payment.php or copy the route definitions here
});
```

### Step 3: Run Migrations

Run the database migrations:

```bash
php artisan migrate
```

### Step 4: Run Permission Seeder

Seed the permissions for the payment module:

```bash
php artisan db:seed --class=PaymentConfigurationPermissionSeeder
```

Or add it to your main `DatabaseSeeder.php`:

```php
public function run(): void
{
    // ... other seeders
    $this->call(PaymentConfigurationPermissionSeeder::class);
}
```

### Step 5: Add Environment Variables

Add the MTN MoMo API credentials to your `.env` file:

```env
MOMO_ENVIRONMENT=sandbox
MOMO_COLLECTION_API_USER=
MOMO_COLLECTION_API_KEY=
MOMO_COLLECTION_SUBSCRIPTION_KEY=
MOMO_DISBURSEMENT_API_USER=
MOMO_DISBURSEMENT_API_KEY=
MOMO_DISBURSEMENT_SUBSCRIPTION_KEY=
```

### Step 6: Add Navigation Link (Optional)

Add a navigation link to your sidebar or navigation menu:

```blade
@role('Super Manager')
    <x-nav-link :href="route('config.payment.index')" :active="request()->routeIs('config.payment.*')">
        <i class="fas fa-credit-card mr-2"></i>
        Payment Config
    </x-nav-link>
@endrole
```

---

## Verification

After integration, verify the installation:

### 1. Check Routes
```bash
php artisan route:list --name=config.payment
```

### 2. Check Migrations
```bash
php artisan migrate:status
```

### 3. Check Permissions
```bash
php artisan tinker
>>> Spatie\Permission\Models\Permission::where('name', 'like', '%payment%')->get();
```

### 4. Access Dashboard
Navigate to `/config/payment` as a Super Manager user.

---

## Configuration

### MTN MoMo API Credentials

1. Register at [MTN MoMo Developer Portal](https://momodeveloper.mtn.com)
2. Subscribe to Collection and/or Disbursement products
3. Create API User and API Key for each product
4. Copy the subscription keys
5. Enter credentials in the configuration form at `/config/payment/create`

### Environment Modes

| Mode | Purpose | Base URL |
|------|---------|----------|
| `sandbox` | Testing and development | `https://sandbox.momodeveloper.mtn.com` |
| `production` | Live transactions | `https://momodeveloper.mtn.com` |

---

## Using PaymentService in Other Modules

The `PaymentService` can be injected into any controller or service:

```php
use App\Services\PaymentService;

class OrderController extends Controller
{
    public function __construct(
        protected PaymentService $paymentService
    ) {}

    public function pay(Request $request)
    {
        $result = $this->paymentService->initiateCollection(
            phoneNumber: $request->phone,
            amount: $request->amount,
            reference: 'ORD-' . $order->id
        );

        if ($result['success']) {
            // Payment request sent
        }
    }
}
```

See the documentation page at `/config/payment/documentation` for complete examples.

---

## Troubleshooting

### Common Issues

1. **"Class not found" errors**
   - Run `composer dump-autoload`

2. **Permission denied errors**
   - Ensure user has Super Manager role
   - Run the permission seeder

3. **Views not found**
   - Clear view cache: `php artisan view:clear`
   - Verify view files are in correct location

4. **Routes not working**
   - Clear route cache: `php artisan route:clear`
   - Verify routes are registered: `php artisan route:list`

5. **API connection failures**
   - Check credentials are correct
   - Verify environment is set correctly
   - Check network connectivity
   - Review payment logs for details

---

## Support

For issues related to:
- **Module functionality**: Check the documentation page at `/config/payment/documentation`
- **MTN MoMo API**: Visit [MTN MoMo Developer Portal](https://momodeveloper.mtn.com)
- **SSHIA System**: Contact your system administrator

---

## Version History

| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | 2024-01-15 | Initial release |

---

## License

This module is part of the SSHIA Laravel System and follows the same license terms.
