@jskit-ai/payments-core 0.1.61 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,128 @@
+# Changelog
+
+## 0.2.0 - 2026-10-29
+
+- Translation ready: every user-visible text is a message key with its English in `locales/en.json`, so an app translates it by supplying translation files only. With no translations, texts and behaviour are unchanged. See the guide "Translating a JSKIT app".
+- `PaymentError` takes `{ messageCode, messageParams }` as its fourth argument; existing `payment_*` codes keep their values.
+
+### New message keys (53)
+
+All keys in `locales/en.json` (exported as `./locales/en.json`) are new in this version.
+
+<details><summary>Key list</summary>
+
+- `jskit.errors.payment_plan_unknown`
+- `jskit.errors.payment_readiness_invalid`
+- `jskit.errors.payment_forbidden`
+- `jskit.errors.payment_operation_conflict`
+- `jskit.errors.payment_request_invalid`
+- `jskit.errors.payment_subscription_exists`
+- `jskit.errors.payment_history_unavailable`
+- `jskit.errors.payment_customer_missing`
+- `jskit.errors.payment_reconciliation_required`
+- `jskit.errors.payment_customer_conflict`
+- `jskit.errors.payment_catalogue_pending`
+- `jskit.errors.payment_catalogue_uncertain`
+- `jskit.errors.payment_balance_limit`
+- `jskit.errors.payment_feature_required`
+- `jskit.errors.payment_insufficient_credits`
+- `jskit.errors.payment_debit_missing`
+- `jskit.errors.payment_customer_unbound`
+- `jskit.payments.scope.readinessMismatch`
+- `jskit.payments.scope.catalogueMismatch`
+- `jskit.payments.scope.merchantMismatch`
+- `jskit.payments.operation.unfinished`
+- `jskit.payments.operation.mayHaveSucceeded`
+- `jskit.payments.input.billingEmail`
+- `jskit.payments.input.historyPage`
+- `jskit.payments.input.historyCollection`
+- `jskit.payments.input.recoveryObjectId`
+- `jskit.payments.input.reference`
+- `jskit.payments.input.creditQuantity`
+- `jskit.payments.input.timestamp`
+- `jskit.payments.reference.otherPlan`
+- `jskit.payments.reference.differentInputs`
+- `jskit.payments.provider.checkAccount`
+- `jskit.payments.provider.unsupportedEvent`
+- `jskit.payments.provider.objectIdMissing`
+- `jskit.payments.provider.subscriptionBinding`
+- `jskit.payments.provider.renewalBinding`
+- `jskit.payments.webhook.rawBodyRequired`
+- `jskit.payments.webhook.verificationFailed`
+- `jskit.payments.configuration.invalid`
+- `jskit.payments.configuration.taxCategoryUnpublishable`
+- `jskit.payments.configuration.sharedConnectionRequired`
+- `jskit.payments.configuration.paddleEnvironment`
+- `jskit.payments.configuration.paddleTaxCategory`
+- `jskit.payments.configuration.paddleClientToken`
+- `jskit.payments.catalogue.reviewFirst`
+- `jskit.payments.catalogue.publicationChanged`
+- `jskit.payments.catalogue.planChanged`
+- `jskit.payments.catalogue.productChanged`
+- `jskit.payments.catalogue.priceChanged`
+- `jskit.payments.catalogue.pendingCatalogueRequestChanged`
+- `jskit.payments.catalogue.recoveryReviewChanged`
+- `jskit.payments.catalogue.pendingRequestChanged`
+- `jskit.payments.catalogue.objectMismatch`
+
+</details>
+
+### Codes (53)
+
+Error, field-error and message codes this package sends, with their English. Undotted codes kept their existing values and render from `jskit.errors.<code>`.
+
+| Code | English |
+| --- | --- |
+| `payment_plan_unknown` | Select a published payment plan. |
+| `payment_readiness_invalid` | App readiness checks must return bounded status and safe explanatory text. |
+| `payment_forbidden` | You cannot manage this billable account. |
+| `payment_operation_conflict` | The pending payment operation changed. |
+| `payment_request_invalid` | Supply a stable checkout request identifier. |
+| `payment_subscription_exists` | Manage the existing subscription through billing instead of starting another checkout. |
+| `payment_history_unavailable` | Billing history could not be loaded. Check provider access and retry. |
+| `payment_customer_missing` | Create a billing account first. |
+| `payment_reconciliation_required` | Provider inspection did not resolve this request. |
+| `payment_customer_conflict` | This provider customer is already bound to a different billable subject. |
+| `payment_catalogue_pending` | Another catalogue request needs resolution. |
+| `payment_catalogue_uncertain` | Catalogue publication stopped. Inspect the pending provider request before retrying; completed items are preserved. |
+| `payment_balance_limit` | Credit balance exceeds the supported integer range. |
+| `payment_feature_required` | Your subscription does not include this feature. |
+| `payment_insufficient_credits` | Not enough credits for this action. |
+| `payment_debit_missing` | No debit exists for this reference. |
+| `payment_customer_unbound` | Bind this provider customer before processing its events. |
+| `payments.scope.readinessMismatch` | Readiness returned a different payment account or environment. |
+| `payments.scope.catalogueMismatch` | Catalogue scope does not match its configured environment. |
+| `payments.scope.merchantMismatch` | The payment scope does not match this environment's merchant configuration. |
+| `payments.operation.unfinished` | Inspect the unfinished provider request before retrying. |
+| `payments.operation.mayHaveSucceeded` | Inspect this account's provider activity before retrying; the request may have succeeded. |
+| `payments.input.billingEmail` | Supply the authenticated billing contact's email. |
+| `payments.input.historyPage` | Select billing subscriptions or transactions and a valid page cursor. |
+| `payments.input.historyCollection` | Select a billing history collection. |
+| `payments.input.recoveryObjectId` | Supply the exact provider object ID to recover. |
+| `payments.input.reference` | Use a nonempty business reference of at most 150 characters. |
+| `payments.input.creditQuantity` | Use a positive integer credit quantity, at most one billion. |
+| `payments.input.timestamp` | Use an integer UTC timestamp in milliseconds. |
+| `payments.reference.otherPlan` | The checkout request already selected another plan. |
+| `payments.reference.differentInputs` | This business reference was already used with different inputs. |
+| `payments.provider.checkAccount` | Check the {provider} account, price mapping and subscription shape. |
+| `payments.provider.unsupportedEvent` | The event is not a supported subscription payment for this customer. |
+| `payments.provider.objectIdMissing` | The provider did not return an object ID. |
+| `payments.provider.subscriptionBinding` | Check the provider subscription and logical price binding. |
+| `payments.provider.renewalBinding` | Check the renewal's logical price binding. |
+| `payments.webhook.rawBodyRequired` | Supply the unmodified webhook request bytes. |
+| `payments.webhook.verificationFailed` | {provider} webhook verification failed. |
+| `payments.configuration.invalid` | Check the application's payment configuration. |
+| `payments.configuration.taxCategoryUnpublishable` | Set the application's Paddle product tax category before publishing. |
+| `payments.configuration.sharedConnectionRequired` | Select a shared Stripe or Paddle connection with a backend API-key Env reference for {environment}. |
+| `payments.configuration.paddleEnvironment` | Select a Paddle connection configured for {environment}. |
+| `payments.configuration.paddleTaxCategory` | Choose the Paddle tax category for the products this app sells. |
+| `payments.configuration.paddleClientToken` | Set the Env reference for this environment's Paddle public client token. |
+| `payments.catalogue.reviewFirst` | Review the current catalogue and resolve provider drift or unfinished requests first. |
+| `payments.catalogue.publicationChanged` | Another publication changed the catalogue; review again. |
+| `payments.catalogue.planChanged` | This plan changed; review again. |
+| `payments.catalogue.productChanged` | This product changed; review again. |
+| `payments.catalogue.priceChanged` | This price changed; review again. |
+| `payments.catalogue.pendingCatalogueRequestChanged` | The pending catalogue request changed. |
+| `payments.catalogue.recoveryReviewChanged` | The recovery review changed. Inspect the current pending operation first. |
+| `payments.catalogue.pendingRequestChanged` | The pending request changed. |
+| `payments.catalogue.objectMismatch` | The provider object does not match the pending operation. |

