Missio ERP + Gusto Payroll Integration

1 Executive Summary

Missio ERP has a fully functional employee/HR module, time management system, and fund-based budget/accounting system. The platform currently integrates with QuickBooks Online for invoice/payment sync and has an ERPNext integration in progress for General Ledger and finance. However, no payroll processing engine exists — the payroll, position control, and benefits pages are static demo UIs with hardcoded data.

Recommendation

Integrate Gusto Embedded Payroll API as the payroll calculation engine. Missio remains the system of record for employee data, time/attendance, and position management. Gusto handles all tax calculations, direct deposit, compliance filings, and benefits administration.

Why Gusto

2 Integration Architecture

System Ownership Model

3 Gusto API Authentication

3.1 Base URLs

3.2 API Versioning

Gusto uses date-based API versioning via the X-Gusto-API-Version header. Current version: 2026-02-01. Available versions: 2024-03-01, 2024-04-01, 2025-06-15, 2025-11-15, 2026-02-01.

3.3 Token Types

3.4 System Access Token Request

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "grant_type": "system_access"
}

{
  "access_token": "system_level_token_here",
  "token_type": "Bearer",
  "created_at": 1712345678,
  "expires_in": 7200
}

3.5 Company Access Token Request (Refresh)

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "grant_type": "refresh_token",
  "refresh_token": "previously_stored_refresh_token"
}

{
  "access_token": "new_company_access_token",
  "refresh_token": "new_refresh_token",  // Previous refresh token is revoked
  "company_uuid": "abc-123-def-456",
  "expires_in": 7200
}

3.6 Required OAuth Scopes

4 Gusto API Endpoints — Full Reference

Below is the complete list of Gusto API endpoints we need to integrate, organized by domain. Base URL: https://api.gusto.com/v1

4.1 Company Setup

4.2 Locations

4.3 Departments

4.4 Employees (W-2)

4.5 Employee Onboarding & Compliance

4.6 Employee Addresses

4.7 Jobs & Compensations

4.8 Terminations & Rehires

4.9 Pay Schedules & Pay Periods

4.10 Earning Types

4.11 Payroll Operations (Core)

4.12 Pay Stubs & Receipts

4.13 Benefits Administration

4.14 Garnishments

4.15 1099 Contractors

4.16 Time Off Policies

4.17 Tax & Compliance

4.18 Forms & Documents

4.19 Reporting & General Ledger

4.20 Webhooks

4.21 Bank Accounts & Payment Methods

5 Data Field Mapping (Missio → Gusto)

5.1 Employee Create/Update Mapping

5.2 Job & Compensation Mapping

5.3 Time & Attendance → Payroll Mapping

5.4 Department & Location Mapping

6 Payroll Run Lifecycle — Step-by-Step API Flow

Step 1: Get Unprocessed Payrolls from Gusto

GET /v1/companies/{company_id}/payrolls?processing_statuses=unprocessed
Authorization: Bearer {company_access_token}
X-Gusto-API-Version: 2026-02-01

[
  {
    "payroll_id": "pay_abc123",
    "pay_period": {
      "start_date": "2026-04-01",
      "end_date": "2026-04-15",
      "pay_schedule_id": "ps_xyz789"
    },
    "check_date": "2026-04-20",
    "processing_status": "unprocessed",
    "employee_compensations": [
      {
        "employee_id": "emp_001",
        "fixed_compensations": [
          { "name": "Regular", "amount": "0.00", "job_id": "job_123" }
        ],
        "hourly_compensations": [
          { "name": "Regular", "hours": "0.000", "job_id": "job_123", "compensation_multiplier": 1 },
          { "name": "Overtime", "hours": "0.000", "job_id": "job_123", "compensation_multiplier": 1.5 }
        ],
        "paid_time_off": [
          { "name": "Vacation Hours", "hours": "0.000" },
          { "name": "Sick Hours", "hours": "0.000" }
        ]
      }
      // ... one object per employee
    ]
  }
]

Step 2: Aggregate Approved Hours from Missio

The TimesheetAggregationService queries Missio's time tracking data:

// TimesheetAggregationService.php

