@saasicat/spec 1.0.0-rc.15 → 1.0.0-rc.17

package/admin-api.openapi.yaml

@@ -29,7 +29,7 @@ openapi: 3.1.0
 
 info:
     title: SaaS Platform SuperAdmin API
-    version: 1.0.0-rc.15
+    version: 1.0.0-rc.17
     description: |
         Read and write operations for platform administration:
         tenants, users, subscriptions, promo codes, audit log,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saasicat/spec",
-  "version": "1.0.0-rc.15",
+  "version": "1.0.0-rc.17",
   "description": "Language-neutral spec of the SaaS platform: JSON Schemas, OpenAPI contract, Prisma fragments, acceptance scenarios.",
   "type": "module",
   "main": "./index.cjs",

package/prisma-fragments/01-subscription.prisma

@@ -1,5 +1,5 @@
 // =============================================================================
-// SaaS-Platform Prisma fragment: Subscription + Payment method
+// SaaS-Platform Prisma fragment: Subscription + CheckoutOffer
 // =============================================================================
 //
 // REFERENCE SNIPPET — not a standalone schema. Consumers copy
@@ -39,14 +39,6 @@ enum SubscriptionStatus {
     PENDING_SALES
 }
 
-enum SubscriptionPaymentType {
-    CARD
-    SEPA
-    PAYPAL
-    KLARNA
-    INVOICE
-}
-
 // -----------------------------------------------------------------------------
 // Subscription — one per Tenant. Binds to PlanVersion (see 03-plan-versions).
 // -----------------------------------------------------------------------------
