@jskit-ai/payments-core 0.1.62 → 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.62",
+  "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

@@ -11,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);
@@ -38,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;
@@ -70,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;
@@ -86,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

@@ -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,7 +42,7 @@ 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.");
+    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 }
@@ -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) =>
@@ -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

@@ -1,11 +1,17 @@
 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) {
+  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 };
+    }
   }
 }
 

package/src/server/paddle.js

@@ -2,7 +2,11 @@ import { Paddle, Environment } from "@paddle/paddle-node-sdk";
 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.");
@@ -14,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") {
@@ -65,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.
@@ -89,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/readiness.js

@@ -27,7 +27,9 @@ function createPaymentReadiness({ adapter, catalogue, scope, inspectApplication
     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;
       set("credentials", verified ? "passed" : "unknown", verified

package/src/server/service.js

@@ -1,16 +1,16 @@
 import { PaymentError, fingerprint } from "./errors.js";
 
-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 unexpired = (lot, now) => lot.expiresAt === null || lot.expiresAt > now;
@@ -20,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();
@@ -48,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"
+      });
     }
   }
 
@@ -128,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
@@ -137,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

@@ -3,7 +3,11 @@ 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.");
@@ -16,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;
   }
@@ -82,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,15 +3,19 @@ import schema from "../../contracts/configuration.schema.json" with { type: "jso
 
 const validate = new Ajv({ allErrors: true, strict: true }).compile(schema);
 
-function configurationError(message, fieldErrors) {
-  return Object.assign(new Error(message), { code: "payment_configuration_invalid", statusCode: 422, fieldErrors });
+// 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)) {
     throw configurationError("Check the application's payment configuration.",
-      validate.errors.map(({ instancePath, message }) => ({ path: `extensions.payments${instancePath}`, message })));
+      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 = [];
@@ -20,15 +24,27 @@ function validatePaymentConfiguration(document) {
     const path = `extensions.payments/environments/${environment}`;
     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 (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);
+  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"
+  ]);
+});