public function aggregateForPayPeriod($startDate, $endDate): Collection
{
    return ProjectTimeLog::query()
        ->where('approved', true)
        ->whereBetween('start_time', [$startDate, $endDate])
        ->select('user_id')
        ->selectRaw('SUM(total_minutes) / 60 as total_hours')
        ->groupBy('user_id')
        ->get()
        ->map(function($row) {
            return [
                'employee_id' => $row->user->employeeDetail->gusto_employee_id,
                'regular_hours' => min($row->total_hours, 80), // 80 for semi-monthly
                'overtime_hours' => max($row->total_hours - 80, 0),
            ];
        });
}

// Also aggregate approved leaves
public function aggregateLeavesForPayPeriod($startDate, $endDate): Collection
{
    return Leave::query()
        ->where('status', 'approved')
        ->where('paid', true)
        ->whereBetween('leave_date', [$startDate, $endDate])
        ->with('type')
        ->get()
        ->groupBy('user_id');
}

Step 3: Update Payroll with Employee Hours/Earnings

PUT /v1/companies/{company_id}/payrolls/{payroll_id}
Authorization: Bearer {company_access_token}
Content-Type: application/json

{
  "employee_compensations": [
    {
      "employee_id": "emp_001",
      "fixed_compensations": [
        {
          "name": "Coaching Stipend",
          "amount": "250.00",
          "job_id": "job_123"
        }
      ],
      "hourly_compensations": [
        {
          "name": "Regular",
          "hours": "80.000",
          "job_id": "job_123"
        },
        {
          "name": "Overtime",
          "hours": "4.500",
          "job_id": "job_123"
        }
      ],
      "paid_time_off": [
        {
          "name": "Vacation Hours",
          "hours": "8.000"
        },
        {
          "name": "Sick Hours",
          "hours": "0.000"
        }
      ]
    }
    // ... repeat for all employees in this payroll
  ]
}

Step 4: Calculate Payroll (Async)

PUT /v1/companies/{company_id}/payrolls/{payroll_id}/calculate
Authorization: Bearer {company_access_token}

// Returns 202 Accepted - Gusto calculates taxes, deductions, net pay asynchronously
// Poll GET /payrolls/{payroll_id}?include=taxes,benefits,deductions to get results

GET /v1/companies/{company_id}/payrolls/{payroll_id}?include=taxes,benefits,deductions

// Response includes calculated employee_compensations with:
{
  "payroll_id": "pay_abc123",
  "processing_status": "calculated",
  "totals": {
    "company_debit": "156432.87",
    "net_pay_debit": "112345.67",
    "tax_debit": "31208.45",
    "reimbursement_debit": "1250.00",
    "child_support_debit": "450.00",
    "benefits_debit": "11178.75"
  },
  "employee_compensations": [
    {
      "employee_id": "emp_001",
      "gross_pay": "4500.00",
      "net_pay": "3245.67",
      "taxes": [
        { "name": "Federal Income Tax", "amount": "540.00", "employer": false },
        { "name": "Social Security", "amount": "279.00", "employer": false },
        { "name": "Social Security", "amount": "279.00", "employer": true },
        { "name": "Medicare", "amount": "65.25", "employer": false },
        { "name": "Medicare", "amount": "65.25", "employer": true },
        { "name": "Georgia Income Tax", "amount": "225.00", "employer": false }
      ],
      "benefits": [
        { "name": "Health Insurance", "employee_deduction": "42.00", "company_contribution": "840.00" },
        { "name": "Georgia TRS", "employee_deduction": "270.00", "company_contribution": "936.00" }
      ],
      "deductions": [
        { "name": "403(b)", "amount": "225.00" }
      ]
    }
  ]
}

Step 5-6: Review & Approve (Missio Internal)

Payroll manager reviews calculated results in Missio dashboard. If approved, triggers the existing ApprovalController workflow. Payroll run status transitions to approved.

Step 7: Submit Payroll for Processing (Async)

PUT /v1/companies/{company_id}/payrolls/{payroll_id}/submit
Authorization: Bearer {company_access_token}

// Returns 202 Accepted
// Gusto initiates ACH transfers and direct deposits
// Listen for payroll.paid webhook or poll for processing_status = "processed"

Step 8: Post to GL

After payroll is processed, Missio generates journal entries. See Section 8 for full GL posting flow.

7 Webhook Integration

7.1 Webhook Setup Flow

