Step-by-step defense guide. From PayPal Sandbox setup to human-approved execution.
PHALANX protects PayPal merchants by gathering carrier proof, assembling evidence dossiers, running multi-juror red-team reviews, and enforcing an immutable human approval gate before any PayPal API call.
1. Setup & Prerequisites
PHALANX operates out-of-the-box with zero configuration in seeded demo mode. For live Sandbox execution, configure PayPal Developer credentials in .env.local:
# PayPal Sandbox Credentials (developer.paypal.com) PAYPAL_CLIENT_ID=your-sandbox-client-id PAYPAL_CLIENT_SECRET=your-sandbox-client-secret PAYPAL_WEBHOOK_ID=your-sandbox-webhook-id PAYPAL_BASE_URL=https://api-m.sandbox.paypal.com # Multi-Provider AI Keys (Optional - zero-key mode falls back to deterministic template floor) GEMINI_API_KEY=your-gemini-key LLM_PROVIDER=gemini
2. The 3 Seeded Scenarios (SIMULATED)
Three canonical dispute archetypes demonstrate PHALANX's deterministic routing and proof assembly:
PP-D-88412
Item Not Received. Pass 1 scores 60/100 (lacks merchant log). Hound extracts customer chat; Pass 2 passes at 85/100.
PP-D-88413
Not As Described. Delivered but lacks condition proof (score 60/100). Arbiter routes a 40% ($84.00 USD) refund offer.
PP-D-88414
Tracking shows carrier package loss (score 0/100). Immediate concede saves $15 dispute fee. Suggests carrier insurance claim.
3. Deterministic 0–100 Checklist Rubric
Checklist scores are computed by deterministic code in src/lib/scorer.ts — the LLM never generates numbers or decides routing:
- +30 Points
- Carrier tracking status indicates DELIVERED to buyer destination.
- +15 Points
- Delivery verifiable via carrier records, tracking number, and delivery timestamp.
- +15 Points
- Signature confirmation verified on file (mandatory for transactions >$750).
- +25 Points
- Post-delivery merchant communication log confirming receipt or item condition.
- +15 Points
- Original purchase invoice, transaction metadata, and store terms of service.
4. The Mandatory Human Approval Gate
PayPal merchants must never be exposed to rogue automated actions. PHALANX physically gates every PayPal mutation:
- Pre-approval: Clicking Execute without prior human approval returns
APPROVAL_REQUIRED. - Human review: Merchant inspects the evidence summary, Judge framing, and deterministic outcome matrix.
- Approve button: Records merchant identity, action (
provide-evidence,make-offer, oraccept-claim), and timestamp. - Seeded protection: In seeded demo mode, clicking Execute records a logged refusal (
REFUSED_SEEDED_MODE) preventing fake API calls.
5. Verification & Negative Test Suite
Verify the complete deterministic pipeline and all 84 negative test cases locally:
# 1. Run Next.js production build npm run build # 2. Run deterministic unit checks (114/114 passing) npx tsx scripts/unit-checks.ts # 3. Run negative test suite against production server (84/84 passing) PORT=3100 npx next start -p 3100 PHALANX_BASE_URL=http://localhost:3100 node scripts/negative-tests.mjs
Ready to inspect the live workbench?
Launch the dispute defense swarm on Scenarios A, B, and C with full PDF dossiers.
Open the Workbench →