@ambushsoftworks/nestjs-payments-graphql 0.3.0 → 0.4.0-rc.1

package/CHANGELOG.md

@@ -5,10 +5,125 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Reading this file
+
+Alongside the standard Keep-a-Changelog sections, releases may carry:
+
+### ⚠ External configuration required
+
+Steps that must be performed **outside your repository** — a Stripe Dashboard
+setting, DNS, a third-party console — to make the release work.
+
+These get their own heading because they are a different species from API
+changes. A breaking export, a new required field, a changed signature: your
+compiler, your tests or a code review will catch all of them. A webhook
+endpoint that was never subscribed to a required event is invisible to every
+one of those, and the failure shows up as money moving at the provider while
+your invoices quietly stay open.
+
+Grep for `⚠ External configuration required` across the versions you are
+skipping to build an upgrade checklist mechanically, rather than reading
+prose for buried obligations. The marker was introduced in v0.4.0 and
+**retro-applied** to earlier releases, so it is reliable for the whole file.
+
 ## [Unreleased]
 
+## [0.4.0] - 2026-08-20
+
+> **Upgrade notes.** Two database changes, both in your own schema:
+>
+> 1. **If you copied the reference schema**, widen three columns —
+>    `Invoice.taxRate`, `RecurringInvoice.taxRate`, `PaymentConfig.defaultTaxRate`
+>    — from `numeric(5,4)` to `numeric(6,5)`. Non-destructive; see the first
+>    entry under Fixed. Skip if you chose your own column types.
+> 2. **Only if you want invoices carrying more than one tax**, add the
+>    `InvoiceTaxComponent` table (and `RecurringInvoiceTaxComponent` if you use
+>    recurring billing) and implement the matching optional repository methods.
+>    Single-rate invoices need neither, and behave exactly as they do today.
+>
+> Includes everything in 0.3.1, which was never published separately. If you
+> are on 0.3.0 and running Checkout alongside inline PaymentIntent flows, read
+> the 0.3.1 notes below before moving traffic onto this — the double-application
+> fix has an audit step attached to it.
+
+### Fixed
+- **Tax rates lost precision at 4 decimal places, systematically over-charging.** `Invoice.taxRate`, `RecurringInvoice.taxRate` and `PaymentConfig.defaultTaxRate` were declared `Decimal(5, 4)` in `prisma/payment-models.prisma`, which cannot hold Quebec's 9.975% QST: `0.09975` stores as `0.0998`. The error is not random — it rounds up, so every affected invoice over-charges by the same margin (5¢ per $1,000). All three are now `Decimal(6, 5)`.
+  - **This is a reference-schema fix, not a package-code fix.** `DecimalLike` always handled five decimal places, and `recalculateTotals` has carried a comment about *"rates like 9.975%"* since before the column existed — we anticipated the rate and then shipped a column that could not hold it. Consumers who chose their own column types were never affected.
+  - **Migration required if you copied the reference schema.** Widening a numeric scale is non-destructive and no package behaviour changes, but values already truncated on write stay truncated: re-save any tax rate with more than four decimal places after migrating. `ALTER TABLE "Invoice" ALTER COLUMN "taxRate" TYPE numeric(6,5);` and likewise for `RecurringInvoice.taxRate` and `PaymentConfig.defaultTaxRate`.
+  - A spec now asserts the precision of every tax-rate column in the reference schema, and that every money column stays `Int`, so a future re-sync cannot narrow them back silently.
+
+### Added
+- **Invoices can carry more than one tax.** `Invoice.taxRate` models a sale attracting exactly one tax, which is all most sales are — and cannot express one attracting two. A Quebec sale carries 5% GST *and* 9.975% QST: two taxes, levied by two governments, remitted separately. Blending them to 14.975% produces an invoice the client cannot claim input tax credits from and the supplier cannot reconcile two remittances against. US state + county + city sales tax stacks the same way. `CreateInvoiceInput.taxComponents` now accepts a list of `{ name, rate, authority?, registrationNumber?, sortOrder? }`, stored as `InvoiceTaxComponent` rows.
+  - **Nothing changes for single-rate invoices**, which remain the default and the entire behaviour when `taxComponents` is omitted. `taxRate` keeps working exactly as before, including against repository adapters that never implement the new optional methods.
+  - **The consumer owns the rate table; the package owns the arithmetic.** You decide which taxes apply and at what rate — that is tax law and it changes without warning. The package computes each component's `amount` from the invoice's taxable subtotal and re-prices them whenever line items change, so a component's amount cannot go stale against the invoice it belongs to.
+  - **Components are authoritative.** `taxAmount` is their sum, not a blended rate applied to the subtotal — each component is remitted to a different authority, so the invoice total is derived from them rather than the other way round. `taxRate` becomes the sum of the component rates, kept as a rollup for callers reading one number; re-deriving `taxAmount` from it can differ by a cent, and when it does, the components are right.
+  - **`IInvoiceRepository.findTaxComponentsByInvoice` / `replaceTaxComponents`** — new OPTIONAL methods, so v0.3.x adapters keep compiling untouched. Implement both or neither. Supplying components to a repository missing them throws `InvalidTaxConfigurationException` rather than silently dropping them, which would write an invoice whose stated tax covers taxes it cannot list.
+  - **`InvalidTaxConfigurationException`** (`INVALID_TAX_CONFIGURATION`) — thrown for `taxRate` and `taxComponents` together, an empty component list, an unnamed or duplicately-named component, or a negative/non-finite rate. Each of those would otherwise resolve to a silently wrong figure on a financial document; failing to issue the invoice is the better outcome.
+  - **`InvoiceTaxComponent` GraphQL type** and **`CreateTaxComponentInput`** are registered by the package — see "Reserved GraphQL Type Names". `InvoiceModel.taxComponents` exposes them, consumer-populated like `lineItems` (the package ships no `@ResolveField`).
+- **Recurring templates carry tax components too.** `RecurringInvoiceService.create` accepts `taxComponents`, stored as `RecurringInvoiceTaxComponent` rows and copied onto every invoice the template generates, priced against that invoice's own subtotal. Without this, a template billing a client in a multi-tax province could only hold the blended rollup rate, and every invoice it generated would misstate which taxes were collected — silently, on a schedule, for as long as the template ran. That is a worse failure than the single-invoice case, not a lesser one.
+  - The template rows deliberately have **no `amount` column**: a template has no subtotal to price against. Amounts exist only on the generated invoices.
+  - **`IRecurringInvoiceRepository.findTaxComponentsByRecurringInvoice` / `replaceTaxComponents`** — new OPTIONAL methods, same contract as the invoice-level pair.
+- **`PaymentConfig.taxRegistrationNumber`** — the supplier's tax registration number, rendered on invoices so the recipient can claim input tax credits; a Canadian invoice without the supplier's GST/HST number is not fully usable by the client. Stored and displayed verbatim, not validated — the format differs by jurisdiction. Per-tax overrides live on `InvoiceTaxComponent.registrationNumber`, because a supplier's GST and QST numbers are different. Optional on the interface so existing `PaymentConfig` adapters keep compiling. Settable through `UpdatePaymentConfigInput` and readable on `PaymentConfigModel`.
+- **Refunds do not apportion tax across components**, and now say so. A refund reduces `amountPaid` and recalculates invoice status; it does not write back a reduced `taxAmount` or adjust component amounts. The components continue to state the tax charged on the original sale, which is what a credit note references. Whether a partial refund releases tax pro-rata or tax-last is a tax-law question, so the package does not answer it — documented under "Tax" in the README rather than left for someone to discover.
+- **The default invoice email now shows a totals block** — subtotal, each tax on its own line with its name and registration number, discount, total. It previously showed only the amount due, so no tax was visible at all. Invoices without components print a single `Tax` line as they always effectively did. Consumers using their own `IPaymentEmailTemplateRenderer` receive `taxComponents` on the invoice and can render them however they like; the package still ships no PDF renderer.
+- **`STRIPE_WEBHOOK_EVENTS`** — the Stripe webhook events this package routes, exported so consumers can assert a live Dashboard subscription list against the version they actually run. Split into `always` (every Stripe deployment) and `inlinePaymentIntent` (`payment_intent.succeeded`, needed only when calling `createPaymentIntent`), so a Checkout-only consumer is not told to subscribe to an event it never receives. Compute your own required set from your own configuration; see "Stripe Gateway & Webhooks" in the README for a preflight example, including handling `enabled_events: ['*']`.
+- **`ALL_STRIPE_WEBHOOK_EVENTS`** — both groups flattened, for consumers using Checkout and inline flows together.
+- **`webhook-events.spec.ts`** — asserts the constant against the gateway in **both** directions: every named event is really routed (driving `handleWebhook` end to end), and every event the routing switch handles is really named. The second is the one that matters — adding a `case` to `normalizeWebhookEvent` without updating the constant would ship consumers an incomplete list and quietly recreate the failure the constant exists to prevent.
+
+- **`verifyStripeConfiguration(opts)`** — checks a Stripe deployment against what this version of the package needs and returns `StripeConfigFinding[]`. Verifies that the secret key authenticates (reporting the account id and display name), that the account has `charges_enabled`, that the publishable key is a `pk_` key belonging to the same account and mode as the secret, that a webhook endpoint exists for `webhookUrl` and is enabled, that it is subscribed to everything in `STRIPE_WEBHOOK_EVENTS`, and that its `api_version` matches the version the package pins. **Returns findings and never throws** — including for bad keys, permission errors and network failures — so consumers choose the policy: fail CI, fail boot, print a report, expose a health check.
+  - **Supplying `publishableKey` is treated as a declaration of intent.** It means the deployment uses inline PaymentIntent flows, which is what makes `payment_intent.succeeded` mandatory. A missing subscription for it is an `error` when the key is set and `info` when it is not, because a Checkout-only deployment genuinely never receives that event.
+  - **A check that could not run is reported, never passed.** A restricted key without webhook read permission yields `webhook_endpoints_unreadable` rather than an empty result, and an endpoint returned without its event list yields `webhook_events_unreadable` rather than being read as "subscribed to nothing" — absent is not empty. Keys that do not embed an account id yield `publishable_key_account_undetermined` rather than a guess, since a false mismatch would fail a correct deployment's CI. `webhook_endpoint_not_found` is a `warning` rather than an `error` because Stripe's v2 event destinations and CLI listeners are not returned by the endpoints API and would otherwise look missing. `enabled_events: ['*']` is treated as satisfying everything, and where several endpoints share a URL the enabled one is reported on.
+  - **The same-account check calibrates instead of assuming a key layout.** The secret key has just authenticated as the account, so if it embeds that account's id the property holds for these keys and the publishable key not embedding it is real evidence of a different account; if it does not, no conclusion is drawn. An earlier draft compared a fixed-width prefix of each key, which bled past a shorter account body into the random tail and produced a false `error` on a correct pair.
+  - Match on `code` (typed as `StripeConfigFindingCode`), not on `message`. Codes are public API; messages are written for humans and may be reworded.
+  - `client` accepts a `StripeVerificationClient` — a narrow structural slice of the SDK — so the function is testable without a live account and usable with a client configured for Connect or a proxy.
+- **`STRIPE_API_VERSION`** — the Stripe API version the SDK client is pinned to, now a shared constant. `StripeGateway` and `verifyStripeConfiguration` both read it, so the version the package parses payloads as and the version it checks endpoints against cannot drift apart.
+
+- **`stripe.verifyOnBoot?: boolean`** — runs `verifyStripeConfiguration` at application bootstrap and logs each finding at its severity. Defaults to `false` so nobody pays a network call at boot without asking. **Never throws and never blocks startup**: a check that fails or exceeds a 10-second timeout is logged as `UNVERIFIED` — explicitly not as a pass — so an unreachable Stripe API cannot stall a deploy. Consumers wanting a hard gate call `verifyStripeConfiguration` in a preflight or CI job, where failing is free; refusing to boot a running service because Stripe was briefly unreachable trades a configuration problem for an outage.
+- **`stripe.webhookUrl?: string`** — the public URL of this app's webhook endpoint, used *only* by `verifyOnBoot`. The package does not route on it; the controller still mounts at the fixed path `POST /webhooks/stripe`. Without it, boot verification checks the keys and the account but cannot check the webhook subscription.
+- **Setting `publishableKey` is now treated as a declaration of intent.** Previously the package held that signal at module init and did nothing with it: the key gates `createPaymentIntent`, so configuring it means the deployment uses inline PaymentIntent flows, which is exactly what makes `payment_intent.succeeded` mandatory. With `verifyOnBoot` on, a webhook endpoint missing that subscription now logs at **error** naming the consequence in operator terms — *inline payments will succeed at Stripe and the invoice will never close* — instead of at `info`. Without a publishable key the same gap stays informational, because a Checkout-only deployment genuinely never receives that event.
+
+### Changed
+- **The CHANGELOG now marks external configuration with its own `### ⚠ External configuration required` heading**, and the marker has been **retro-applied to 0.2.1 and 0.3.0** so it is reliable across the whole file — anyone upgrading from 0.1.x reads those entries, and a convention that only exists going forward does not help them. Requirements satisfied outside the consumer's repository are a different species from API changes: a compiler, a test and a code review all catch a changed signature, and none of them can see an unsubscribed webhook endpoint. The 0.2.1 requirement was previously the second-to-last sentence of a seven-line paragraph under `Fixed`, which read as a description of what was fixed rather than as a task. Consumers can now grep the versions they are skipping and build an upgrade checklist mechanically. Convention documented for readers at the top of this file and for maintainers in `CONTRIBUTING.md`.
+
+### Testing
+- **293 specs across 14 suites** (up from 100 at 0.3.0). Beyond the per-feature coverage above, three of those suites exist to stop a class of silent drift rather than to test a behaviour, and a fourth exercises the module as a consumer would get it:
+  - `webhook-events.spec.ts` — the exported webhook-event list against the gateway's routing switch, in both directions.
+  - `prisma-schema.spec.ts` — tax-rate precision and integer money columns in the reference schema, which ships in the tarball and is what consumers copy from.
+  - `published-docs.spec.ts` — the README's exception table and reserved GraphQL type names against what the package actually exports, and that the packaged version has a CHANGELOG entry. Both lists are load-bearing: a missing exception code leaves consumers unable to map an error, and a missing reserved type name means a consumer registers the same name and their application crashes at boot.
+  - `payments.module.spec.ts` boots the real module against stub repositories, because unit tests cannot see a provider registered in the wrong place or a lifecycle hook that never fires — those surface at a consumer's boot rather than ours.
+
+## [0.3.1] - 2026-08-20
+
+> **Upgrade note.** This release repairs invoice totals going forward but does
+> not touch rows already written. If you run Checkout alongside inline
+> PaymentIntent flows, or use recurring auto-charge, audit your invoices for
+> the double-application described below before upgrading traffic onto it —
+> the corruption is confined to invoice totals, and the `Payment` ledger is
+> intact, so affected invoices can be recomputed from it.
+
+### Fixed
+- **A payment could be applied to its invoice twice, inflating `amountPaid`.** One Stripe payment emits two success events — `checkout.session.completed` (keyed by the Checkout Session id, `cs_…`) and `payment_intent.succeeded` (keyed by the PaymentIntent id, `pi_…`). They carry different event ids, so the `IWebhookIdempotencyRepository` dedup did not catch them, and `handlePaymentSucceeded` had no guard on the payment's current status: it transitioned an already-SUCCEEDED payment to SUCCEEDED again and re-ran `applyPaymentToInvoice`, adding the amount a second time. `handlePaymentFailed` and `handlePaymentProcessing` already gated on status; only the success path did not.
+  - **Who was affected.** Consumers subscribed to **both** events — which is every consumer running inline PaymentIntent flows alongside Checkout, since 0.2.1 requires `payment_intent.succeeded` for the inline surface. Full payments were saved by accident: the invoice reached `PAID`, which is not in `PAYABLE_STATUSES`, so the second application hit the non-payable warn branch. **Partial payments were not** — `PARTIALLY_PAID` is payable, so deposits and payment-plan installments double-counted, and an invoice could flip to `PAID` on half the money.
+  - **Detecting corrupted invoices.** Only the invoice totals drift — the `Payment` ledger stays correct, because the double application updated one existing row rather than inserting a second. So the corruption is detectable, and repairable, from the ledger: `amountPaid` should equal `SUM(payments WHERE status IN ('SUCCEEDED','PARTIALLY_REFUNDED','REFUNDED')) - SUM(succeeded refunds)`, and any invoice whose `amountPaid` **exceeds** that sum has drifted. Recompute `amountPaid`/`amountDue`/`status` from it; `RefundService.recalculateInvoiceAmounts` implements exactly this formula. Re-check the invoice `status` afterwards — an invoice pushed to `PAID` on a partial payment needs to go back to `PARTIALLY_PAID` and, if its due date has passed, `OVERDUE`.
+  - **A flagged invoice is not proof this defect reached you.** `amountPaid` is net of refunds, so *any* cause of drift between an invoice and its ledger shows up identically — most commonly a refund recorded without recalculating the invoice it belonged to. Before concluding it was double-applied, compare the gap: a double-application overshoots by **exactly one SUCCEEDED card payment's amount** (and that payment carries a `provider`), whereas refund drift overshoots by the **sum of that invoice's SUCCEEDED refunds**. The repair is the same either way — recompute from the ledger — but the cause, and whether you need to audit anything else, is not. (Reported by a consumer whose only flagged row turned out to be a seeded fixture.)
+  - **Duplicate confirmation emails.** The second application also re-sent the payment confirmation email to the customer. Fixed by the same change.
+  - **Recurring auto-charges were affected too.** `recordAutoChargePayment` creates its `Payment` row already `SUCCEEDED` and keyed by the PaymentIntent id, then applies the amount. Stripe fires `payment_intent.succeeded` for that same off-session charge, which the old handler treated as a fresh success and applied again. Any consumer using recurring billing *and* subscribed to `payment_intent.succeeded` double-counted every auto-charged partial payment — this was not limited to the Checkout + inline combination.
+- **`checkout.session.completed` could fail permanently when `payment_intent.succeeded` arrived first.** The intent event could not find the row stored under the session id, so it took the create-from-metadata path and inserted its own record under the PaymentIntent id. The checkout event then tried to swap the original row to that same id and hit `@@unique([provider, providerPaymentId])` — throwing through all three controller retries and leaving the original row stranded in `PENDING` forever, where the reconciliation sweep and `findReusablePendingByInvoiceId` would both keep picking it up. (The invoice itself was credited once and correctly, by the webhook-created row — this path stuck the webhook rather than corrupting totals. It requires the consumer to have put `invoiceId` in the PaymentIntent metadata via `gatewayOptions.paymentIntentData`; without it the intent event simply logged and skipped.) `handlePaymentSucceeded` now resolves the target row **canonically** — by the PaymentIntent id, which both events carry in `providerData` — so the outcome no longer depends on delivery order, and the leftover pre-swap row is marked `CANCELLED` with an explanatory note instead of stranded.
+- **Concurrent delivery of both events no longer double-applies.** The payment row is now re-read under `findByIdForUpdate` *inside* the transaction before its status is checked, so two simultaneous deliveries cannot both observe the pre-transition status. Lock order is payment-then-invoice, matching `confirmPayment`, so the two cannot deadlock. When both transactions race past the lookup, the `@@unique([provider, providerPaymentId])` constraint on `Payment` makes the loser roll back — un-recording its idempotency row with it — and Stripe's retry re-runs it against the settled record. That constraint (already relied on by `createPendingPayment`) is load-bearing; adapters must not drop it.
+
+### Changed
+- **`handlePaymentSucceeded` now gates on payment status.** The amount is applied only from `PENDING`, `PROCESSING`, or `FAILED`. `FAILED` is included deliberately: Stripe reuses one PaymentIntent across retries, so a declined attempt followed by a successful retry on the same intent is a real money-moving flow, and `handlePaymentFailed` never touched invoice amounts. `SUCCEEDED` (already applied), `REFUNDED`/`PARTIALLY_REFUNDED` (would silently undo a refund on the invoice), `PENDING_CONFIRMATION`/`REJECTED` (the e-transfer lifecycle, owned by `confirmPayment`/`rejectPayment`), and `CANCELLED` are skipped. Skips still record the event id so Stripe stops retrying, and log at a severity matching how surprising they are — the already-applied case is routine for dual-subscribed endpoints and logs at `log`; the rest log at `warn`.
+- **Payments created from a webhook are now keyed by the canonical PaymentIntent id** rather than the event's own `providerPaymentId`, so a later duplicate event resolves to the same row. Affects only the create-from-metadata path (provider-dashboard charges); rows created by `createPendingPayment` are unchanged until the existing session-id → intent-id swap.
+- **`handlePaymentSucceeded` now records and credits the amount the provider actually charged**, rather than the amount the pending `Payment` row was created with. A pending row holds an *intention*; the success event holds what was taken. Previously the invoice was credited with the intention, so an under-charged payment could still mark the invoice `PAID` on money that never arrived. The row's `amount` is re-stated at the same time, so the payment ledger and the invoice agree and `RefundService.recalculateInvoiceAmounts` recomputes from the real figure. The divergence is reachable via `createPaymentSession`, whose `gatewayOptions` are spread at the top level of the Checkout Session call — a consumer enabling `allow_promotion_codes` or `automatic_tax` lets Stripe settle on a total the pending row never saw. Any drift is logged at `warn`.
+  - Two cases deliberately keep the recorded amount. **A currency mismatch** logs at `error` and credits the recorded amount — the package will not invent an exchange rate, and a human has to resolve it. **A non-positive event amount** logs at `warn` and keeps the recorded amount: `handleCheckoutSessionCompleted` falls back to `session.amount_total ?? 0` when its PaymentIntent retrieve fails, so zero means "unknown", not "free".
+- **+28 specs** covering `PaymentService.handlePaymentSucceeded`, total now 128 across 7 suites. They run against an in-memory store that enforces the `Payment` unique constraint and rolls back on throw, so the ordering, concurrency and rollback behaviour above is exercised rather than asserted in prose. The suite also pins the *opposite* failure mode — that legitimate repeat payments (a second PaymentIntent on the same invoice, a card payment on top of a manual one) still apply in full.
+
 ## [0.3.0] - 2026-05-28
 
