Because

• PAY-3759: FxA's stripe dependency was pinned to 17.4.0 (API 2024-11-20.acacia),
  several majors behind. Upgrading to 22.3.1 (API 2026-06-24.dahlia) crosses Stripe's "basil"
  billing redesign, which reshaped the invoice, subscription, line-item, discount, and payment-intent
  objects the Subscription Platform relies on. Remaining on the old SDK keeps us on an
  unsupported API version and blocks further Stripe work.

This pull request

• Bumps stripe from 17.4.0 to 22.3.1 and pins apiVersion: '2026-06-24.dahlia' via a shared
  STRIPE_API_VERSION constant (libs/payments/stripe/src/lib/stripe.constants.ts), consumed at
  every app/library client-construction site (libs/payments/stripe/src/lib/stripe.client.ts,
  packages/fxa-auth-server/lib/payments/stripe.ts,
  packages/fxa-admin-server/src/subscriptions/stripe.service.ts, and the auth-server maintenance
  scripts). packages/functional-tests/lib/sub-helpers.ts pins the same version directly to avoid
  pulling the payments graph into the E2E helpers.
• Migrates every affected read across the modern libs/payments/* StripeClient stack and the
  legacy fxa-auth-server StripeHelper: invoice.subscription ->
  invoice.parent.subscription_details.subscription; invoice.payment_intent/invoice.charge ->
  invoice.payments[].payment.* + confirmation_secret; subscription.current_period_* ->
  subscription-item level; invoices.retrieveUpcoming -> invoices.createPreview.
• Applies the wider basil object reshape the new types require: invoice/line-item
  tax+discount+pricing (total_taxes, line-item taxes/pricing/parent), discount.coupon ->
  source.coupon, PromotionCode.coupon -> promotion.coupon, lineItem.plan re-sourced via the
  line-item price, and branded Decimal coercions.
• Preserves the FxA-facing DTO/output shapes while re-sourcing their values from the new schema:
  invoice tax totals from invoice.total_taxes, per-line amount_excluding_tax reconstructed from
  the line item's inclusive taxes, and discount/coupon metadata from
  invoice.discounts[].source.coupon — expanded on the invoices.retrieve path
  (expand: ['confirmation_secret', 'discounts']) so the current-invoice preview keeps its coupon
  name/duration/end.
• Derives PayPal-vs-Stripe refund routing in the auth-server maintenance scripts from
  invoice.collection_method === 'send_invoice' and invoice paid state from invoice.status,
  replacing the removed invoice.paid_out_of_band/invoice.paid fields.
• Reads webhook-delivered invoices in stripe-webhook.ts and paypal-notifications.ts from both the
  new and legacy shapes, so events serialized at the account's previous API version are still handled
  during the Dashboard API-version rollout. Webhook signature verification is unchanged.
• Updates the hand-written Stripe object factories (libs/payments/stripe/src/lib/factories/*,
  including a new invoice-payment.factory.ts) and the co-located specs and fixtures to the basil shapes.

Issue that this pull request solves

Closes: PAY-3759

Checklist

Put an x in the boxes that apply

• My commit is GPG signed.
• If applicable, I have modified or added tests which pass locally.
• I have added necessary documentation (if appropriate).
• I have verified that my changes render correctly in RTL (if appropriate).
• I have manually reviewed all AI generated code.

How to review

• Key files/areas to focus on: libs/payments/stripe/src/lib/stripe.client.types.ts (the
  NegotiateExpanded/DeepOverride type wrappers driving the migration);
  packages/fxa-auth-server/lib/payments/stripe.ts (legacy StripeHelper, all categories);
  libs/payments/customer/src/lib/util/stripeInvoiceToFirstInvoicePreviewDTO.ts and
  packages/fxa-auth-server/lib/payments/stripe-formatter.ts (invoice-preview DTO re-sourcing).
• Suggested review order: foundation types/factories -> modern libs/payments consumers -> legacy
  auth-server StripeHelper + routes -> maintenance scripts -> fixtures.
• Risky or complex parts: the webhook dual-read; the tax/discount/amount_excluding_tax re-sourcing
  (billing-adjacent values, preserved to match prior output); and the PayPal-refund routing in
  scripts/* (collection_method === 'send_invoice'), which issues real refunds against production
  customer data.
• Verify locally: nx run-many -t build-ts -p payments-stripe fxa-auth-server and
  nx run-many -t test-unit -p payments-stripe payments-customer fxa-auth-server. The
  StripeClient wrapper suite (libs/payments/stripe/src/lib/stripe.client.spec.ts) mocks stripe's
  default export so new Stripe() constructs under @swc/jest, and asserts the invoices.retrieve
  expand list.

Screenshots (Optional)

Please attach the screenshots of the changes made in case of change in user interface.

Other information (Optional)

• Deploy coordination — sequencing: deploy this code first, then flip the Stripe API version
  (per environment; stage and prod are independent). Do not flip first. Outbound API calls are safe the
  moment the code deploys: every client pins apiVersion: '2026-06-24.dahlia', so Stripe returns dahlia
  shapes per request regardless of the account's Dashboard default. Only inbound webhook payloads lag —
  they are serialized at the endpoint/account version until the flip.
  • Coverage during the window is partial. The dual-read only makes the invoice's
    subscription-reference lookup tolerant of both shapes. Other invoice-driven handlers still read
    basil-only fields directly off the raw event payload (e.g. extractInvoiceDetailsForEmail:
    line.parent.type, lineItem.pricing.price_details.price, invoice.payments[].payment.charge,
    invoice.discounts[].source.coupon). On an acacia-era payload these find no line item and throw;
    handleInvoicePaidEvent catches it, reports to Sentry, and skips the email — so subscription
    first-invoice/renewal emails are dropped (and not retried) for the duration of the window. No hard
    crash and no data corruption, but not fully correct until the flip.
  • Therefore: keep the deploy→flip window short. To close it entirely, a follow-up should re-fetch
    the invoice by id at webhook-handler entry (invoicesRetrieve(id) returns dahlia because the SDK
    pins it) and read everything off that, at which point the dual-read can be removed.
• Type resolution: stripe@22 ships its types only via its package exports map, which the repo's
  moduleResolution: "node" does not read. A Berry (yarn) patch re-adds the top-level types field
  stripe dropped (.yarn/patches/stripe-npm-22.3.1-291b1ac8f8.patch), so the SDK's .d.ts resolves
  with no paths alias and no moduleResolution/emit change; it is documented in the package.json
  resolutionComments and must be regenerated on the next Stripe upgrade.