package/docs/contract.md

@@ -124,3 +124,11 @@ Configuration failures use `payment_configuration_invalid` (422). Field errors
 identify `extensions.payments/...` paths, including cross-reference failures at
 `environments/<environment>/integrationId` and missing Paddle token/tax-category
 fields. Messages explain the repair without echoing credential values.
+
+Every error keeps its English `message` and its stable `payment_*` `code`. The
+English of a code used for one sentence lives under `jskit.errors.<code>` in
+`locales/en.json`. Where one code covers several sentences, the error also
+carries `messageCode` and `messageParams` naming a `jskit.payments.*` message,
+and binding field errors carry `code` and `params`, so a JSKIT application can
+show them in the user's language. Other implementations may ignore these
+fields.

package/locales/en.json

@@ -0,0 +1,77 @@
+{
+  "jskit": {
+    "errors": {
+      "payment_plan_unknown": "Select a published payment plan.",
+      "payment_readiness_invalid": "App readiness checks must return bounded status and safe explanatory text.",
+      "payment_forbidden": "You cannot manage this billable account.",
+      "payment_operation_conflict": "The pending payment operation changed.",
+      "payment_request_invalid": "Supply a stable checkout request identifier.",
+      "payment_subscription_exists": "Manage the existing subscription through billing instead of starting another checkout.",
+      "payment_history_unavailable": "Billing history could not be loaded. Check provider access and retry.",
+      "payment_customer_missing": "Create a billing account first.",
+      "payment_reconciliation_required": "Provider inspection did not resolve this request.",
+      "payment_customer_conflict": "This provider customer is already bound to a different billable subject.",
+      "payment_catalogue_pending": "Another catalogue request needs resolution.",
+      "payment_catalogue_uncertain": "Catalogue publication stopped. Inspect the pending provider request before retrying; completed items are preserved.",
+      "payment_balance_limit": "Credit balance exceeds the supported integer range.",
+      "payment_feature_required": "Your subscription does not include this feature.",
+      "payment_insufficient_credits": "Not enough credits for this action.",
+      "payment_debit_missing": "No debit exists for this reference.",
+      "payment_customer_unbound": "Bind this provider customer before processing its events."
+    },
+    "payments": {
+      "scope": {
+        "readinessMismatch": "Readiness returned a different payment account or environment.",
+        "catalogueMismatch": "Catalogue scope does not match its configured environment.",
+        "merchantMismatch": "The payment scope does not match this environment's merchant configuration."
+      },
+      "operation": {
+        "unfinished": "Inspect the unfinished provider request before retrying.",
+        "mayHaveSucceeded": "Inspect this account's provider activity before retrying; the request may have succeeded."
+      },
+      "input": {
+        "billingEmail": "Supply the authenticated billing contact's email.",
+        "historyPage": "Select billing subscriptions or transactions and a valid page cursor.",
+        "historyCollection": "Select a billing history collection.",
+        "recoveryObjectId": "Supply the exact provider object ID to recover.",
+        "reference": "Use a nonempty business reference of at most 150 characters.",
+        "creditQuantity": "Use a positive integer credit quantity, at most one billion.",
+        "timestamp": "Use an integer UTC timestamp in milliseconds."
+      },
+      "reference": {
+        "otherPlan": "The checkout request already selected another plan.",
+        "differentInputs": "This business reference was already used with different inputs."
+      },
+      "provider": {
+        "checkAccount": "Check the {provider} account, price mapping and subscription shape.",
+        "unsupportedEvent": "The event is not a supported subscription payment for this customer.",
+        "objectIdMissing": "The provider did not return an object ID.",
+        "subscriptionBinding": "Check the provider subscription and logical price binding.",
+        "renewalBinding": "Check the renewal's logical price binding."
+      },
+      "webhook": {
+        "rawBodyRequired": "Supply the unmodified webhook request bytes.",
+        "verificationFailed": "{provider} webhook verification failed."
+      },
+      "configuration": {
+        "invalid": "Check the application's payment configuration.",
+        "taxCategoryUnpublishable": "Set the application's Paddle product tax category before publishing.",
+        "sharedConnectionRequired": "Select a shared Stripe or Paddle connection with a backend API-key Env reference for {environment}.",
+        "paddleEnvironment": "Select a Paddle connection configured for {environment}.",
+        "paddleTaxCategory": "Choose the Paddle tax category for the products this app sells.",
+        "paddleClientToken": "Set the Env reference for this environment's Paddle public client token."
+      },
+      "catalogue": {
+        "reviewFirst": "Review the current catalogue and resolve provider drift or unfinished requests first.",
+        "publicationChanged": "Another publication changed the catalogue; review again.",
+        "planChanged": "This plan changed; review again.",
+        "productChanged": "This product changed; review again.",
+        "priceChanged": "This price changed; review again.",
+        "pendingCatalogueRequestChanged": "The pending catalogue request changed.",
+        "recoveryReviewChanged": "The recovery review changed. Inspect the current pending operation first.",
+        "pendingRequestChanged": "The pending request changed.",
+        "objectMismatch": "The provider object does not match the pending operation."
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/payments-core",
-  "version": "0.1.61",
+  "version": "0.2.0",
   "type": "module",
   "description": "Application-owned payment configuration, subscription access and transactional usage credits.",
   "exports": {
@@ -15,7 +15,8 @@
     "./server/stripe": "./src/server/stripe.js",
     "./server/paddle": "./src/server/paddle.js",
     "./server/catalogue": "./src/server/catalogue.js",
-    "./server/readiness": "./src/server/readiness.js"
+    "./server/readiness": "./src/server/readiness.js",
+    "./locales/en.json": "./locales/en.json"
   },
   "scripts": {
     "test": "node --test --test-concurrency=1"

package/src/server/catalogue.js

@@ -1,7 +1,6 @@
-import { createHash, randomUUID } from "node:crypto";
-import { PaymentError } from "./service.js";
+import { randomUUID } from "node:crypto";
+import { PaymentError, fingerprint } from "./errors.js";
 
-const fingerprint = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
 const priceFields = (plan) => ({ amount: plan.amount, currency: plan.currency, interval: plan.interval });
 const samePrice = (a, b) => fingerprint(priceFields(a)) === fingerprint(priceFields(b));
 
@@ -12,7 +11,9 @@ function createPaymentCatalogue({ store, adapter, scope, configuration }) {
   const merchant = structuredClone(scope);
   const environment = configuration.environments[merchant.environment];
   if (!environment || environment.integrationId !== merchant.integrationId || environment.providerAccountId !== merchant.providerAccountId) {
-    throw new PaymentError("payment_scope_invalid", "Catalogue scope does not match its configured environment.", 403);
+    throw new PaymentError("payment_scope_invalid", "Catalogue scope does not match its configured environment.", 403, {
+      messageCode: "payments.scope.catalogueMismatch"
+    });
   }
   async function preview() {
     const state = await store.inspectCatalogue(merchant);
@@ -39,19 +40,19 @@ function createPaymentCatalogue({ store, adapter, scope, configuration }) {
   }
   async function publish({ reviewId }) {
     const review = await preview();
-    if (review.reviewId !== reviewId || review.drift.length || review.pending) throw new PaymentError("payment_catalogue_review_required", "Review the current catalogue and resolve provider drift or unfinished requests first.", 409);
+    if (review.reviewId !== reviewId || review.drift.length || review.pending) throw new PaymentError("payment_catalogue_review_required", "Review the current catalogue and resolve provider drift or unfinished requests first.", 409, { messageCode: "payments.catalogue.reviewFirst" });
     const completed = [];
     let expectedRevision = review.revision;
     for (const change of review.changes) {
       const token = randomUUID();
       const pending = await store.withCatalogue(merchant, async (state) => {
         if (state.pending) throw new PaymentError("payment_catalogue_pending", "Another catalogue request needs resolution.", 409);
-        if ((state.revision || 0) !== expectedRevision) throw new PaymentError("payment_catalogue_review_required", "Another publication changed the catalogue; review again.", 409);
+        if ((state.revision || 0) !== expectedRevision) throw new PaymentError("payment_catalogue_review_required", "Another publication changed the catalogue; review again.", 409, { messageCode: "payments.catalogue.publicationChanged" });
         const current = state.plans[change.planId];
         // Reject another publisher changing this plan after the reviewed read.
-        if (change.action === "create-product" && current) throw new PaymentError("payment_catalogue_review_required", "This plan changed; review again.", 409);
-        if (change.action === "rename-product" && current?.productId !== change.productId) throw new PaymentError("payment_catalogue_review_required", "This product changed; review again.", 409);
-        if (change.action === "create-price" && (!current?.productId || (current.priceId && samePrice(current, change)))) throw new PaymentError("payment_catalogue_review_required", "This price changed; review again.", 409);
+        if (change.action === "create-product" && current) throw new PaymentError("payment_catalogue_review_required", "This plan changed; review again.", 409, { messageCode: "payments.catalogue.planChanged" });
+        if (change.action === "rename-product" && current?.productId !== change.productId) throw new PaymentError("payment_catalogue_review_required", "This product changed; review again.", 409, { messageCode: "payments.catalogue.productChanged" });
+        if (change.action === "create-price" && (!current?.productId || (current.priceId && samePrice(current, change)))) throw new PaymentError("payment_catalogue_review_required", "This price changed; review again.", 409, { messageCode: "payments.catalogue.priceChanged" });
         const operation = { ...change, token, productId: current?.productId };
         state.pending = operation;
         return operation;
@@ -71,9 +72,9 @@ function createPaymentCatalogue({ store, adapter, scope, configuration }) {
     return { completed, removed: review.removed };
   }
   async function finish(pending, result) {
-    if (typeof result?.id !== "string" || !result.id) throw new PaymentError("payment_provider_result_invalid", "The provider did not return an object ID.", 502);
+    if (typeof result?.id !== "string" || !result.id) throw new PaymentError("payment_provider_result_invalid", "The provider did not return an object ID.", 502, { messageCode: "payments.provider.objectIdMissing" });
     await store.withCatalogue(merchant, async (state) => {
-      if (state.pending?.token !== pending.token) throw new PaymentError("payment_catalogue_review_required", "The pending catalogue request changed.", 409);
+      if (state.pending?.token !== pending.token) throw new PaymentError("payment_catalogue_review_required", "The pending catalogue request changed.", 409, { messageCode: "payments.catalogue.pendingCatalogueRequestChanged" });
       const current = state.plans[pending.planId];
       if (pending.action === "create-product") state.plans[pending.planId] = { productId: result.id, name: pending.name };
       else if (pending.action === "rename-product") current.name = pending.name;
@@ -87,26 +88,26 @@ function createPaymentCatalogue({ store, adapter, scope, configuration }) {
   }
   async function recover({ reviewId, providerId, confirmedNotCreated = false }) {
     const review = await preview();
-    if (review.reviewId !== reviewId) throw new PaymentError("payment_catalogue_review_required", "The recovery review changed. Inspect the current pending operation first.", 409);
+    if (review.reviewId !== reviewId) throw new PaymentError("payment_catalogue_review_required", "The recovery review changed. Inspect the current pending operation first.", 409, { messageCode: "payments.catalogue.recoveryReviewChanged" });
     const pending = review.pending;
     if (!pending) return { pending: false };
     if (confirmedNotCreated) {
       // Trusted app administrator must supply actual provider inspection evidence.
       // This parameter must not be exposed as an unauthenticated browser command.
       await store.withCatalogue(merchant, async (current) => {
-        if (current.pending?.token !== pending.token) throw new PaymentError("payment_catalogue_review_required", "The pending request changed.", 409);
+        if (current.pending?.token !== pending.token) throw new PaymentError("payment_catalogue_review_required", "The pending request changed.", 409, { messageCode: "payments.catalogue.pendingRequestChanged" });
         delete current.pending;
       });
       return { pending: false, retryAllowed: true };
     }
     if (typeof providerId !== "string" || !/^[A-Za-z0-9_-]{1,200}$/.test(providerId)) {
-      throw new PaymentError("payment_input_invalid", "Supply the exact provider object ID to recover.");
+      throw new PaymentError("payment_input_invalid", "Supply the exact provider object ID to recover.", 422, { messageCode: "payments.input.recoveryObjectId" });
     }
     const result = pending.action === "create-price" ? await adapter.readPrice(providerId) : await adapter.readProduct(providerId);
     if (!result || result.id !== providerId || (pending.action === "create-price" && (result.active !== true || result.productId !== pending.productId || !samePrice(result, pending))) ||
         (pending.action !== "create-price" && result.name !== pending.name) ||
         (pending.action === "rename-product" && providerId !== pending.productId)) {
-      throw new PaymentError("payment_catalogue_review_required", "The provider object does not match the pending operation.", 409);
+      throw new PaymentError("payment_catalogue_review_required", "The provider object does not match the pending operation.", 409, { messageCode: "payments.catalogue.objectMismatch" });
     }
     await finish(pending, { id: providerId });
     return { pending: false };

package/src/server/checkout.js

@@ -1,5 +1,5 @@
-import { createHash, randomUUID } from "node:crypto";
-import { PaymentError } from "./service.js";
+import { randomUUID } from "node:crypto";
+import { PaymentError, fingerprint } from "./errors.js";
 
 // Application composition boundary: authorization is mandatory and supplied by
 // the app's framework. Actor and subject must come from its authenticated route.
@@ -19,7 +19,7 @@ function createPaymentCheckoutService({ adapter, store, payments, merchantScope,
   async function perform(scope, operation, remote, complete) {
     const token = randomUUID();
     const prepared = await store.withAccount(scope, async (tx) => {
-      if (tx.state.pendingPaymentOperation) throw new PaymentError("payment_operation_uncertain", "Inspect the unfinished provider request before retrying.", 409);
+      if (tx.state.pendingPaymentOperation) throw new PaymentError("payment_operation_uncertain", "Inspect the unfinished provider request before retrying.", 409, { messageCode: "payments.operation.unfinished" });
       const ready = await operation(tx);
       if (ready.cached) return ready;
       tx.state.pendingPaymentOperation = { token, ...ready };
@@ -30,7 +30,7 @@ function createPaymentCheckoutService({ adapter, store, payments, merchantScope,
     // unresolved operation, rather than permitting a duplicate provider write.
     let result;
     try { result = await remote(prepared); }
-    catch { throw new PaymentError("payment_operation_uncertain", "Inspect this account's provider activity before retrying; the request may have succeeded.", 409); }
+    catch { throw new PaymentError("payment_operation_uncertain", "Inspect this account's provider activity before retrying; the request may have succeeded.", 409, { messageCode: "payments.operation.mayHaveSucceeded" }); }
     return store.withAccount(scope, async (tx) => {
       if (tx.state.pendingPaymentOperation?.token !== token) throw new PaymentError("payment_operation_conflict", "The pending payment operation changed.", 409);
       const value = await complete(tx, result, prepared);
@@ -42,8 +42,8 @@ function createPaymentCheckoutService({ adapter, store, payments, merchantScope,
     const scope = await allowed(actor, subjectId, "checkout");
     adapter.validatePlan(planId);
     if (typeof requestId !== "string" || !/^[A-Za-z0-9_-]{1,100}$/.test(requestId)) throw new PaymentError("payment_request_invalid", "Supply a stable checkout request identifier.");
-    if (typeof email !== "string" || email.length > 320 || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) throw new PaymentError("payment_input_invalid", "Supply the authenticated billing contact's email.");
-    const identity = createHash("sha256").update(JSON.stringify(scope)).digest("hex");
+    if (typeof email !== "string" || email.length > 320 || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) throw new PaymentError("payment_input_invalid", "Supply the authenticated billing contact's email.", 422, { messageCode: "payments.input.billingEmail" });
+    const identity = fingerprint(scope);
     const customerId = await perform(scope, async (tx) => tx.state.customerId
       ? { cached: true, result: tx.state.customerId }
       : { action: "customer", email },
@@ -53,7 +53,7 @@ function createPaymentCheckoutService({ adapter, store, payments, merchantScope,
     return perform(scope, async (tx) => {
       const saved = await tx.find(`checkout:${requestId}`);
       if (saved) {
-        if (saved.planId !== planId) throw new PaymentError("payment_reference_conflict", "The checkout request already selected another plan.", 409);
+        if (saved.planId !== planId) throw new PaymentError("payment_reference_conflict", "The checkout request already selected another plan.", 409, { messageCode: "payments.reference.otherPlan" });
         return { cached: true, result: saved.result };
       }
       if (Object.values(tx.state.subscriptions).some((subscription) =>
@@ -62,7 +62,7 @@ function createPaymentCheckoutService({ adapter, store, payments, merchantScope,
       }
       return { action: "checkout", customerId, planId, requestId };
     }, () => adapter.createCheckout({ customerId, planId, returnUrl: target.href,
-      requestId: `checkout-${createHash("sha256").update(JSON.stringify([scope, requestId])).digest("hex")}` }),
+      requestId: `checkout-${fingerprint([scope, requestId])}` }),
     async (tx, result) => { await tx.record(`checkout:${requestId}`, { planId, result }); return result; });
   }
   async function account({ actor, subjectId }) {
@@ -75,7 +75,7 @@ function createPaymentCheckoutService({ adapter, store, payments, merchantScope,
     const scope = await allowed(actor, subjectId, "history");
     if (!["subscriptions", "transactions"].includes(collection) ||
       (after !== null && (typeof after !== "string" || !/^[A-Za-z0-9_-]{1,200}$/.test(after)))) {
-      throw new PaymentError("payment_input_invalid", "Select billing subscriptions or transactions and a valid page cursor.");
+      throw new PaymentError("payment_input_invalid", "Select billing subscriptions or transactions and a valid page cursor.", 422, { messageCode: "payments.input.historyPage" });
     }
     // Never accept a customer identifier from the browser or editor caller.
     const { customerId } = await store.inspect(scope);
@@ -121,7 +121,7 @@ function createPaymentCheckoutService({ adapter, store, payments, merchantScope,
     const { eventId, customerId } = identity;
     return payments.reconcileEvent(merchant, { eventId, customerId, load: async () => {
       const facts = await adapter.loadEvent(event);
-      if (!facts || facts.customerId !== customerId) throw new PaymentError("payment_provider_result_invalid", "The event is not a supported subscription payment for this customer.", 422);
+      if (!facts || facts.customerId !== customerId) throw new PaymentError("payment_provider_result_invalid", "The event is not a supported subscription payment for this customer.", 422, { messageCode: "payments.provider.unsupportedEvent" });
       return facts;
     } });
   }

package/src/server/errors.js

@@ -0,0 +1,21 @@
+import { createHash } from "node:crypto";
+
+// code is the stable payment_* code callers branch on; a code shared by several
+// sentences adds a messageCode (and messageParams) naming this sentence.
+class PaymentError extends Error {
+  constructor(code, message, statusCode = 422, { messageCode = "", messageParams = {} } = {}) {
+    super(message);
+    this.name = "PaymentError";
+    this.code = code;
+    this.statusCode = statusCode;
+    if (messageCode) {
+      this.messageCode = messageCode;
+      this.messageParams = { ...messageParams };
+    }
+  }
+}
+
+// Stable sha256 hex of a JSON value: idempotency digests, review IDs and store keys.
+const fingerprint = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+
+export { PaymentError, fingerprint };

package/src/server/knexStore.js

@@ -1,6 +1,5 @@
-import { createHash } from "node:crypto";
+import { PaymentError, fingerprint } from "./errors.js";
 
-const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
 const empty = () => ({ lots: [], subscriptions: {} });
 
 function merchant(scope) {
@@ -15,7 +14,7 @@ function identifier(value) {
   if (typeof value !== "string" || !value || value.length > 200) throw new TypeError("Payment identity is required (maximum 200 characters).");
   return value;
 }
-const accountKey = (scope) => hash([...merchant(scope), identifier(scope.subjectId)]);
+const accountKey = (scope) => fingerprint([...merchant(scope), identifier(scope.subjectId)]);
 
 function createKnexPaymentStore({ knex }) {
   if (typeof knex !== "function" || typeof knex.transaction !== "function") throw new TypeError("Supply the application's transactional Knex client.");
@@ -35,11 +34,11 @@ function createKnexPaymentStore({ knex }) {
       const result = await work({
         state,
         async find(reference) {
-          const entry = await trx("payment_entries").where({ entry_key: hash([key, identifier(reference)]) }).first();
+          const entry = await trx("payment_entries").where({ entry_key: fingerprint([key, identifier(reference)]) }).first();
           return entry ? JSON.parse(entry.payload) : null;
         },
         async record(reference, payload) {
-          await trx("payment_entries").insert({ entry_key: hash([key, identifier(reference)]), account_key: key, payload: JSON.stringify(payload) });
+          await trx("payment_entries").insert({ entry_key: fingerprint([key, identifier(reference)]), account_key: key, payload: JSON.stringify(payload) });
         }
       });
       await trx("payment_accounts").where({ account_key: key }).update({ payload: JSON.stringify(state) });
@@ -47,25 +46,25 @@ function createKnexPaymentStore({ knex }) {
     });
   }
   async function bindCustomer(scope, customerId, subjectId) {
-    const key = hash([...merchant(scope), identifier(customerId)]);
+    const key = fingerprint([...merchant(scope), identifier(customerId)]);
     identifier(subjectId);
     await knex.transaction(async (trx) => {
       await trx("payment_customers").insert({ customer_key: key, subject_id: subjectId })
         .onConflict("customer_key").merge({ customer_key: key });
       const row = await trx("payment_customers").where({ customer_key: key }).first();
-      if (row.subject_id !== subjectId) throw new Error("This provider customer is already bound to a different billable subject.");
+      if (row.subject_id !== subjectId) throw new PaymentError("payment_customer_conflict", "This provider customer is already bound to a different billable subject.", 409);
     });
   }
   async function resolveCustomer(scope, customerId) {
-    const row = await knex("payment_customers").where({ customer_key: hash([...merchant(scope), identifier(customerId)]) }).first();
+    const row = await knex("payment_customers").where({ customer_key: fingerprint([...merchant(scope), identifier(customerId)]) }).first();
     return row?.subject_id ?? null;
   }
   async function inspectCatalogue(scope) {
-    const row = await knex("payment_catalogues").where({ catalogue_key: hash(merchant(scope)) }).first();
+    const row = await knex("payment_catalogues").where({ catalogue_key: fingerprint(merchant(scope)) }).first();
     return row ? JSON.parse(row.payload) : { plans: {}, history: [] };
   }
   async function withCatalogue(scope, work) {
-    const key = hash(merchant(scope));
+    const key = fingerprint(merchant(scope));
     return knex.transaction(async (trx) => {
       await trx("payment_catalogues").insert({ catalogue_key: key, payload: JSON.stringify({ plans: {}, history: [] }) })
         .onConflict("catalogue_key").merge({ catalogue_key: key });

package/src/server/paddle.js

@@ -1,20 +1,16 @@
 import { Paddle, Environment } from "@paddle/paddle-node-sdk";
-import { PaymentError } from "./service.js";
+import { PaymentError } from "./errors.js";
+import { createPriceBindings } from "./priceBindings.js";
 
-const invalid = () => { throw new PaymentError("payment_provider_result_invalid", "Check the Paddle account, price mapping and subscription shape.", 502); };
+const invalid = () => {
+  throw new PaymentError("payment_provider_result_invalid", "Check the Paddle account, price mapping and subscription shape.", 502, {
+    messageCode: "payments.provider.checkAccount", messageParams: { provider: "Paddle" }
+  });
+};
 
 function createPaddlePaymentAdapter({ apiKey, webhookSecret, environment, priceBindings, taxCategory, historicalPriceBindings = {}, client = new Paddle(apiKey, { environment: environment === "live" ? Environment.production : Environment.sandbox }) }) {
   if (!["sandbox", "live"].includes(environment) || typeof webhookSecret !== "string" || !webhookSecret) throw new TypeError("Supply Paddle credentials and environment.");
-  const prices = structuredClone(priceBindings);
-  const planFor = (priceId) => {
-    const matches = Object.entries(prices).filter(([, value]) => value === priceId);
-    if (!matches.length && Object.hasOwn(historicalPriceBindings, priceId)) return historicalPriceBindings[priceId];
-    if (matches.length !== 1) invalid();
-    return matches[0][0];
-  };
-  function validatePlan(planId) {
-    if (!Object.hasOwn(prices, planId)) throw new PaymentError("payment_plan_unknown", "Select a published payment plan.");
-  }
+  const { validatePlan, priceFor, planFor } = createPriceBindings({ priceBindings, historicalPriceBindings, invalid });
   async function verifyAccount() {
     await client.products.list({ perPage: 1 }).next();
     // A successful catalogue read cannot prove merchant verification or identify
@@ -22,9 +18,11 @@ function createPaddlePaymentAdapter({ apiKey, webhookSecret, environment, priceB
     return { environment, credentialsVerified: true, accountIdentityVerified: false, merchantApproval: "manual-check-required" };
   }
   async function verifyEvent(rawBody, signature) {
-    if (!Buffer.isBuffer(rawBody)) throw new PaymentError("payment_signature_invalid", "Supply the unmodified webhook request bytes.", 400);
+    if (!Buffer.isBuffer(rawBody)) throw new PaymentError("payment_signature_invalid", "Supply the unmodified webhook request bytes.", 400, { messageCode: "payments.webhook.rawBodyRequired" });
     try { return await client.webhooks.unmarshal(rawBody.toString("utf8"), webhookSecret, signature); }
-    catch { throw new PaymentError("payment_signature_invalid", "Paddle webhook verification failed.", 400); }
+    catch { throw new PaymentError("payment_signature_invalid", "Paddle webhook verification failed.", 400, {
+      messageCode: "payments.webhook.verificationFailed", messageParams: { provider: "Paddle" }
+    }); }
   }
   function eventIdentity(event) {
     if (event.eventType === "transaction.completed") {
@@ -61,10 +59,10 @@ function createPaddlePaymentAdapter({ apiKey, webhookSecret, environment, priceB
     return customer.id;
   }
   async function createCheckout({ customerId, planId, returnUrl }) {
-    if (!Object.hasOwn(prices, planId)) throw new PaymentError("payment_plan_unknown", "Select a published payment plan.");
+    const priceId = priceFor(planId);
     // This URL is an app-owned Paddle.js checkout page, approved in Paddle.
     const result = await client.transactions.create({ customerId, collectionMode: "automatic",
-      items: [{ priceId: prices[planId], quantity: 1 }], checkout: { url: returnUrl } });
+      items: [{ priceId, quantity: 1 }], checkout: { url: returnUrl } });
     if (typeof result.checkout?.url !== "string") invalid();
     return { id: result.id, url: result.checkout.url };
   }
@@ -73,7 +71,7 @@ function createPaddlePaymentAdapter({ apiKey, webhookSecret, environment, priceB
     return { id: result.id, url: result.urls.general.overview };
   }
   async function readHistory({ customerId, collection, after = null }) {
-    if (!["subscriptions", "transactions"].includes(collection)) throw new PaymentError("payment_input_invalid", "Select a billing history collection.");
+    if (!["subscriptions", "transactions"].includes(collection)) throw new PaymentError("payment_input_invalid", "Select a billing history collection.", 422, { messageCode: "payments.input.historyCollection" });
     const query = { customerId: [customerId], perPage: 20, ...(after ? { after } : {}) };
     const page = collection === "subscriptions" ? client.subscriptions.list(query) : client.transactions.list(query);
     // Fetch one page only; never iterate the SDK collection over the account.
@@ -97,7 +95,9 @@ function createPaddlePaymentAdapter({ apiKey, webhookSecret, environment, priceB
     return { id: value.id, name: value.name };
   }
   async function createProduct({ name }) {
-    if (!taxCategory) throw new PaymentError("payment_configuration_invalid", "Set the application's Paddle product tax category before publishing.");
+    if (!taxCategory) throw new PaymentError("payment_configuration_invalid", "Set the application's Paddle product tax category before publishing.", 422, {
+      messageCode: "payments.configuration.taxCategoryUnpublishable"
+    });
     return client.products.create({ name, taxCategory });
   }
   async function renameProduct({ id, name }) {

package/src/server/priceBindings.js

@@ -0,0 +1,23 @@
+import { PaymentError } from "./errors.js";
+
+// Plan-to-price bindings shared by the provider adapters. `invalid` throws the
+// adapter's own provider-result error for an unknown or ambiguous price.
+function createPriceBindings({ priceBindings, historicalPriceBindings = {}, invalid }) {
+  const prices = structuredClone(priceBindings);
+  function validatePlan(planId) {
+    if (!Object.hasOwn(prices, planId)) throw new PaymentError("payment_plan_unknown", "Select a published payment plan.");
+  }
+  function priceFor(planId) {
+    validatePlan(planId);
+    return prices[planId];
+  }
+  function planFor(priceId) {
+    const matches = Object.entries(prices).filter(([, value]) => value === priceId);
+    if (!matches.length && Object.hasOwn(historicalPriceBindings, priceId)) return historicalPriceBindings[priceId];
+    if (matches.length !== 1) invalid();
+    return matches[0][0];
+  }
+  return { validatePlan, priceFor, planFor };
+}
+
+export { createPriceBindings };

package/src/server/readiness.js

@@ -1,4 +1,18 @@
-import { PaymentError } from "./service.js";
+import { PaymentError } from "./errors.js";
+
+const DEFAULT_CHECKS = Object.freeze([
+  { id: "credentials", status: "unknown", detail: "Check the provider credentials for this environment." },
+  { id: "account", status: "unknown", detail: "Confirm the configured merchant owns these credentials." },
+  { id: "charges", status: "manual", detail: "Confirm payment acceptance is enabled in the provider dashboard." },
+  { id: "payouts", status: "manual", detail: "Confirm payout eligibility in the provider dashboard." },
+  { id: "catalogue", status: "unknown", detail: "Inspect the saved products and prices." },
+  { id: "webhook", status: "unknown", detail: "Verify the deployed webhook route, signing secret and subscribed events." },
+  { id: "checkout", status: "unknown", detail: "Verify app checkout and portal routes, authorization and return handling." },
+  { id: "site", status: "manual", detail: "Review required site content and provider domain or website approval." },
+  { id: "deployment", status: "unknown", detail: "Verify the intended release uses this configuration and environment." }
+]);
+// Only these checks take their result from the application's own evidence.
+const APPLICATION_CHECKS = ["webhook", "checkout", "site", "deployment"];
 
 // App-server inspection, invoked only after the host authorizes management.
 // Missing app evidence stays unknown; provider errors never become display text.
@@ -6,56 +20,50 @@ function createPaymentReadiness({ adapter, catalogue, scope, inspectApplication
   const merchant = structuredClone(scope);
   if (!["sandbox", "live"].includes(merchant?.environment) || !merchant.providerAccountId) throw new TypeError("Supply the configured payment merchant scope.");
   async function inspect() {
-    const checks = [
-      { id: "credentials", status: "unknown", detail: "Check the provider credentials for this environment." },
-      { id: "account", status: "unknown", detail: "Confirm the configured merchant owns these credentials." },
-      { id: "charges", status: "manual", detail: "Confirm payment acceptance is enabled in the provider dashboard." },
-      { id: "payouts", status: "manual", detail: "Confirm payout eligibility in the provider dashboard." },
-      { id: "catalogue", status: "unknown", detail: "Inspect the saved products and prices." },
-      { id: "webhook", status: "unknown", detail: "Verify the deployed webhook route, signing secret and subscribed events." },
-      { id: "checkout", status: "unknown", detail: "Verify app checkout and portal routes, authorization and return handling." },
-      { id: "site", status: "manual", detail: "Review required site content and provider domain or website approval." },
-      { id: "deployment", status: "unknown", detail: "Verify the intended release uses this configuration and environment." }
-    ];
+    const checks = new Map(DEFAULT_CHECKS.map((check) => [check.id, { ...check }]));
+    const set = (id, status, detail) => Object.assign(checks.get(id), { status, detail });
     let provider;
     try { provider = await adapter.verifyAccount(); }
-    catch { checks[0] = { id: "credentials", status: "failed", detail: "Provider verification failed. Check the account, credentials and environment." }; }
+    catch { set("credentials", "failed", "Provider verification failed. Check the account, credentials and environment."); }
     if (provider) {
       if (provider.environment !== merchant.environment || (provider.accountId && provider.accountId !== merchant.providerAccountId)) {
-        throw new PaymentError("payment_scope_invalid", "Readiness returned a different payment account or environment.", 403);
+        throw new PaymentError("payment_scope_invalid", "Readiness returned a different payment account or environment.", 403, {
+          messageCode: "payments.scope.readinessMismatch"
+        });
       }
       const verified = provider.credentialsVerified === true || provider.accountId === merchant.providerAccountId;
-      checks[0] = { id: "credentials", status: verified ? "passed" : "unknown", detail: verified
-        ? "The provider accepted credential verification for this environment." : "The provider returned no affirmative credential verification." };
-      checks[1] = { id: "account", status: provider.accountId === merchant.providerAccountId ? "passed" : "manual",
-        detail: provider.accountId === merchant.providerAccountId ? "The provider account matches the saved merchant identity." : "This provider check does not establish merchant identity. Confirm it in the provider dashboard." };
-      for (const [index, property] of [[2, "chargesEnabled"], [3, "payoutsEnabled"]]) {
-        if (typeof provider[property] === "boolean") checks[index] = { id: checks[index].id, status: provider[property] ? "passed" : "failed",
-          detail: `The provider reports ${checks[index].id} ${provider[property] ? "enabled" : "not enabled"}.` };
+      set("credentials", verified ? "passed" : "unknown", verified
+        ? "The provider accepted credential verification for this environment." : "The provider returned no affirmative credential verification.");
+      const accountMatches = provider.accountId === merchant.providerAccountId;
+      set("account", accountMatches ? "passed" : "manual", accountMatches
+        ? "The provider account matches the saved merchant identity." : "This provider check does not establish merchant identity. Confirm it in the provider dashboard.");
+      for (const [id, property] of [["charges", "chargesEnabled"], ["payouts", "payoutsEnabled"]]) {
+        if (typeof provider[property] === "boolean") {
+          set(id, provider[property] ? "passed" : "failed", `The provider reports ${id} ${provider[property] ? "enabled" : "not enabled"}.`);
+        }
       }
       try {
         const review = await catalogue.preview();
         if (review.environment !== merchant.environment || review.providerAccountId !== merchant.providerAccountId) throw new Error("scope");
         const unresolved = Boolean(review.pending || review.changes.length || review.drift.length || review.removed.length);
-        checks[4] = { id: "catalogue", status: unresolved ? "failed" : "passed",
-          detail: unresolved ? "Catalogue changes, drift, removed plans or an unresolved write need review." : "Saved plans match their published provider products and prices." };
-      } catch { checks[4] = { id: "catalogue", status: "failed", detail: "Catalogue inspection failed. Review the application's catalogue command and provider access." }; }
+        set("catalogue", unresolved ? "failed" : "passed",
+          unresolved ? "Catalogue changes, drift, removed plans or an unresolved write need review." : "Saved plans match their published provider products and prices.");
+      } catch { set("catalogue", "failed", "Catalogue inspection failed. Review the application's catalogue command and provider access."); }
     }
     if (inspectApplication) {
       let evidence;
       try { evidence = await inspectApplication(); } catch { evidence = {}; }
-      for (const check of checks.slice(5)) {
-        const value = evidence?.[check.id];
+      for (const id of APPLICATION_CHECKS) {
+        const value = evidence?.[id];
         if (value === undefined) continue;
         if (!value || !["passed", "failed", "unknown", "manual"].includes(value.status) || typeof value.detail !== "string" ||
           !value.detail.trim() || value.detail.length > 500 || /[\p{Cc}\p{Cf}]/u.test(value.detail)) {
           throw new PaymentError("payment_readiness_invalid", "App readiness checks must return bounded status and safe explanatory text.");
         }
-        check.status = value.status;
-        check.detail = value.detail;
+        set(id, value.status, value.detail);
       }
     }
-    return { paymentEnvironment: merchant.environment, providerAccountId: merchant.providerAccountId, checks };
+    return { paymentEnvironment: merchant.environment, providerAccountId: merchant.providerAccountId, checks: [...checks.values()] };
   }
   return Object.freeze({ inspect });
 }

package/src/server/service.js

@@ -1,26 +1,18 @@
-import { createHash } from "node:crypto";
+import { PaymentError, fingerprint } from "./errors.js";
 
-class PaymentError extends Error {
-  constructor(code, message, statusCode = 422) {
-    super(message);
-    this.code = code;
-    this.statusCode = statusCode;
-  }
-}
-const fail = (code, message, status) => { throw new PaymentError(code, message, status); };
+const fail = (code, message, status, options) => { throw new PaymentError(code, message, status, options); };
 function reference(value) {
-  if (typeof value !== "string" || !value || value.length > 150 || ["__proto__", "constructor", "prototype"].includes(value)) fail("payment_input_invalid", "Use a nonempty business reference of at most 150 characters.");
+  if (typeof value !== "string" || !value || value.length > 150 || ["__proto__", "constructor", "prototype"].includes(value)) fail("payment_input_invalid", "Use a nonempty business reference of at most 150 characters.", 422, { messageCode: "payments.input.reference" });
   return value;
 }
 function units(value) {
-  if (!Number.isSafeInteger(value) || value < 1 || value > 1e9) fail("payment_input_invalid", "Use a positive integer credit quantity, at most one billion.");
+  if (!Number.isSafeInteger(value) || value < 1 || value > 1e9) fail("payment_input_invalid", "Use a positive integer credit quantity, at most one billion.", 422, { messageCode: "payments.input.creditQuantity" });
   return value;
 }
 function timestamp(value) {
-  if (!Number.isSafeInteger(value) || value < 0) fail("payment_input_invalid", "Use an integer UTC timestamp in milliseconds.");
+  if (!Number.isSafeInteger(value) || value < 0) fail("payment_input_invalid", "Use an integer UTC timestamp in milliseconds.", 422, { messageCode: "payments.input.timestamp" });
   return value;
 }
-const fingerprint = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
 const unexpired = (lot, now) => lot.expiresAt === null || lot.expiresAt > now;
 const available = (lots, now) => lots.reduce((sum, lot) => sum + (unexpired(lot, now) ? lot.remaining : 0), 0);
 
@@ -28,7 +20,7 @@ async function once(tx, key, input, work) {
   const digest = fingerprint(input);
   const previous = await tx.find(key);
   if (previous) {
-    if (previous.digest !== digest) fail("payment_reference_conflict", "This business reference was already used with different inputs.", 409);
+    if (previous.digest !== digest) fail("payment_reference_conflict", "This business reference was already used with different inputs.", 409, { messageCode: "payments.reference.differentInputs" });
     return { ...previous.result, duplicate: true };
   }
   const result = await work();
@@ -56,7 +48,9 @@ function createPaymentService({ store, configuration, clock = Date.now }) {
   function checkScope(scope) {
     const expected = environments[scope?.environment];
     if (!expected || expected.integrationId !== scope.integrationId || expected.providerAccountId !== scope.providerAccountId) {
-      fail("payment_scope_invalid", "The payment scope does not match this environment's merchant configuration.", 403);
+      fail("payment_scope_invalid", "The payment scope does not match this environment's merchant configuration.", 403, {
+        messageCode: "payments.scope.merchantMismatch"
+      });
     }
   }
 
@@ -136,7 +130,7 @@ function createPaymentService({ store, configuration, clock = Date.now }) {
       const { subscription, renewal } = await load();
       reference(subscription?.id);
       if (!["active", "trialing", "past_due", "paused", "canceled", "unpaid", "incomplete", "incomplete_expired"].includes(subscription.status) ||
-          !Object.hasOwn(plans, subscription.planId)) fail("payment_provider_result_invalid", "Check the provider subscription and logical price binding.", 502);
+          !Object.hasOwn(plans, subscription.planId)) fail("payment_provider_result_invalid", "Check the provider subscription and logical price binding.", 502, { messageCode: "payments.provider.subscriptionBinding" });
       timestamp(subscription.periodEnd);
       tx.state.subscriptions[subscription.id] = {
         id: subscription.id, status: subscription.status, planId: subscription.planId, periodEnd: subscription.periodEnd
@@ -145,7 +139,7 @@ function createPaymentService({ store, configuration, clock = Date.now }) {
       if (renewal) {
         reference(renewal.id);
         timestamp(renewal.periodEnd);
-        if (!Object.hasOwn(plans, renewal.planId)) fail("payment_provider_result_invalid", "Check the renewal's logical price binding.", 502);
+        if (!Object.hasOwn(plans, renewal.planId)) fail("payment_provider_result_invalid", "Check the renewal's logical price binding.", 502, { messageCode: "payments.provider.renewalBinding" });
         const quantity = plans[renewal.planId].renewalCredits;
         // A provider invoice/transaction is the business key, not its delivery ID.
         if (quantity) creditGrant = await grant(tx, { reference: `renewal:${renewal.id}`, units: quantity, expiresAt: renewal.periodEnd }, timestamp(clock()));

package/src/server/stripe.js

@@ -1,22 +1,18 @@
 import Stripe from "stripe";
-import { PaymentError } from "./service.js";
+import { PaymentError } from "./errors.js";
+import { createPriceBindings } from "./priceBindings.js";
 
 const id = (value) => typeof value === "string" ? value : value?.id;
-const invalid = () => { throw new PaymentError("payment_provider_result_invalid", "Check the Stripe account, price mapping and subscription shape.", 502); };
+const invalid = () => {
+  throw new PaymentError("payment_provider_result_invalid", "Check the Stripe account, price mapping and subscription shape.", 502, {
+    messageCode: "payments.provider.checkAccount", messageParams: { provider: "Stripe" }
+  });
+};
 
 function createStripePaymentAdapter({ apiKey, webhookSecret, environment, providerAccountId, priceBindings, historicalPriceBindings = {}, client = new Stripe(apiKey, { maxNetworkRetries: 0 }) }) {
   if (!["sandbox", "live"].includes(environment) || typeof webhookSecret !== "string" || !webhookSecret || !providerAccountId) throw new TypeError("Supply Stripe credentials, environment and account identity.");
   const live = environment === "live";
-  const prices = structuredClone(priceBindings);
-  const planFor = (priceId) => {
-    const matches = Object.entries(prices).filter(([, value]) => value === priceId);
-    if (!matches.length && Object.hasOwn(historicalPriceBindings, priceId)) return historicalPriceBindings[priceId];
-    if (matches.length !== 1) invalid();
-    return matches[0][0];
-  };
-  function validatePlan(planId) {
-    if (!Object.hasOwn(prices, planId)) throw new PaymentError("payment_plan_unknown", "Select a published payment plan.");
-  }
+  const { validatePlan, priceFor, planFor } = createPriceBindings({ priceBindings, historicalPriceBindings, invalid });
   async function verifyAccount() {
     const account = await client.accounts.retrieve();
     const balance = await client.balance.retrieve();
@@ -24,10 +20,12 @@ function createStripePaymentAdapter({ apiKey, webhookSecret, environment, provid
     return { accountId: account.id, environment, chargesEnabled: account.charges_enabled === true, payoutsEnabled: account.payouts_enabled === true };
   }
   async function verifyEvent(rawBody, signature) {
-    if (!Buffer.isBuffer(rawBody)) throw new PaymentError("payment_signature_invalid", "Supply the unmodified webhook request bytes.", 400);
+    if (!Buffer.isBuffer(rawBody)) throw new PaymentError("payment_signature_invalid", "Supply the unmodified webhook request bytes.", 400, { messageCode: "payments.webhook.rawBodyRequired" });
     let event;
     try { event = client.webhooks.constructEvent(rawBody, signature, webhookSecret); }
-    catch { throw new PaymentError("payment_signature_invalid", "Stripe webhook verification failed.", 400); }
+    catch { throw new PaymentError("payment_signature_invalid", "Stripe webhook verification failed.", 400, {
+      messageCode: "payments.webhook.verificationFailed", messageParams: { provider: "Stripe" }
+    }); }
     if (event.livemode !== live || (event.account && event.account !== providerAccountId)) invalid();
     return event;
   }
@@ -76,10 +74,10 @@ function createStripePaymentAdapter({ apiKey, webhookSecret, environment, provid
     return customer.id;
   }
   async function createCheckout({ customerId, planId, returnUrl, requestId }) {
-    if (!Object.hasOwn(prices, planId)) throw new PaymentError("payment_plan_unknown", "Select a published payment plan.");
+    const price = priceFor(planId);
     await verifyAccount();
     const result = await client.checkout.sessions.create({ mode: "subscription", customer: customerId,
-      line_items: [{ price: prices[planId], quantity: 1 }], success_url: returnUrl, cancel_url: returnUrl
+      line_items: [{ price, quantity: 1 }], success_url: returnUrl, cancel_url: returnUrl
     }, { idempotencyKey: requestId });
     if (typeof result.url !== "string") invalid();
     return { id: result.id, url: result.url };
@@ -90,7 +88,7 @@ function createStripePaymentAdapter({ apiKey, webhookSecret, environment, provid
     return { id: result.id, url: result.url };
   }
   async function readHistory({ customerId, collection, after = null }) {
-    if (!["subscriptions", "transactions"].includes(collection)) throw new PaymentError("payment_input_invalid", "Select a billing history collection.");
+    if (!["subscriptions", "transactions"].includes(collection)) throw new PaymentError("payment_input_invalid", "Select a billing history collection.", 422, { messageCode: "payments.input.historyCollection" });
     await verifyAccount();
     const query = { customer: customerId, limit: 20, ...(after ? { starting_after: after } : {}) };
     const page = collection === "subscriptions"

package/src/shared/configuration.js

@@ -3,36 +3,48 @@ import schema from "../../contracts/configuration.schema.json" with { type: "jso
 
 const validate = new Ajv({ allErrors: true, strict: true }).compile(schema);
 
+// Each JSKIT field error also has a code and params; the error's messageCode names its sentence.
+function configurationError(message, fieldErrors, { messageCode, messageParams = {} }) {
+  return Object.assign(new Error(message), {
+    code: "payment_configuration_invalid", statusCode: 422, fieldErrors, messageCode, messageParams
+  });
+}
+
 function validatePaymentConfiguration(document) {
   const value = document?.extensions?.payments;
   if (!validate(value)) {
-    const error = new Error("Check the application's payment configuration.");
-    error.code = "payment_configuration_invalid";
-    error.statusCode = 422;
-    error.fieldErrors = validate.errors.map(({ instancePath, message }) => ({ path: `extensions.payments${instancePath}`, message }));
-    throw error;
+    throw configurationError("Check the application's payment configuration.",
+      validate.errors.map(({ instancePath, message }) => ({ path: `extensions.payments${instancePath}`, message })),
+      { messageCode: "payments.configuration.invalid" });
   }
+  // Report every environment's binding problems at once, like the schema stage.
+  const fieldErrors = [];
   for (const [environment, binding] of Object.entries(value.environments)) {
     const slot = document.integrations?.[binding.integrationId];
     const path = `extensions.payments/environments/${environment}`;
-    const fieldErrors = [];
     if (!slot || !["stripe", "paddle"].includes(slot.provider) || slot.accountMode !== "shared" ||
         slot.authentication?.method !== "api-key" || !/^env:[A-Z_][A-Z0-9_]*$/.test(slot.authentication.secretRef || "")) {
-      fieldErrors.push({ path: `${path}/integrationId`, message: `Select a shared Stripe or Paddle connection with a backend API-key Env reference for ${environment}.` });
+      fieldErrors.push({ path: `${path}/integrationId`, message: `Select a shared Stripe or Paddle connection with a backend API-key Env reference for ${environment}.`,
+        code: "payments.configuration.sharedConnectionRequired", params: { environment } });
     }
     if (slot?.provider === "paddle") {
-      if (slot.settings?.environment !== environment) fieldErrors.push({ path: `${path}/integrationId`, message: `Select a Paddle connection configured for ${environment}.` });
-      if (!binding.taxCategory) fieldErrors.push({ path: `${path}/taxCategory`, message: "Choose the Paddle tax category for the products this app sells." });
-      if (!binding.publicClientTokenRef) fieldErrors.push({ path: `${path}/publicClientTokenRef`, message: "Set the Env reference for this environment's Paddle public client token." });
-    }
-    if (fieldErrors.length) {
-      const error = new Error(fieldErrors[0].message);
-      error.code = "payment_configuration_invalid";
-      error.statusCode = 422;
-      error.fieldErrors = fieldErrors;
-      throw error;
+      if (slot.settings?.environment !== environment) {
+        fieldErrors.push({ path: `${path}/integrationId`, message: `Select a Paddle connection configured for ${environment}.`,
+          code: "payments.configuration.paddleEnvironment", params: { environment } });
+      }
+      if (!binding.taxCategory) {
+        fieldErrors.push({ path: `${path}/taxCategory`, message: "Choose the Paddle tax category for the products this app sells.",
+          code: "payments.configuration.paddleTaxCategory", params: {} });
+      }
+      if (!binding.publicClientTokenRef) {
+        fieldErrors.push({ path: `${path}/publicClientTokenRef`, message: "Set the Env reference for this environment's Paddle public client token.",
+          code: "payments.configuration.paddleClientToken", params: {} });
+      }
     }
   }
+  if (fieldErrors.length) throw configurationError(fieldErrors[0].message, fieldErrors, {
+    messageCode: fieldErrors[0].code, messageParams: fieldErrors[0].params
+  });
   // The validated declaration is JSON data; callers may supply reactive proxies.
   return JSON.parse(JSON.stringify(value));
 }

package/test/i18nCatalog.test.js

@@ -0,0 +1,79 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { catalogMessage, formatMessage, messageKeyForCode } from "@jskit-ai/kernel/shared/i18n";
+import { evaluateI18nCatalogContract } from "../../../tooling/test-support/i18nCatalogContract.mjs";
+import { validatePaymentConfiguration } from "../src/shared/configuration.js";
+import conformance from "../contracts/conformance.json" with { type: "json" };
+import en from "../locales/en.json" with { type: "json" };
+
+const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(TEST_DIRECTORY, "..", "..", "..");
+const PACKAGE_DIR = path.join(REPO_ROOT, "packages", "payments-core");
+
+function english(code, params) {
+  const template = catalogMessage(en, messageKeyForCode(code));
+  return template === undefined ? undefined : formatMessage(template, params);
+}
+
+test("payments-core English catalog matches its source", () => {
+  const { problems } = evaluateI18nCatalogContract({
+    repoRoot: REPO_ROOT,
+    packageDir: PACKAGE_DIR
+  });
+  assert.deepEqual(problems, []);
+});
+
+test("every payment error's catalog English equals the English it throws", () => {
+  const site = /(?:PaymentError|fail)\(\s*"(payment_[a-z_]+)",\s*"((?:[^"\\]|\\.)*)"(?:,\s*\d+)?(?:,\s*\{\s*messageCode:\s*"([^"]+)"(?:,\s*messageParams:\s*\{\s*provider:\s*"([^"]+)"\s*\})?\s*\})?/gu;
+  const sources = fs.readdirSync(path.join(PACKAGE_DIR, "src", "server"))
+    .map((file) => fs.readFileSync(path.join(PACKAGE_DIR, "src", "server", file), "utf8"));
+  const sites = sources.join("\n").match(/(?:PaymentError|fail)\("payment_/gu).length;
+  let checked = 0;
+  for (const source of sources) {
+    for (const [, code, message, messageCode, provider] of source.matchAll(site)) {
+      const expected = JSON.parse(`"${message}"`);
+      if (messageCode) {
+        assert.equal(english(messageCode, provider ? { provider } : {}), expected, messageCode);
+      } else {
+        assert.equal(english(code), expected, code);
+      }
+      checked += 1;
+    }
+  }
+  assert.equal(checked, sites);
+});
+
+test("configuration errors carry codes whose English matches each field error", () => {
+  const coded = new Set();
+  for (const item of conformance.configurationCases) {
+    const documents = [item.document];
+    if (item.id === "paddle-sandbox") {
+      const document = structuredClone(item.document);
+      delete document.extensions.payments.environments.sandbox.taxCategory;
+      documents.push(document);
+    }
+    for (const document of documents) {
+      let error = null;
+      try {
+        validatePaymentConfiguration(document);
+      } catch (caught) {
+        error = caught;
+      }
+      if (!error) continue;
+      assert.equal(english(error.messageCode, error.messageParams), error.message, item.id);
+      for (const entry of error.fieldErrors.filter(({ code }) => code)) {
+        assert.equal(english(entry.code, entry.params), entry.message, entry.code);
+        coded.add(entry.code);
+      }
+    }
+  }
+  assert.deepEqual([...coded].sort(), [
+    "payments.configuration.paddleClientToken",
+    "payments.configuration.paddleEnvironment",
+    "payments.configuration.paddleTaxCategory",
+    "payments.configuration.sharedConnectionRequired"
+  ]);
+});

package/test/service.test.js

@@ -36,6 +36,21 @@ test("portable configuration rejects secret literals, invalid prices and mismatc
   }
 });
 
+test("configuration reports binding problems in every environment at once", () => {
+  const value = structuredClone(document);
+  value.integrations.billing.accountMode = "per-user";
+  value.integrations.production.authentication.secretRef = "sk_live_pasted";
+  assert.throws(() => validatePaymentConfiguration(value), (error) => {
+    assert.equal(error.code, "payment_configuration_invalid");
+    assert.equal(error.statusCode, 422);
+    assert.deepEqual(error.fieldErrors.map(({ path }) => path), [
+      "extensions.payments/environments/sandbox/integrationId", "extensions.payments/environments/live/integrationId"
+    ]);
+    assert.equal(error.message, error.fieldErrors[0].message);
+    return true;
+  });
+});
+
 test("configuration accepts reactive objects and returns an independent plain snapshot", () => {
   const input = structuredClone(document);
   input.extensions.payments = new Proxy(input.extensions.payments, {});
@@ -84,7 +99,7 @@ test("transactional payment state isolates subjects, grants once, prevents overs
     });
     await t.test("customer bindings cannot be stolen or resolved across environments", async () => {
       await store.bindCustomer(scope, "cus_a", "tenant-a");
-      await assert.rejects(store.bindCustomer(scope, "cus_a", "tenant-b"), /already bound/);
+      await assert.rejects(store.bindCustomer(scope, "cus_a", "tenant-b"), { name: "PaymentError", code: "payment_customer_conflict", statusCode: 409, message: /already bound/ });
       await assert.rejects(service.reconcileEvent(scope, { eventId: "evt_unbound", customerId: "cus_b", load: async () => {} }), { code: "payment_customer_unbound" });
     });
     await t.test("event failure rolls back; retries grant once per renewal rather than event", async () => {