README

Laravel SISP is a Laravel package for SISP Cabo Verde payment flows, with transaction management, invoice generation, callback validation, sandbox tooling, and multi-merchant credential support.

Install

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

{
  "require": {
    "akira/laravel-sisp": "^2.0"
  }
}

Quick Start

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
SISP_SANDBOX=true

<form action="{{ route('sisp.payment') }}" method="POST">
    @csrf

    <input type="number" name="amount" required>
    <input type="text" name="items[0][product_name]" required>
    <input type="number" name="items[0][quantity]" required>
    <input type="number" name="items[0][unit_price]" required>
    <input type="number" name="items[0][total_price]" required>
    <input type="email" name="customer_email">

    <button type="submit">Pay</button>
</form>

Use the facade when application code needs lower-level package operations:

use Akira\Sisp\Facades\Sisp;

$transaction = Sisp::reconcileTransactionStatus($transaction);
$countries = Sisp::countries();

Requirements (v2)

• PHP 8.5+
• Laravel 13+

Architecture (v2)

Version 2 is built on four explicit patterns. Each one is an extension point.

Builders

Compose payment and refund requests fluently instead of assembling value objects by hand:

use Akira\Sisp\Facades\Sisp;

$paymentRequest = Sisp::payment()
    ->amount(1500.0)
    ->currency('132')
    ->customerEmail('buyer@example.cv')
    ->locale('pt')
    ->build();

$transaction = Sisp::refund($transaction)
    ->amount(500.0)
    ->reason('partial_return')
    ->process();

Drivers

Gateway interactions go through a driver resolved by SispManager. The production driver targets the live Vinti4 gateway and the sandbox driver targets the local simulator. Selection follows config('sisp.driver'), falling back to the resolved credentials' sandbox flag. Register custom gateways with SispManager::extend():

use Akira\Sisp\Drivers\SispManager;

resolve(SispManager::class)->extend('custom', fn () => new CustomDriver());

Pipelines

The payment and callback flows run through Laravel pipelines. Every stage is a small, single-purpose pipe, and the stages are configurable in config/sisp.php under pipelines.payment and pipelines.callback, so you can reorder, remove, or append your own pipes:

'pipelines' => [
    'payment' => [
        EnsureIpIsNotBlacklisted::class,
        EnforceRateLimits::class,
        BuildPaymentRequest::class,
        PersistTransaction::class,
        CaptureRequestMetadata::class,
        YourCustomPipe::class, // implements Akira\Sisp\Contracts\PaymentPipe
    ],
],

Actions

Every unit of work remains a dedicated, final, constructor-injected action class with a single handle() method. Pipes and builders delegate to actions, and actions depend on contracts, never on concrete infrastructure.

The package also uses native Laravel 13 syntax throughout: #[Fillable], #[UseFactory], and #[Scope] attributes on Eloquent models, #[Signature] and #[Description] on console commands, and #[Bind]/#[Singleton] container attributes on contracts and services.

Documentation

• Roadmap
• Installation
• Configuration
• Quick Start
• Payment Flow
• Transaction Management
• Invoice Generation
• Security
• Examples
• Troubleshooting
• FAQ
• API Reference
• Architecture (v2)
• Upgrade Guide (1.x → 2.0)
• Idempotency

Reference documentation is maintained in this repository under docs.

Testing

composer test

Additional focused checks are available through Composer scripts:

composer test:coverage
composer test:type-coverage
composer test:types
composer test:lint

Changelog

See CHANGELOG.md for release history. Releases are generated with git-cliff.

Contributing

See CONTRIBUTING.md for local setup, test expectations, commit style, and pull request guidance.

Security

Report security issues through the process documented in SECURITY.md.

Credits

Laravel SISP is maintained by Kidiatoliny and the Akira team. Contributor recognition is managed through All Contributors.

License

Laravel SISP is dual-licensed under MIT or Apache-2.0. Unless you state otherwise, contributions are licensed under both licenses.