FixIT — build plan

Adding payments to a training product creates two ways to ruin it. Both are avoidable, and both have to be decided now rather than patched later.

Practically, rule two means three things. Checkout sends a plan_code, never an amount — the price is looked up server-side. Nothing is granted when the browser returns from Paystack; the webhook is the only path that grants access. And every credit movement is an append-only ledger row, with the balance treated as a cache of it.

Two currencies only work if they never overlap. The subscription is a door; credits are a vending machine.

Why credits exist at all

A wallet is only worth its complexity if it pays for something that genuinely costs you money or protects a friction you designed on purpose. Yours has four real jobs.

• Instructor review — the real one. The task ladder already says Tier 4–5 written outputs should be graded against a rubric with borderline submissions flagged for a human. That review is a person reading an escalation note. It is the only part of FixIT with a genuine cost per use, and exactly what a credit system is for.
• Protecting designed friction. The 30-minute retry cooldown is pedagogical. Removing it free would undermine the learning; removing it for credits makes the impatient trainee pay for their impatience and leaves the default intact.
• Giving free users one thing to buy. Someone who finished Tier 1 but is not ready to commit to a month can spend 5 credits on a single Tier 2 fault. A far better conversion ramp than a hard wall — and it tells you which faults actually sell.
• Making the subscription obviously better. Every plan grants a monthly credit allowance. Annual covers a certificate.

What credits cost

That last row matters. Hints already cost score. Charging subscribers credits as well is a double penalty and reads as gouging. All of these are editable from the admin console without a deploy.

Plans

The free tier has to be genuinely good — all six Tier 1 faults, the real terminal, byte-accurate output, streamed timings, Services console, Task Manager. A crippled demo converts nobody. Tier 1 ends at exactly the moment the product gets interesting, when distractors and wrong paths arrive in Tier 2, and that is the honest place to ask for money.

Granted credits expire at period end; purchased credits never do. Easy to explain, and it keeps your outstanding liability bounded.

Four flows, one file that must be right, and two prerequisites with lead time you should start this week.

The four flows

The webhook is the whole integration

billing/webhook.php is publicly reachable, unauthenticated, and grants access. It is the most security-sensitive file in the application.

// NO session_start(). NO CSRF check. NO auth guard. Paystack is not a browser.
$raw = file_get_contents('php://input');

// 1. Verify the signature BEFORE parsing anything. On cPanel read the header
//    from $_SERVER — apache_request_headers() is unreliable under PHP-FPM.
$sig = $_SERVER['HTTP_X_PAYSTACK_SIGNATURE'] ?? '';
if (!hash_equals(hash_hmac('sha512', $raw, $secret), $sig)) {
    http_response_code(401); exit;   // log it, then stop. Never process.
}

$event = json_decode($raw, true);

// 2. Idempotency. Paystack WILL deliver the same event more than once —
//    that is normal behaviour, not an error. UNIQUE(provider,event_id)
//    makes the second insert fail harmlessly.
if (!webhook_claim('paystack', $event['data']['id'], $event)) {
    http_response_code(200); exit;   // already handled
}

// 3. Dispatch inside a DB transaction: grant, ledger, and event-completion
//    all commit together or not at all.
switch ($event['event']) {
    case 'charge.success':         handle_charge_success(...);  break;
    case 'subscription.create':    handle_sub_create(...);      break;
    case 'subscription.disable':   handle_sub_disable(...);     break;
    case 'invoice.payment_failed': handle_payment_failed(...);  break;
    case 'refund.processed':      handle_refund(...);          break;
}
http_response_code(200);

Non-negotiable, in this order:

1. Verify the HMAC before parsing. Compare with hash_equals, not ==.
2. Idempotency is mandatory, not defensive. Without the unique constraint, one retry grants two months of access or double-credits a wallet.
3. Re-check the amount server-side. Trust the signature for authenticity, then still compare against the plan price.
4. Never trust metadata for authorisation. Use it to find the user, then re-derive entitlement from your own tables.
5. Log every event, verified or rejected. When a trainee says "I paid and nothing happened", this is how you answer in thirty seconds.
6. Exclude the path from maintenance mode and every rewrite rule. A 302 on your webhook URL means Paystack marks deliveries failed.

Grace, and what a downgrade must not do

A failed renewal moves the subscription to past_due with three days of full access. Card declines from insufficient balance, expired debit cards and bank downtime are routine in Nigeria and are not the trainee's fault; cutting access the instant a charge fails punishes people for their bank's problems. Email on day 0, 1 and 3, then downgrade.

Downgrading must be non-destructive. An expired trainee keeps their account, full attempt history, badges, leaderboard position, and unspent purchased credits. They lose access to Tier 2+ content and nothing else. Resubscribe three months later and everything is where they left it. Hiding progress on downgrade is the most common way subscription products lose returning customers.

There are two entirely separate questions to answer before showing a trainee a scenario. Conflating them is what turns a training product into a slot machine.

Both checks live in one function, can_start_scenario(), and it returns two distinct failure codes. locked_payment shows an upgrade button. locked_progression shows "You need 70% on Tier 2. You're at 61% — replay NET-202 to lift it." Showing an upgrade button to someone who simply has not earned the tier yet is the single fastest way to make training feel like a shakedown.

Surface separation