1. Create an HTTPS POST endpoint in Missio: /api/gusto/webhooks
2. Create webhook subscription via API with desired event types
3. Gusto sends verification_token POST to our endpoint
4. Call PUT /webhook_subscriptions/{id}/verify with the token
5. Implement HMAC-SHA256 signature verification using verification_token as secret
6. Compare computed hash against X-Gusto-Signature request header

7.2 Webhook Payload Structure

{
  "uuid": "evt_abc123",
  "event_type": "payroll.paid",
  "resource_type": "Company",
  "resource_uuid": "company_uuid_here",
  "entity_type": "Payroll",
  "entity_uuid": "payroll_uuid_here",
  "timestamp": 1712345678
}

// Header: X-Gusto-Signature: hmac_sha256_hash

7.3 Events to Subscribe

7.4 Retry Policy

Gusto retries webhook delivery up to 16 times over 3 days using exponential backoff. Missio endpoint must return 2xx within 10 seconds. Queue heavy processing as Laravel jobs.

7.5 Laravel Webhook Handler

// app/Http/Controllers/Api/GustoWebhookController.php

public function handle(Request $request): JsonResponse
{
    // 1. Verify HMAC signature
    $signature = $request->header('X-Gusto-Signature');
    $computed  = hash_hmac('sha256', $request->getContent(), config('gusto.webhook_secret'));

    if (!hash_equals($computed, $signature)) {
        return response()->json(['error' => 'Invalid signature'], 401);
    }

    // 2. Dispatch to appropriate handler based on event_type
    match ($request->input('event_type')) {
        'payroll.paid'         => FetchPayrollResults::dispatch($request->input('entity_uuid')),
        'employee.created'     => SyncEmployeeFromGusto::dispatch($request->input('entity_uuid')),
        'employee.updated'     => SyncEmployeeFromGusto::dispatch($request->input('entity_uuid')),
        'employee.terminated'  => HandleGustoTermination::dispatch($request->input('entity_uuid')),
        'form.available'       => NotifyFormAvailable::dispatch($request->all()),
        default                => Log::info('Unhandled Gusto webhook', $request->all()),
    };

    return response()->json(['status' => 'ok']);
}

8 GL Journal Entry Flow (Gusto → Missio → ERPNext/QB)

8.1 Flow Overview

8.2 Gusto General Ledger Report

After each payroll is processed, call the Gusto GL endpoint to get debits/credits by account:

POST /v1/companies/{company_id}/general_ledger
{
  "start_date": "2026-04-01",
  "end_date": "2026-04-15"
}

// Returns journal entries with:
// - Account categories (Wages, Taxes, Benefits, etc.)
// - Debit and credit amounts
// - Per-employee breakdown

8.3 Fund Split Example

Employee Jane Smith: 60% General Fund (100), 40% Title I (200).
Gross Pay: $4,500.00 semi-monthly.

Yellow-highlighted rows = employer cost entries. Each entry updates the corresponding BudgetAllocation.expended_amount.

8.4 Account Code Mapping

9 New Laravel Code — Services, Jobs, Controllers

9.1 New Directory Structure

9.2 Existing Files to Modify

9.3 GustoClient.php — Core HTTP Client

namespace App\Services\Gusto;

use Illuminate\Support\Facades\Http;
use App\Models\GustoSetting;

class GustoClient
{
    private GustoSetting $settings;
    private string $baseUrl;

    public function __construct()
    {
        $this->settings = GustoSetting::firstOrFail();
        $this->baseUrl = config('gusto.environment') === 'production'
            ? 'https://api.gusto.com'
            : 'https://api.gusto-demo.com';
    }

    public function get(string $endpoint, array $query = []): array
    {
        return $this->request('GET', $endpoint, $query);
    }

    public function post(string $endpoint, array $data = []): array
    {
        return $this->request('POST', $endpoint, $data);
    }

    public function put(string $endpoint, array $data = []): array
    {
        return $this->request('PUT', $endpoint, $data);
    }

    private function request(string $method, string $endpoint, array $data): array
    {
        $this->refreshTokenIfNeeded();

        $response = Http::withToken($this->settings->access_token)
            ->withHeaders([
                'X-Gusto-API-Version' => '2026-02-01',
                'Content-Type' => 'application/json',
            ])
            ->retry(3, 1000, fn($e) => $e->response?->status() === 429)
            ->{strtolower($method)}($this->baseUrl . $endpoint, $data);

        if ($response->failed()) {
            Log::error('Gusto API error', [
                'endpoint' => $endpoint, 'status' => $response->status(),
                'body' => $response->json(),
            ]);
            $response->throw();
        }

        return $response->json() ?? [];
    }

