Complete Business Flow

The Add-on Services system operates on a comprehensive credit-based model with multiple interconnected workflows.

High-Level Business Process

graph TD
    A[User Views Services Dashboard] --> B{Service Status Check}
    B -->|Service Disabled| C[Display Disabled Message]
    B -->|Service Active| D[Show Current Credits & Threshold]
    D --> E{Credit Level Check}
    E -->|Healthy| F[Allow Service Usage]
    E -->|Low/Empty| G[Show Top-up Warning]
    G --> H[Navigate to Pricing Plans]
    H --> I[Select Pricing Plan]
    I --> J[Generate Invoice]
    J --> K[Choose Payment Method]
    K -->|MPesa| L[STK Push Payment]
    K -->|Card| M[Card Gateway Payment]
    K -->|Complimentary| N[Admin Credit Grant]
    L --> O[Payment Verification]
    M --> O
    N --> P[Credits Added to Account]
    O -->|Success| P
    O -->|Failed| Q[Payment Failed]
    P --> R[User Consumes Service]
    R --> S[Credits Deducted]
    S --> T{Threshold Check}
    T -->|Below Threshold| U[Send Low Credit Alert]
    T -->|Above Threshold| V[Continue Normal Usage]
    U --> G
    V --> R
    F --> R

Detailed Workflow Stages

0. Create Service and Pricing Plans/Rates on Portal

Product Item:

Create product item on Portal (e.g.SMSs, EvaDocs pages) https://portal.solutechlabs.com/billing/product-items/list
Create product item (pricing) plan for the product item just created https://portal.solutechlabs.com/billing/product-item-plans/list
Sync product item to a client

1. Service Discovery & Status Check

User Journey:

User accesses add-on services dashboard
System displays available services with current status
Real-time credit balances and threshold indicators shown
Services can be temporarily disabled via configuration

System Actions:

Query active service subscriptions
Check service disable configuration
Calculate current credit balances
Evaluate threshold status for each service
Display service cards with status indicators

2. Credit Purchase Flow

Step-by-Step Process:

Plan Selection

User selects service requiring credits
System shows available pricing plans (bundles or rates)
User chooses between:
- Bundle Plans: Fixed quantity for fixed price (e.g., 100 SMS for KES 500)
- Rate Plans: Pay-per-use with transparent unit costs (e.g., KES 5 per SMS)

Invoice Generation

System validates selected plan
Creates proforma invoice
Generates PDF document
Stores invoice record with "Pending" status

Payment Processing

User selects payment method:
- MPesa: STK push to mobile phone
Payment gateway processes transaction
System receives payment confirmation
Invoice status updated to "Closed"

Credit Allocation

Payment verification completed
Credits added to user's service account
Invoice marked as paid
User notified of successful credit purchase

3. Service Consumption Pattern

Credit Usage Flow:

Pre-consumption Validation

// Example: SMS service consumption
$check = (new CheckCreditsAddOnServiceService('SMS Messaging', $sms_count))->handle();

if (!$check['status']) {
    throw new InsufficientCreditsException();
}

Credit Hold Mechanism

For services requiring confirmation (like SMS delivery):

Hold Credits: Reserve credits for pending operations
Execute Service: Perform the actual service (send SMS, process document)
Confirm or Release:
- Success: Convert held credits to consumed credits
- Failure: Release held credits back to available balance

FIFO Credit Consumption

Credits are consumed on a First-In-First-Out basis:

Oldest purchased credits are used first
Prevents credit expiration issues
Maintains fair usage across multiple purchases

4. Threshold Monitoring & Alerts

Continuous Monitoring:

Real-time monitoring during credit consumption
Scheduled threshold checks via cron jobs
Configurable threshold values per service

Alert Triggers:

Real-time: When credits are consumed and fall below threshold
Scheduled: Cron job checks all accounts every 15 minutes
Manual: Admin-initiated threshold checks

Notification Levels:

Healthy: Credits above threshold
Low: Credits at or below threshold but greater than zero
Empty: No credits remaining

Business Rules & Constraints

Service Enable/Disable Logic

Services can be disabled per service type via configuration:

// Service disable check in CheckCreditsAddOnServiceService
public function disable(): bool
{
    $service_key = str_replace(' ', '_', strtolower($this->addon_service_key));
    $general_setting = config("settings.disable_addons_for_{$service_key}");

    return !is_null($general_setting) && $general_setting == 'yes';
}

// Examples:
// disable_addons_for_sms_messaging = 'yes'
// disable_addons_for_eva_docs = 'yes'

When Service is Disabled:

Users can view existing credit balances
Credit purchases remain allowed
Credit consumption is blocked with appropriate messaging
Service appears in interface but marked as disabled

Credit Hold & Release Mechanism

Hold Credits (Async Operations):

// Hold credits for SMS sending
(new RemoveCreditsFromAddOnServiceService(
        addon_service_key: $service_key, 
        credits_to_remove: $sms_count, 
        hold: true
))->handle();

Release Credits (Failure):

// Return held credits to available balance
(new RemoveCreditsFromAddOnServiceService(
    addon_service_key: $service_key, 
    credits_to_remove: $sms_count
))->release();

Pricing Plan Types

Bundle Plans (`rate_type = 'pricing_plan'`)

Fixed quantity for fixed price
Example: 100 SMS for KES 500
Popular for bulk usage scenarios
Often marked as "Recommended"

Rate Plans (`rate_type = 'rate'`)

Pay-per-use with transparent unit costs
Example: KES 5 per SMS
Flexible for variable usage
Dynamic quantity selection

Error Handling in Business Flow

Payment Failures

STK Push Timeout: User prompted to retry or contact support
Payments Error: User notified of error and allowed to try again

Credit Consumption Failures

Insufficient Credits: User redirected to purchase more credits
Service Disabled: Clear messaging with alternative options
System Errors: Credits held are automatically released #

This comprehensive business flow ensures smooth operation of the Add-on Services system while providing flexibility for various business scenarios and maintaining excellent user experience.

Business Flow

On this page