Laravel OfficeGuy Payment Gateway Package

A comprehensive Laravel package for integrating SUMIT (OfficeGuy) payment gateway with invoice creation, credit card token storage, and secure transaction processing. This package is a complete conversion of the WooCommerce plugin to a Laravel 12+ compatible package.

🚀 Quick Start: See QUICKSTART.md for a 5-minute setup guide.

Features

• 🔒 Secure Payment Processing - PCI-compliant credit card processing
• 💳 Token Management - Store and manage payment tokens securely
• 📄 Invoice Generation - Automatic invoice/receipt creation
• 🔄 Subscription Support - Recurring payment handling
• 📦 Stock Synchronization - Inventory sync with SUMIT
• 🎯 Event System - Laravel events for payment lifecycle
• 🔗 Webhook Support - Handle payment callbacks
• 🌐 Multi-currency - Support for ILS, USD, EUR, GBP
• 📊 Payment Tracking - Complete payment history and logging

Requirements

• PHP 8.1 or higher
• Laravel 11.x or 12.x
• MySQL/PostgreSQL database
• SUMIT account with API credentials

Installation

1. Install via Composer

composer require nm-digitalhub/laravel-officeguy

2. Publish Configuration

php artisan vendor:publish --tag=officeguy-config

This will create a config/officeguy.php file where you can customize the package settings.

3. Publish Migrations

php artisan vendor:publish --tag=officeguy-migrations

4. Run Migrations

php artisan migrate

This will create the following tables:

• officeguy_payment_tokens - Stores payment tokens
• officeguy_payments - Payment transaction records
• officeguy_customers - Customer information
• officeguy_stock_sync_logs - Stock synchronization logs

5. Configure Environment Variables

Add the following to your .env file:

OFFICEGUY_COMPANY_ID=your_company_id
OFFICEGUY_PRIVATE_KEY=your_private_key
OFFICEGUY_PUBLIC_KEY=your_public_key
OFFICEGUY_ENVIRONMENT=www
OFFICEGUY_MERCHANT_NUMBER=your_merchant_number

# Optional settings
OFFICEGUY_TESTING_MODE=false
OFFICEGUY_AUTHORIZE_ONLY=false
OFFICEGUY_DRAFT_DOCUMENT=false
OFFICEGUY_SEND_DOCUMENT_BY_EMAIL=true

You can find your API credentials at: https://app.sumit.co.il/developers/keys/

Configuration

The package configuration file (config/officeguy.php) contains all available settings:

• Credentials - Company ID, API keys
• Environment - Production or development
• Payment Settings - Merchant numbers, authorization settings
• Payment Limits - Maximum payments, minimum amounts
• Customer Settings - Customer merge options
• Document Settings - Language, VAT settings
• Token Settings - Token storage configuration
• Stock Settings - Inventory synchronization
• Logging - Log channel and level
• Routes - API endpoint configuration

Usage

Processing a Payment

use NmDigitalHub\LaravelOfficeGuy\Services\PaymentService;

class CheckoutController extends Controller
{
    public function processPayment(PaymentService $paymentService)
    {
        $result = $paymentService->processPayment([
            'amount' => 100.00,
            'currency' => 'ILS',
            'user_id' => auth()->id(),
            'order_id' => 12345,
            'description' => 'Order #12345',
            'customer' => [
                'name' => 'John Doe',
                'email' => 'john@example.com',
                'phone' => '0501234567',
                'address' => '123 Main St',
                'city' => 'Tel Aviv',
            ],
            'single_use_token' => $request->input('payment_token'),
            'save_token' => true,
        ]);

        if ($result['success']) {
            return redirect()->route('payment.success')
                ->with('payment_id', $result['payment']->id);
        }

        return back()->with('error', $result['error']);
    }
}

Creating a Payment Token

use NmDigitalHub\LaravelOfficeGuy\Services\TokenService;

class PaymentMethodController extends Controller
{
    public function addCard(TokenService $tokenService, Request $request)
    {
        $result = $tokenService->createToken([
            'user_id' => auth()->id(),
            'single_use_token' => $request->input('token'),
            'set_as_default' => true,
        ]);

        if ($result['success']) {
            return response()->json([
                'message' => 'Card added successfully',
                'token' => $result['token'],
            ]);
        }

        return response()->json([
            'error' => $result['error']
        ], 400);
    }
}

Subscription Payment

use NmDigitalHub\LaravelOfficeGuy\Services\SubscriptionService;