+### ⚠ External configuration required
+
+- **Stripe Dashboard:** subscribe your webhook endpoint to `payment_intent.succeeded` before enabling the inline PaymentIntent surface. Carried forward from 0.2.1 and load-bearing here: setting `stripe.publishableKey` and calling `createPaymentIntent` moves you onto a flow whose success signal is this event, not `checkout.session.completed`. Miss it and inline payments succeed at Stripe while the invoice stays open with a live "Pay now" button. *(Marker retro-applied in 0.4.0.)*
+
 ### Added
 - **`PaymentGateway.createPaymentIntent(params)`** — new (optional) interface method. Returns `{ providerPaymentId, clientSecret, status, reused, providerStatus? }` for an inline payment flow (Stripe Elements / `flutter_stripe` / equivalents). The Stripe implementation reuses an existing PaymentIntent when the consumer's payment repository has a still-confirmable PENDING row for the same invoice (via the new optional `IPaymentRepository.findReusablePendingByInvoiceId`). Idempotent on the Stripe side via a stable `idempotencyKey` per `(invoiceId, attemptId)`; pass a request-scoped UUID as `attemptId` for the most robust idempotency, or omit and the gateway falls back to invoice-only. Non-Stripe gateways without an implementation throw `PaymentIntentOperationNotSupportedException`. Use `GatewayRegistryService.getInlineCapable('stripe')` to obtain a type-narrowed gateway where the methods are non-optional.
 - **`PaymentGateway.cancelPaymentIntent(providerPaymentId)`** — new (optional) interface method. Cancels a still-cancellable PaymentIntent and returns `{ success, alreadyTerminal }`. Distinct from `cancelPayment` (which is the refund-adjacent variant used by `voidInvoice` cleanup). Throws `PaymentIntentNotCancellableException` when the intent is mid-3DS — callers should retry after the challenge resolves or expires.
