@ambushsoftworks/nestjs-payments-graphql 0.5.0-rc.2 → 0.6.0

package/CHANGELOG.md

@@ -28,12 +28,261 @@ prose for buried obligations. The marker was introduced in v0.4.0 and
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-09-19
+
+> **Upgrade notes.** One optional database column; nothing else to migrate.
+>
+> 1. **`CreateRefundInput`, `RecordManualPaymentInput`, `CreateInvoiceInput`,
+>    `CreatePaymentPlanInput`, `CreateRecurringInvoiceInput` and
+>    `UpdateRecurringTemplateInput` now mean the *service* interfaces.** The
+>    GraphQL `@InputType` classes of the same names moved to the `/graphql`
+>    subpath. If you use them for `@Args()`, change the import; if you were
+>    fighting the types when calling a service, that is what this fixes — the
+>    type you needed was not exported at all.
+> 2. **If you want saved-card management**, add
+>    `defaultPaymentMethodId String?` to `PaymentCustomer`, implement
+>    `IPaymentCustomerRepository.setDefaultPaymentMethod`, and set
+>    `features.cardManagement`. The module refuses to boot without both. Leave
+>    the flag off and nothing changes.
+> 3. **A Stripe gateway that cannot be constructed now fails the boot.** It
+>    used to log and continue, leaving every payment to fail at request time.
+>    If your deployment has been starting with a bad key, it will now stop.
+> 4. **Recurring templates no longer backfill missed cycles.** A template whose
+>    schedule has stalled generates one invoice on the next run, not one per
+>    missed cycle. If you were relying on the old behaviour to catch up, you
+>    will need to trigger those invoices explicitly.
+> 5. **Delayed-notification payments no longer close an invoice on session
+>    completion.** ACH, SEPA and Bacs now record as processing and close when
+>    they settle. If you report on invoices closing, expect the lag to appear.
+> 6. Services now reject non-integer and negative money. Anything that was
+>    silently storing fractional cents will start throwing.
+> 7. **If you took Checkout payments before 0.3.1, back them up to the
+>    PaymentIntent id before upgrading, or refunds for them are silently
+>    skipped.** 0.3.1 fixed how new payments are keyed; it did not migrate
+>    existing rows. A pre-0.3.1 Checkout payment can be keyed on the Checkout
+>    Session id while refund webhooks quote the PaymentIntent id, and the lookup
+>    is an exact match with no fallback — so `RefundService` logs an error and
+>    skips, the customer's money goes back, and the invoice stays PAID. The
+>    README's "Backfilling Checkout payments taken before 0.3.1" has the SQL.
+>    Found by the jobsites team while upgrading from 0.2.0; our own answer to
+>    their question about this had said 0.3.1 covered it, which was true only
+>    for rows written after it.
+> 8. **Subscribe to `charge.dispute.created` and `charge.dispute.closed`** — see
+>    the external-configuration section below. Build the list from
+>    `STRIPE_WEBHOOK_EVENTS` rather than prose, or set `stripe.verifyOnBoot`.
+> 9. **The package no longer searches the provider for a customer to adopt.**
+>    If you lose a `PaymentCustomer` row while the provider customer survives,
+>    a new one is created and the client re-saves their card. In exchange,
+>    whether two divisions share a wallet is now entirely your repository's
+>    decision — see "Provider customers and the scope key" in the README. No
+>    action needed if you use the bundled adapter or scope per division; that
+>    behaviour is unchanged.
+
+### ⚠ External configuration required
+
+- **Stripe Dashboard:** subscribe your webhook endpoint to
+  `charge.dispute.created` and `charge.dispute.closed`. Without them a
+  chargeback pulls the funds with no local record at all — the payment stays
+  `SUCCEEDED`, the invoice stays `PAID`, and nothing in your system knows the
+  money has gone. `STRIPE_WEBHOOK_EVENTS.always` carries both, so a preflight
+  built from that constant will tell you if the subscription is missing.
+
+### Added
+- **Dispute handling.** `charge.dispute.created` and `charge.dispute.closed`
+  are routed; the package annotates the payment, sets `needsReconciliation`,
+  and fires the new optional `IPaymentEventListener.onPaymentDisputed`. It
+  deliberately does **not** adjust the invoice — writing it off, re-invoicing,
+  or pursuing the client is a business decision, and a payments library
+  guessing at it would be worse than saying nothing. A dispute that cannot be
+  matched to a payment is still announced, with `paymentId: null` and an error
+  log: money has left the account, and silence is the worst outcome.
+- **`PaymentMethodService`** — saved-card management, gated behind
+  `features.cardManagement`. `listPaymentMethods`, `setDefaultPaymentMethod`,
+  `removePaymentMethod`, `confirmSetup`, `resolveChargeablePaymentMethod` and
+  `requireChargeablePaymentMethod`. Keyed by `(divisionId, clientDetailsId)`
+  rather than a customer id, so tenant scope is structural; every method naming
+  a `paymentMethodId` verifies ownership and throws
+  `PaymentMethodNotOwnedException` otherwise. Requested by the jobsites team.
+- **`PaymentCustomer.defaultPaymentMethodId`** — optional, a read-through cache
+  of the provider's own default. The provider stays authoritative for what gets
+  charged; this exists so a consumer can render the current card without a
+  round trip. Requires `features.cardManagement`.
+- **Four optional members on `RecurringPaymentGateway`** —
+  `listPaymentMethods`, `detachPaymentMethod`, `setDefaultPaymentMethod`,
+  `getDefaultPaymentMethod` — reached through
+  `GatewayRegistryService.getPaymentMethodCapable()`.
+- **`@ambushsoftworks/nestjs-payments-graphql/testing`** — in-memory
+  repositories and a transaction manager, so a consumer can test an integration
+  without a database. They enforce the unique constraints the reference schema
+  declares, because the package's recovery paths depend on them. They do not
+  model row locking; for that, run against PostgreSQL.
+- **`@ambushsoftworks/nestjs-payments-graphql/graphql`** — the `@InputType`
+  classes, moved off the main entry point.
+- **New exceptions:** `PaymentMethodNotOwnedException`
+  (`PAYMENT_METHOD_NOT_OWNED`), `PaymentMethodOperationNotSupportedException`
+  (`PAYMENT_METHOD_OPERATION_NOT_SUPPORTED`),
+  `NoChargeablePaymentMethodException` (`NO_CHARGEABLE_PAYMENT_METHOD`).
+- **`SavedPaymentMethod`** GraphQL object type and TypeScript interface.
+- **`computeNextInvoiceDateAfter`** and **`assertMoneyAmount`**, both exported.
+- **Five README sections that did not exist:** Services, Tenancy and scoping,
+  Error handling, Operations, and Upgrading. Three exported services had never
+  been mentioned in the README at all, and neither had the manual-payment
+  confirmation flow the Quick Start promises.
+
+### Fixed
+- **Two writers of `amountPaid`/`amountDue` disagreed on the invariant.**
+  `RefundService` derived `amountDue` from the clamped `amountPaid` and
+  documented that the two must sum to the total; `applyPaymentToInvoice` wrote
+  `amountPaid` unclamped and `amountDue` clamped, so an overpayment persisted
+  exactly the state the other side's comment forbade. Both now share
+  `deriveInvoiceAmounts`: `amountPaid` records reality and never goes negative,
+  `amountDue` is always derived from it, and an overpayment is kept and logged
+  rather than silently absorbed — it is money somebody has to decide about.
+- **A lost refund response could refund twice.** `stripe.refunds.create` carried
+  no idempotency key, so a refund whose HTTP response was lost was
+  indistinguishable from one that failed. The operator retries,
+  `resolveRefundAmount` reads the local table — which never recorded the first —
+  and a second real refund goes out. The `(paymentId, providerRefundId)`
+  constraint cannot catch it: two genuinely different provider refunds. Now
+  keyed on the payment and amount, so a retry collapses while a deliberate
+  second partial refund still goes through.
+  - **Who was affected.** Anyone issuing online refunds. The 0.4.0 post-mortem
+    measured a refund call at 7.8 seconds; a timeout anywhere in that window is
+    all it takes.
+- **A stalled recurring template charged once per missed cycle.** The claim
+  advanced `nextInvoiceAt` by one cycle from its own stale value, leaving the
+  template still due, so the batch loop re-claimed it and went round again. A
+  daily template six weeks behind generated ~42 invoices in one run — and under
+  `autoCharge`, 42 distinct invoice ids meant 42 distinct idempotency keys and
+  **42 real card charges**. Missed cycles are now skipped, matching `resume()`.
+  - `computeNextInvoiceDateAfter` also corrects an overshoot in `resume()`
+    itself: rounding the elapsed cycles could step over a date that had not
+    happened yet, so a Jan 15 anchor resumed on May 3 moved to June 15 rather
+    than May 15.
+- **ACH and other delayed payments closed the invoice before settling.**
+  `checkout.session.completed` was treated as success regardless of
+  `payment_status`, so a session completing `unpaid` with the intent still
+  `processing` marked the payment SUCCEEDED, closed the invoice and emailed a
+  receipt. There was no way back — `handlePaymentFailed` only transitions from
+  PENDING/PROCESSING, so a later ACH return could not reopen it. The webhook now
+  emits `payment.processing` unless the session is genuinely paid.
+- **Voiding an invoice left its payment session live.** `voidInvoice`'s comment
+  said cancellation was "handled separately by the caller"; no such call
+  existed, and `PaymentGateway.cancelPayment` was implemented and invoked
+  nowhere. The client's open checkout tab stayed payable: they pay, the webhook
+  declines to apply it, and the money sits at the provider with no refund path.
+  Voiding now cancels pending provider sessions, outside any transaction, and
+  flags `needsReconciliation` when the provider cannot be reached.
+- **A declined Checkout card was never recorded as failed.**
+  `handlePaymentFailed` and `handlePaymentProcessing` looked up the event's own
+  id, but a Checkout row is keyed by the session id while
+  `payment_intent.payment_failed` carries the intent id. The lookup never
+  matched, the idempotency row was written so Stripe stopped retrying, and no
+  listener heard anything. Both now resolve canonically and fall back to the
+  invoice the event names.
+- **`sendInvoice` could send twice and store a mismatched e-transfer pair.**
+  Read-then-write with no lock let two callers both observe DRAFT and proceed:
+  two "your invoice" emails, and both ran `assignCode`, so the stored
+  `eTransferCode` and `eTransferAnswer` could come from different writers. The
+  client was emailed a pair that did not match the row and their transfer
+  bounced. The transition is now claimed under a row lock. `ensureSent` is
+  documented as the call to make before opening a payment session, so a
+  double-clicked Pay button was the ordinary way in.
+- **A rolled-back payment could leave an instalment permanently PAID.**
+  `applyPaymentToInvoice` ran inside the caller's transaction but notified
+  `PaymentPlanService` through the module-scoped repository, which committed on
+  a separate connection. The instalment update now happens after the
+  transaction commits.
+- **Cancelling a payment plan voided invoices outside its own transaction**, and
+  since voiding now calls the provider, would have made a provider call inside
+  one. The cancellation is transactional; the invoice voids follow it.
+- **A failed line item restarted invoice creation and orphaned the first
+  invoice.** The retry caught `UniqueConstraintViolationException` from a block
+  spanning creation, every line item, tax components and the totals update, then
+  retried the whole thing with a fresh number — leaving a numbered row with
+  partial line items and `total: 0`, indistinguishable from a real invoice. Only
+  the `create` is retried now.
+- **Refunding a payment on a VOID invoice made it payable again.** Status was
+  derived from amounts alone, so a partial refund moved a voided invoice to
+  `PARTIALLY_PAID` — which is in `PAYABLE_STATUSES`. VOID is now terminal.
+- **The services accepted money that was not money.** `amount: -5000` passed
+  `recordManualPayment`'s only check and left the invoice owing more than its
+  total; `amount: 10.5` stored fractional cents that propagated into every later
+  sum. The only guards were in the GraphQL DTOs, which the documented
+  architecture does not require anyone to use.
+- **A Stripe gateway that failed to construct was swallowed.** The consumer
+  booted cleanly, every payment threw at request time, and the webhook answered
+  400 — so Stripe retried every real payment event for three days and then
+  disabled the endpoint. Supplying `stripe` config now means a failure to build
+  the gateway fails the boot.
+- **`checkout.session.completed` cast `payment_intent` to a string.** Stripe
+  sends null for a zero-amount or fully-discounted session; the cast fed null to
+  `paymentIntents.retrieve`, whose failure was logged as a receipt-URL problem.
+- **Documentation corrections.** The auth-exemption instructions told readers to
+  compare a route path against `PAYMENTS_WEBHOOK`, which is a metadata key — a
+  guard written as documented never matches and every webhook 401s. Invoice
+  numbering was described as per-division and is global. The e-transfer prefix
+  sample produced `ARD--A1B2-C3D4` because the service adds its own separator,
+  and the documented code format named an invoice component that does not
+  exist. The webhook controller was described as mounting conditionally; it
+  mounts always. Design Principles contradicted the Email Options table on which
+  pieces are required.
+
+### Changed
+- **The scope key for provider customers belongs to your repository.**
+  `StripeGateway.createOrRetrieveCustomer` no longer searches the provider for
+  a customer to adopt; it creates. `IPaymentCustomerRepository.findByClientAndProvider`
+  is the only index, so filtering on `divisionId` gives each division its own
+  wallet and ignoring it gives one client one wallet across all of them —
+  whichever is right for what a division means in your product.
+
+  This **supersedes the 0.5.0 fix below rather than relaxing it.** 0.5.0
+  narrowed *which* provider customers could be adopted, from "anyone with this
+  email" to "one this package created for this division and client". That made
+  it safe and also nearly pointless: if the package created it, the package
+  wrote a row, and the repository lookup one step earlier would have found it.
+  Removing adoption entirely closes the same hole harder, and hands the
+  decision to the layer that can actually make it. Email was never identity —
+  a company billing address is shared by several clients, and clients change
+  email.
+
+  Requested by the jobsites team, whose `divisionId` is a job site: one
+  recruiter, one card, three sites. Note that a shared wallet means every
+  division can change the default card the others charge, and is only safe when
+  `clientDetailsId` is globally unique. Both are documented.
+- **`createInMemoryRepositories` takes `customerKey: 'division' | 'client'`**
+  (default `'division'`). The in-memory double enforced the reference schema's
+  three-column constraint unconditionally, which made it *more permissive than
+  the database* of a consumer scoped per client — the one failure mode a fake
+  must not have.
+- **`InvoiceService` and `PaymentService` gained a shared money validator**, and
+  `PaymentService.cancelPendingPaymentsForInvoice` is new and public.
+- **`PaymentGateway.createRefund` takes an optional `idempotencyKey`**, and
+  `RecurringPaymentGateway` gained the four optional card members above. All
+  optional, so a gateway written against v0.5.x still satisfies both interfaces.
+- **`assertPaymentsSchema` takes `cardManagement`.** The `PaymentCustomer`
+  requirement is now driven by either `recurringInvoices` or `cardManagement`,
+  and the new column is only required by the latter — so an existing consumer's
+  schema still passes unchanged.
+
+### Testing
+- **+87 specs, 551 across 24 suites.** New: `payment-method.service.spec.ts`,
+  `recurring-invoice-scheduling.spec.ts`, `money-validation.spec.ts`, plus
+  saved-card coverage on the Stripe gateway and the catch-up storm, the
+  session-cancellation path, the auto-charge convergence race and the money
+  validators. Five new documentation guards fail the build when an exported
+  service, a module option or an optional interface member goes undocumented —
+  each one encoding drift that had already happened.
+
 ## [0.5.0] - 2026-09-15
 
 > **Release candidates.** `0.5.0-rc.1` carries the tax-input changes, the
 > billing jobs, and the webhook retry and duplicate-delivery fixes. The shared
 > Prisma repositories (`@ambushsoftworks/nestjs-payments-graphql/prisma`) were
 > not in rc.1. `0.5.0-rc.2` adds them, with no change to the main entry point.