class SubscriptionController extends Controller
{
    public function processSubscription(SubscriptionService $subscriptionService)
    {
        $result = $subscriptionService->createSubscription([
            'user_id' => auth()->id(),
            'amount' => 99.00,
            'currency' => 'ILS',
            'description' => 'Monthly Subscription',
            'customer' => [
                'name' => auth()->user()->name,
                'email' => auth()->user()->email,
            ],
            'single_use_token' => $request->input('token'),
        ]);

        if ($result['success']) {
            // Store subscription details
            return redirect()->route('subscription.success');
        }

        return back()->with('error', $result['error']);
    }
}

Stock Synchronization

use NmDigitalHub\LaravelOfficeGuy\Services\StockService;

class StockController extends Controller
{
    public function syncStock(StockService $stockService)
    {
        $result = $stockService->updateStock(forceSync: true);

        return response()->json($result);
    }
}

Using the Facade

use NmDigitalHub\LaravelOfficeGuy\Facades\OfficeGuy;

// Process payment
$result = OfficeGuy::processPayment($paymentData);

// Create token
$result = OfficeGuy::createToken($tokenData);

// Update stock
$result = OfficeGuy::updateStock();

Events

The package dispatches the following events:

PaymentProcessed

Fired when a payment is successfully processed.

use NmDigitalHub\LaravelOfficeGuy\Events\PaymentProcessed;

Event::listen(PaymentProcessed::class, function ($event) {
    // $event->payment - Payment model
    // $event->response - API response
    
    // Send confirmation email, update order, etc.
});

PaymentFailed

Fired when a payment fails.

use NmDigitalHub\LaravelOfficeGuy\Events\PaymentFailed;

Event::listen(PaymentFailed::class, function ($event) {
    // $event->payment - Payment model
    // $event->response - API response
    
    // Log failure, notify admin, etc.
});

TokenCreated

Fired when a payment token is created.

use NmDigitalHub\LaravelOfficeGuy\Events\TokenCreated;

Event::listen(TokenCreated::class, function ($event) {
    // $event->token - PaymentToken model
    
    // Update user preferences, send notification, etc.
});

StockSynced

Fired when stock synchronization completes.

use NmDigitalHub\LaravelOfficeGuy\Events\StockSynced;

Event::listen(StockSynced::class, function ($event) {
    // $event->updatedCount - Number of products updated
    // $event->failedCount - Number of failed updates
    
    // Log results, notify admin, etc.
});

API Routes

The package registers the following API routes (prefix: /api/officeguy):

Payment Routes

• POST /payments - Process a payment
• GET /payments - List user payments
• GET /payments/{id} - Get payment details
• POST /payments/{id}/refund - Refund a payment

Token Routes

• POST /tokens - Create a payment token
• GET /tokens - List user tokens
• DELETE /tokens/{id} - Delete a token
• POST /tokens/{id}/set-default - Set token as default

Stock Routes

• POST /stock/sync - Trigger stock synchronization
• GET /stock/logs - Get sync logs
• GET /stock/status - Get sync status

Webhook Routes

• POST /webhook - Handle payment webhooks
• GET /redirect - Handle payment redirects

Models

Payment

use NmDigitalHub\LaravelOfficeGuy\Models\Payment;

// Find payment
$payment = Payment::find($id);

// Check status
if ($payment->isSuccessful()) {
    // Payment completed
}

// Get payments
$payments = Payment::successful()->get();
$subscriptionPayments = Payment::subscription()->get();

PaymentToken

use NmDigitalHub\LaravelOfficeGuy\Models\PaymentToken;

// Get user tokens
$tokens = PaymentToken::forUser($userId)->get();

// Get default token
$defaultToken = PaymentToken::forUser($userId)->default()->first();

// Check expiry
if ($token->isExpired()) {
    // Token expired
}

Customer

use NmDigitalHub\LaravelOfficeGuy\Models\Customer;

// Find by email
$customer = Customer::byEmail('john@example.com')->first();

// Get full address
$address = $customer->full_address;

Migration from WooCommerce Plugin

If you're migrating from the WooCommerce plugin, here's a mapping of key components:

Testing

Run the package tests:

composer test

Security

• Never store raw credit card data
• All card data is tokenized via SUMIT's API
• Use HTTPS in production
• Validate webhook signatures
• Log all payment attempts
• Regular security audits recommended

Support

For support and bug reports:

• GitHub Issues: https://github.com/nm-digitalhub/laravel-officeguy
• Email: info@nm-digitalhub.com
• SUMIT Support: https://help.sumit.co.il

License

MIT License. See LICENSE file for details.

Credits

Developed by NM Digital Hub Based on the WooCommerce OfficeGuy Plugin