    private function refreshTokenIfNeeded(): void
    {
        if (now()->lt($this->settings->token_expires_at->subSeconds(60))) {
            return; // Token still valid
        }

        // Lock row to prevent race condition on concurrent refresh
        DB::transaction(function() {
            $settings = GustoSetting::lockForUpdate()->first();
            $response = Http::post($this->baseUrl . '/oauth/token', [
                'client_id'     => config('gusto.client_id'),
                'client_secret' => config('gusto.client_secret'),
                'grant_type'    => 'refresh_token',
                'refresh_token' => $settings->refresh_token,
            ]);

            $data = $response->json();
            $settings->update([
                'access_token'     => $data['access_token'],
                'refresh_token'    => $data['refresh_token'],
                'token_expires_at' => now()->addSeconds($data['expires_in']),
            ]);
            $this->settings = $settings;
        });
    }
}

10 Database Migrations & Model Changes

10.1 Gusto Settings Table

Schema::create('gusto_settings', function (Blueprint $table) {
    $table->id();
    $table->unsignedBigInteger('company_id');
    $table->string('gusto_company_uuid')->nullable();
    $table->string('client_id')->nullable();
    $table->string('client_secret')->nullable();
    $table->enum('environment', ['sandbox', 'production'])->default('sandbox');
    $table->text('access_token')->nullable();
    $table->text('refresh_token')->nullable();
    $table->timestamp('token_expires_at')->nullable();
    $table->string('webhook_secret')->nullable();
    $table->boolean('status')->default(false);
    $table->timestamps();
});

10.2 Payroll Runs Table

Schema::create('payroll_runs', function (Blueprint $table) {
    $table->id();
    $table->unsignedBigInteger('company_id');
    $table->unsignedBigInteger('pay_period_id');
    $table->string('gusto_payroll_id')->nullable();
    $table->enum('status', [
        'draft', 'pending_review', 'pending_approval',
        'approved', 'submitted', 'processing',
        'calculated', 'gl_posted', 'completed', 'voided'
    ])->default('draft');
    $table->integer('employee_count')->default(0);
    $table->decimal('total_gross', 14, 2)->default(0);
    $table->decimal('total_deductions', 14, 2)->default(0);
    $table->decimal('total_employer_taxes', 14, 2)->default(0);
    $table->decimal('total_net', 14, 2)->default(0);
    $table->decimal('total_employer_cost', 14, 2)->default(0);
    $table->unsignedBigInteger('approved_by')->nullable();
    $table->timestamp('approved_at')->nullable();
    $table->timestamp('processed_at')->nullable();
    $table->json('exceptions')->nullable();
    $table->text('notes')->nullable();
    $table->timestamps();
    $table->softDeletes();
});

10.3 Paychecks Table

Schema::create('paychecks', function (Blueprint $table) {
    $table->id();
    $table->unsignedBigInteger('payroll_run_id');
    $table->unsignedBigInteger('employee_id');
    $table->string('gusto_paycheck_id')->nullable();
    $table->decimal('gross_pay', 12, 2)->default(0);
    $table->decimal('net_pay', 12, 2)->default(0);
    $table->decimal('total_taxes', 12, 2)->default(0);
    $table->decimal('total_deductions', 12, 2)->default(0);
    $table->decimal('total_employer_cost', 12, 2)->default(0);
    $table->decimal('regular_hours', 8, 2)->default(0);
    $table->decimal('overtime_hours', 8, 2)->default(0);
    $table->decimal('pto_hours', 8, 2)->default(0);
    $table->json('taxes_detail')->nullable();        // Full tax breakdown from Gusto
    $table->json('benefits_detail')->nullable();     // Benefits deduction detail
    $table->json('earnings_detail')->nullable();     // Earnings breakdown
    $table->json('deductions_detail')->nullable();   // All deductions
    $table->json('fund_allocations')->nullable();    // Fund split snapshot
    $table->timestamps();
});

10.4 Employee Details Extension

Schema::table('employee_details', function (Blueprint $table) {
    $table->decimal('annual_salary', 12, 2)->nullable();
    $table->enum('pay_type', ['salary', 'hourly'])->default('salary');
    $table->unsignedBigInteger('position_id')->nullable();
    $table->string('gusto_employee_id')->nullable();
    $table->string('gusto_sync_status', 20)->nullable(); // synced, pending, error
    $table->timestamp('gusto_last_synced_at')->nullable();
});