+> `0.5.0-rc.3` adds the saved-card and auto-charge fixes reported by the
+> jobsites team — retest auto-charge on a recurring template, and saving a card
+> end to end, against Stripe test mode.
 
 > **Upgrade notes.** No database migration.
 >
@@ -53,6 +302,23 @@ prose for buried obligations. The marker was introduced in v0.4.0 and
 >    so two concurrent `invoiceInstallment` calls cannot both link an invoice.
 > 5. If you construct `InvoiceService` or `RecurringInvoiceService` by hand, pass
 >    `{ requireExplicit: false }` as the new last argument.
+> 6. **If you use auto-charge or saved cards, they did not work before this
+>    release** — see the entries under Fixed. Nothing to migrate, but the
+>    first successful auto-charge on an existing recurring template may be its
+>    first ever. Check `consecutiveFailures` on your templates before upgrading:
+>    a template at 3 was auto-paused and stays paused until you resume it.
+> 7. **Provider customers are now scoped to the division that created them.**
+>    Existing shared customers are left alone, so nothing breaks on upgrade, but
+>    a client billed by two divisions will get a second provider customer the
+>    next time `createOrLinkCustomer` runs for the division that did not create
+>    the first one — and cards saved against the original are not visible to it.
+>    If you bill one client from more than one division and rely on a shared
+>    saved card, have them re-save it under the second division.
+> 8. If you construct `CustomerService` by hand, it takes two new constructor
+>    arguments: `PaymentConfigService` and the `DEFAULT_CURRENCY` value.
+> 9. **`createSetupSession().providerSetupId` is now the Checkout Session id**
+>    (`cs_…`), not the SetupIntent id. It previously returned `null` cast to a
+>    string on every call, so nothing can have depended on the old value.
 
 ### Added
 - **`tax.requireExplicit` module option.** With it set,