@@ -140,7 +132,6 @@ model Subscription {
 
     // Relations — consumer must define `Tenant` and enable the relation.
     // tenant             Tenant                    @relation(fields: [tenantId], references: [id], onDelete: Cascade)
-    paymentMethod       SubscriptionPaymentMethod?
     promoRedemption     PromoCodeRedemption? // see 02-promo-code.prisma
     planVersion         PlanVersion                 @relation("SubscriptionPlanVersion", fields: [planVersionId], references: [id])
     pendingPlanVersion  PlanVersion?                @relation("SubscriptionPendingPlanVersion", fields: [pendingPlanVersionId], references: [id])
@@ -154,39 +145,6 @@ model Subscription {
     @@map("subscriptions")
 }
 
-// -----------------------------------------------------------------------------
-// SubscriptionPaymentMethod — masked payment data per Subscription.
-// -----------------------------------------------------------------------------
-
-model SubscriptionPaymentMethod {
-    id             String                  @id @default(uuid())
-    subscriptionId String                  @unique
-    type           SubscriptionPaymentType
-
-    // Card (masked)
-    cardName  String?
-    cardBrand String?
-    cardLast4 String?
-    cardExp   String?
-
-    // SEPA (masked)
-    ibanLast4 String?
-    ibanName  String?
-
-    // PayPal
-    paypalEmail String?
-
-    // Klarna
-    klarnaPlan String? // "invoice" | "instalments"
-
-    createdAt DateTime @default(now())
-    updatedAt DateTime @updatedAt
-
-    subscription Subscription @relation(fields: [subscriptionId], references: [id], onDelete: Cascade)
-
-    @@map("subscription_payment_methods")
-}
-
 // -----------------------------------------------------------------------------
 // CheckoutOffer — immutable package snapshot from the website through to the
 // Subscription (METAMODELL §17a).

package/prisma-fragments/08-subscription-contract.prisma

@@ -8,6 +8,12 @@
 // V3 rule: billing and entitlement must not depend on live-mutable catalog
 // tables. `SubscriptionContract` and `ContractLineItem` therefore store full
 // snapshots. Catalog FKs are optional and only audit/trace references.
+//
+// A contract belongs to its subscriber (13-subscriber.prisma), not to the
+// tenant, and outlives the tenant (ADR 0012). `tenantId` is kept as a trace of
+// the tenant it was concluded for, and deliberately has no relation to the
+// application's `Tenant` model: a cascade there deletes the tax record with the
+// tenant, and a restriction keeps a tenant from ever being deleted.
 
 enum SubscriptionContractStatus {
     active
@@ -28,6 +34,19 @@ model SubscriptionContract {
     id       String @id @default(uuid())
     tenantId String
 
+    // Who the contract is between, copied on the day it is concluded: the
+    // subscriber as its record stood, and the issuer as `config/saas.yaml`
+    // named it — null where it named none. Neither copy follows a later change
+    // to the subscriber or the configuration. The invoice email is not copied:
+    // it says how the party is reached, not who it is.
+    subscriberId       String
+    subscriberSnapshot Json
+    issuerSnapshot     Json?
+    // The copies were made by the migration that attached contracts concluded
+    // before subscribers existed, not at conclusion, and are never presented as
+    // what was agreed.
+    partiesMigrated    Boolean @default(false)
+
     status         SubscriptionContractStatus @default(active)
     effectiveFrom  DateTime
     effectiveUntil DateTime?
@@ -50,9 +69,10 @@ model SubscriptionContract {
     createdAt DateTime @default(now())
     updatedAt DateTime @updatedAt
 
-    // tenant Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+    subscriber Subscriber @relation(fields: [subscriberId], references: [id], onDelete: Restrict)
 
     @@index([tenantId, status, effectiveFrom])
+    @@index([subscriberId])
     @@index([status])
     @@index([originalOfferId])
     @@map("subscription_contracts")

package/prisma-fragments/09-pending-registration.prisma

@@ -1,5 +1,5 @@
 // =============================================================================
-// SaaS Platform Prisma fragment: PendingRegistration + PaymentEventLog
+// SaaS Platform Prisma fragment: PendingRegistration
 // =============================================================================
 //
 // REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
@@ -7,8 +7,9 @@
 // Persistence of the multi-step registration and onboarding flow
 // (`PendingRegistrationService`). A PendingRegistration holds the
 // intermediate state between step 1 (capturing sign-up data) and the final
-// activation (step 4: payment). Only after successful payment does it become
-// User + Tenant + Subscription — until then the record deliberately stays
+// activation (step 4: billing address and payment method). Only once the
+// payment gateway confirmed the payment method does it become User + Tenant +
+// Subscriber + Subscription — until then the record deliberately stays
 // without a foreign key to consumer models.
 //
 // Unlike the other fragments, WITHOUT `@@map`: the model was adopted back from
@@ -16,12 +17,14 @@
 // default names — a subsequent `@@map` would only force a table rename.
 //
 // Contract: @saasicat/core (src/registration.types.ts) (PendingRegistration,
-//           PendingRegistrationRepository, PaymentEventLog).
+//           PendingRegistrationRepository). The gateway events a sign-up's
+//           confirmation is claimed in are `PaymentEventLog`, in
+//           14-payments.prisma.
 // Service logic: @saasicat/nest/registration (PendingRegistrationService).
 
 // Multi-step registration flow: status of a PendingRegistration
 // between sign-up-data capture (step 1) and final activation
-// after payment (step 4).
+// once the payment method is confirmed (step 4).
 enum RegistrationStatus {
     PENDING_EMAIL_VERIFICATION
     EMAIL_VERIFIED
@@ -64,11 +67,29 @@ model PendingRegistration {
     // - billingCycle: 'MONTHLY' | 'YEARLY' — determines the price calculation.
     // - appliedPromoCode: last-applied code (plaintext, only for UI display;
     //   validation runs fresh every time via PromoCodesService).
-    configJson        Json?
-    billingCycle      String?
-    appliedPromoCode  String?
-    checkoutSessionId String?
-    checkoutStartedAt DateTime?
+    configJson       Json?
+    billingCycle     String?
+    appliedPromoCode String?
+
+    // Billing details (step 4), which the subscriber is created with. The
+    // address is required before a payment method is set up; the tax
+    // identifiers stay optional.
+    addressLine1 String?
+    addressLine2 String?
+    postalCode   String?
+    city         String?
+    country      String? // ISO 3166-1 alpha-2
+    vatId        String?
+    taxNumber    String?
+
+    // The payment gateway's session for the payment method. A session id is
+    // unique only within the gateway account that opened it, so the account
+    // is kept beside it; the customer the gateway created is reused when the
+    // step is repeated.
+    checkoutSessionId      String?
+    checkoutGatewayAccount String?
+    gatewayCustomerRef     String?
+    checkoutStartedAt      DateTime?
 
     expiresAt DateTime
     createdAt DateTime @default(now())
@@ -76,21 +97,5 @@ model PendingRegistration {
 
     @@index([status, expiresAt])
     @@index([tenantSlug])
-}
-
-// PaymentEventLog — idempotency key for payment webhooks.
-// Prevents a doubly delivered webhook (Stripe at-least-once) from triggering
-// the final activation more than once. `eventId` is the provider event ID
-// (Stripe `event.id`), `tryClaim` uses a @unique INSERT as race protection.
-model PaymentEventLog {
-    id          String   @id @default(cuid())
-    eventId     String   @unique
-    provider    String
-    sessionId   String?
-    status      String
-    payload     Json?
-    processedAt DateTime @default(now())
-
-    @@index([sessionId])
-    @@index([status, processedAt])
+    @@index([checkoutGatewayAccount, checkoutSessionId])
 }

package/prisma-fragments/13-subscriber.prisma

@@ -0,0 +1,94 @@
+// =============================================================================
+// SaaS platform Prisma fragment: Subscriber, its tenants, its corrections
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
+//
+// A tenant is where the application keeps a customer's data. The subscriber is
+// the party the contract is with: a customer number and the master data a
+// contract names. A tenant can be deleted; its subscriber stays for as long as
+// a document that has to be kept belongs to it (ADR 0012). That is why nothing
+// here points at the application's `Tenant` model with a cascade — the link
+// below names the tenant as a value and stays after the tenant row is gone.
+//
+// Every model carries `Subscriber` in its name, so it cannot collide with a
+// `Customer` an application already keeps for the people it sells to.
+
+model Subscriber {
+    id String @id @default(uuid())
+
+    // The customer number, counted per installation. The number orders; the
+    // prefix is the one `config/saas.yaml` named when the subscriber was
+    // created, kept beside it so a later prefix renames nobody. Counting starts
+    // at 10001 (sql/constraints.postgres.sql), so numbers have five digits long
+    // before they need a sixth.
+    customerSequence     Int    @unique @default(autoincrement())
+    customerNumberPrefix String @default("")
+
+    // The legal identity. Only the name is required until invoicing requires
+    // the rest; under a running contract these change only as a correction,
+    // recorded in `SubscriberCorrection`.
+    legalName String
+    vatId     String?
+    taxNumber String?
+
+    // Contact details, which change at any time.
+    addressLine1 String?
+    addressLine2 String?
+    postalCode   String?
+    city         String?
+    country      String? // ISO 3166-1 alpha-2
+    invoiceEmail String?
+
+    // Created by the migration that gave every existing tenant its subscriber,
+    // from the application's own tenant record.
+    migrated Boolean @default(false)
+
+    createdAt DateTime @default(now())
+    updatedAt DateTime @updatedAt
+
+    tenants        SubscriberTenant[]
+    corrections    SubscriberCorrection[]
+    contracts      SubscriptionContract[]
+    paymentMethods      SubscriberPaymentMethod[] // see 14-payments.prisma
+    paymentMethodSetups SubscriberPaymentMethodSetup[]
+
+    @@map("subscribers")
+}
+
+// Which tenant a subscriber is live for, and which it was before. A subscriber
+// has at most one live tenant and a tenant at most one live subscriber — two
+// partial unique indexes in sql/constraints.postgres.sql, which Prisma cannot
+// express. `unlinkedAt` stays null while the link is live.
+model SubscriberTenant {
+    id           String    @id @default(uuid())
+    subscriberId String
+    tenantId     String
+    linkedAt     DateTime  @default(now())
+    unlinkedAt   DateTime?
+
+    subscriber Subscriber @relation(fields: [subscriberId], references: [id], onDelete: Restrict)
+
+    @@index([tenantId])
+    @@index([subscriberId])
+    @@map("subscriber_tenants")
+}
+
+// A correction of a subscriber's legal identity: the values it replaced, the
+// values it wrote, why, and who made it. Only the fields that moved are in the
+// two JSON objects. Written in the same transaction as the change, and never
+// rewritten.
+model SubscriberCorrection {
+    id           String   @id @default(uuid())
+    subscriberId String
+    previous     Json
+    corrected    Json
+    reason       String
+    correctedBy  String
+    correctedAt  DateTime
+
+    subscriber Subscriber @relation(fields: [subscriberId], references: [id], onDelete: Restrict)
+
+    @@index([subscriberId, correctedAt])
+    @@map("subscriber_corrections")
+}

package/prisma-fragments/14-payments.prisma

@@ -0,0 +1,100 @@
+// =============================================================================
+// SaaS platform Prisma fragment: SubscriberPaymentMethod, its setups, PaymentEventLog
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
+//
+// How a subscriber pays, as the payment gateway's reference to it. The card
+// number or the IBAN never reaches this table: the person enters them in the
+// gateway's own form, and what is kept is the gateway's reference and the
+// masked details that tell one payment method from another (ADR 0012).
+//
+// A reference means something only to the gateway account that issued it —
+// the merchant account named in `config/saas.yaml#payments.accounts` — so
+// every row records that account. A subscriber has at most one `ACTIVE`
+// payment method, a partial unique index in sql/constraints.postgres.sql;
+// the one a newer payment method replaced stays as `REPLACED`.
+//
+// Contract: @saasicat/core (SubscriberPaymentMethodRepository, PaymentEventLog).
+// Both are needed wherever payment methods are taken — self-registration or
+// not — because every gateway callback is claimed in `PaymentEventLog`.
+
+model SubscriberPaymentMethod {
+    id           String @id @default(uuid())
+    subscriberId String
+
+    // The account the references below belong to, and its provider when the
+    // payment method was confirmed.
+    gatewayAccount   String
+    provider         String
+    customerRef      String
+    paymentMethodRef String
+
+    // What tells the payment method apart, never enough to pay with it.
+    type             String // card | sepa_debit
+    brand            String?
+    last4            String
+    expiryMonth      Int?
+    expiryYear       Int?
+    country          String? // ISO 3166-1 alpha-2
+    bankCode         String?
+    mandateReference String?
+
+    status      String    @default("ACTIVE") // ACTIVE | REPLACED
+    confirmedAt DateTime
+    replacedAt  DateTime?
+    createdAt   DateTime  @default(now())
+
+    subscriber Subscriber @relation(fields: [subscriberId], references: [id], onDelete: Restrict)
+
+    @@unique([gatewayAccount, paymentMethodRef])
+    @@index([subscriberId, status])
+    @@index([gatewayAccount, status])
+    @@map("subscriber_payment_methods")
+}
+
+// A change of payment method a tenant started: the gateway session opened for
+// the subscriber. A confirmation is recorded only against the setup whose
+// account, session and subscriber it names, and completes it on the same
+// transaction — so a callback naming another subscriber than the session was
+// opened for changes nobody's payment method. A setup nobody finishes stays
+// open; it holds no reference that could be charged.
+model SubscriberPaymentMethodSetup {
+    id             String    @id @default(uuid())
+    subscriberId   String
+    gatewayAccount String
+    sessionRef     String
+    customerRef    String
+    startedAt      DateTime  @default(now())
+    completedAt    DateTime?
+
+    subscriber Subscriber @relation(fields: [subscriberId], references: [id], onDelete: Restrict)
+
+    @@unique([gatewayAccount, sessionRef])
+    @@index([subscriberId])
+    @@map("subscriber_payment_method_setups")
+}
+
+// PaymentEventLog — every payment gateway event, handled once.
+// Gateways deliver at least once. An event is claimed on the transaction that
+// writes what it changes, so a retry after a rollback is handled and a retry
+// after a commit finds the claim. `eventId` is unique only within the gateway
+// account that sent it — two accounts side by side never take each other's
+// event for a duplicate. `status` holds the event's kind as SaaSiCat read it
+// (`payment-method-confirmed`, …) and `payload` a summary that names no person.
+// One session is confirmed once, however many events report it: a partial
+// unique index in sql/constraints.postgres.sql, where the reasoning is.
+model PaymentEventLog {
+    id             String   @id @default(cuid())
+    gatewayAccount String
+    eventId        String
+    provider       String
+    sessionId      String?
+    status         String
+    payload        Json?
+    processedAt    DateTime @default(now())
+
+    @@unique([gatewayAccount, eventId])
+    @@index([sessionId])
+    @@index([status, processedAt])
+}

package/prisma-fragments/README.md

@@ -28,20 +28,22 @@ regenerated after fragment changes (`tests/reference-sql-drift.test.js`).
 
 ## Files
 
-| File                                                                 | Models                                                               |
-| -------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| [`01-subscription.prisma`](01-subscription.prisma)                   | `Subscription`, `SubscriptionPaymentMethod`, `CheckoutOffer` + Enums |
-| [`02-promo-code.prisma`](02-promo-code.prisma)                       | `PromoCode`, `PromoCodeRedemption`, `PromoCodeValidationLog` + Enums |
-| [`03-plan-versions.prisma`](03-plan-versions.prisma)                 | `Plan`, `PlanVersion`                                                |
-| [`04-audit-log.prisma`](04-audit-log.prisma)                         | `AuditLog`                                                           |
-| [`05-bundle.prisma`](05-bundle.prisma)                               | `Bundle`, `BundleVersion`                                            |
-| [`06-catalog-entries.prisma`](06-catalog-entries.prisma)             | Capability, feature, quota and marketing catalog models              |
-| [`07-promotion.prisma`](07-promotion.prisma)                         | `Promotion`                                                          |
-| [`08-subscription-contract.prisma`](08-subscription-contract.prisma) | `SubscriptionContract`, `ContractLineItem`                           |
-| [`09-pending-registration.prisma`](09-pending-registration.prisma)   | `PendingRegistration`, `PaymentEventLog` + `RegistrationStatus`      |
-| [`10-super-admin.prisma`](10-super-admin.prisma)                     | `SuperAdminUser`, `SuperAdminMfa`                                    |
-| [`11-subscription-bundle.prisma`](11-subscription-bundle.prisma)     | `SubscriptionBundle`                                                 |
-| [`12-applied-settings.prisma`](12-applied-settings.prisma)           | `AppliedSettings`, `SettingsChange`                                  |
+| File                                                                 | Models                                                                       |
+| -------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| [`01-subscription.prisma`](01-subscription.prisma)                   | `Subscription`, `CheckoutOffer` + Enums                                      |
+| [`02-promo-code.prisma`](02-promo-code.prisma)                       | `PromoCode`, `PromoCodeRedemption`, `PromoCodeValidationLog` + Enums         |
+| [`03-plan-versions.prisma`](03-plan-versions.prisma)                 | `Plan`, `PlanVersion`                                                        |
+| [`04-audit-log.prisma`](04-audit-log.prisma)                         | `AuditLog`                                                                   |
+| [`05-bundle.prisma`](05-bundle.prisma)                               | `Bundle`, `BundleVersion`                                                    |
+| [`06-catalog-entries.prisma`](06-catalog-entries.prisma)             | Capability, feature, quota and marketing catalog models                      |
+| [`07-promotion.prisma`](07-promotion.prisma)                         | `Promotion`                                                                  |
+| [`08-subscription-contract.prisma`](08-subscription-contract.prisma) | `SubscriptionContract`, `ContractLineItem`                                   |
+| [`09-pending-registration.prisma`](09-pending-registration.prisma)   | `PendingRegistration` + `RegistrationStatus`                                 |
+| [`10-super-admin.prisma`](10-super-admin.prisma)                     | `SuperAdminUser`, `SuperAdminMfa`                                            |
+| [`11-subscription-bundle.prisma`](11-subscription-bundle.prisma)     | `SubscriptionBundle`                                                         |
+| [`12-applied-settings.prisma`](12-applied-settings.prisma)           | `AppliedSettings`, `SettingsChange`                                          |
+| [`13-subscriber.prisma`](13-subscriber.prisma)                       | `Subscriber`, `SubscriberTenant`, `SubscriberCorrection`                     |
+| [`14-payments.prisma`](14-payments.prisma)                           | `SubscriberPaymentMethod`, `SubscriberPaymentMethodSetup`, `PaymentEventLog` |
 
 ## How the consumer uses the fragments
 
@@ -83,16 +85,24 @@ Fields such as `tenantId String` and `userId String?` remain as plain
 string columns in the fragments; the corresponding `@relation` is left as a
 comment. The consumer enables them using their own `Tenant`/`User` model names.
 
+Two models deliberately carry no such pointer: `SubscriptionContract` and
+`SubscriberTenant`. A contract belongs to its subscriber and outlives the tenant
+it was concluded for, so its `tenantId` is a trace — a cascade from the tenant
+would delete the tax record with it, and a restriction would keep the tenant
+from ever being deleted.
+
 ### 3. Table names (`@@map`) are canonical
 
-`subscriptions`, `subscription_payment_methods`, `checkout_offers`, `plans`,
-`plan_versions`, `promo_codes`, `promo_code_redemptions`,
-`promo_code_validation_logs`, `audit_logs`, `bundles`, `bundle_versions`,
-`capability_catalog_entries`, `feature_catalog_entries`,
+`subscriptions`, `checkout_offers`, `plans`, `plan_versions`, `promo_codes`,
+`promo_code_redemptions`, `promo_code_validation_logs`, `audit_logs`, `bundles`,
+`bundle_versions`, `capability_catalog_entries`, `feature_catalog_entries`,
 `quota_catalog_entries`, `marketing_projections`, `marketing_settings`,
 `promotions`, `subscription_contracts`, `contract_line_items`,
-`pending_registrations`, `payment_event_logs`, `super_admin_users`,
-`super_admin_mfa`, `subscription_bundles`.
+`super_admin_users`, `super_admin_mfa`, `subscription_bundles`, `subscribers`,
+`subscriber_tenants`, `subscriber_corrections`, `subscriber_payment_methods`,
+`subscriber_payment_method_setups`.
+`PendingRegistration` and `PaymentEventLog` carry no `@@map` and keep Prisma's
+default names, `"PendingRegistration"` and `"PaymentEventLog"`.
 Please do **not change** them — otherwise platform migration scripts and the
 `@saasicat/cli` commands that rely on these names will break.
 

package/schemas/plan-catalog.schema.json

@@ -137,6 +137,98 @@
                 }
             }
         },
+        "issuer": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["legalName"],
+            "description": "The legal entity on the operator's side of every contract this installation concludes, and later of every invoice it issues. A contract copies it on the day it is concluded, so the contract keeps naming its counterparty after this block changes. Optional for now: a contract concluded while it is absent records that no issuer was named.",
+            "properties": {
+                "legalName": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "The registered name, legal form included, as a contract names the party (e.g. \"Example Software GmbH\")."
+                },
+                "addressLine1": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Street and number."
+                },
+                "addressLine2": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "A second address line, such as a building or a c/o."
+                },
+                "postalCode": {
+                    "type": "string",
+                    "minLength": 1
+                },
+                "city": {
+                    "type": "string",
+                    "minLength": 1
+                },
+                "country": {
+                    "type": "string",
+                    "pattern": "^[A-Z]{2}$",
+                    "description": "ISO 3166-1 alpha-2 country code, e.g. DE."
+                },
+                "vatId": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "VAT identification number, e.g. DE123456789."
+                },
+                "taxNumber": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "The tax number the issuer's tax office assigned, where it is stated beside or instead of the VAT identification number."
+                }
+            }
+        },
+        "subscribers": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "How the parties this installation concludes contracts with are numbered.",
+            "properties": {
+                "customerNumberPrefix": {
+                    "type": "string",
+                    "pattern": "^[A-Za-z0-9._/-]{1,16}$",
+                    "description": "Put in front of every customer number assigned from the next start on: `K-` gives K-10001. A customer number keeps the prefix it was assigned with, so changing this renumbers nobody. Omitted, a customer number is the number alone."
+                }
+            }
+        },
+        "payments": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["accounts", "returnUrlOrigins"],
+            "description": "The payment gateway accounts this installation takes payment methods through. SaaSiCat keeps the gateway's reference to a payment method and its masked details, never a card number or an IBAN. The keys and the webhook secret of each account are bound in the application's code from the environment and never written here.",
+            "properties": {
+                "newPaymentMethods": {
+                    "type": "string",
+                    "pattern": "^[a-z0-9][a-z0-9-]{0,39}$",
+                    "description": "The account a new payment method is taken at, at sign-up and when a tenant changes its payment method. It names one of `accounts`, which then has to list its `methods`. Omitted, no new payment method is taken, and the accounts listed stay for the references they hold."
+                },
+                "returnUrlOrigins": {
+                    "type": "array",
+                    "minItems": 1,
+                    "uniqueItems": true,
+                    "items": {
+                        "type": "string",
+                        "pattern": "^https?://[^/?#\\s]+$"
+                    },
+                    "description": "The origins a gateway's form may send a person back to, e.g. `https://app.example.com`: the scheme, the host and a port, no path. A sign-up or a tenant naming a success or cancel URL at any other origin is refused, so the operator's own payment form cannot be made to forward somebody to a page of a stranger's choosing."
+                },
+                "accounts": {
+                    "type": "object",
+                    "minProperties": 1,
+                    "propertyNames": {
+                        "pattern": "^[a-z0-9][a-z0-9-]{0,39}$"
+                    },
+                    "additionalProperties": {
+                        "$ref": "#/$defs/PaymentGatewayAccount"
+                    },
+                    "description": "Every gateway account by the name its webhook route carries: `/webhooks/payment/<name>`. An account that still holds a payment method in use stays listed after another takes the new ones, so its callbacks keep being handled; a start that finds a stored reference to an account missing here refuses, naming the account."
+                }
+            }
+        },
         "features": {
             "type": "array",
             "items": {
@@ -153,6 +245,29 @@
         }
     },
     "$defs": {
+        "PaymentGatewayAccount": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["provider"],
+            "description": "One account at a payment gateway: a merchant account whose keys the application binds.",
+            "properties": {
+                "provider": {
+                    "type": "string",
+                    "pattern": "^[a-z0-9][a-z0-9-]{0,39}$",
+                    "description": "The gateway the account is at, as its adapter names itself: `stripe` for @saasicat/payment-stripe. A start refuses an account whose bound adapter names another."
+                },
+                "methods": {
+                    "type": "array",
+                    "minItems": 1,
+                    "uniqueItems": true,
+                    "items": {
+                        "type": "string",
+                        "enum": ["card", "sepa_debit"]
+                    },
+                    "description": "The payment methods a new payment method may be at this account: `card`, `sepa_debit`. Required for the account `newPaymentMethods` names and read for no other."
+                }
+            }
+        },
         "FeatureDef": {
             "type": "object",
             "required": ["key"],