PPHALANXPayPal Sandbox
Documentation · Implementation Runbook

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:

Scenario A · $480.00 USD

PP-D-88412

Item Not Received. Pass 1 scores 60/100 (lacks merchant log). Hound extracts customer chat; Pass 2 passes at 85/100.

Verdict: CONTEST_HARD_PROOF
Scenario B · $210.00 USD

PP-D-88413

Not As Described. Delivered but lacks condition proof (score 60/100). Arbiter routes a 40% ($84.00 USD) refund offer.

Verdict: DE_ESCALATE_OFFER
Scenario C · $95.00 USD

PP-D-88414

Tracking shows carrier package loss (score 0/100). Immediate concede saves $15 dispute fee. Suggests carrier insurance claim.

Verdict: CONCEDE_FAST_SETTLE

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.
Routing Policy: Score ≥ 75 → CONTEST_HARD_PROOF · Score 35–74 → DE_ESCALATE_OFFER · Score < 35 → CONCEDE_FAST_SETTLE.

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, or accept-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 →