# Phase 9.1 — Real Stripe TEST-Mode Integration Validation Status: **VALIDATED.** A real Stripe TEST Checkout Session, a real Stripe TEST payment ($399.00 — the founder-approved Winter Break Founding Cohort tuition), a genuine Stripe-signed webhook, and the existing registration→enrollment conversion path were all proven end to end against Stripe's real TEST-mode API — no live money, no live-mode credential, nothing simulated. This document also records the first, credential-less attempt at this phase (which correctly stopped rather than fake anything) and a real defect the live traffic exposed and fixed. ## 1. Baseline verification - First attempt (credential-less): branch `main`, clean tree, HEAD = `origin/main` = `80a5f6e4576cb9b83a60c9e9b57e4ebc52b62f07` — the Phase 9 milestone. - Resume attempt (this run): `git fetch origin` confirmed HEAD = `origin/main` = `77fd1869dbe694a7ff323a6fac07382e1f55b225` — the prior, credential-less Phase 9.1 commit. - No `docs/ROOTNODE_PRICING_AND_OFFERS_V1.md` or any "Phase 9.5" commit exists anywhere in this repository's history, branches, or tags (verified via `git log --all`) — the pricing decision below came directly from Chase in this session, not from a document that turned out not to have reached this canonical repo yet (it was apparently done on a different machine and not yet pushed). Used directly; no invented business decision was needed to proceed. - Phase 9 payment code and documentation re-inspected: `payment-provider.js`, `commerce.js`, `webhook-routes.js`, `offerings.js`'s conversion path, `admin-offerings-routes.js`'s payment routes, `integration-routes.js`'s checkout/agreement/status routes, `platform/test/ e2e-phase9.js`, `infra/scripts/drills/test-phase9-winter-camp-commerce.js`. ## 2. Stripe TEST credential status **First attempt**: none found anywhere reachable (process env, every `.env` file, this repo's Infisical wiring, session memory) — correctly stopped and documented rather than faked (see git history for that version of this document). **This run**: Chase provided a real `sk_test_...` secret key directly. Format-verified as TEST mode (never printed in full anywhere in this document, any commit, or any persisted log — only an 8-character prefix `sk_test_` ever appears). Stored in `platform/.env` (gitignored, never committed — confirmed via `git status` throughout this phase). A push to Infisical for durable storage was attempted (per Chase's request) but the existing machine identity credential at `~/.config/infisical/identity.env` returned a consistent `401 Invalid credentials` from `app.infisical.com` across three attempts — a pre-existing, unrelated credential-store problem, not something fixable from this session. The Stripe key remains safely local in the meantime. The webhook signing secret was obtained via `stripe listen --api-key ... --forward-to http://localhost:4200/api/webhooks/payment --print-secret` (the Stripe CLI, installed to `~/.local/bin/stripe` this session for exactly this purpose — no Dashboard endpoint needed for local TEST-mode validation). ## 3. Stripe adapter architecture — confirmed, unchanged `StripeProvider.createCheckoutSession()` uses **dynamic Checkout line-item `price_data`**, never pre-created Stripe Price/Product IDs. RootNode's `offerings` table remains the sole source of truth for identity, price, and currency. Confirmed still true after this phase's fix (below) — the fix only changes how a LATER webhook event is correlated back to a transaction, not how the Checkout Session itself is created. ## 4. Disposable TEST offering used A clearly-labeled, disposable offering — `[TEST] Stripe Integration Check ` — `delivery_mode: cohort`, price **39900 (cents) / usd = $399.00**, the founder-approved Winter Break "Founding Cohort" launch tuition Chase gave directly in this session (standard/reference retail $449, paid in full, no deposit, no payment plan — none of that billing structure was built, only the flat price was used for this validation). **Not** the real Winter Break offering — a separate, disposable fixture, transitioned to `cancelled` at the end of the run (confirmed). ## 5. Registration result A real **guardian + minor** registration (the more complex path, preferred per the mission spec since the Winter Break audience may include minors) via `POST /api/integrations/registrations` — guardian `display_name`/email/phone real-shaped test data, registrant `is_minor: true`, no real child PII. Registration created, seat reserved, payment status tracked separately from registration status, no enrollment existed before payment — all as designed. ## 6. Agreement gate result Checkout attempted before agreement acceptance → `409 AGREEMENTS_INCOMPLETE`. Agreement then accepted via `POST /api/integrations/registrations/:id/agreements` → `201`, `accepted_version: 1` persisted. Checkout attempted again → succeeded. The real, live enforcement path, not bypassed. ## 7. Real Stripe TEST Checkout Session result `POST /api/integrations/registrations/:id/checkout` returned a real `https://checkout.stripe.com/...` URL. Independently retrieved via **Stripe's own** `checkout.sessions.retrieve` API (never trusting RootNode's own echo): ``` Stripe session cs_test_a1VBoHHATcDr3DRTnZixQX8E0E5Ulk3H1UAKwTYVEOYVboOcaKCuZEMuff: amount_total = 39900, currency = usd, mode = payment, livemode = false ``` ## 8. Server-authoritative amount verification The checkout request was sent with a tampered body (`amount: 1, currency: "eur"` — neither field exists on the real contract, sent anyway to prove they're inert). Stripe's own recorded session still shows `amount_total: 39900, currency: usd` — the real, configured offering price, not the caller-supplied value. **The caller cannot choose the price or currency.** ## 9. Real TEST payment result Chase completed the real Stripe-hosted TEST Checkout in a browser with Stripe's official test card (4242 4242 4242 4242). Independently confirmed via Stripe's own API (not just the redirect): ``` GET /v1/checkout/sessions/cs_test_a1VB... → status: complete, payment_status: paid, payment_intent: pi_3U9QuqPl0OwZKsjY0lprOPWi ``` ## 10. Real signed webhook result `stripe listen` relayed a genuine Stripe-signed `checkout.session.completed` event (`evt_1U9QutPl0OwZKsjYSkW8Le84`) to `POST /api/webhooks/payment`, which accepted it (`200`, `{"received":true,"result":"processed"}`). This is Stripe's own real signature over Stripe's own real event body — not a locally-fabricated one. ## 11. Invalid-signature result A garbage `Stripe-Signature` header against a fabricated body → `400 invalid_signature`. The registration's status was re-read before and after and confirmed unchanged — zero domain side effect from a rejected signature. ## 12. Payment transaction result Exactly one `payment_transactions` row for this registration, `status: paid`, `provider_reference` matching the real Checkout Session id. No `card_number`/`cvv`/`card_last4`/ `payment_method_details` field exists anywhere on the record (none is ever stored, by design). ## 13. Registration confirmation result `offering_registrations.status = enrollment_activated`, server-derived entirely from the real payment webhook — never a client action. ## 14. Enrollment conversion result The **existing, unmodified** `convertRegistrationToEnrollment()` path ran — no second implementation was created. Verified directly against the database: exactly one row in `enrollments` for this student/program. ## 15. Cohort/capacity result Exactly one row in `cohort_enrollments` for this student/cohort — the offering's `cohort_id` correctly produced real classroom membership on conversion, unchanged from Phase 8/9's design. ## 16. Guardian preservation result Exactly one row in `student_guardians` for this student (the Phase 9 guardian-linking fix from the original Phase 9 phase held under real Stripe traffic too). `students.email` for the minor remains the empty string — the guardian's email was never written into the student's own identity record. ## 17. Activation/notification result The real activation notification was queued and delivered through the existing dev-preview mechanism (the same one every prior phase's testing has used — `EMAIL_PROVIDER` was left at its dev default this run; Google Workspace live delivery was not exercised, since nothing about Stripe validation requires it and the mission explicitly said not to make GWS delivery a Stripe blocker). No second, Stripe-specific notification path exists — this reuses the exact `notifyForEnrollment` flow every other enrollment trigger already uses. ## 18. Student access result The real one-time activation token worked: `POST /api/student/activate` → `200`, and the newly activated student's `GET /api/student/programs` includes the enrolled program. One access proof, as instructed — no full curriculum rehearsal was repeated (Phase 8/9's own rehearsals already cover that in depth). ## 19. Duplicate-event/idempotency result The **real** Stripe event was fetched fresh via `stripe.events.retrieve(eventId)` and re-signed locally with the real webhook secret (`stripe.webhooks.generateTestHeaderString`) — never a fabricated "payment succeeded" event for an unpaid session, but a genuine replay of the exact event Stripe itself recorded, mirroring what `stripe events resend` does server-side (not usable here directly — an ephemeral `stripe listen` session has no persistent dashboard endpoint id to target). Result: `200`, `{"result":"duplicate"}`. Confirmed via direct query: still exactly one enrollment, still exactly one activation/confirmation notification — no double conversion, no double seat consumption, no double email. ## 20. Declined-payment result **Not exercised via an actual real declined Stripe TEST payment this session** — doing so would require a second full browser-driven Checkout completion (Stripe Checkout Sessions have no supported pure-API "decline" trigger; PaymentIntents-direct-confirm would mean not using Checkout Sessions at all, which this phase was told not to redesign toward). Phase 9's deterministic suite already proves "failed payment retains the seat" directly, and this phase's own new regression test (§28) proves the exact real-Stripe reference-correlation shape a genuine `payment_intent.payment_failed` event would use. Available on request if Chase wants one more manual decline-card checkout to close this specific gap with fully real traffic. ## 21. Abandoned-checkout result Fully automated, no browser needed: a second, separate registration's Checkout Session was created normally, then expired via Stripe's own `sessions.expire()` API (a real, supported, pure-API operation — no fabricated event). Stripe itself then fired a genuine `checkout.session.expired` webhook, relayed by `stripe listen` and accepted (`200`). Confirmed: the registration's status became `cancelled` and its seat was released exactly once, within the polling window. ## 22. Refund result `stripe.refunds.create({ payment_intent })` against the real PaymentIntent → `succeeded` (`re_3U9QuqPl0OwZKsjY0IYvfOsM`, `39900 usd`). RootNode's own refund state was confirmed (`status: refunded`). The non-cascade rule was reconfirmed directly against the database: the registration stayed `enrollment_activated` and the enrollment stayed `active` — a refund does **not** automatically revoke registration or academic access. Whether it *should*, for this specific offering/policy, remains an explicit business-policy question this phase does not decide in code (per Phase 9's own design and this phase's own instruction). ## 23. Stripe ↔ RootNode reconciliation | | | |---|---| | RootNode registration | `04772e72-4a09-4afd-8032-d6ef4d132375` | | RootNode enrollment | `10e2724a-43bb-4d35-8bea-98f600cbd8e9` | | RootNode student | `student-001` | | Stripe Checkout Session | `cs_test_a1VBoHHATcDr3DRTnZixQX8E0E5Ulk3H1UAKwTYVEOYVboOcaKCuZEMuff` | | Stripe PaymentIntent | `pi_3U9QuqPl0OwZKsjY0lprOPWi` | | Stripe webhook event | `evt_1U9QutPl0OwZKsjYSkW8Le84` | | Stripe refund | `re_3U9QuqPl0OwZKsjY0IYvfOsM` | | Amount / currency | `39900` / `usd` ($399.00) | No secret key, webhook secret, card number, or CVV appears above or anywhere in this document. ## 24. Stripe Dashboard reconciliation For a real transaction, Chase can locate it in the Stripe Dashboard under **Test mode → Payments** (search by the PaymentIntent id `pi_...` or the Checkout Session id `cs_test_...` above) or **Developers → Events** (search by the event id `evt_...`). The RootNode admin UI's own Payments card (on the registration detail view) shows the matching `provider_reference` side by side with RootNode's own status/timestamps — reconciliation is possible without either system exposing credentials or card data to the other. ## 25. Security revalidation (with real Stripe enabled) | Check | Result | |---|---| | Stripe secret key never reaches browser | Server-only env var; not referenced anywhere in `frontend/`. | | Webhook signing secret never reaches browser | Same. | | Caller cannot choose price | Proven directly (§8) against Stripe's own recorded amount. | | Caller cannot choose currency | Proven directly (§8), same test. | | Caller cannot bypass required agreements | Proven directly (§6). | | Caller cannot bypass capacity | Unchanged architecture; existing `e2e-phase9.js` last-seat race regression rerun clean (§27). | | Success redirect cannot forge payment | The script never trusted the redirect — every "paid" claim in this document is independently verified via Stripe's own API or the real webhook, not the URL. | | Invalid webhook signature rejected | Proven directly (§11). | | Duplicate webhook safe | Proven directly with a REAL re-signed event (§19). | | No card number enters RootNode DB | Proven directly (§12) — no such field exists. | | No card number enters RootNode logs | Confirmed — grepped this session's own logs/scratch files for the real secret values and any card-shaped pattern; none found. | | No Stripe secret enters audit log | Existing `e2e-phase9.js` hygiene test rerun clean (§27). | | No Stripe secret enters metrics | Same. | | Stripe provider IDs not high-cardinality metric labels | Unchanged architecture — metrics still use only fixed-enum labels. | | One student cannot inspect another's payment | Structural — payment routes are admin/owner-only; students have no route to any payment data at all. | | Integration shared secret remains server-to-server only | Unchanged — never read from any browser-facing code. | ## 26. Bugs found **One real defect**, found only because real Stripe traffic was exercised: `payment_intent. payment_failed` and `charge.refunded` webhook events reference Stripe's PaymentIntent/Charge object, never the Checkout Session — but `payment_transactions.provider_reference` only ever stored the Session id. A real Stripe-issued failure or refund event would have silently failed to match any transaction (`result: 'error', reason: 'UNKNOWN_TRANSACTION'`). Phase 9's deterministic TestProvider never exposed this because its fabricated events always reuse whatever reference the calling test explicitly supplies, never distinguishing real Stripe object id shapes. ## 27. Bugs fixed Smallest correct fix, matching Stripe's own documented pattern for this exact problem: - `payment-provider.js`: `StripeProvider.createCheckoutSession()` now also sets `payment_intent_data: { metadata }` at session creation, so the SAME metadata (which already carries our own `transaction_id`) propagates onto the PaymentIntent Stripe creates — not just the Session. - `normalizeEvent()` (now `async`, one extra API call only on the rare refund path): for `payment_intent.payment_failed`, reads `obj.metadata.transaction_id` directly (the event object IS the PaymentIntent). For `charge.refunded`, retrieves the PaymentIntent (`stripe.paymentIntents.retrieve`) since Charges do not inherit PaymentIntent metadata automatically, and reads `transaction_id` from there. - `commerce.js`: the transaction lookup now matches `provider_reference = $1 OR transaction_id::text = $1` — a single additional `OR` clause, no schema/migration change. - `webhook-routes.js`: added the now-required `await` on `verifyAndParseWebhook` (the deterministic `TestProvider`'s synchronous return is unaffected — `await` on a non-promise value resolves immediately). Verified fixed: the real Stripe refund in this session (§22) correctly resolved via this new path (the refund's `charge.refunded` webhook references the PaymentIntent, exactly the previously-broken case), and a new permanent deterministic regression test (§28) proves the mechanism directly. ## 28. Permanent regression coverage added `platform/test/e2e-phase9.js` gained one new test: *"a webhook event referencing OUR OWN transaction_id (not provider_reference) — the real Stripe payment_intent/charge shape — is still matched"* — builds a test event whose `providerReference` is the transaction's own UUID (exactly what the fixed `normalizeEvent()` now produces for real Stripe failure/refund events) and confirms it's found and processed. This runs on every future deterministic `e2e-phase9.js` pass, with no Stripe credentials required. `platform/test/stripe-integration-test.js` (the opt-in real-Stripe check from the first Phase 9.1 attempt) was substantially extended: configurable price/currency (`STRIPE_TEST_PRICE_CENTS`/`STRIPE_TEST_CURRENCY`, defaults stay cheap/generic), a `STRIPE_TEST_MINOR=true` guardian+minor path, and — once a real payment lands — fully automated deep verification (payment record, enrollment/cohort/guardian reconciliation, the real re-signed-event duplicate proof, student access, a real refund) plus a fully automated, browser-free abandoned/expired-checkout proof via `sessions.expire()`. Still opt-in, still a guaranteed no-op by default, still refuses live-mode keys. ## 29. Regression results - `platform/test/e2e-phase9.js`: **20/20** (fresh stack, `PAYMENT_PROVIDER=test`) — includes the one new regression test from §28. - `infra/scripts/drills/test-phase9-winter-camp-commerce.js`: **13/13** (fresh stack) — unaffected by the fix, rerun to confirm. - No registration/agreement/enrollment/notification-template code changed beyond the webhook correlation fix itself, so Phase 8/5B/5C were not rerun (per the mission's own conditional rule) — the fix is entirely inside `commerce.js`/`payment-provider.js`/`webhook-routes.js`, already covered by the Phase 9 suite. - No frontend code changed — no frontend build was required. ## 30. Documentation Rewrote `PHASE9_1_STRIPE_TEST_VALIDATION.md` (this document) from BLOCKED to the real, proven results. Updated `docs/STRIPE_INTEGRATION_RUNBOOK.md` (real-Stripe local testing is no longer "not yet exercised") and `docs/WINTER_BREAK_LAUNCH_CHECKLIST.md` (the Stripe TEST technical validation item is now checked; live-mode items remain unchecked, correctly — this phase never touched live mode). `docs/WEBSITE_REGISTRATION_AND_CHECKOUT.md` needed no change — nothing about the website-facing contract itself changed this phase, only the server-side webhook correlation internals. ## 31. Remaining Stripe TEST gaps An actual real declined-payment checkout was not exercised (§20) — available on request, needs one more manual browser step. Everything else the mission asked for was proven with real Stripe traffic. ## 32. Remaining LIVE Stripe gaps Unchanged from Phase 9 — see `docs/STRIPE_INTEGRATION_RUNBOOK.md`'s "Going live" section and `docs/WINTER_BREAK_LAUNCH_CHECKLIST.md`: business/account verification, a live secret key, a permanent live webhook endpoint, payout/bank configuration, a real HTTPS production URL, and production deployment itself. None of this phase's work performed or authorized any live-mode action. ## 33. Remaining Winter Break business decisions Real dates, venue, and final capacity remain undecided (price is now decided — $399 launch / $449 standard retail, per Chase directly this session; not yet reflected in a committed `ROOTNODE_PRICING_AND_OFFERS_V1.md` in this canonical repo — see §1). Refund/cancellation *policy* (as opposed to the mechanical non-cascade behavior proven in §22) remains an open business decision. ## 34. Remaining legal requirements Unchanged from every prior phase: the actual agreement/waiver legal text, jurisdiction-specific minor-consent review, data-retention/deletion policy — see `docs/STUDENT_GUARDIAN_DATA_MODEL.md`. ## Final status **PHASE 9.1 COMPLETE / STRIPE TEST-MODE VALIDATED** A real Stripe TEST Checkout Session, a real Stripe TEST payment, a genuine Stripe-signed webhook, and the existing registration→enrollment conversion were all proven end to end, plus a real duplicate-delivery proof, a real automated abandoned-checkout proof, and a real refund with the non-cascade rule reconfirmed. One genuine defect (webhook-event correlation for PaymentIntent/Charge-referencing events) was found only by this real traffic, fixed with the smallest correct change, and covered by a new permanent deterministic regression test.