See the full Markdown document docs/PAYROLL_GUSTO_INTEGRATION_PLAN.md for complete migration schemas for all 11 new tables (positions, salary_schedules, salary_schedule_steps, employee_salary_placements, pay_calendars, pay_periods, employee_fund_allocations, payroll_journal_entries).

11 Environment & Configuration

11.1 Environment Variables

# .env additions for Gusto integration

GUSTO_CLIENT_ID=your_gusto_client_id
GUSTO_CLIENT_SECRET=your_gusto_client_secret
GUSTO_ENVIRONMENT=sandbox                  # sandbox | production
GUSTO_COMPANY_UUID=                        # Set after company creation
GUSTO_WEBHOOK_SECRET=                      # Set after webhook verification

11.2 Config File

// config/gusto.php

return [
    'client_id'       => env('GUSTO_CLIENT_ID'),
    'client_secret'   => env('GUSTO_CLIENT_SECRET'),
    'environment'     => env('GUSTO_ENVIRONMENT', 'sandbox'),
    'base_url'        => env('GUSTO_ENVIRONMENT') === 'production'
        ? 'https://api.gusto.com'
        : 'https://api.gusto-demo.com',
    'api_version'     => '2026-02-01',
    'webhook_secret'  => env('GUSTO_WEBHOOK_SECRET'),
    'sync_interval'   => 15,  // minutes between reconciliation checks
    'token_expiry'    => 7200, // seconds (2 hours)
    'refresh_buffer'  => 60,  // seconds before expiry to trigger refresh
];

11.3 Webhook Route

// routes/api.php

Route::post('gusto/webhooks', [GustoWebhookController::class, 'handle'])
    ->withoutMiddleware(['auth:sanctum'])
    ->name('gusto.webhooks');

11.4 Scheduled Jobs

// app/Console/Kernel.php

$schedule->job(new ReconcileGustoEmployees)->dailyAt('02:00');
$schedule->job(new SyncBenefitsFromGusto)->dailyAt('03:00');

12 Implementation Phases & Timeline

Total: 16 weeks (4 months)  |  Team: 1-2 backend + 1 frontend developer

13 Risks & Mitigations

14 Open Questions

15 Portal Pages & Features Summary

This section provides a consolidated view of all new portal pages required and their key features. Pages marked "replaces demo" replace existing static demo UIs with fully functional backends.

15.1 Portal Pages to Add

15.2 Key Features by Area

Payroll Processing

• Full payroll lifecycle: Draft → Review → Approve → Submit to Gusto → Receive Results → Post to GL → Completed
• Automatic timesheet aggregation — approved hours by employee by pay period
• Overtime calculation with 40hr/week FLSA threshold rules
• Payroll approval workflow integrated with existing ApprovalController
• Off-cycle payroll support (bonuses, corrections, termination pay)
• Exception handling & resolution before submission

Position Control

• Track authorized vs filled vs vacant vs frozen positions
• Link positions to fund codes, budget allocations, and salary schedules
• FTE tracking (1.0 = full-time, 0.5 = half-time, etc.)
• Grant-funded position flag with grant code tracking
• Location/school/building assignment
• Budget vs actual salary cost comparison per position

Salary & Compensation

• K-12 step/lane salary matrices (education level vs years of experience)
• Stipend management: coaching, mentoring, additional duties
• Substitute teacher pay rates and auto-calculation
• Pay type support: salary vs hourly
• Contract days configuration (typically 190 for teachers)
• Auto-calculate daily rate and hourly rate from annual salary

GL / Accounting Integration

• Auto-generate journal entries from Gusto payroll results
• Multi-fund salary splitting across fund codes (e.g., General Fund + Title I)
• Auto-post to QuickBooks Online (extends existing QB integration)
• Update BudgetAllocation.expended_amount per fund on each payroll run
• Account code mapping: Missio account codes → QuickBooks Account IDs
• Debit/credit balancing validation before GL posting

Employee Self-Service

• View current and historical pay stubs with full earnings/deduction detail
• Download pay stub PDFs
• View benefits enrollment information
• View salary placement (schedule, step, lane, stipends)

Employee Profile Additions