Three front-ends share one database and never share assets. The admin console can load 200 KB of CSS and nobody cares — you use it on a laptop, a few times a day. The trainee app must never ship a byte the simulator does not need, which means zero payment logic in the JS bundle: no price table, no plan codes, no Paystack key. Checkout is an ordinary server-rendered page. A bug in billing can then never break a scenario mid-attempt.

The original seven tables survive intact. Twenty-four more carry money, platform settings, and administration. The full schema is importable as-is.

Three decisions worth defending

Kobo, always

Every money column is INT UNSIGNED in kobo. Paystack's API works in kobo, so integers matching the provider's unit mean zero conversion at the boundary — which is where conversion bugs live. Never FLOAT for money: 0.1 + 0.2 != 0.3 in binary floating point and the error compounds across a ledger. ₦6,500 is stored as 650000.

Ledger as truth, balance as cache

wallet_ledger is append-only — no UPDATE, no DELETE, ever. A correction is a new compensating row. This is the only way to answer "why does this trainee have 7 credits?" six months later, and the only defensible position in a dispute. The cached balance columns are written in the same transaction and reconciled nightly.

// Without FOR UPDATE, two tabs both read balance=5, both spend 3,
// and you have given away a credit. Trainees DO open two tabs —
// it is already on your own pre-launch test list.
$db->prepare('SELECT credits_purchased, credits_granted
              FROM users WHERE id = ? FOR UPDATE')->execute([$userId]);

// Spend the perishable bucket first: granted credits expire,
// purchased ones never do.
$fromGranted   = min($granted, $cost);
$fromPurchased = $cost - $fromGranted;

// idempotency_key is UNIQUE — a double-tapped button or a retried
// request rolls back instead of charging twice.
ledger_insert($db, $userId, 'granted', -$fromGranted, $action, $idemKey);

Derive skill, store money

The build plan is right that progress must never be a stored column — it drifts. Six rows from one indexed query give you attempts, solves, accuracy and average commands per tier. That last figure is what the task ladder calls the best available proxy for growing diagnostic instinct, and it arrives free, so put it on the profile and the certificate.

Money is the exception. Entitlement is stored, because a subscription's state depends on events — renewals, cancellations, grace periods — that cannot be reconstructed from a payment list alone.

Three roles, not one — because the day you hand instructor access to someone else, you want that boundary already enforced rather than bolted on.

Every admin file calls require_role() on line one, before any output. Never guard by hiding a nav link — a guard that lives only in the menu is not a guard.

Modules

Priority: P1 before the pilot · P2 before real money · P3 after, driven by what actually hurts.

The ordering rule for everything else: build the tool the first time you need it manually, not before. The two exceptions are the audit log and the health strip — retrofitting an audit log means you have no record of exactly the period you most want one for.

Empty cPanel account to a live, HTTPS, payment-taking install. No SSH anywhere.

1. PreflightPHP 8.1+, extensions, MySQL 5.7+, cron, Git Version Control — and the outbound HTTPS test.
2. SubdomainDocument root at fixit/public_html so the app sits one level above the web root.
3. DatabaseCreate, add user with all privileges, import schema.sql via phpMyAdmin.
4. Code onto the servercPanel Git Version Control with a .cpanel.yml, or File Manager zip.
5. Configurationconfig.php outside the web root, chmod 600, gitignored.
6. .htaccessHTTPS force, security headers, gzip, long asset cache, error log to file.
7. HTTPSAutoSSL, then HSTS and secure session cookies. Paystack rejects http webhooks.
8. EmailAuthenticated SMTP, queue + cron, SPF and DKIM verified in Email Deliverability.
9. CronMail queue 5-min, subscriptions hourly, maintenance and backup nightly.
10. PaystackTest mode, plans created, webhook URL set, all three test cards run.
11. Smoke testInfrastructure, application, money, admin — every line, every deploy.
12. BackupsDB export before each deploy, nightly dump, weekly copy taken off the server.

The layout that makes secrets safe

When you create the subdomain, uncheck "share document root" and point it at fixit/public_html. Then fixit/ itself is not web-accessible, and that is where includes/, storage/, vendor/, bin/ and scenarios/ live. Strictly better than the .htaccess-deny fallback: no single misconfiguration can expose your Paystack secret key.

Note that Composer is not available without SSH. Upload PHPMailer's src/ by hand and require it directly. You need nothing else — the Paystack integration is plain cURL and the app is deliberately framework-free.

Gotchas, with their causes

The source plan lays out roughly 25 days for engine, auth, content, admin basics and pilot. That is reasonable for what it covers. It does not include payments, a subscription lifecycle, a credit wallet, or a super admin console — realistically 20–25 further working days.

Plan against the right-hand column unless FixIT is your full-time job. Nobody sustains eight focused hours a day on a side project, and the gap between those columns is where most projects quietly die.

If you are running late, cut in this order

1. Coupons, announcements, data export, certificates — post-pilot anyway
2. Impersonation — useful, but you can read the database
3. The credit wallet entirely. Subscriptions alone are a complete product. Ship subscription-only and add credits once you know which consumables people actually want. Biggest saving available, and it costs almost nothing because the schema is already there.
4. Tiers 4–5 content — launch with 22 faults across three tiers

Grouped by when the answer actually blocks something. Everything above works under the stated assumptions; these are where a different answer changes the build.