@@ -37,6 +152,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [0.2.1] - 2026-05-28
 
+### ⚠ External configuration required
+
+- **Stripe Dashboard:** subscribe your webhook endpoint to `payment_intent.succeeded`. Required for direct-PaymentIntent flows — anything not going through Checkout, including the inline Stripe Elements surface added in 0.3.0 and any consumer calling `paymentIntents.create` directly. Without it those payments succeed at Stripe and the invoice never closes. *(Marker retro-applied in 0.4.0; the requirement itself shipped with this release, stated inside the `Fixed` entry below.)*
+
 ### Fixed
 - **`payment_intent.succeeded` Stripe webhook event is now handled.** Previously the event fell through to the `default → ignored` branch in `StripeGateway.normalizeWebhookEvent`, meaning any PaymentIntent created outside the Checkout flow — chiefly the inline Stripe Elements surface arriving in 0.3.0, but also any consumer calling `stripe.paymentIntents.create` directly — succeeded at Stripe with no corresponding invoice or payment-record update. The new handler mirrors `handleCheckoutSessionCompleted`'s `latest_charge` → `receipt_url` fetch pattern (including the inflated-object vs string-id fork) and emits `type: 'payment.succeeded'` with `providerPaymentId: intent.id`, so `PaymentService.handlePaymentSucceeded` matches the row stored at `createPendingPayment` time without an id-swap step. Consumers using direct-PaymentIntent flows MUST subscribe to `payment_intent.succeeded` in their Stripe Dashboard webhook configuration — see "Stripe Gateway & Webhooks" in the README. This is also a precondition for the inline-PaymentIntent surface arriving in 0.3.0.
 

