Re-enable new-card entry across all 8 flows via Square Web Payments SDK
cnon: nonces (backend was already P11-ready):
- Add square.ts SDK loader (env-gated on VITE_SQUARE_APPLICATION_ID/LOCATION_ID,
sandbox vs prod URL auto-derived from app-ID prefix) + SquareCardInput.svelte
(tokenize() via bind:this, onReady state, CardEntryUnavailable fallback)
- CardSelection.svelte: replace newCardDisabled gate with new-card toggle +
SquareCardInput; expose tokenize() for parent flows
- Wire new-card mode into tip x3, booking payment (UserPaymentModal), deposit
(BookingFlow incl. guest), Buy a Gift Card + Add a Card (account), and admin
till online_square (GiftCardsManagement create/topup)
- Retry-safe: each flow caches the one-shot nonce and reuses it on retry so the
backend idempotency key dedups instead of re-tokenizing
- Docs: README, Gap Backlog P11, Feature Catalog, Technical Manual, P11 plan
**What it does:** Customers pay online with a card. Saved-card payments work end-to-end via Square tokenized card IDs (`ccof:`). New-card entry is currently gated in the UI (a `CardEntryUnavailable` notice) pending Square Web Payments SDK nonce tokenization (P11) — the backend already accepts `cnon:` nonces everywhere and rejects raw PANs (PCI-DSS parity, mirrored by the dev mock). See `plans/p11-square-web-payments-sdk.md`. Used for deposits, full payments, balance payments, and tips.
### 2.1 Online Card Payment (Square — saved cards or newcards via Web Payments SDK)
**What it does:** Customers pay online with a card. Saved-card payments work via Square tokenized card IDs (`ccof:`); new-card payments are tokenized client-side through the Square Web Payments SDK into `cnon:` nonces and accepted by the backend everywhere. The backend rejects raw PANs (PCI-DSS parity, mirrored by the dev mock). Local dev without Square credentials (`VITE_SQUARE_APPLICATION_ID`/`VITE_SQUARE_LOCATION_ID`) keeps new-card entry gated behind a `CardEntryUnavailable` notice. Used for deposits, full payments, balance payments, and tips.
**Layman summary:** "Pay online with your card — just like any online shop."
**Related:** [[Gift Cards|4. Gift Cards]], [[VAT Calculation|2.10 VAT Calculation]]
### 2.5 Saved Cards
**What it does:** Customers can save their card details for faster checkout next time. Cards are tokenized via Square (`ccof:` card IDs; the full PAN exists only in Square's vault — our DB stores only the reference + brand/last4/fingerprint). The dev mock mirrors this (raw PANs rejected). Soft-deleted with 7-year UK retention. The "Add Card" flow posts a `card_token` (nonce) to `CreatePaymentMethodFromToken`, which calls `CreateCardOnFile` — the UI is currently gated pending P11 (Web Payments SDK nonces) — see `plans/p11-square-web-payments-sdk.md`.
**What it does:** Customers can save their card details for faster checkout next time. Cards are tokenized via Square (`ccof:` card IDs; the full PAN exists only in Square's vault — our DB stores only the reference + brand/last4/fingerprint). The dev mock mirrors this (raw PANs rejected). Soft-deleted with 7-year UK retention. The "Add Card" flow posts a `card_token` (a Web Payments SDK `cnon:`nonce) to `CreatePaymentMethodFromToken`, which calls `CreateCardOnFile`. When frontend Square credentials are unset (local dev), add-card shows the `CardEntryUnavailable` notice.
**Layman summary:** "Save your card for next time — one-click payment."
@@ -35,7 +35,7 @@ These are things that work fine in dev (with mocks) but need real implementation
| P8 | **Social auth stubs (Google/Microsoft/Facebook)** | L (2-3d) | Backend + Frontend | `handlers/auth/social.go` is 1 line (`package auth`). Frontend login page has 3 social buttons that show `toast.info("${provider} login coming soon")`. The `user_social_logins` table and `account_type` enum values exist from early schema design. | The schema was designed for social auth from the start (table + enum values). The OAuth flow itself was never implemented. Buttons exist as UI placeholders. |
| P9 | **Tip payments: replace placeholder card tokens** | S (1d) | Frontend | ✅ COMPLETED July 2026 — `card_token: 'placeholder'` replaced with real saved card selection + CardInput with Luhn/expiry/CVC validation across all 3 tip pages. | |
| P10 | **No automated database backups** | M (1d) | Infrastructure | PostgreSQL volume is persistent in Docker but no `pg_dump` cron, no point-in-time recovery. | Standard production DB setup task. |
| P11 | **Square Web Payments SDK: re-enable new-card entry with nonce-based flow** | S-M (2-3d) | Frontend | Backend groundwork is DONE (Aug 2026): `CreateCardOnFileRaw` deleted; all card-creation paths (`CreatePaymentMethodFromToken`, till `online_square`, tip/booking/gift-card `new_card_token`) accept `cnon:`/`ccof:` tokens via `CreateCardOnFile`. The frontend no longer sends raw PAN anywhere — new-card entry is **gated** behind `CardEntryUnavailable` (saved-card payments work). Remaining work is frontend-only: load the Web Payments SDK, create a `SquareCardInput` (the old hand-rolled `CardInput.svelte` was deleted), tokenize to `cnon:xxx`, and re-enable the 8 gated flows (tips ×3, booking payment, deposit, Buy a Gift Card, account Add Card, till `online_square`). See `plans/p11-square-web-payments-sdk.md` for the full plan. | **Action plan:** 1) Load Square Web Payments SDK (script tag in `app.html` or `@square/web-payments-sdk` npm). 2) Create `SquareCardInput.svelte` using `payments.card()` + `card.tokenize()`. 3) Send only the nonce as `new_card_token` / `card_token` in each flow. 4) Set `newCardDisabled={false}` / remove the `CardEntryUnavailable` gate. 5) Re-enable admin till `online_square` and account Add Card. 6) Update docs. |
| P11 | **Square Web Payments SDK: re-enable new-card entry with nonce-based flow** | S-M (2-3d) | Frontend | ✅ **COMPLETED Aug 2026** — `SquareCardInput.svelte` tokenizes cards to `cnon:` nonces via the Web Payments SDK (env-gated on `VITE_SQUARE_APPLICATION_ID`/`VITE_SQUARE_LOCATION_ID`); all 8 flows re-enabled (tips ×3, booking payment, deposit, Buy a Gift Card, account Add Card, till `online_square`); `CardEntryUnavailable` kept only as the no-credentials fallback. See `plans/p11-square-web-payments-sdk.md`. | |
| Square | **Active** | Payment processing — in-person Terminal (`CreateTerminalCheckout`) + online card payments (saved cards working; new-card entry gated pending Square Web Payments SDK nonce integration — backlog P11, see `plans/p11-square-web-payments-sdk.md`). Backend accepts only `cnon:`/`ccof:` tokens (raw PANs rejected). Dev mock (`//go:build dev`) mirrors production PCI-DSS behaviour; prod client (`!dev`) connects to live API. |
| Square | **Active** | Payment processing — in-person Terminal (`CreateTerminalCheckout`) + online card payments (saved cards + newcards tokenized via the Square Web Payments SDK `cnon:` nonces; new-card entry is gated only when the frontend Square env vars are unset — see `plans/p11-square-web-payments-sdk.md`). Backend accepts only `cnon:`/`ccof:` tokens (raw PANs rejected). Dev mock (`//go:build dev`) mirrors production PCI-DSS behaviour; prod client (`!dev`) connects to live API. |
| SMTP | Not implemented | Email/SMS notifications — backend not wired |
# P11 — Square Web Payments SDK Implementation Plan
**Status:**READY TO PICK UP (updated August 2026 — revised after the P0/P1/P3 payment-safety work landed)
**Status:**✅ COMPLETE (implemented August 2026 — all 8 flows re-enabled; new-card entry tokenized via `cnon:` nonces)
**Owner:** Agent implementing P11 (Square Web Payments SDK)
**Estimated effort:** 2-3 days (backend groundwork already landed; this is now a frontend-only integration)
**Backlog reference:**`Future Work - Gap Backlog.md` item P11
@@ -9,29 +9,29 @@
## Executive Summary
New-card entry is currently **gated off** in the UI (a deliberate interim state after the PCI-DSS parity work): every "Use a new card" path shows a `CardEntryUnavailable` notice because the frontend has no way to produce a Square nonce. Saved-card payments work end-to-end. The **backend is fully P11-ready** — it already accepts `cnon:`/`ccof:` tokens everywhere (`CreateCardOnFileRaw` is deleted; all card-creation paths call `CreateCardOnFile` with a token). **This plan re-enables new-card payments** by integrating Square's Web Payments SDK client-side to generate `cnon:xxx` nonces, then removing the gating.
New-card entry is **tokenized via the Square Web Payments SDK** (`cnon:` nonces) across all 8 flows. The **backend was already P11-ready** — it accepts `cnon:`/`ccof:` tokens everywhere. This plan re-enabled new-card payments by integrating Square's Web Payments SDK client-side to generate `cnon:xxx` nonces, then removing the gating.
---
## Current State (verified August 2026)
### Frontend — new-card entry is GATED (not sending raw PAN):
No `new_card_token` / `card_number` / `card_cvc` fields remain in any request body. Each flow now has a saved-card list and, when the user has no saved card (or tries to add one), shows `CardEntryUnavailable` (`frontend/src/lib/components/payments/CardEntryUnavailable.svelte`, message in `frontend/src/lib/constants/payments.ts`):
### Frontend — new-card entry is TOKENIZED (no raw PANs anywhere):
All 8 flows now render `SquareCardInput` (`frontend/src/lib/components/payments/SquareCardInput.svelte`), which loads the Square Web Payments SDK (`frontend/src/lib/square/square.ts`, env-gated on `VITE_SQUARE_APPLICATION_ID`/`VITE_SQUARE_LOCATION_ID`) and tokenizes the enteredcard into a `cnon:xxx` nonce sent as `new_card_token`. The tokenized form is the only card-entry path — there is no raw-PAN fallback. When the SDK env vars are not configured (e.g. local dev), flows keep the `CardEntryUnavailable` notice.
1.`frontend/src/routes/tip/+page.svelte` — tip; saved-card list + `card_id`, gated new-card
1.`frontend/src/routes/tip/+page.svelte` — tip; saved-card list + `card_id`, SquareCardInput for newcard
2.`frontend/src/routes/pay-tip/[id]/+page.svelte` — tip; same pattern
3.`frontend/src/lib/components/account/UserBookingModal.svelte` — tip modal; same pattern
4.`frontend/src/lib/components/payments/UserPaymentModal.svelte` — booking payment; uses `CardSelection` with `newCardDisabled`
5.`frontend/src/lib/components/booking/BookingFlow.svelte` — deposit; saved-card list + `card_id`, gated new-card
6.`frontend/src/routes/account/+page.svelte` — Buy a Gift Card; saved-card list + `card_id`, gated new-card
7.`frontend/src/lib/components/admin/GiftCardsManagement.svelte` — admin till; `online_square`/`saved_card` card options removed from the UI (cash / card_machine / on_the_house only)
8. Account "Add a Card" — gated off (no raw-PAN add-card UI remains)
4.`frontend/src/lib/components/payments/UserPaymentModal.svelte` — booking payment; uses `CardSelection` with SquareCardInput
5.`frontend/src/lib/components/booking/BookingFlow.svelte` — deposit; saved-card list + `card_id`, SquareCardInput for newcard (incl. guest flow)
6.`frontend/src/routes/account/+page.svelte` — Buy a Gift Card; saved-card list + `card_id`, SquareCardInput for newcard
8. Account "Add a Card" — re-enabled with SquareCardInput → `card_token` → `CreatePaymentMethodFromToken`
### `CardSelection.svelte` (the reusable card picker):
`frontend/src/lib/components/payments/CardSelection.svelte` — saved-card list + "Use a new card" toggle + `newCardDisabled` prop that swaps the new-card section for the `CardEntryUnavailable` notice. **Currently used only by UserPaymentModal.** The other flows (tip ×3, account Buy Gift Card, BookingFlow) have their own simpler saved-card lists with `CardEntryUnavailable` — the ~100-line duplicated validation blocks were deleted during the raw-PAN cleanup, so there is far less to consolidate than when this plan was first written.
`frontend/src/lib/components/payments/CardSelection.svelte` — saved-card list + "Use a new card" toggle + SquareCardInput; exposes a `tokenize()` method via `bind:this` that parents call at submit time. Used by UserPaymentModal. The other flows have their own saved-card lists wired to SquareCardInput directly.
### `CardInput.svelte`:
**DELETED.** The hand-rolled card entry form was removed in the P3 cleanup. P11 creates a fresh `SquareCardInput.svelte` from scratch — nothing to migrate.
### `SquareCardInput.svelte` (NEW — P11):
The tokenization component. Loads the SDK, attaches the Square card iframe form, and exposes `tokenize()` returning the `cnon:` nonce (or a user-facing error). One-shot nonce: each flow caches the token and reuses it on retry so a retry does not re-tokenize (the backend idempotency key dedups).
### Backend (already P11-ready — verified):
-`backend/internal/square/square_http_client.go` — `createCardOnFileHTTP` accepts a `source_id` token and calls `POST /v2/cards`. Works with `cnon:xxx` nonces.
@@ -53,19 +53,13 @@ No `new_card_token` / `card_number` / `card_cvc` fields remain in any request bo
---
## Implementation Steps
## Implementation Steps (ALL COMPLETE)
### Step 1 — Load the Square Web Payments SDK
### Step 1 — Load the Square Web Payments SDK ✅
- **Chosen**: dynamic script injection (`frontend/src/lib/square/square.ts`) — loads `https://sandbox.web.squarecdn.com/v1/square.js` (sandbox) or `https://web.squarecdn.com/v1/square.js` (prod) lazily when a card form mounts, cached across forms. Env-gated: no `VITE_SQUARE_*` vars → `isSquareConfigured()` returns false and flows keep the `CardEntryUnavailable` fallback.
Exposes `tokenize()` (via `bind:this`) returning the nonce; reports readiness via `onReady`. No raw-PAN fallback exists. Local dev without Square credentials keeps the `CardEntryUnavailable` notice.
**Design decision**: create `SquareCardInput.svelte` and swap it into `CardSelection.svelte` (and the gated flows) when a Square app ID is configured. Because the frontend no longer has a raw-PAN fallback form, the gating logic (`newCardDisabled` / `CardEntryUnavailable`) is what the tokenized form replaces — there is no hand-rolled form left to fall back to. Local dev without Square credentials keeps the gated state.
### Step 3 — Re-enable the payment flows with nonces
For each gated flow, replace the `CardEntryUnavailable` notice / `newCardDisabled` gate with the tokenized `SquareCardInput` and send the resulting `cnon:xxx` as `new_card_token` (the backend already accepts it in `CreateTipPayment`, `CreateBookingPayment`, `BuyGiftCard`,`CreatePaymentMethodFromToken`, and till `online_square`):
1. Extend`CardSelection.svelte` to the 5 remaining card UIs (tip ×3, account Buy Gift Card, BookingFlow) OR wire `SquareCardInput` directly into each saved-card list — the duplication is now small (saved-card list only), so either approach is cheap.
2. UserPaymentModal: set `newCardDisabled={false}` and use the tokenized form inside `CardSelection`.
3. Re-enable the account "Add a Card" flow (posts `card_token` → `CreatePaymentMethodFromToken`).
4. Re-enable the admin till `online_square` option (posts `card_token` → till.go nonce path) and remove the `CardEntryUnavailable` notice.
5.`card_expiry`/`card_cvc` are already removed from all request bodies — no work needed.
### Step 3 — Re-enable the payment flows with nonces ✅
All 8 flows render `SquareCardInput` and send the resulting `cnon:xxx` as `new_card_token` (backend already accepted it in `CreateTipPayment`, `CreateBookingPayment`, `BuyGiftCard`, `CreatePaymentMethodFromToken`, and till `online_square`):
5.`card_expiry`/`card_cvc` already removed from all request bodies — no work needed.
### Step 4 — Migrate the two raw-PAN backend paths ✅ **DONE (previous sessions)**
-`CreatePaymentMethodFromDetails` → replaced by `CreatePaymentMethodFromToken` using `CreateCardOnFile` with the nonce. **Verified at service.go:504-526.**
- Till `online_square` → `CreateCardOnFileRaw` → `CreateCardOnFile` with a nonce. **Verified at till.go:497-509.**
-`README.md` line 9: update the "currently raw-PAN entry in dev only; production nonce integration is backlog item P11" caveat — the current truth is "new-card entry is gated pending P11 nonce integration".
-`Future Work - Gap Backlog.md` P11: mark completed
-`Feature Catalog.md` (lines ~166, ~194): update the "raw PAN entry in the UI is a documented dead end" claims — new-card entry is gated, not raw-PAN
-`Technical Manual.md` (line ~53): update the "new-card entry pending Web Payments SDK nonces" claim — now that P11 lands, say "new-card payments tokenized via Web Payments SDK nonces"
### Step 6 — Update docs ✅
-`README.md` line 9 updated — new-card entry now tokenized via Web Payments SDK nonces (gated only when frontend Square env vars are absent)
-`Future Work - Gap Backlog.md` P11: marked completed
-`Feature Catalog.md` (lines ~166, ~194): updated — new-card entry is tokenized, not gated
-`Technical Manual.md` (line ~53): updated — new-card payments tokenized via Web Payments SDK nonces
---
## Testing Plan
1.**Unit tests**:
-`square_http_client_test.go`: `createCardOnFileHTTP` request-shape tests via `httptest.Server` (verify `source_id` is the token, `idempotency_key` deterministic sha256, no raw PAN in body).
- Error-path tests for the HTTP client (non-2xx, malformed body).
2.**Integration tests**:
- Handler tests using `cnon:` tokens through the mock (mock accepts `cnon:` nonces) — `TestCreatePaymentMethod_HappyPath` (now asserts 200 with `cnon:visa`) and `TestDevClient_CreateCardOnFile_...` cover the backend; extend to the payment flows (tip/booking/giftcard with a `cnon:` source).
- Add a test: card created with nonce → payment with saved card works.
- Each of the 8 flows: enter new card → tokenize → pay → verify charge in Square dashboard.
- Saved-card flow still works. Refund still works.
@@ -123,19 +103,19 @@ For each gated flow, replace the `CardEntryUnavailable` notice / `newCardDisable
## Risks / Gotchas
- **Square iframe requires HTTPS** — localhost is exempt, but any non-local dev URL needs TLS.
- **Tokenization is one-shot** — a `cnon:` nonce is single-use. The idempotency key logic (cached per payment attempt) handles retries, but a retry must NOT re-tokenize if the first tokenize succeeded and the payment failed — the backend's idempotency dedup handles this, but the frontend should reuse the cached token on retry if the payment record is pending.
- **Do not regress the PCI-DSS parity work** — the backend rejects raw PANs by design; the tokenized form must never fall back to sending PAN/CVC to our server.
- **`CardEntryUnavailable` stays as the offline/dev fallback** — when no Square app ID is configured, flows keep the gated notice rather than breaking.
- **Tokenization is one-shot** — a `cnon:` nonce is single-use. Implemented per the plan: each flow caches the token after the first `tokenize()` and **reuses it on retry** (the backend idempotency key dedups), so a retry does not re-tokenize or double-charge.
- **PCI-DSS parity preserved** — the backend rejects raw PANs by design; the tokenized form never falls back to sending PAN/CVC to our server.
- **`CardEntryUnavailable` stays as the offline/dev fallback** — when no `VITE_SQUARE_*` credentials are configured, flows keep the gated notice rather than breaking.
- [x] All 8 flows re-enabled to send nonces, not PANs (tip ×3, booking payment, deposit, Buy a Gift Card, account Add Card, admin till `online_square`)
- [x]`CardEntryUnavailable` kept only as the no-credentials fallback
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
