Open Flow Laravel SDK

Description

Open Flow Laravel SDK is a Laravel 13-based payment integration project that provides a unified API for processing payments through multiple gateways (currently PayChangu).

It solves the problem of gateway-specific integration complexity by introducing a shared gateway contract, a gateway factory, and a core payment processor that standardizes transaction persistence and event dispatching.

Key value proposition

• One HTTP endpoint for multiple payment providers.
• Consistent transaction records in your database.
• Extensible architecture for adding new gateways.

Features

• Unified payment processing API (POST /api/v1/pay).
• Pluggable gateway architecture via GatewayInterface.
• Built-in Stripe gateway integration.
• Built-in Malipo gateway integration.
• Transaction persistence with UUID primary keys.
• Payment processed event dispatch (PaymentProcessed).
• Laravel Telescope integration for application observability.
• Laravel WorkOS-based authentication flow for dashboard/settings routes.

Tech Stack

• Backend: PHP 8.3+, Laravel 13
• Auth/session tooling: Laravel WorkOS
• UI stack: Livewire 4 (Flux), Blade (Volt migrated to Single-File Components)
• Frontend build: Vite 6, Tailwind CSS 4
• Payments: Stripe PHP SDK, HTTP integration for Malipo
• Observability: Laravel Telescope, Opcodes Log Viewer
• Testing: Pest 5 + Laravel testing utilities (PHPUnit 13 runner)

Installation

Prerequisites

• PHP 8.3+ (Required by Laravel 13)
• Composer
• Node.js + npm
• A database supported by Laravel (SQLite/MySQL/PostgreSQL, etc.)

Step-by-step setup

1. Clone the repository:

   git clone <your-repo-url>
   cd open-flow-laravel-sdk

2. Install PHP dependencies:

   composer install

3. Install JavaScript dependencies:

   npm install

4. Create your environment file.

   Assumption: this repository does not currently include a committed .env.example, so create .env manually (or copy from your team template) and populate required values listed in the Configuration section. Ensure you configure explicit session cookies and cache prefixes to prevent framework migration drops.

5. Generate application key:

   php artisan key:generate

6. Run database migrations:

   php artisan migrate

7. Start local development services:

   composer run dev

Usage

Run the application

• Full local dev workflow (app server, queue worker, log tailing, vite):

  composer run dev

• Alternative split commands:

  php artisan serve
  php artisan queue:listen --tries=1
  npm run dev

Build frontend assets

npm run build

Process a payment (API)

Endpoint:

POST /api/v1/pay
Content-Type: application/json

Stripe example

curl -X POST http://localhost:8000/api/v1/pay \
  -H "Content-Type: application/json" \
  -d '{
    "gateway": "stripe",
    "amount": 5000,
    "currency": "USD",
    "source": "tok_visa",
    "description": "Order #1001"
  }'

Malipo example

curl -X POST http://localhost:8000/api/v1/pay \
  -H "Content-Type: application/json" \
  -d '{
    "gateway": "malipo",
    "amount": 2500,
    "customerPhone": "265991234567",
    "bankId": 1,
    "description": "Wallet top-up"
  }'

Project Structure

app/
  Events/                    # Domain events (e.g., PaymentProcessed)
  Http/Controllers/          # Request handlers (PaymentController)
  Models/                    # Eloquent models (Transaction, User)
  Payments/
    Gateways/                # Gateway implementations (Stripe, Malipo)
    CoreProcessor.php        # Gateway-agnostic payment orchestration
    GatewayFactory.php       # Gateway resolver
    GatewayInterface.php     # Contract for all gateways
config/
  livewire.php               # Livewire 4 configuration & layout setups
  openflow.php               # Payment gateway configuration
database/
  migrations/                # Schema definitions (includes transactions table)
routes/
  web.php                    # Web + API routes (using native Livewire routing)
tests/                       # Unit and feature tests (Pest 5)

Configuration

The project uses Laravel environment/config conventions.

Required payment-related environment variables

Set these in .env:

# Stripe
STRIPE_SECRET=

# Malipo
MALIPO_API_KEY=
MALIPO_APP_ID=
MALIPO_BASE_URL=

Authentication/session (WorkOS)

WORKOS_CLIENT_ID=
WORKOS_API_KEY=
WORKOS_REDIRECT_URL=

Framework Upgrade Fallbacks (Important)

Laravel 13 updates key defaults. Pin these in .env to prevent losing session state during deployments:

CACHE_PREFIX="myapp_cache"
SESSION_COOKIE="myapp_session"

Optional observability variables

TELESCOPE_ENABLED=true
TELESCOPE_PATH=telescope

API Documentation

High-level overview

• Base path: /api/v1
• Primary endpoint: POST /pay
• Controller: App\Http\Controllers\PaymentController

Request behavior

• gateway must be stripe or malipo.
• Stripe requests require: amount, currency, source.
• Malipo requests require: amount, customerPhone (optional bankId).

Contributing

Contributions are welcome.

1. Fork the repository.
2. Create a feature branch.
3. Make your changes with tests.
4. Run formatting and tests (vendor/bin/pint and php artisan test).
5. Open a pull request.

Testing

Run the test suite:

php artisan test

Or run Pest directly:

./vendor/bin/pest

Deployment

This is a standard Laravel deployment model.

Typical production steps:

1. Ensure the hosting server environment runs PHP 8.3+.
2. Set production .env values (including CACHE_PREFIX and SESSION_COOKIE).
3. Install dependencies (composer install --no-dev, npm ci && npm run build).
4. Run migrations (php artisan migrate --force).
5. Set correct file permissions for storage/ and bootstrap/cache/.
6. Configure queue workers and scheduler as needed.

License

This project is licensed under the MIT License (per composer.json).

Author / Maintainers

• Current maintainers: @innocentmisheck