@@ -122,6 +388,16 @@ prose for buried obligations. The marker was introduced in v0.4.0 and
   schema, and copies drift.
 
 ### Changed
+- **`RecurringPaymentGateway` gained one optional method and three optional
+  params.** `adoptSetupPaymentMethod?()` records the card a completed setup
+  session collected; `createOffSessionPayment` takes `paymentMethodId?` and
+  `idempotencyKey?`; `createSetupSession` takes `currency?`. All optional, so a
+  custom gateway written against v0.2.x still satisfies the interface — but one
+  that does not implement `adoptSetupPaymentMethod` cannot support saved cards,
+  and the webhook logs a warning saying so.
+- **`CustomerService` takes two new constructor arguments**, `PaymentConfigService`
+  and the `DEFAULT_CURRENCY` value. This only matters if you construct it by
+  hand, in tests for example.
 - **An empty `taxComponents` list means untaxed.** `createInvoice` and
   `RecurringInvoiceService.create` treat `taxComponents: []` exactly like
   `taxRate: 0`, with no component rows and `taxAmount` 0, where it used to
@@ -164,6 +440,114 @@ prose for buried obligations. The marker was introduced in v0.4.0 and
   unrenamed. A hand-written adapter can still rename anything.
 
 ### Fixed
+
+Five of these were reported by the jobsites team against `0.2.0`, from running a
+prototype on live cards; the rest were found auditing the same paths before this
+release. They share one property: every one of them is silent. The API returns
+200, the webhook returns 200, and the logs look healthy.
+
+- **Auto-charge took the money and then refused to record it.**
+  `generateInvoiceFromConfig` creates a DRAFT invoice, optionally sends it, then
+  charges the saved card — and charged *before* checking the invoice could
+  accept a payment. `recordAutoChargePayment` then rejected the DRAFT, so the
+  charge stood at Stripe while the consumer's listener was told the renewal had
+  FAILED. One client was emailed a failure notice while the package held their
+  money. `attemptAutoCharge` now re-reads the invoice and refuses to call the
+  provider unless it is in `PAYABLE_STATUSES`, recording an
+  `invoice_not_payable` failure instead.
+  - **Who was affected.** Any consumer using recurring auto-charge. Two
+    configurations reach it: `autoCharge: true` with `autoSend: false`, which
+    jobsites found, and `autoSend: true` where `sendInvoice` throws — an email
+    transport outage, say — which `generateInvoiceFromConfig` swallows as
+    non-fatal before charging anyway. The second was not reported and is the
+    reason the fix is a status check at the charge site rather than a validation
+    on the template.
+  - **Detecting affected charges.** Look for provider charges whose invoice is
+    still DRAFT, or for `onRecurringPaymentFailed` events whose invoice has no
+    corresponding `Payment` row. The money is real; the invoice never moved.
+- **Auto-charge could be charged, paid, and reported as failed at the same time.**
+  Stripe fires `payment_intent.succeeded` the moment an off-session charge
+  settles, so the webhook races `recordAutoChargePayment` for the same
+  `(provider, providerPaymentId)`. The webhook usually won: its writer applied
+  the amount and closed the invoice, then `recordAutoChargePayment` hit the
+  unique constraint, its transaction rolled back, and the throw reached
+  `attemptAutoCharge`'s catch — which recorded a failure and fired
+  `onRecurringPaymentFailed`. **The client was charged, the invoice was paid,
+  and the consumer was told the renewal had failed.** Three consecutive
+  "failures" auto-pause the schedule, so a working subscription could pause
+  itself. Both writers now converge on one row, covering either ordering: a
+  pre-check for a webhook that already committed (needed because
+  `validatePayable` would otherwise throw on the now-PAID invoice before the
+  constraint could fire), and unique-violation adoption for one that commits
+  mid-transaction. The adopting call announces nothing — the writer that caused
+  the transition already did.
+- **Auto-charge billed the invoice total, not the balance.** The payable-status
+  check re-read the invoice, but the amount still came from the snapshot taken
+  before the invoice was sent. Anything that landed in between — an operator
+  recording an advance, or the client paying the link in the auto-send email —
+  leaves the invoice `PARTIALLY_PAID`, which *is* payable, so the check passed
+  and the full total was charged on top. `recordAutoChargePayment` validates
+  payability but never the amount, so nothing downstream caught it, and
+  `applyPaymentToInvoice` clamped `amountDue` to zero and marked the invoice
+  PAID while the client had been billed twice. It now charges `amountDue`, and
+  skips entirely when nothing is outstanding.
+- **`RecurringInvoiceService` threw a `TypeError` when the feature was off.**
+  The module provides `RECURRING_INVOICE_REPOSITORY` as `?? null` while the
+  service injected it as non-null — the same defect fixed in `PaymentPlanService`
+  and `CustomerService` above, and the last of the three. A consumer whose cron
+  called `processDueRecurringInvoices` without `features.recurringInvoices` got
+  `Cannot read properties of null` inside a scheduler. It now names the missing
+  option.
+- **Auto-charge could never charge anyone.** `createOffSessionPayment` built a
+  PaymentIntent with a `customer` and no `payment_method`. Stripe applies
+  `invoice_settings.default_payment_method` to Invoices and Subscriptions, not
+  to a bare PaymentIntent, so confirming one failed every time with *"You cannot
+  confirm this PaymentIntent because it's missing a payment method."* The
+  gateway now resolves the customer's default method and attaches it explicitly,
+  accepts an optional `paymentMethodId` override, and returns
+  `failureReason: 'no_payment_method'` without calling Stripe when nothing
+  resolves — rather than falling back to whichever card was added most recently.
+- **"Add a card" failed for every client.** `createSetupSession` omitted
+  `currency`, which Stripe requires in `mode: 'setup'` when `payment_method_types`
+  is not given, so every call raised *"Missing required param: currency."* The
+  currency now comes from the division's `PaymentConfig.defaultCurrency`, then
+  the module's `defaultCurrency`, and can be overridden per call. This is the
+  first thing in the package to read `PaymentConfig.defaultCurrency`.
+- **A saved card was invisible to auto-charge.** Nothing in the package ever
+  wrote `invoice_settings.default_payment_method` — the gateway's own docblock
+  asserted that Stripe set it on setup-session completion, which Stripe does
+  not do. The webhook now records the collected method as the customer's
+  default when they have none, leaving an existing default alone so adding a
+  second card does not silently change which one gets charged. Together with
+  the two entries above, this is the first release in which saving a card and
+  charging it later works end to end.
+- **`PaymentPlanService` threw on every successful payment when payment plans
+  were off.** `PaymentService` calls `onInvoicePaid` after every invoice reaches
+  PAID, and the service dereferenced a repository the module provides as `null`,
+  logging `Cannot read properties of null` each time. Cosmetic, but it trains
+  people to ignore payment warnings in a module where the other four bugs here
+  are silent. `onInvoicePaid` and `markInstallmentOverdue` now return early, and
+  consumer-facing methods name the missing option instead of throwing a
+  `TypeError`. `CustomerService` had the same latent fault and got the same
+  treatment.
+- **Two divisions billing the same person shared one provider customer, and one
+  set of saved cards.** `createOrRetrieveCustomer` matched on email across the
+  whole Stripe account, ignoring the `divisionId`/`clientDetailsId` metadata it
+  then wrote — so it also adopted customers this package never created. It now
+  reuses a customer only when both metadata values match, and creates one
+  otherwise. Found while fixing the reported bugs, not reported. See upgrade
+  note 7.
+- **A retried generation job could charge twice.** The off-session
+  `paymentIntents.create` carried no `idempotencyKey`, unlike
+  `createPaymentIntent`. It now derives one from the invoice id.
+- **Auto-charge payments never recorded a receipt URL.**
+  `createOffSessionPayment` read `latest_charge.receipt_url` without expanding
+  `latest_charge`, so the field was an id string and the check silently fell
+  through to `undefined` on every charge.
+- **`createSetupSession` returned null as a string.** `providerSetupId` was
+  `session.setup_intent`, which Stripe leaves null in setup mode until the
+  customer completes the session, feeding a non-nullable GraphQL field. It now
+  returns the Checkout Session id.
 - **`invoiceInstallment` recorded a tax rate it did not charge.** Its single
   line was non-taxable and it passed no tax, so `PaymentConfig.defaultTaxRate`
   was stamped on the invoice. With a 13% default, the client received a
