WKQ-branded payment receipt email replacing Pal-E-branded Stripe default #506

New issue

Open

opened 2026-04-19 01:44:21 +00:00 by forgejo_admin · 0 comments

forgejo_admin commented

2026-04-19 01:44:21 +00:00

Owner

Type

Feature

Lineage

Standalone — discovered 2026-04-18 during the #497 recovery blast testing. Lucas flagged the receipt email from Stripe as Pal-E-branded, not Westside Kings & Queens.

Repo

forgejo_admin/basketball-api

User Story

As a parent who just paid my player's first monthly fee, the receipt email in my inbox is clearly from Westside Kings & Queens — the organization I signed my player up under, the emails I already receive from, and the team my player plays for. Not from "Pal-E," a platform name the parent has no relationship with.

Context

Stripe sends an automatic receipt email after every successful payment. Because the Stripe account is registered under Pal-E (as merchant of record), Stripe's default receipt carries Pal-E branding: Pal-E business name, Pal-E contact info, Pal-E visual styling. Parents have no mental model for Pal-E — they signed contracts with Westside Kings & Queens, received all prior emails from westsidebasktball@gmail.com, and understand themselves to be paying dues to Westside. The Pal-E receipt feels off-brand and raises questions ("is this the right charge?").

Two broad paths forward exist:

Keep Pal-E as merchant of record, override the receipt — either customize Stripe's receipt templates at the account level (limited) or disable Stripe's default receipt and send our own WKQ-styled receipt email from westsidebasktball@gmail.com using the existing gmail-sdk path (same as contract / first-payment / apology emails).
Move WKQ to its own Stripe setup so Stripe's default receipt naturally carries WKQ branding — scoped separately as a spike (sibling ticket).

This ticket covers path 1 — the near-term fix that doesn't require legal entity / EIN / bank onboarding work. The spike ticket decides the long-term architecture.

File Targets

Dev agent's decision. Relevant surfaces include the webhook handler that flips Order → paid (where a WKQ receipt email could be dispatched), the existing email helpers in services/email.py, and the Stripe account-level receipt configuration.

Acceptance Criteria

Parents who pay a basketball-api-minted Payment Link receive a receipt email from westsidebasktball@gmail.com with Westside Kings & Queens visual branding (Kings red / Queens pink by division, same convention as first-payment email).
The WKQ receipt includes: player name, amount paid, date, payment method last-4, a receipt / order reference, WKQ contact path (reply-to works), no Pal-E references.
Stripe's default Pal-E-branded receipt is either suppressed or customized so parents don't receive two conflicting receipts.
Existing paid flows (jerseys, tournament fees, tryouts, monthly) all continue to produce exactly one receipt email per successful payment.

Test Expectations

Any new behavior covered by tests at the level the dev agent judges appropriate, including: receipt is sent on webhook success, receipt is not sent twice (idempotency), receipt content matches the paid Order.

Constraints

No Pal-E branding in customer-facing surfaces.
Must not break any existing paid-flow behavior (webhook fulfillment, Order flip to paid, Payment Link deactivation).

Checklist

PR opened
Tests pass
Lucas views a sample receipt for both a Kings test payment and a Queens test payment before merge

forgejo_admin/basketball-api #498 — monthly Payment Link migration (receipts fire on completion of links minted there)
Sibling ticket: WKQ-branded post-purchase landing page
Sibling ticket: Stripe Connect / WKQ merchant-of-record spike

### Type Feature ### Lineage Standalone — discovered 2026-04-18 during the #497 recovery blast testing. Lucas flagged the receipt email from Stripe as Pal-E-branded, not Westside Kings & Queens. ### Repo `forgejo_admin/basketball-api` ### User Story As a parent who just paid my player's first monthly fee, the receipt email in my inbox is clearly from Westside Kings & Queens — the organization I signed my player up under, the emails I already receive from, and the team my player plays for. Not from "Pal-E," a platform name the parent has no relationship with. ### Context Stripe sends an automatic receipt email after every successful payment. Because the Stripe account is registered under Pal-E (as merchant of record), Stripe's default receipt carries Pal-E branding: Pal-E business name, Pal-E contact info, Pal-E visual styling. Parents have no mental model for Pal-E — they signed contracts with Westside Kings & Queens, received all prior emails from `westsidebasktball@gmail.com`, and understand themselves to be paying dues to Westside. The Pal-E receipt feels off-brand and raises questions ("is this the right charge?"). Two broad paths forward exist: 1. **Keep Pal-E as merchant of record, override the receipt** — either customize Stripe's receipt templates at the account level (limited) or disable Stripe's default receipt and send our own WKQ-styled receipt email from `westsidebasktball@gmail.com` using the existing gmail-sdk path (same as contract / first-payment / apology emails). 2. **Move WKQ to its own Stripe setup** so Stripe's default receipt naturally carries WKQ branding — scoped separately as a spike (sibling ticket). This ticket covers path 1 — the near-term fix that doesn't require legal entity / EIN / bank onboarding work. The spike ticket decides the long-term architecture. ### File Targets Dev agent's decision. Relevant surfaces include the webhook handler that flips Order → paid (where a WKQ receipt email could be dispatched), the existing email helpers in `services/email.py`, and the Stripe account-level receipt configuration. ### Acceptance Criteria - [ ] Parents who pay a basketball-api-minted Payment Link receive a receipt email from `westsidebasktball@gmail.com` with Westside Kings & Queens visual branding (Kings red / Queens pink by division, same convention as first-payment email). - [ ] The WKQ receipt includes: player name, amount paid, date, payment method last-4, a receipt / order reference, WKQ contact path (reply-to works), no Pal-E references. - [ ] Stripe's default Pal-E-branded receipt is either suppressed or customized so parents don't receive two conflicting receipts. - [ ] Existing paid flows (jerseys, tournament fees, tryouts, monthly) all continue to produce exactly one receipt email per successful payment. ### Test Expectations - Any new behavior covered by tests at the level the dev agent judges appropriate, including: receipt is sent on webhook success, receipt is not sent twice (idempotency), receipt content matches the paid Order. ### Constraints - No Pal-E branding in customer-facing surfaces. - Must not break any existing paid-flow behavior (webhook fulfillment, Order flip to paid, Payment Link deactivation). ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] Lucas views a sample receipt for both a Kings test payment and a Queens test payment before merge ### Related - `forgejo_admin/basketball-api #498` — monthly Payment Link migration (receipts fire on completion of links minted there) - Sibling ticket: WKQ-branded post-purchase landing page - Sibling ticket: Stripe Connect / WKQ merchant-of-record spike