README

SISP Core is a headless, framework-agnostic Laravel 12+ package for integrating the SISP (Sistema Interbancário de Pagamentos) Cabo Verde payment gateway. It provides comprehensive transaction management, automatic PDF invoice generation, fraud detection, and complete payment lifecycle handling.

This is the core package - it handles all backend logic, database operations, and business rules. For frontend integration, see:

sisp-inertia-react - React/Inertia.js UI components
sisp-blade - Traditional Blade views

Quick Start

composer require akira/laravel-sisp
php artisan laravel-sisp:install

Configure your .env:

SISP_URL=https://mc.vinti4net.cv/Client_VbV_v2/biz_vbv_clientdata.jsp
SISP_POS_ID=your_pos_id
SISP_POS_AUT_CODE=your_authorization_code
SISP_MERCHANT_ID=your_merchant_id

Documentation Index

Getting Started

Installation - Install and configure the package
Configuration - Configure SISP credentials and options
Quick Start Guide - Create your first payment in 5 minutes

Core Concepts

Payment Flow - Complete payment process overview
Transaction Management - Create and manage transactions
Invoice Generation - Auto-generate PDF invoices after payments

Features & Security

Security - Rate limiting, metadata collection, fraud detection

Learning & Reference

Examples - Real-world integration examples and code samples
API Reference - Complete API methods and classes
FAQ - Frequently asked questions
Troubleshooting - Common issues and solutions

Key Features

Multi-merchant/SaaS support with runtime credential injection
Payment form rendering (Blade or Inertia.js)
Automatic PDF invoice generation
Multi-item transaction support
Comprehensive rate limiting
Security metadata collection
Complete transaction audit trail
Webhook signature verification
Type-safe DTOs and builders

System Requirements

PHP 8.4 or higher
Laravel 12 or higher
PostgreSQL or MySQL database
Node.js for frontend assets (if using Inertia)

What's Included

After installation, you get:

Service provider and service container bindings
Database migrations for transactions, invoices, and security tables
Payment routes and webhook handling
Blade views or Inertia.js components for payment forms
Invoice generation via Laravel PDF Invoices package
Rate limiting middleware
Security metadata collection

Package Structure

laravel-sisp/
├── src/
│   ├── Actions/              # Business logic
│   ├── Controllers/          # HTTP controllers
│   ├── DTO/                  # Data transfer objects
│   ├── Models/               # Eloquent models
│   ├── Facades/              # Facade classes
│   ├── Middleware/           # HTTP middleware
│   └── Providers/            # Service providers
├── database/
│   ├── migrations/           # Database migrations
│   └── factories/            # Model factories
├── resources/
│   ├── views/                # Blade templates
│   └── components/           # Vue/React components
├── config/
│   └── sisp.php             # Package configuration
└── docs/                     # This documentation

Next Steps

Start with Installation
Follow Configuration for your setup
Try the Quick Start Guide
Read Payment Flow to understand the process

Support

For issues or questions:

Check Troubleshooting
Review Examples
Read API Reference
Visit FAQ for common questions

License

MIT License. See LICENSE file for details.

Testing & Coverage

Run full test suite with code coverage at exactly 100%:
- vendor/bin/pest --parallel --coverage --compact --exactly=100
Enforce 100% type coverage:
- vendor/bin/pest --type-coverage --min=100

Driving sisp:install in tests (no TTY, no mocks)

In tests, interactive prompts for sisp:install are controlled by config flags under sisp.tests.*. These flags are only read when app()->runningUnitTests() is true. In normal usage the command remains fully interactive.

Available toggles (bool):

sisp.tests.publish_config / sisp.tests.force_config
sisp.tests.publish_migrations / sisp.tests.force_migrations
sisp.tests.publish_inertia / sisp.tests.force_inertia
sisp.tests.publish_blade / sisp.tests.force_blade
sisp.tests.run_migrations – whether to run migrations step
sisp.tests.fake_migrate – short-circuit actual migrate call in tests (defaults to true)
sisp.tests.give_star – whether to show the “give a star” note

Example (Pest test):

config()->set('sisp.tests.publish_config', true);
config()->set('sisp.tests.publish_migrations', true);
config()->set('sisp.tests.run_migrations', true);
config()->set('sisp.tests.fake_migrate', true); // don’t run real migrations again
config()->set('sisp.tests.publish_inertia', false); // avoid vendor:publish in CI
config()->set('sisp.tests.publish_blade', false);

This keeps tests stable and fast in parallel CI runs while allowing full branch coverage without using mocks.

akira / sisp-core

Maintainers

Details