@@ -566,16 +950,6 @@ API wrote — and delete the rest. Then recalculate the affected invoices;
 ### 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.
 
-## [0.1.3] - 2026-05-15
-
-### Added
-- **`NormalizedWebhookEvent` / `IgnoredWebhookEvent` types** exported from the package root. `PaymentGateway.handleWebhook` now returns the discriminated union; the `'ignored'` variant signals "received but no action needed" so the webhook controller responds 200 instead of 400 + Stripe retry loop. See "Stripe Gateway & Webhooks" in the README.
-
-### Changed
-- **Stripe webhook controller now responds 200 for unrecognized Stripe event types** (e.g. `payment_intent.created`, `charge.updated`, `charge.succeeded`). Previously it threw inside the gateway's `normalizeWebhookEvent` and the controller's signature-verification try/catch re-threw as `BadRequestException('Webhook signature verification failed')`, causing Stripe to retry the delivery for ~3 days and filling logs with misleading "signature verification failed" messages. The new behavior matches Stripe's documented contract: log unrecognized events at `debug`, acknowledge with 200. Real signature failures are unchanged (still 400 with the correct error message).
-- **`PaymentService` now logs a WARN when a SUCCEEDED payment lands on an invoice in a non-payable status** (DRAFT, VOID, PAID, REFUNDED, …). Previously this was a silent skip — the consumer's card was charged but the invoice never updated. Affects both `handlePaymentSucceeded` (webhook path) and `reconcilePayment` (reconciliation scheduler path). Most commonly hit when a consumer creates a DRAFT invoice and starts checkout without first calling `InvoiceService.sendInvoice` to transition it to SENT.
-- **`PaymentGateway.handleWebhook` return type widened from `Promise<PaymentWebhookEvent>` to `Promise<NormalizedWebhookEvent>`** to express the new `'ignored'` variant. TypeScript covariance: existing custom-gateway implementations whose `handleWebhook` is declared as `Promise<PaymentWebhookEvent>` continue to satisfy the interface without modification (no TS error). Callers who destructure the return value should add a guard on the discriminator (`if (event.type === 'ignored') return;`) before accessing `PaymentWebhookEvent`-only fields.
-
 ## [0.2.0] - 2026-05-15
 
 ### Added
