Step-by-Step Payment Gateway Module Tutorial
This comprehensive tutorial walks you through creating a complete payment gateway module from scratch. We'll build a functional payment gateway module step-by-step, demonstrating every command, file, and configuration needed.
Tutorial Overview
In this tutorial, we'll create a TapGateway payment module that demonstrates:
- Complete module structure creation
- Essential Artisan commands for module development
- Step-by-step file generation and configuration
- Cache management and module activation
- Testing and verification procedures
TUTORIAL APPROACH
This tutorial follows a command-by-command approach where every step is explained in detail with expected outputs and troubleshooting tips.
Prerequisites Check
Before starting, ensure you have:
- Laravel 12.19.3+ installed and configured
- PHP 8.3+ with required extensions
- Database connection properly configured
- Module system installed and working
- Command line access to your Laravel application
- Proper file permissions for module creation
Verify Environment
# Check PHP version
php --version
# Expected: PHP 8.3.x or higher# Check Laravel version
php artisan --version
# Expected: Laravel Framework 12.19.3 or higher# Check if module system is available
php artisan module:list
# Should display module commands and current modulesStep 1: Create the Module Structure
1.1 Generate Base Module
Command: Use the Laravel module command with the critical --type=custom flag:
php artisan module:make TapGateway --type=customCRITICAL COMMAND
Always use php artisan module:make ModuleName --type=custom when creating payment gateway modules. The --type=custom flag is essential for proper module structure and configuration.
Expected Output:
[TapGateway] module created successfully.
Module type: Custom
To activate the module, run: php artisan module:activate TapGatewayWhat This Command Does:
- Creates the complete directory structure under
Modules/TapGateway/ - Generates essential configuration files (
module.json,composer.json,package.json) - Creates basic service providers and route providers
- Sets up asset compilation configuration (
vite.config.js) - Creates initial directory structure for controllers, views, routes
- Establishes proper PHP namespacing and autoloading
1.2 Verify Module Creation
Check Module Directory:
# Navigate to the module directory
cd Modules/TapGateway
# List all generated files and directories
ls -laExpected Directory Structure:
total XX
drwxr-xr-x XX user user XXXX MMM DD HH:MM .
drwxr-xr-x XX user user XXXX MMM DD HH:MM ..
-rw-r--r-- 1 user user XXX MMM DD HH:MM composer.json
-rw-r--r-- 1 user user XXX MMM DD HH:MM module.json
-rw-r--r-- 1 user user XXX MMM DD HH:MM package.json
-rw-r--r-- 1 user user XXX MMM DD HH:MM README.md
-rw-r--r-- 1 user user XXX MMM DD HH:MM TapGateway.php
-rw-r--r-- 1 user user XXX MMM DD HH:MM vite.config.js
drwxr-xr-x X user user XXX MMM DD HH:MM Config/
drwxr-xr-x X user user XXX MMM DD HH:MM Console/
drwxr-xr-x X user user XXX MMM DD HH:MM Database/
drwxr-xr-x X user user XXX MMM DD HH:MM Http/
drwxr-xr-x X user user XXX MMM DD HH:MM Livewire/
drwxr-xr-x X user user XXX MMM DD HH:MM Models/
drwxr-xr-x X user user XXX MMM DD HH:MM Providers/
drwxr-xr-x X user user XXX MMM DD HH:MM resources/
drwxr-xr-x X user user XXX MMM DD HH:MM Routes/1.3 Examine Generated Configuration
Check module.json Configuration:
cat module.jsonExpected Content:
{
"name": "TapGateway",
"alias": "tap-gateway",
"namespace": "Modules\\TapGateway\\",
"provider": "Modules\\TapGateway\\Providers\\TapGatewayServiceProvider",
"author": "Corbital Technologies",
"url": "https://codecanyon.net/user/corbitaltech",
"version": "1.0.0",
"description": "The TapGateway Module",
"keywords": [],
"order": 0,
"providers": ["Modules\\TapGateway\\Providers\\TapGatewayServiceProvider"],
"aliases": [],
"require": [],
"conflicts": [],
"type": "custom"
}Configuration Explanation:
- name: Module identifier for commands and references
- alias: URL-friendly name for routing
- namespace: PHP namespace for all module classes
- provider: Main service provider class
- type:
customindicates this is a custom module (not core system)
Step 2: Generate Core Module Components
2.1 Create Admin Controllers
Generate Admin Settings Controller:
php artisan module:make-controller Admin/TapGatewaySettingsController TapGatewayExpected Output:
Controller [Admin/TapGatewaySettingsController] created successfully.Generated File Location: Modules/TapGateway/Http/Controllers/Admin/TapGatewaySettingsController.php
Verify Controller Creation:
ls -la Http/Controllers/Admin/Expected Output:
total XX
drwxr-xr-x X user user XXX MMM DD HH:MM .
drwxr-xr-x X user user XXX MMM DD HH:MM ..
-rw-r--r-- 1 user user XXX MMM DD HH:MM TapGatewaySettingsController.php2.2 Create Payment Gateway Controller
Generate Payment Gateway Controller:
php artisan module:make-controller PaymentGateways/TapGatewayController TapGatewayExpected Output:
Controller [PaymentGateways/TapGatewayController] created successfully.Generated File Location: Modules/TapGateway/Http/Controllers/PaymentGateways/TapGatewayController.php
2.3 Create API Controller
Generate API Controller:
php artisan module:make-controller Api/TapGatewayApiController TapGatewayExpected Output:
Controller [Api/TapGatewayApiController] created successfully.2.4 Verify All Controllers
Check Complete Controller Structure:
find Http/Controllers -name "*.php" -type fExpected Output:
Http/Controllers/TapGatewayController.php
Http/Controllers/Admin/TapGatewaySettingsController.php
Http/Controllers/Api/TapGatewayApiController.php
Http/Controllers/PaymentGateways/TapGatewayController.phpStep 3: Create Service Classes
3.1 Create Main Payment Gateway Service
Generate Payment Gateway Service:
php artisan module:make-class Services/TapGatewayPaymentGateway TapGatewayExpected Output:
Class [Services/TapGatewayPaymentGateway] created successfully.Generated File Location: Modules/TapGateway/Services/TapGatewayPaymentGateway.php
3.2 Create API Service
Generate API Service:
php artisan module:make-class Services/TapGatewayService TapGatewayExpected Output:
Class [Services/TapGatewayService] created successfully.3.3 Create Helper Services
Generate Webhook Service:
php artisan module:make-class Services/TapGatewayWebhookService TapGatewayGenerate Validation Service:
php artisan module:make-class Services/TapGatewayValidationService TapGateway3.4 Verify Services Directory
Check Services Structure:
ls -la Services/Expected Output:
total XX
drwxr-xr-x X user user XXX MMM DD HH:MM .
drwxr-xr-x X user user XXX MMM DD HH:MM ..
-rw-r--r-- 1 user user XXX MMM DD HH:MM TapGatewayPaymentGateway.php
-rw-r--r-- 1 user user XXX MMM DD HH:MM TapGatewayService.php
-rw-r--r-- 1 user user XXX MMM DD HH:MM TapGatewayValidationService.php
-rw-r--r-- 1 user user XXX MMM DD HH:MM TapGatewayWebhookService.phpStep 4: Create Event Listeners
4.1 Generate Gateway Registration Listener
Create Gateway Registration Listener:
php artisan module:make-listener RegisterTapGateway TapGatewayExpected Output:
Listener [RegisterTapGateway] created successfully.Generated File Location: Modules/TapGateway/Listeners/RegisterTapGateway.php
4.2 Generate Settings Extension Listener
Create Settings Extension Listener:
php artisan module:make-listener ExtendPaymentSettings TapGatewayExpected Output:
Listener [ExtendPaymentSettings] created successfully.4.3 Generate Admin Panel Listener
Create Admin Panel Listener:
php artisan module:make-listener AddTapGatewayPaymentSettings TapGatewayExpected Output:
Listener [AddTapGatewayPaymentSettings] created successfully.4.4 Verify Listeners Directory
Check Listeners Structure:
ls -la Listeners/Expected Output:
total XX
drwxr-xr-x X user user XXX MMM DD HH:MM .
drwxr-xr-x X user user XXX MMM DD HH:MM ..
-rw-r--r-- 1 user user XXX MMM DD HH:MM AddTapGatewayPaymentSettings.php
-rw-r--r-- 1 user user XXX MMM DD HH:MM ExtendPaymentSettings.php
-rw-r--r-- 1 user user XXX MMM DD HH:MM RegisterTapGateway.phpStep 5: Create Models and Database Components
5.1 Create Transaction Model
Generate Transaction Model with Migration:
php artisan module:make-model TapGatewayTransaction TapGateway -mExpected Output:
Model [TapGatewayTransaction] created successfully.
Migration [create_tap_gateway_transactions_table] created successfully.Generated Files:
Modules/TapGateway/Models/TapGatewayTransaction.phpModules/TapGateway/Database/Migrations/YYYY_MM_DD_HHMMSS_create_tap_gateway_transactions_table.php
5.2 Create Additional Models
Generate Refund Model with Migration and Factory:
php artisan module:make-model TapGatewayRefund TapGateway -mfGenerate Webhook Log Model with Migration, Factory, and Seeder:
php artisan module:make-model TapGatewayWebhookLog TapGateway -mfs5.3 Create Settings Migration
Generate Settings Migration:
php artisan module:make-migration add_tap_gateway_payment_settings TapGatewayExpected Output:
Migration [add_tap_gateway_payment_settings] created successfully.5.4 Verify Database Components
Check Models Directory:
ls -la Models/Check Migrations Directory:
ls -la Database/Migrations/Check Factories Directory:
ls -la Database/Factories/Check Seeders Directory:
ls -la Database/Seeders/Step 6: Create Request Validation Classes
6.1 Create Payment Request
Generate Payment Request Validation:
php artisan module:make-request TapGatewayPaymentRequest TapGatewayExpected Output:
Request [TapGatewayPaymentRequest] created successfully.6.2 Create Admin Settings Request
Generate Admin Settings Request:
php artisan module:make-request Admin/TapGatewaySettingsRequest TapGatewayExpected Output:
Request [Admin/TapGatewaySettingsRequest] created successfully.6.3 Verify Requests Directory
Check Requests Structure:
find Http/Requests -name "*.php" -type fExpected Output:
Http/Requests/Admin/TapGatewaySettingsRequest.php
Http/Requests/TapGatewayPaymentRequest.phpStep 7: Create Middleware
7.1 Create Payment Verification Middleware
Generate Payment Verification Middleware:
php artisan module:make-middleware TapGatewayVerifyPayment TapGatewayExpected Output:
Middleware [TapGatewayVerifyPayment] created successfully.7.2 Create Webhook Signature Middleware
Generate Webhook Signature Middleware:
php artisan module:make-middleware TapGatewayVerifyWebhook TapGatewayExpected Output:
Middleware [TapGatewayVerifyWebhook] created successfully.7.3 Verify Middleware Directory
Check Middleware Structure:
ls -la Http/Middleware/Expected Output:
total XX
drwxr-xr-x X user user XXX MMM DD HH:MM .
drwxr-xr-x X user user XXX MMM DD HH:MM ..
-rw-r--r-- 1 user user XXX MMM DD HH:MM TapGatewayVerifyPayment.php
-rw-r--r-- 1 user user XXX MMM DD HH:MM TapGatewayVerifyWebhook.phpStep 8: Create Jobs and Queued Tasks
8.1 Create Payment Processing Job
Generate Payment Processing Job:
php artisan module:make-job ProcessTapGatewayPayment TapGatewayExpected Output:
Job [ProcessTapGatewayPayment] created successfully.8.2 Create Webhook Processing Job
Generate Webhook Processing Job:
php artisan module:make-job ProcessTapGatewayWebhook TapGatewayExpected Output:
Job [ProcessTapGatewayWebhook] created successfully.8.3 Create Notification Job
Generate Notification Job:
php artisan module:make-job SendTapGatewayNotification TapGatewayExpected Output:
Job [SendTapGatewayNotification] created successfully.8.4 Verify Jobs Directory
Check Jobs Structure:
ls -la Jobs/Expected Output:
total XX
drwxr-xr-x X user user XXX MMM DD HH:MM .
drwxr-xr-x X user user XXX MMM DD HH:MM ..
-rw-r--r-- 1 user user XXX MMM DD HH:MM ProcessTapGatewayPayment.php
-rw-r--r-- 1 user user XXX MMM DD HH:MM ProcessTapGatewayWebhook.php
-rw-r--r-- 1 user user XXX MMM DD HH:MM SendTapGatewayNotification.phpStep 9: Create Event Classes
9.1 Create Payment Events
Generate Payment Started Event:
php artisan module:make-event TapGatewayPaymentStarted TapGatewayGenerate Payment Completed Event:
php artisan module:make-event TapGatewayPaymentCompleted TapGatewayGenerate Payment Failed Event:
php artisan module:make-event TapGatewayPaymentFailed TapGateway9.2 Create Webhook Event
Generate Webhook Received Event:
php artisan module:make-event TapGatewayWebhookReceived TapGateway9.3 Verify Events Directory
Check Events Structure:
ls -la Events/Expected Output:
total XX
drwxr-xr-x X user user XXX MMM DD HH:MM .
drwxr-xr-x X user user XXX MMM DD HH:MM ..
-rw-r--r-- 1 user user XXX MMM DD HH:MM TapGatewayPaymentCompleted.php
-rw-r--r-- 1 user user XXX MMM DD HH:MM TapGatewayPaymentFailed.php
-rw-r--r-- 1 user user XXX MMM DD HH:MM TapGatewayPaymentStarted.php
-rw-r--r-- 1 user user XXX MMM DD HH:MM TapGatewayWebhookReceived.phpStep 10: Create API Resources
10.1 Create Payment Resource
Generate Payment Resource:
php artisan module:make-resource TapGatewayPaymentResource TapGatewayExpected Output:
Resource [TapGatewayPaymentResource] created successfully.10.2 Create Transaction Collection
Generate Transaction Collection:
php artisan module:make-resource TapGatewayTransactionCollection TapGatewayExpected Output:
Resource [TapGatewayTransactionCollection] created successfully.10.3 Verify Resources Directory
Check Resources Structure:
ls -la Http/Resources/Expected Output:
total XX
drwxr-xr-x X user user XXX MMM DD HH:MM .
drwxr-xr-x X user user XXX MMM DD HH:MM ..
-rw-r--r-- 1 user user XXX MMM DD HH:MM TapGatewayPaymentResource.php
-rw-r--r-- 1 user user XXX MMM DD HH:MM TapGatewayTransactionCollection.phpStep 11: Create Tests
11.1 Create Feature Tests
Generate Payment Feature Test:
php artisan module:make-test TapGatewayPaymentTest TapGatewayGenerate Admin Settings Feature Test:
php artisan module:make-test Admin/TapGatewaySettingsTest TapGateway11.2 Create Unit Tests
Generate Service Unit Test:
php artisan module:make-test Services/TapGatewayServiceTest TapGateway --unitGenerate Model Unit Test:
php artisan module:make-test Models/TapGatewayTransactionTest TapGateway --unit11.3 Verify Tests Directory
Check Tests Structure:
find Tests -name "*.php" -type fExpected Output:
Tests/Feature/Admin/TapGatewaySettingsTest.php
Tests/Feature/TapGatewayPaymentTest.php
Tests/Unit/Models/TapGatewayTransactionTest.php
Tests/Unit/Services/TapGatewayServiceTest.phpStep 12: Create Additional Components
12.1 Create Mail Classes
Generate Payment Confirmation Mail:
php artisan module:make-mail TapGatewayPaymentConfirmation TapGatewayGenerate Payment Failed Mail:
php artisan module:make-mail TapGatewayPaymentFailed TapGateway12.2 Create Notifications
Generate Payment Notification:
php artisan module:make-notification TapGatewayPaymentNotification TapGateway12.3 Create Custom Commands
Generate Sync Command:
php artisan module:make-command SyncTapGatewayPayments TapGatewayGenerate Health Check Command:
php artisan module:make-command TapGatewayHealthCheck TapGateway12.4 Create Seeders
Generate Settings Seeder:
php artisan module:make-seeder TapGatewaySettingsSeeder TapGatewayGenerate Main Database Seeder:
php artisan module:make-seeder TapGatewayDatabaseSeeder TapGatewayStep 13: Verify Complete Module Structure
13.1 Check Complete Directory Tree
Generate Complete Directory Tree:
cd Modules/TapGateway
treeExpected Complete Structure:
.
composer.json
module.json
package.json
README.md
TapGateway.php
vite.config.js
Config/
config.php
Console/
SyncTapGatewayPayments.php
TapGatewayHealthCheck.php
Database/
Factories/
TapGatewayRefundFactory.php
TapGatewayWebhookLogFactory.php
Migrations/
[timestamp]_create_tap_gateway_transactions_table.php
[timestamp]_create_tap_gateway_refunds_table.php
[timestamp]_create_tap_gateway_webhook_logs_table.php
[timestamp]_add_tap_gateway_payment_settings.php
Seeders/
TapGatewayDatabaseSeeder.php
TapGatewaySettingsSeeder.php
TapGatewayWebhookLogSeeder.php
Events/
TapGatewayPaymentCompleted.php
TapGatewayPaymentFailed.php
TapGatewayPaymentStarted.php
TapGatewayWebhookReceived.php
Http/
Controllers/
TapGatewayController.php
Admin/
TapGatewaySettingsController.php
Api/
TapGatewayApiController.php
PaymentGateways/
TapGatewayController.php
Middleware/
TapGatewayVerifyPayment.php
TapGatewayVerifyWebhook.php
Requests/
TapGatewayPaymentRequest.php
Admin/
TapGatewaySettingsRequest.php
Resources/
TapGatewayPaymentResource.php
TapGatewayTransactionCollection.php
Jobs/
ProcessTapGatewayPayment.php
ProcessTapGatewayWebhook.php
SendTapGatewayNotification.php
Listeners/
AddTapGatewayPaymentSettings.php
ExtendPaymentSettings.php
RegisterTapGateway.php
Livewire/
Mail/
TapGatewayPaymentConfirmation.php
TapGatewayPaymentFailed.php
Models/
TapGatewayRefund.php
TapGatewayTransaction.php
TapGatewayWebhookLog.php
Notifications/
TapGatewayPaymentNotification.php
Providers/
RouteServiceProvider.php
TapGatewayServiceProvider.php
resources/
assets/
css/
app.css
js/
app.js
lang/
en.json
tenant_en.json
views/
index.blade.php
Routes/
api.php
web.php
Services/
TapGatewayPaymentGateway.php
TapGatewayService.php
TapGatewayValidationService.php
TapGatewayWebhookService.php
Tests/
Feature/
TapGatewayPaymentTest.php
Admin/
TapGatewaySettingsTest.php
Unit/
Models/
TapGatewayTransactionTest.php
Services/
TapGatewayServiceTest.php13.2 Count Generated Files
Count All Generated Files:
find . -name "*.php" -type f | wc -lExpected Count: Approximately 40-50 PHP files (depending on additional components created)
Step 14: Module Activation and Management
14.1 Check Module Status
List All Modules:
cd ../../ # Return to Laravel root directory
php artisan module:listExpected Output:
+-------------+---------+----------+----------+---------+
| Name | Status | Order | Path | Version |
+-------------+---------+----------+----------+---------+
| TapGateway | Disabled| 0 | Modules/ | 1.0.0 |
+-------------+---------+----------+----------+---------+14.2 Enable the Module
Enable TapGateway Module:
php artisan module:enable TapGatewayExpected Output:
Module [TapGateway] enabled successfully.14.3 Verify Module Status
Check Module Status Again:
php artisan module:listExpected Output:
+-------------+---------+----------+----------+---------+
| Name | Status | Order | Path | Version |
+-------------+---------+----------+----------+---------+
| TapGateway | Enabled | 0 | Modules/ | 1.0.0 |
+-------------+---------+----------+----------+---------+14.4 Show Module Details
Display Module Information:
php artisan module:show TapGatewayExpected Output:
****************************************
Name : TapGateway
Alias : tap-gateway
Status : Enabled
Order : 0
Path : Modules/TapGateway
Namespace : Modules\TapGateway\
Provider : Modules\TapGateway\Providers\TapGatewayServiceProvider
****************************************Step 15: Cache Management and Optimization
15.1 Clear All Caches
After module creation and activation, clear all application caches:
Clear Application Cache:
php artisan cache:clearExpected Output:
Application cache cleared!Clear Configuration Cache:
php artisan config:clearExpected Output:
Configuration cache cleared!Clear Route Cache:
php artisan route:clearExpected Output:
Route cache cleared!Clear View Cache:
php artisan view:clearExpected Output:
Compiled views cleared!15.2 Restart Queue Workers (if applicable)
Restart Queue Workers:
php artisan queue:restartExpected Output:
Broadcasting queue restart signal.15.3 Dump Composer Autoload
Regenerate Composer Autoload:
composer dump-autoloadExpected Output:
Generating optimized autoload files
Generated optimized autoload files containing X classesStep 16: Run Database Migrations (Optional)
16.1 Run Module Migrations
If you created migrations, run them:
Run All Migrations:
php artisan migrateRun Only Module Migrations:
php artisan module:migrate TapGateway16.2 Run Module Seeders (Optional)
Run Module Seeders:
php artisan module:seed TapGatewayStep 17: Testing and Verification
17.1 Test Route Registration
Check Route List:
php artisan route:list | grep -i tapExpected: Should show any routes defined in the module's route files.
17.2 Test Module Autoloading
Test Namespace Autoloading:
php artisan tinker// In Tinker console
use Modules\TapGateway\Services\TapGatewayService;
$service = new TapGatewayService();
exit;Expected: No errors if autoloading is working correctly.
17.3 Run Module Tests (if created)
Run Module Tests:
php artisan test Modules/TapGateway/Tests/Step 18: Development Best Practices
18.1 Module Development Workflow
Recommended Development Cycle:
- Generate Components: Use Artisan commands to create new components
- Clear Caches: Clear caches after structural changes
- Test Changes: Test functionality after each major change
- Commit Changes: Use version control for all changes
- Document Changes: Update module documentation
18.2 Common Commands Reference
Essential Module Commands:
# Module Status
php artisan module:list
php artisan module:show ModuleName
# Module Management
php artisan module:enable ModuleName
php artisan module:disable ModuleName
# Component Generation
php artisan module:make-controller ControllerName ModuleName
php artisan module:make-model ModelName ModuleName -m
php artisan module:make-service ServiceName ModuleName
# Database Operations
php artisan module:migrate ModuleName
php artisan module:seed ModuleName
# Cache Management
php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clearTroubleshooting Common Issues
Issue 1: Module Not Appearing in List
Problem: Module doesn't appear when running php artisan module:list
Solutions:
- Check
module.jsonexists and is valid JSON - Verify module is in correct directory structure
- Run
composer dump-autoload - Clear configuration cache:
php artisan config:clear
Issue 2: Autoloading Problems
Problem: Classes not found when trying to use module components
Solutions:
- Check
composer.jsonautoload section - Verify namespace matches directory structure
- Run
composer dump-autoload - Check file and directory permissions
Issue 3: Routes Not Working
Problem: Module routes not accessible
Solutions:
- Verify routes are defined in
Routes/web.phporRoutes/api.php - Check route service provider is registered
- Clear route cache:
php artisan route:clear - Ensure module is enabled
Issue 4: Views Not Found
Problem: Blade views not found or not rendering
Solutions:
- Check views are in correct directory:
resources/views/ - Verify view namespace registration in service provider
- Clear view cache:
php artisan view:clear - Check view file names and extensions
Next Steps
After completing this tutorial, you should have:
Complete Module Structure: Fully generated payment gateway module All Core Components: Controllers, services, models, and more Proper Configuration: Module properly configured and activated Working Environment: Caches cleared and autoloading functional
Continue Your Learning
- Payment Gateway Guide - Implement actual payment processing logic
- Module Structure Guide - Deep dive into module architecture
- Advanced Topics - Advanced patterns and best practices
Implementation Checklist
- [ ] Implement payment gateway interface
- [ ] Configure payment settings
- [ ] Create admin configuration pages
- [ ] Implement webhook handlers
- [ ] Add proper error handling
- [ ] Create comprehensive tests
- [ ] Add logging and monitoring
- [ ] Document API endpoints
IMPORTANT REMINDER
This tutorial showed you how to generate the complete module structure. The next step is implementing the actual payment gateway functionality using the Payment Gateway Guide.
Congratulations! You've successfully created a complete payment gateway module structure. The module is now ready for payment gateway implementation and customization.
Need help? Check our FAQ section or join the Developer Community.