package/README.md

@@ -1,6 +1,6 @@
 # @ambushsoftworks/nestjs-payments-graphql
 
-Production-grade payments module for NestJS with GraphQL support. Invoicing, Stripe payment processing, refunds, payment plans, recurring invoicing with auto-charge, e-transfer, and composable email notifications — with zero database coupling.
+Production-grade payments module for NestJS with GraphQL support. Invoicing (including multi-component tax), Stripe payment processing, refunds, payment plans, recurring invoicing with auto-charge, e-transfer, and composable email notifications — with zero database coupling.
 
 ## Table of Contents
 
@@ -10,8 +10,12 @@ Production-grade payments module for NestJS with GraphQL support. Invoicing, Str
 - [Architecture](#architecture)
 - [Features](#features)
   - [Invoicing](#invoicing)
+    - [Tax](#tax)
   - [Stripe Gateway & Webhooks](#stripe-gateway--webhooks)
     - [Stripe-specific session options](#stripe-specific-session-options-gatewayoptions)
+    - [Inline PaymentIntent (Stripe Elements)](#inline-paymentintent-stripe-elements)
+    - [Verifying your Stripe configuration](#verifying-your-stripe-configuration)
+    - [Reconciliation (webhook backstop)](#reconciliation-webhook-backstop)
   - [Refunds](#refunds)
   - [Payment Plans](#payment-plans)
   - [Recurring Invoices](#recurring-invoices)
@@ -110,7 +114,7 @@ Repositories you must implement:
 
 | Interface | Purpose |
 |-----------|---------|
-| `IInvoiceRepository` | Invoice + line item persistence |
+| `IInvoiceRepository` | Invoice + line item persistence (plus optional tax components — see [Tax](#tax)) |
 | `IPaymentRepository` | Payment records |
 | `IRefundRepository` | Refund records |
 | `IPaymentConfigRepository` | Per-division payment config + providers |
@@ -125,6 +129,14 @@ Opt-in interfaces:
 | `IRecurringInvoiceRepository` | `features.recurringInvoices = true` |
 | `IPaymentCustomerRepository` | `features.recurringInvoices = true` |
 
+Some interfaces also carry **optional methods** that unlock a capability without breaking existing adapters — implement them only if you need what they enable:
+
+| Optional method | On | Enables |
+|---|---|---|
+| `findReusablePendingByInvoiceId` | `IPaymentRepository` | Durable PaymentIntent reuse for inline flows (v0.3.0) |
+| `findTaxComponentsByInvoice` + `replaceTaxComponents` | `IInvoiceRepository` | Invoices carrying more than one tax (v0.4.0) |
+| `findTaxComponentsByRecurringInvoice` + `replaceTaxComponents` | `IRecurringInvoiceRepository` | The same, on recurring templates (v0.4.0) |
+
 ### 2. Register the module
 
 ```typescript
@@ -250,15 +262,63 @@ The dynamic module is registered as `global: true` — any module in your app ca
 - Create DRAFT invoices with optional line items.
 - Line item edits allowed only in DRAFT; totals auto-recalculate on mutation.
 - `InvoiceNumberService` generates globally-unique numbers against a per-division prefix, retrying on unique-constraint collisions up to 5 times.
-- Tax rate resolution: use the value passed on `createInvoice` if provided, otherwise `PaymentConfig.defaultTaxRate` for the division, otherwise `0`.
+- Tax rate resolution: use the value passed on `createInvoice` if provided, otherwise `PaymentConfig.defaultTaxRate` for the division, otherwise `0`. Invoices attracting more than one tax pass `taxComponents` instead — see [Tax](#tax).
 - Status transitions: `DRAFT → SENT → {PARTIALLY_PAID, PAID, OVERDUE, VOID, REFUNDED}`.
 - Invoice `metadata` is a Stripe-style `Record<string, string>` for consumer-specific context.
 
+#### Tax
+
+Most sales attract exactly one tax, and `taxRate` on its own covers them:
+
+```typescript
+await invoiceService.createInvoice(divisionId, {
+  clientDetailsId,
+  taxRate: 0.13,          // 13% HST
+  lineItems: [...],
+}, userId);
+```
+
+Some attract two. A Quebec sale carries **5% GST and 9.975% QST** — two taxes, levied by two governments, remitted separately. Blending them to 14.975% produces an invoice the client cannot claim input tax credits from and the supplier cannot reconcile two remittances against. US state + county + city sales tax stacks the same way. Pass `taxComponents` instead:
+
+```typescript
+await invoiceService.createInvoice(divisionId, {
+  clientDetailsId,
+  taxComponents: [
+    { name: 'GST', rate: 0.05,    authority: 'CRA',           registrationNumber: '123456789 RT0001' },
+    { name: 'QST', rate: 0.09975, authority: 'Revenu Québec', registrationNumber: '1234567890 TQ0001' },
+  ],
+  lineItems: [...],
+}, userId);
+```
+
+**The consumer owns the rate table; the package owns the arithmetic.** Which taxes apply to a given sale, at what rate, and whether a supplier charges tax at all is tax law — it varies by jurisdiction and changes without notice, and the package does not model it. You decide the components; the package computes each `amount` from the invoice's taxable subtotal and re-prices them whenever line items change, so a component's amount can never go stale against the invoice it belongs to.
+
+**Components are authoritative.** `taxAmount` is their sum, not a blended rate applied to the subtotal — each component is remitted to a different authority. `taxRate` becomes the sum of the component rates, kept as a rollup for surfaces that read one number; re-deriving `taxAmount` from it can differ by a cent, and when it does the components are right.
+
+`taxRate` and `taxComponents` are **mutually exclusive** — supplying both throws `InvalidTaxConfigurationException`, as do an empty list, an unnamed or duplicately-named component, and a negative or non-finite rate. Each of those would otherwise put a silently wrong number on a financial document.
+
+To store components, implement two OPTIONAL methods on your `IInvoiceRepository`:
+
+```typescript
+findTaxComponentsByInvoice(invoiceId: string): Promise<InvoiceTaxComponent[]>;
+replaceTaxComponents(invoiceId: string, components: CreateInvoiceTaxComponentData[]): Promise<InvoiceTaxComponent[]>;
+```
+
+Implement both or neither. `replaceTaxComponents` must be atomic — the package calls it immediately after writing `taxAmount`, and the two must agree. Supplying components to a repository without them throws rather than dropping them silently. Copy `InvoiceTaxComponent` from [`prisma/payment-models.prisma`](./prisma/payment-models.prisma); single-rate consumers need no new table.
+
+**Recurring templates** take `taxComponents` the same way, stored without amounts (a template has no subtotal) and priced onto each generated invoice. `IRecurringInvoiceRepository` has the matching optional pair.
+
+**Supplier registration number.** Set `PaymentConfig.taxRegistrationNumber` for the number that appears on every invoice — a Canadian invoice without the supplier's GST/HST number is not fully usable by the recipient. Where two authorities are involved and the supplier has a different number for each, set `registrationNumber` per component; it takes precedence. The package stores and renders these verbatim and does not validate the format, which differs by jurisdiction.
+
+**Rendering.** The default invoice email prints a totals block: subtotal, each tax on its own line with its name and registration number, discount, total. Supply your own `IPaymentEmailTemplateRenderer` to change it — `params.invoice.taxComponents` carries the list. The package ships no PDF renderer; invoice PDFs stay with the consumer.
+
+**Refunds do not apportion tax across components.** A refund reduces the invoice's `amountPaid` and recalculates its status; it does not write back a reduced `taxAmount`, and it does not adjust component amounts. The components continue to state the tax that was charged on the original sale, which is what a credit note references. If your jurisdiction requires a tax-adjusted credit note, generate it in your own layer — deciding whether a partial refund releases tax pro-rata or tax-last is a tax-law question, and the package does not answer those.
+
 ### Stripe Gateway & Webhooks
 
 When `stripe` config is provided, the module registers `StripeGateway` and mounts `POST /webhooks/stripe`. Webhook security relies entirely on Stripe signature verification. Behaviour:
 
-- **Idempotency** — every event ID is recorded via `IWebhookIdempotencyRepository` before the handler runs; replays no-op.
+- **Idempotency** — two levels, both required. *Event level*: each event ID is recorded via `IWebhookIdempotencyRepository` (inside the handler's transaction, so a failed attempt rolls the record back and Stripe's retry can re-run it); replays no-op. *Payment level*: one payment emits more than one success event — a Checkout payment fires both `checkout.session.completed` and `payment_intent.succeeded`, under two different event IDs and two different provider payment IDs. `handlePaymentSucceeded` resolves both to a single `Payment` row by the PaymentIntent ID and applies the amount to the invoice only once, whichever event arrives first. Subscribing to both events is safe and expected. (Before v0.3.1 it was not: the second event re-applied the amount, inflating `amountPaid` on partially-paid invoices.)
 - **Retries** — `payment_intent.succeeded` events retry up to 3 times with a 2-second delay if the corresponding `Payment` row has not yet been created.
 - **Unrecognized event types** — Stripe fires many events per checkout (`payment_intent.created`, `charge.updated`, `charge.succeeded`, …) that the package does not route. These return 200 with a `debug`-level log and Stripe does not retry. The gateway surfaces them as an `IgnoredWebhookEvent` (`{ type: 'ignored', eventId, eventType }`) — if you implement a custom `PaymentGateway`, your `handleWebhook` must return this sentinel for unrouted events instead of throwing.
 - **Error reporting** — configure `webhook.errorReporter` to pipe exceptions into Sentry/GlitchTip/etc.
@@ -271,6 +331,43 @@ When `stripe` config is provided, the module registers `StripeGateway` and mount
 - `payment_intent.payment_failed` — surfaces declines back into the payment record.
 - `charge.refunded` — closes the loop on refunds.
 
+**Do not transcribe that list by hand.** As of v0.4.0 the package exports it, so your deployment can assert its live Stripe configuration against the events this version actually routes instead of against a README you read once:
+
+```typescript
+import {
+  STRIPE_WEBHOOK_EVENTS,
+  ALL_STRIPE_WEBHOOK_EVENTS,
+} from '@ambushsoftworks/nestjs-payments-graphql';
+
+// Compute your own required set from your own configuration.
+const required = [
+  ...STRIPE_WEBHOOK_EVENTS.always,
+  ...(usingInlinePaymentIntent ? STRIPE_WEBHOOK_EVENTS.inlinePaymentIntent : []),
+];
+
+// Fail a preflight / CI job / health check when the endpoint falls behind.
+const endpoint = await stripe.webhookEndpoints.retrieve(endpointId);
+const subscribed = new Set(endpoint.enabled_events);
+const missing = subscribed.has('*')
+  ? []
+  : required.filter((e) => !subscribed.has(e));
+
+if (missing.length) {
+  throw new Error(
+    `Stripe endpoint ${endpointId} is missing ${missing.join(', ')}. ` +
+      `Payments will succeed at Stripe and invoices will not close.`,
+  );
+}
+```
+
+The split is deliberate: `always` is what every Stripe deployment needs, and `inlinePaymentIntent` is required only if you call `createPaymentIntent`, because that flow's success signal is the PaymentIntent event rather than the Checkout Session one. A Checkout-only consumer genuinely never receives `payment_intent.succeeded`. `ALL_STRIPE_WEBHOOK_EVENTS` is both groups flattened, for consumers using both flows.
+
+Handle `enabled_events: ['*']` as shown — Stripe allows a wildcard subscription, and a naive superset check reports it as missing everything.
+
+Subscribing to more events than you need is safe. A Checkout payment emits both `checkout.session.completed` and `payment_intent.succeeded`; since v0.3.1 the package applies that payment to the invoice exactly once no matter how many success events describe it.
+
+A spec asserts this constant against the gateway's routing switch, so the exported list cannot drift from the events the code handles.
+
 > **Payable-status requirement.** `PaymentService.handlePaymentSucceeded` only applies an incoming payment if the invoice is in `SENT`, `PARTIALLY_PAID`, or `OVERDUE`. If a consumer creates a DRAFT invoice and starts checkout without first transitioning it to SENT, the SUCCEEDED payment lands in the `Payment` table but the invoice stays in DRAFT with `amountPaid=0`.
 >
 > As of v0.1.3 this fires a WARN log identifying the payment, provider, invoice, and status. As of v0.2.0, call `InvoiceService.ensureSent(invoiceId, eTransferEnabled, eTransferAutoDeposit, eTransferConfig?)` from your checkout flow immediately before `gateway.createPaymentSession(...)`. `ensureSent` is idempotent: DRAFT → SENT (delegates to `sendInvoice`), already-SENT/PARTIALLY_PAID/OVERDUE → returns the invoice unchanged with no re-emailed notification, PAID/VOID/REFUNDED → throws `InvalidInvoiceStateException`. `sendInvoice` itself remains strict (DRAFT-only) for callers that want the strictness.
@@ -350,6 +447,8 @@ If you forget, the first call to `createPaymentIntent` throws `PublishableKeyNot
 
 **Subscribe to `payment_intent.succeeded`.** Inline payments succeed at Stripe via a direct PaymentIntent confirmation (no Checkout session). The package handles `payment_intent.succeeded` as of v0.2.1 — your Stripe Dashboard webhook config must list this event or invoices will never close. See the bullet list at the top of "Stripe Gateway & Webhooks".
 
+Do not take that on trust: as of v0.4.0, [`verifyStripeConfiguration`](#verifying-your-stripe-configuration) checks the live subscription for you, and reports a missing `payment_intent.succeeded` as an `error` precisely when a publishable key is configured. This is the one requirement in this package that lives entirely outside your repository, where no diff, type error or review can catch it.
+
 **Reuse-via-pending-row.** `StripeGateway.createPaymentIntent` looks up an existing PENDING payment for the same invoice via `IPaymentRepository.findReusablePendingByInvoiceId(invoiceId, provider)` and, when one is found, retrieves the intent from Stripe. The retrieved intent is reused **only when all of the following hold**:
 
 - its status is still confirmable (`requires_payment_method`, `requires_confirmation`, or `requires_action`),
@@ -477,6 +576,124 @@ export class ClientInvoicesResolver {
 }
 ```
 
+#### Verifying your Stripe configuration
+
+The subscription list above, the keys, and the account's ability to charge all live in the Stripe Dashboard — outside your repository, where no diff, type error, code review or CI job can see them. `verifyStripeConfiguration` checks them against what this version of the package actually needs and reports what's wrong.
+
+```typescript
+import { verifyStripeConfiguration } from '@ambushsoftworks/nestjs-payments-graphql';
+
+const findings = await verifyStripeConfiguration({
+  secretKey: process.env.STRIPE_SECRET_KEY!,
+  publishableKey: process.env.STRIPE_PUBLISHABLE_KEY, // omit for Checkout-only
+  webhookUrl: `${process.env.API_URL}/webhooks/stripe`,
+});
+
+for (const f of findings) {
+  console.log(`[${f.severity}] ${f.code}: ${f.message}`);
+  if (f.remediation) console.log(`         → ${f.remediation}`);
+}
+
+if (findings.some((f) => f.severity === 'error')) process.exit(1);
+```
+
+**It returns findings and never throws**, including for bad keys, permission errors and network failures. That leaves the policy to you — fail a CI job, fail a boot, print a setup report, expose a health check. Throwing would impose one of those on everyone.
+
+What it checks:
+
+| Check | Severity when wrong |
+|---|---|
+| Secret key authenticates; reports account id and display name | `error` if it doesn't |
+| Account has `charges_enabled` | `error` — test payments still succeed, so a dead account looks healthy |
+| Publishable key is a `pk_` key | `error` — a secret key here gets served to browsers |
+| Publishable and secret keys are the same mode (test/live) | `error` — presents to customers as a card decline |
+| Publishable and secret keys are the same account | `error` — same misdiagnosis |
+| Webhook endpoint exists for `webhookUrl` and is enabled | `warning` / `error` |
+| Endpoint is subscribed to everything in `STRIPE_WEBHOOK_EVENTS.always` | `error` |
+| Endpoint is subscribed to `payment_intent.succeeded` | `error` when `publishableKey` is set, `info` otherwise |
+| Endpoint's `api_version` matches the version the package pins | `warning` |
+
+Two behaviours worth knowing:
+
+- **Supplying `publishableKey` is a declaration of intent.** It means "we use inline PaymentIntent flows", which is what makes `payment_intent.succeeded` mandatory rather than optional. Omit it and a missing subscription for that event is reported at `info`, because a Checkout-only deployment genuinely never receives it.
+- **A check that couldn't run is reported, never passed.** A restricted key without webhook read permission yields `webhook_endpoints_unreadable`, not an empty result; an endpoint returned without its event list yields `webhook_events_unreadable` rather than "subscribed to nothing". Keys that don't embed an account id yield `publishable_key_account_undetermined` rather than a guess — a false mismatch would fail a correct deployment's CI. Similarly, `webhook_endpoint_not_found` is a `warning` rather than an `error`, because Stripe's v2 event destinations and CLI listeners aren't returned by the endpoints API and will look missing.
+
+  The same-account check calibrates rather than assuming a key layout: the secret key has just authenticated *as* the account, so if it embeds that account's id the property holds for your keys and the publishable key not embedding it is real evidence. If it doesn't, no conclusion is drawn.
+
+Match on `code` (typed as `StripeConfigFindingCode`), not on `message` — messages are written for humans and may be reworded; codes are public API.
+
+For tests, or to use a client configured your own way, pass `client`:
+
+```typescript
+await verifyStripeConfiguration({
+  secretKey: 'sk_test_…',
+  client: myStubOrConfiguredStripeInstance,
+});
+```
+
+##### Checking at boot
+
+Set `stripe.verifyOnBoot` to run the same check at application bootstrap and log each finding at its severity:
+
+```typescript
+stripe: {
+  secretKey: cfg.get('STRIPE_SECRET_KEY'),
+  webhookSecret: cfg.get('STRIPE_WEBHOOK_SECRET'),
+  publishableKey: cfg.get('STRIPE_PUBLISHABLE_KEY'),
+  webhookUrl: `${cfg.get('API_URL')}/webhooks/stripe`,   // needed to check the subscription
+  verifyOnBoot: cfg.get('NODE_ENV') !== 'test',
+}
+```
+
+Defaults to `false`, so nobody pays a network call at boot without asking for it. `webhookUrl` is used *only* by this check — the controller still mounts at the fixed path `POST /webhooks/stripe`. Without it, boot verification checks the keys and the account but not the subscription, which is the setting most likely to be wrong.
+
+**It never throws and never blocks startup.** Findings are logged; a check that fails or times out is logged as `UNVERIFIED` — explicitly not as a pass — and abandoned after 10 seconds so an unreachable Stripe API cannot stall a deploy. If you want a hard gate, call `verifyStripeConfiguration` in a preflight or CI job instead, where failing costs nothing. Refusing to boot a running service because Stripe was briefly unreachable trades a configuration problem for an outage.
+
+Setting `publishableKey` raises the stakes: it declares the deployment uses inline PaymentIntent flows, so an endpoint not subscribed to `payment_intent.succeeded` logs at **error** naming the consequence, rather than as information.
+
+```
+ERROR [StripeConfigVerifier] [webhook_inline_events_missing] A publishable key is
+configured, so this deployment uses inline PaymentIntent flows — but the endpoint is
+not subscribed to payment_intent.succeeded. Inline payments will succeed at Stripe and
+the invoice will never close, leaving a live "Pay now" button on an invoice the
+customer already paid. → Add payment_intent.succeeded to the endpoint's events in the
+Stripe Dashboard.
+ERROR [StripeConfigVerifier] Stripe configuration has 1 error(s) and 0 warning(s).
+Payments will not work correctly until these are resolved.
+```
+
+#### Reconciliation (webhook backstop)
+
+Webhooks are best-effort. An endpoint can be down, misconfigured, unsubscribed from a required event, or exhaust Stripe's ~3 days of retries — and in every one of those cases money moves at Stripe while the local invoice stays open. Reconciliation closes that gap after the fact, independent of the cause.
+
+`PaymentService` ships the pieces; the schedule is yours (the package deliberately ships no schedulers):
+
+```typescript
+// Consumer-side, e.g. @nestjs/schedule
+@Cron(CronExpression.EVERY_15_MINUTES)
+async reconcileStalePayments() {
+  const cutoff = new Date(Date.now() - 15 * 60 * 1000);
+  const stale = await this.paymentService.findStalePayments(
+    ['PENDING', 'PROCESSING'],
+    cutoff,
+  );
+
+  for (const payment of stale) {
+    try {
+      await this.paymentService.reconcilePayment(payment.id);
+    } catch (err) {
+      this.logger.error(`Reconcile failed for ${payment.id}`, err);
+    }
+  }
+}
+```
+
+`reconcilePayment` fetches the payment's current status from the gateway and, when the provider says `succeeded` and the local row is still `PENDING`/`PROCESSING`, applies the amount to the invoice inside a transaction, fires `onInvoicePaid`, and sends the confirmation email — the same effects the webhook would have had. It is safe to run against payments that are already settled: a status that already matches the provider is a no-op, and a payment that is already `SUCCEEDED` is never re-applied.
+
+Uses `IPaymentRepository.findStaleByStatuses`, already part of the repository interface. The reference schema indexes `Payment` on `(invoiceId, status)`; if your sweep interval is short or the table is large, consider adding `(status, createdAt)` to match the query shape.
+
+> Strongly recommended for any production deployment. Had this been running, the class of incident that motivated the v0.3.1 fixes — an endpoint not subscribed to `payment_intent.succeeded`, so inline payments succeeded at Stripe and invoices never closed — would have self-healed within one sweep interval instead of being found by hand.
+
 ### Refunds
 
 Full and partial refunds through Stripe (when the originating payment went through Stripe) or manual refund records. All amounts in cents.
@@ -574,6 +791,8 @@ You can override:
 
 Covered emails: invoice sent, e-transfer instructions, payment confirmation, overdue reminder, refund confirmation.
 
+The invoice email prints a totals block — subtotal, each tax on its own line with its name and registration number, discount, total. Invoices without tax components print a single `Tax` line. `InvoiceEmailParams.invoice` is an `InvoiceWithItems`, so a custom renderer receives `lineItems` and `taxComponents` and can lay them out however it likes. The package ships no PDF renderer; invoice PDFs stay with the consumer.
+
 ### Event Listeners
 
 Register a single `IPaymentEventListener` to react to domain events without touching services. All handlers except `onInvoicePaid` are optional.
@@ -632,6 +851,8 @@ stripe: {
   secretKey: string;
   webhookSecret: string;
   publishableKey?: string;   // v0.3.0+ — required only for inline PaymentIntent flows
+  webhookUrl?: string;       // v0.4.0+ — used only by verifyOnBoot
+  verifyOnBoot?: boolean;    // v0.4.0+ — default false
 }
 ```
 
@@ -639,6 +860,12 @@ Omit the entire `stripe` key for non-Stripe deployments. A warning logs at start
 
 `publishableKey` is **optional**. It is required only if your consumer uses `StripeGateway.createPaymentIntent` (inline Stripe Elements) or exposes a `stripePublicConfig` GraphQL query. Validation happens at first call rather than at module init — consumers using only Checkout-redirect never need to set this. Per Stripe's docs, the publishable key is safe to ship to any client; it cannot create charges on its own.
 
+Setting it also declares intent: it means this deployment uses inline PaymentIntent flows, which is what makes `payment_intent.succeeded` a required webhook subscription rather than an optional one. `verifyOnBoot` acts on that — see [Verifying your Stripe configuration](#verifying-your-stripe-configuration).
+
+`verifyOnBoot` runs `verifyStripeConfiguration` at application bootstrap and logs each finding at its severity. Defaults to `false` so nobody pays a network call at boot without asking. It never throws and never blocks startup — a check that fails or exceeds a 10-second timeout is logged as `UNVERIFIED`, explicitly not as a pass. Use `verifyStripeConfiguration` directly in a preflight or CI job if you want a hard gate.
+
+`webhookUrl` is your app's public webhook URL (your base URL + `/webhooks/stripe`). It is used **only** by `verifyOnBoot`; the controller still mounts at the fixed path regardless. Without it, boot verification checks the keys and the account but not the webhook subscription — the setting most likely to be wrong.
+
 ### Email Options
 
 ```typescript
@@ -703,11 +930,11 @@ import {
 
 The package registers these names on module import. Consumers **must not** redefine or re-register them, or GraphQL will throw `"type already registered"`.
 
-**Object types:** `Invoice`, `InvoiceLineItem`, `InvoiceClient`, `Payment`, `Refund`, `PaymentPlan`, `PaymentPlanInstallment`, `PaymentConfig`, `PaymentProvider`, `PaymentMethodSetup`, `ETransferInstructions`, `OnlinePaymentSession`, `RecurringInvoice`, `RecurringInvoiceLineItem`, `PaginatedInvoices`, `PaginatedPaymentPlans`, `PaginatedRecurringInvoices`, `InlinePaymentIntent`, `StripePublicConfig`
+**Object types:** `Invoice`, `InvoiceLineItem`, `InvoiceTaxComponent`, `InvoiceClient`, `Payment`, `Refund`, `PaymentPlan`, `PaymentPlanInstallment`, `PaymentConfig`, `PaymentProvider`, `PaymentMethodSetup`, `ETransferInstructions`, `OnlinePaymentSession`, `RecurringInvoice`, `RecurringInvoiceLineItem`, `PaginatedInvoices`, `PaginatedPaymentPlans`, `PaginatedRecurringInvoices`, `InlinePaymentIntent`, `StripePublicConfig`
 
 **Enums:** `InvoiceStatus`, `PaymentMethod`, `PaymentStatus`, `RefundStatus`, `PaymentPlanStatus`, `InstallmentStatus`, `RecurringIntervalUnit`, `RecurringInvoiceStatus`, `PaymentIntentStatus`
 
-**Input types:** `CreateInvoiceInput`, `CreateLineItemInput`, `CreateRefundInput`, `CreateInstallmentInput`, `CreatePaymentPlanInput`, `CreateRecurringInvoiceInput`, `CreateRecurringLineItemInput`, `RecordManualPaymentInput`, `UpdatePaymentConfigInput`, `UpdateInvoiceMetadataInput`, `UpdateRecurringTemplateInput`, `UpsertPaymentProviderInput`, `InvoiceFilterInput`, `PaymentPlanFilterInput`, `RecurringInvoiceFilterInput`
+**Input types:** `CreateInvoiceInput`, `CreateLineItemInput`, `CreateTaxComponentInput`, `CreateRefundInput`, `CreateInstallmentInput`, `CreatePaymentPlanInput`, `CreateRecurringInvoiceInput`, `CreateRecurringLineItemInput`, `RecordManualPaymentInput`, `UpdatePaymentConfigInput`, `UpdateInvoiceMetadataInput`, `UpdateRecurringTemplateInput`, `UpsertPaymentProviderInput`, `InvoiceFilterInput`, `PaymentPlanFilterInput`, `RecurringInvoiceFilterInput`
 
 ---
 
@@ -731,6 +958,7 @@ All exceptions extend `PaymentException` (a plain `Error` subclass) with a stabl
 | `PaymentIntentNotReusableException` | `PAYMENT_INTENT_NOT_REUSABLE` |
 | `PaymentIntentNotCancellableException` | `PAYMENT_INTENT_NOT_CANCELLABLE` |
 | `PaymentIntentOperationNotSupportedException` | `PAYMENT_INTENT_OPERATION_NOT_SUPPORTED` |
+| `InvalidTaxConfigurationException` | `INVALID_TAX_CONFIGURATION` |
 
 Repository adapters are responsible for translating ORM-specific unique-constraint errors (e.g. Prisma `P2002`) into `UniqueConstraintViolationException` so core services stay ORM-agnostic.
 

package/dist/dto/create-invoice.input.d.ts

@@ -1,7 +1,9 @@
 import { CreateLineItemInput } from './create-line-item.input';
+import { CreateTaxComponentInput } from './create-tax-component.input';
 export declare class CreateInvoiceInput {
     clientDetailsId: string;
     taxRate?: number;
+    taxComponents?: CreateTaxComponentInput[];
     currency?: string;
     referenceType?: string;
     referenceId?: string;

package/dist/dto/create-invoice.input.js

@@ -18,6 +18,7 @@ const class_transformer_1 = require("class-transformer");
 const class_validator_1 = require("class-validator");
 const graphql_type_json_1 = __importDefault(require("graphql-type-json"));
 const create_line_item_input_1 = require("./create-line-item.input");
+const create_tax_component_input_1 = require("./create-tax-component.input");
 const is_metadata_1 = require("./validators/is-metadata");
 let CreateInvoiceInput = class CreateInvoiceInput {
 };
@@ -36,6 +37,13 @@ __decorate([
     (0, class_validator_1.Max)(1),
     __metadata("design:type", Number)
 ], CreateInvoiceInput.prototype, "taxRate", void 0);
+__decorate([
+    (0, graphql_1.Field)(() => [create_tax_component_input_1.CreateTaxComponentInput], { nullable: true }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.ValidateNested)({ each: true }),
+    (0, class_transformer_1.Type)(() => create_tax_component_input_1.CreateTaxComponentInput),
+    __metadata("design:type", Array)
+], CreateInvoiceInput.prototype, "taxComponents", void 0);
 __decorate([
     (0, graphql_1.Field)({ nullable: true, defaultValue: 'CAD' }),
     (0, class_validator_1.IsOptional)(),

package/dist/dto/create-invoice.input.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-invoice.input.js","sourceRoot":"","sources":["../../src/dto/create-invoice.input.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,6CAA0D;AAC1D,yDAAyC;AACzC,qDAWyB;AACzB,0EAA4C;AAC5C,qEAA+D;AAC/D,0DAAsD;AAG/C,IAAM,kBAAkB,GAAxB,MAAM,kBAAkB;CAyD9B,CAAA;AAzDY,gDAAkB;AAI7B;IAHC,IAAA,eAAK,GAAE;IACP,IAAA,wBAAM,GAAE;IACR,IAAA,4BAAU,GAAE;;2DACW;AAOxB;IALC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,eAAK,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACtC,IAAA,4BAAU,GAAE;IACZ,IAAA,0BAAQ,GAAE;IACV,IAAA,qBAAG,EAAC,CAAC,CAAC;IACN,IAAA,qBAAG,EAAC,CAAC,CAAC;;mDACU;AAMjB;IAJC,IAAA,eAAK,EAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;IAC9C,IAAA,4BAAU,GAAE;IACZ,IAAA,0BAAQ,GAAE;IACV,IAAA,2BAAS,EAAC,CAAC,CAAC;;oDACK;AAMlB;IAJC,IAAA,eAAK,EAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACzB,IAAA,4BAAU,GAAE;IACZ,IAAA,0BAAQ,GAAE;IACV,IAAA,2BAAS,EAAC,GAAG,CAAC;;yDACQ;AAKvB;IAHC,IAAA,eAAK,EAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACzB,IAAA,4BAAU,GAAE;IACZ,IAAA,wBAAM,GAAE;;uDACY;AAKrB;IAHC,IAAA,eAAK,EAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACzB,IAAA,4BAAU,GAAE;IACZ,IAAA,wBAAM,GAAE;8BACD,IAAI;iDAAC;AAMb;IAJC,IAAA,eAAK,EAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACzB,IAAA,4BAAU,GAAE;IACZ,IAAA,0BAAQ,GAAE;IACV,IAAA,2BAAS,EAAC,IAAI,CAAC;;iDACD;AAMf;IAJC,IAAA,eAAK,EAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACzB,IAAA,4BAAU,GAAE;IACZ,IAAA,0BAAQ,GAAE;IACV,IAAA,2BAAS,EAAC,IAAI,CAAC;;uDACK;AAKrB;IAHC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,2BAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC5C,IAAA,4BAAU,GAAE;IACZ,IAAA,wBAAU,GAAE;;oDACqB;AAMlC;IAJC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,CAAC,4CAAmB,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACtD,IAAA,4BAAU,GAAE;IACZ,IAAA,gCAAc,EAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC9B,IAAA,wBAAI,EAAC,GAAG,EAAE,CAAC,4CAAmB,CAAC;;qDACE;6BAxDvB,kBAAkB;IAD9B,IAAA,mBAAS,GAAE;GACC,kBAAkB,CAyD9B"}
+{"version":3,"file":"create-invoice.input.js","sourceRoot":"","sources":["../../src/dto/create-invoice.input.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,6CAA0D;AAC1D,yDAAyC;AACzC,qDAWyB;AACzB,0EAA4C;AAC5C,qEAA+D;AAC/D,6EAAuE;AACvE,0DAAsD;AAG/C,IAAM,kBAAkB,GAAxB,MAAM,kBAAkB;CAsE9B,CAAA;AAtEY,gDAAkB;AAI7B;IAHC,IAAA,eAAK,GAAE;IACP,IAAA,wBAAM,GAAE;IACR,IAAA,4BAAU,GAAE;;2DACW;AAOxB;IALC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,eAAK,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACtC,IAAA,4BAAU,GAAE;IACZ,IAAA,0BAAQ,GAAE;IACV,IAAA,qBAAG,EAAC,CAAC,CAAC;IACN,IAAA,qBAAG,EAAC,CAAC,CAAC;;mDACU;AAajB;IAJC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,CAAC,oDAAuB,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC1D,IAAA,4BAAU,GAAE;IACZ,IAAA,gCAAc,EAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC9B,IAAA,wBAAI,EAAC,GAAG,EAAE,CAAC,oDAAuB,CAAC;;yDACM;AAM1C;IAJC,IAAA,eAAK,EAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;IAC9C,IAAA,4BAAU,GAAE;IACZ,IAAA,0BAAQ,GAAE;IACV,IAAA,2BAAS,EAAC,CAAC,CAAC;;oDACK;AAMlB;IAJC,IAAA,eAAK,EAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACzB,IAAA,4BAAU,GAAE;IACZ,IAAA,0BAAQ,GAAE;IACV,IAAA,2BAAS,EAAC,GAAG,CAAC;;yDACQ;AAKvB;IAHC,IAAA,eAAK,EAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACzB,IAAA,4BAAU,GAAE;IACZ,IAAA,wBAAM,GAAE;;uDACY;AAKrB;IAHC,IAAA,eAAK,EAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACzB,IAAA,4BAAU,GAAE;IACZ,IAAA,wBAAM,GAAE;8BACD,IAAI;iDAAC;AAMb;IAJC,IAAA,eAAK,EAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACzB,IAAA,4BAAU,GAAE;IACZ,IAAA,0BAAQ,GAAE;IACV,IAAA,2BAAS,EAAC,IAAI,CAAC;;iDACD;AAMf;IAJC,IAAA,eAAK,EAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACzB,IAAA,4BAAU,GAAE;IACZ,IAAA,0BAAQ,GAAE;IACV,IAAA,2BAAS,EAAC,IAAI,CAAC;;uDACK;AAKrB;IAHC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,2BAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC5C,IAAA,4BAAU,GAAE;IACZ,IAAA,wBAAU,GAAE;;oDACqB;AAMlC;IAJC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,CAAC,4CAAmB,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACtD,IAAA,4BAAU,GAAE;IACZ,IAAA,gCAAc,EAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC9B,IAAA,wBAAI,EAAC,GAAG,EAAE,CAAC,4CAAmB,CAAC;;qDACE;6BArEvB,kBAAkB;IAD9B,IAAA,mBAAS,GAAE;GACC,kBAAkB,CAsE9B"}

package/dist/dto/create-tax-component.input.d.ts

@@ -0,0 +1,7 @@
+export declare class CreateTaxComponentInput {
+    name: string;
+    rate: number;
+    authority?: string;
+    registrationNumber?: string;
+    sortOrder?: number;
+}

package/dist/dto/create-tax-component.input.js

@@ -0,0 +1,56 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CreateTaxComponentInput = void 0;
+const graphql_1 = require("@nestjs/graphql");
+const class_validator_1 = require("class-validator");
+let CreateTaxComponentInput = class CreateTaxComponentInput {
+};
+exports.CreateTaxComponentInput = CreateTaxComponentInput;
+__decorate([
+    (0, graphql_1.Field)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    (0, class_validator_1.MaxLength)(60),
+    __metadata("design:type", String)
+], CreateTaxComponentInput.prototype, "name", void 0);
+__decorate([
+    (0, graphql_1.Field)(() => graphql_1.Float),
+    (0, class_validator_1.IsNumber)(),
+    (0, class_validator_1.Min)(0),
+    (0, class_validator_1.Max)(1),
+    __metadata("design:type", Number)
+], CreateTaxComponentInput.prototype, "rate", void 0);
+__decorate([
+    (0, graphql_1.Field)({ nullable: true }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(120),
+    __metadata("design:type", String)
+], CreateTaxComponentInput.prototype, "authority", void 0);
+__decorate([
+    (0, graphql_1.Field)({ nullable: true }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(60),
+    __metadata("design:type", String)
+], CreateTaxComponentInput.prototype, "registrationNumber", void 0);
+__decorate([
+    (0, graphql_1.Field)(() => graphql_1.Int, { nullable: true }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsNumber)(),
+    (0, class_validator_1.Min)(0),
+    __metadata("design:type", Number)
+], CreateTaxComponentInput.prototype, "sortOrder", void 0);
+exports.CreateTaxComponentInput = CreateTaxComponentInput = __decorate([
+    (0, graphql_1.InputType)()
+], CreateTaxComponentInput);
+//# sourceMappingURL=create-tax-component.input.js.map