@@ -587,6 +961,16 @@ API wrote — and delete the rest. Then recalculate the affected invoices;
 ### Changed
 - **`InvoiceModel.payments` and `InvoiceModel.lineItems` are now nullable in the GraphQL schema** (`@Field(() => [...], { nullable: 'itemsAndList' })`, TS properties optional). The package ships no `@ResolveField` for these fields per its "no resolvers in the package" rule; the previous non-nullable declaration caused Apollo to throw `Cannot return null for non-nullable field` for any consumer that hadn't wired up their own resolver. Both fields now carry JSDoc explaining the consumer-population responsibility. **This is a GraphQL schema-shape change**: consumer clients that selected `payments` or `lineItems` and assumed non-null arrays must now handle `null` (defensive `?.` / `?? []`).
 
+## [0.1.3] - 2026-05-15
+
+### Added
+- **`NormalizedWebhookEvent` / `IgnoredWebhookEvent` types** exported from the package root. `PaymentGateway.handleWebhook` now returns the discriminated union; the `'ignored'` variant signals "received but no action needed" so the webhook controller responds 200 instead of 400 + Stripe retry loop. See "Stripe Gateway & Webhooks" in the README.
+
+### Changed
+- **Stripe webhook controller now responds 200 for unrecognized Stripe event types** (e.g. `payment_intent.created`, `charge.updated`, `charge.succeeded`). Previously it threw inside the gateway's `normalizeWebhookEvent` and the controller's signature-verification try/catch re-threw as `BadRequestException('Webhook signature verification failed')`, causing Stripe to retry the delivery for ~3 days and filling logs with misleading "signature verification failed" messages. The new behavior matches Stripe's documented contract: log unrecognized events at `debug`, acknowledge with 200. Real signature failures are unchanged (still 400 with the correct error message).
+- **`PaymentService` now logs a WARN when a SUCCEEDED payment lands on an invoice in a non-payable status** (DRAFT, VOID, PAID, REFUNDED, …). Previously this was a silent skip — the consumer's card was charged but the invoice never updated. Affects both `handlePaymentSucceeded` (webhook path) and `reconcilePayment` (reconciliation scheduler path). Most commonly hit when a consumer creates a DRAFT invoice and starts checkout without first calling `InvoiceService.sendInvoice` to transition it to SENT.
+- **`PaymentGateway.handleWebhook` return type widened from `Promise<PaymentWebhookEvent>` to `Promise<NormalizedWebhookEvent>`** to express the new `'ignored'` variant. TypeScript covariance: existing custom-gateway implementations whose `handleWebhook` is declared as `Promise<PaymentWebhookEvent>` continue to satisfy the interface without modification (no TS error). Callers who destructure the return value should add a guard on the discriminator (`if (event.type === 'ignored') return;`) before accessing `PaymentWebhookEvent`-only fields.
+
 ## [0.1.2] - 2026-04-19
 
 ### Fixed