@veruna/api-contracts 20.0.0 → 20.1.0

package/build/v1/payment/schemas/cp-decline-codes.js

@@ -1,71 +1,150 @@
 "use strict";
+// libs/contracts/v1/payment/schemas/cp-decline-codes.ts
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CP_SOFT_DECLINE_REASON_CODES = exports.CP_BANK_FRAUD_SUSPECTED_REASON_CODES = exports.CP_ISSUER_UNAVAILABLE_REASON_CODES = exports.CP_LIMIT_OR_DETAILS_REASON_CODES = exports.CP_INSUFFICIENT_FUNDS_REASON_CODES = exports.CP_HARD_DECLINE_REASON_CODES = exports.CP_UNCONDITIONAL_HARD_DECLINE_REASON_CODES = exports.CP_CARD_DEAD_REASON_CODES = exports.CP_CARD_EXPIRED_REASON_CODES = void 0;
+/**
+ * CloudPayments decline reason-code classification for dunning decisions.
+ *
+ * Source: CloudPayments docs "Коды ошибок" (2026-06).
+ * These sets are the single source-of-truth shared by the payment and
+ * subscription modules without cross-module imports.
+ *
+ * LEGAL NOTE (376-ФЗ, art. 6):
+ *   Soft declines allow retries because the charge was not explicitly rejected
+ *   by the cardholder — the schedule already spaces attempts ≥12 h apart,
+ *   which satisfies the implicit "no more than once per 24 h" guidance from
+ *   payment-system acquirer rules. Confirm this cadence with your CP manager
+ *   if your MCC or acquiring bank has stricter retry-frequency policies.
+ */
+/**
+ * Expired-card decline codes (subset of CP_CARD_DEAD_REASON_CODES).
+ * Single source-of-truth used by the decline classifier; keeps
+ * CP_CARD_DEAD_REASON_CODES and classifier in sync automatically (F20).
+ */
 exports.CP_CARD_EXPIRED_REASON_CODES = new Set([
-    5033,
-    5054,
+    5033, // Expired card (alternate code)
+    5054, // Expired card (unconditional, owner decision 2026-10-27)
 ]);
+/**
+ * Hard decline codes that mean the card is permanently dead.
+ * Dunning MUST stop AND the physical card becomes unusable, not revoked (payments-v2 §1.6):
+ *   5033 / 5054 / 5004 / 5007 / 5014 / 5041 / 5043 → SavedMethodStatus.UNUSABLE
+ *
+ * 5004/5007 ("Pick up card" / "...special conditions", owner decision 2026-10-03): the
+ * issuer is explicitly instructing the merchant to retain/seize the card — a stronger,
+ * unambiguous "this physical card is dead" signal than 5059 (merely *suspected* fraud,
+ * see CP_BANK_FRAUD_SUSPECTED_REASON_CODES below), so they are classified alongside the
+ * lost/stolen codes rather than left in the generic "stop but keep the card ACTIVE" set.
+ *
+ * 5014 ("Invalid card number", owner decision 2026-11-02): on a saved-card charge the number
+ * no longer exists at the issuer (card closed or reissued); retrying it is pointless and is a
+ * "do not reattempt" decline for the card schemes, so it is a dead card, not a soft decline.
+ */
 exports.CP_CARD_DEAD_REASON_CODES = new Set([
     ...exports.CP_CARD_EXPIRED_REASON_CODES,
-    5004,
-    5007,
-    5014,
-    5041,
-    5043,
+    5004, // Pick up card
+    5007, // Pick up card, special conditions
+    5014, // Invalid card number (owner decision 2026-11-02)
+    5041, // Lost card
+    5043, // Stolen card
 ]);
+/**
+ * CP_SUBSCRIPTIONS design doc's owner-defined "unconditionally negative" codes (2026-09
+ * decision, reconfirmed 2026-10-03): regular MIT charges after any of these are
+ * permanently forbidden without a fresh card setup — the strict basis for
+ * CARD_STOPPING_DECLINE_KINDS (classify() -> DeclineKind.HARD/CARD_EXPIRED/CARD_REVOKED).
+ * 5059 (suspected fraud, NOT unconditional in the owner's list) is deliberately excluded
+ * — see CP_BANK_FRAUD_SUSPECTED_REASON_CODES.
+ * 5003 (invalid merchant) is unconditional for dunning but, by owner decision 2026-10-20,
+ * never touches the card (no UNUSABLE) until a 5003-spike alert exists — an exemption in the payment
+ * module's card-effects policy (CARD_EFFECT_EXEMPT_REASON_CODES), not a reclassification.
+ */
 exports.CP_UNCONDITIONAL_HARD_DECLINE_REASON_CODES = new Set([
-    5001,
-    5003,
-    5012,
-    5017,
-    5033,
-    5054,
-    5034,
-    5057,
+    5001, // Do not honour
+    5003, // Invalid merchant
+    5012, // Card not permitted
+    5017, // Transaction not permitted
+    5033, // Expired card (alternate code)
+    5054, // Expired card (unconditional, owner decision 2026-10-27)
+    5034, // Suspected fraud (unconditional per owner decision — unlike 5059 below)
+    5057, // Transaction not permitted to cardholder
 ]);
+/**
+ * Hard decline codes the classifier reports as HARD (dunning stops); it checks
+ * CP_CARD_DEAD_REASON_CODES first, which takes precedence. What a decline does to the card
+ * is decided by the payment module's card-effects policy, not by this set: every
+ * unconditional code makes the physical card UNUSABLE (not revoked) except 5003.
+ */
 exports.CP_HARD_DECLINE_REASON_CODES = new Set([
     ...exports.CP_UNCONDITIONAL_HARD_DECLINE_REASON_CODES,
     ...exports.CP_CARD_DEAD_REASON_CODES,
 ]);
+/**
+ * 5059 "Suspected fraud" (owner decision 2026-10-03, item 8): classified separately from
+ * CP_HARD_DECLINE_REASON_CODES as DeclineKind.BANK_FRAUD_SUSPECTED. Unlike the
+ * unconditional HARD codes, 5059 is a probabilistic bank-side signal that can be a false
+ * positive — the card itself is NOT revoked and stays usable elsewhere (one-off charges,
+ * other subscriptions). Only recurring/automatic collection on THIS subscription stops
+ * (no provider retry-grid restart, no local dunning continuation) — see
+ * RecurringDeclineEffectsService (payment module) and SubscriptionLifecyclePolicy
+ * (subscription module) for the two stop paths this kind drives.
+ */
+/**
+ * The one decline the customer is told "insufficient funds" about (smart renewal, phase 1):
+ * every other soft code gets neutral wording. Subset of CP_SOFT_DECLINE_REASON_CODES.
+ */
 exports.CP_INSUFFICIENT_FUNDS_REASON_CODES = new Set([
-    5051,
+    5051, // Insufficient funds
 ]);
+/**
+ * Soft codes that tell the payer to check limits or card details (payer-facing class
+ * LIMIT_OR_DETAILS). Subset of CP_SOFT_DECLINE_REASON_CODES: classification, dunning and card
+ * effects are unchanged — only the payer-class mapping reads this set.
+ */
 exports.CP_LIMIT_OR_DETAILS_REASON_CODES = new Set([
-    5055,
-    5061,
-    5063,
-    5065,
+    5055, // Incorrect PIN
+    5061, // Exceeds amount limit
+    5063, // Security violation (transient)
+    5065, // Exceeds withdrawal frequency limit
 ]);
+/**
+ * Soft codes that mean the issuer could not process the charge right now (payer-facing class
+ * BANK_UNAVAILABLE). Subset of CP_SOFT_DECLINE_REASON_CODES, read only by the payer-class mapping.
+ */
 exports.CP_ISSUER_UNAVAILABLE_REASON_CODES = new Set([
-    5091,
-    5092,
-    5096,
+    5091, // Issuer or switch is inoperative
+    5092, // Financial institution not found
+    5096, // System malfunction
 ]);
 exports.CP_BANK_FRAUD_SUSPECTED_REASON_CODES = new Set([
-    5059,
+    5059, // Suspected fraud
 ]);
+/**
+ * Soft decline codes — transient failures that should be retried per schedule.
+ * 5051 = insufficient funds; 52xx = various network/processing issues.
+ */
 exports.CP_SOFT_DECLINE_REASON_CODES = new Set([
-    5005,
-    5051,
-    5061,
-    5096,
-    5006,
-    5013,
-    5030,
-    5055,
-    5063,
-    5065,
-    5091,
-    5092,
-    5200,
-    5201,
-    5202,
-    5203,
-    5204,
-    5205,
-    5206,
-    5207,
-    5208,
-    5209,
+    5005, // Do not honour (issuer) — «условно негативный» в документации CP
+    5051, // Insufficient funds
+    5061, // Exceeds amount limit
+    5096, // System malfunction
+    5006, // Error (generic, transient)
+    5013, // Invalid amount
+    5030, // Format error (transient)
+    5055, // Incorrect PIN
+    5063, // Security violation (transient)
+    5065, // Exceeds withdrawal frequency limit
+    5091, // Issuer or switch is inoperative
+    5092, // Financial institution not found
+    5200, // Processing error
+    5201, // Processing error
+    5202, // Processing error
+    5203, // Processing error
+    5204, // Processing error
+    5205, // Processing error
+    5206, // Processing error
+    5207, // Processing error
+    5208, // Processing error
+    5209, // Processing error
 ]);
 //# sourceMappingURL=cp-decline-codes.js.map

package/build/v1/payment/schemas/cp-decline-codes.js.map

@@ -1 +1 @@
-{"version":3,"file":"cp-decline-codes.js","sourceRoot":"","sources":["../../../../v1/payment/schemas/cp-decline-codes.ts"],"names":[],"mappings":";;;AAsBa,QAAA,4BAA4B,GAAG,IAAI,GAAG,CAAS;IACxD,IAAI;IACJ,IAAI;CACP,CAAC,CAAC;AAiBU,QAAA,yBAAyB,GAAG,IAAI,GAAG,CAAS;IACrD,GAAG,oCAA4B;IAC/B,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;CACP,CAAC,CAAC;AAaU,QAAA,0CAA0C,GAAG,IAAI,GAAG,CAAS;IACtE,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;CACP,CAAC,CAAC;AAQU,QAAA,4BAA4B,GAAG,IAAI,GAAG,CAAS;IACxD,GAAG,kDAA0C;IAC7C,GAAG,iCAAyB;CAC/B,CAAC,CAAC;AAgBU,QAAA,kCAAkC,GAAG,IAAI,GAAG,CAAS;IAC9D,IAAI;CACP,CAAC,CAAC;AAOU,QAAA,gCAAgC,GAAG,IAAI,GAAG,CAAS;IAC5D,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;CACP,CAAC,CAAC;AAMU,QAAA,kCAAkC,GAAG,IAAI,GAAG,CAAS;IAC9D,IAAI;IACJ,IAAI;IACJ,IAAI;CACP,CAAC,CAAC;AAEU,QAAA,oCAAoC,GAAG,IAAI,GAAG,CAAS;IAChE,IAAI;CACP,CAAC,CAAC;AAMU,QAAA,4BAA4B,GAAG,IAAI,GAAG,CAAS;IACxD,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;CACP,CAAC,CAAC"}
+{"version":3,"file":"cp-decline-codes.js","sourceRoot":"","sources":["../../../../v1/payment/schemas/cp-decline-codes.ts"],"names":[],"mappings":";AAAA,wDAAwD;;;AAExD;;;;;;;;;;;;;GAaG;AAEH;;;;GAIG;AACU,QAAA,4BAA4B,GAAG,IAAI,GAAG,CAAS;IACxD,IAAI,EAAE,gCAAgC;IACtC,IAAI,EAAE,0DAA0D;CACnE,CAAC,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACU,QAAA,yBAAyB,GAAG,IAAI,GAAG,CAAS;IACrD,GAAG,oCAA4B;IAC/B,IAAI,EAAE,eAAe;IACrB,IAAI,EAAE,mCAAmC;IACzC,IAAI,EAAE,kDAAkD;IACxD,IAAI,EAAE,YAAY;IAClB,IAAI,EAAE,cAAc;CACvB,CAAC,CAAC;AAEH;;;;;;;;;;GAUG;AACU,QAAA,0CAA0C,GAAG,IAAI,GAAG,CAAS;IACtE,IAAI,EAAE,gBAAgB;IACtB,IAAI,EAAE,mBAAmB;IACzB,IAAI,EAAE,qBAAqB;IAC3B,IAAI,EAAE,4BAA4B;IAClC,IAAI,EAAE,gCAAgC;IACtC,IAAI,EAAE,0DAA0D;IAChE,IAAI,EAAE,yEAAyE;IAC/E,IAAI,EAAE,0CAA0C;CACnD,CAAC,CAAC;AAEH;;;;;GAKG;AACU,QAAA,4BAA4B,GAAG,IAAI,GAAG,CAAS;IACxD,GAAG,kDAA0C;IAC7C,GAAG,iCAAyB;CAC/B,CAAC,CAAC;AAEH;;;;;;;;;GASG;AACH;;;GAGG;AACU,QAAA,kCAAkC,GAAG,IAAI,GAAG,CAAS;IAC9D,IAAI,EAAE,qBAAqB;CAC9B,CAAC,CAAC;AAEH;;;;GAIG;AACU,QAAA,gCAAgC,GAAG,IAAI,GAAG,CAAS;IAC5D,IAAI,EAAE,gBAAgB;IACtB,IAAI,EAAE,uBAAuB;IAC7B,IAAI,EAAE,iCAAiC;IACvC,IAAI,EAAE,qCAAqC;CAC9C,CAAC,CAAC;AAEH;;;GAGG;AACU,QAAA,kCAAkC,GAAG,IAAI,GAAG,CAAS;IAC9D,IAAI,EAAE,kCAAkC;IACxC,IAAI,EAAE,kCAAkC;IACxC,IAAI,EAAE,qBAAqB;CAC9B,CAAC,CAAC;AAEU,QAAA,oCAAoC,GAAG,IAAI,GAAG,CAAS;IAChE,IAAI,EAAE,kBAAkB;CAC3B,CAAC,CAAC;AAEH;;;GAGG;AACU,QAAA,4BAA4B,GAAG,IAAI,GAAG,CAAS;IACxD,IAAI,EAAE,kEAAkE;IACxE,IAAI,EAAE,qBAAqB;IAC3B,IAAI,EAAE,uBAAuB;IAC7B,IAAI,EAAE,qBAAqB;IAC3B,IAAI,EAAE,6BAA6B;IACnC,IAAI,EAAE,iBAAiB;IACvB,IAAI,EAAE,2BAA2B;IACjC,IAAI,EAAE,gBAAgB;IACtB,IAAI,EAAE,iCAAiC;IACvC,IAAI,EAAE,qCAAqC;IAC3C,IAAI,EAAE,kCAAkC;IACxC,IAAI,EAAE,kCAAkC;IACxC,IAAI,EAAE,mBAAmB;IACzB,IAAI,EAAE,mBAAmB;IACzB,IAAI,EAAE,mBAAmB;IACzB,IAAI,EAAE,mBAAmB;IACzB,IAAI,EAAE,mBAAmB;IACzB,IAAI,EAAE,mBAAmB;IACzB,IAAI,EAAE,mBAAmB;IACzB,IAAI,EAAE,mBAAmB;IACzB,IAAI,EAAE,mBAAmB;IACzB,IAAI,EAAE,mBAAmB;CAC5B,CAAC,CAAC"}

package/build/v1/payment/schemas/cp-transaction-status.enum.d.ts

@@ -1,12 +1,26 @@
+/**
+ * CloudPayments transaction status strings returned in charge API responses.
+ * Source: https://developers.cloudpayments.ru/#statusy-tranzaktsiy
+ */
 export declare enum CpTransactionStatus {
     COMPLETED = "Completed",
     DECLINED = "Declined",
     AUTHORIZED = "Authorized",
     CANCELLED = "Cancelled"
 }
+/**
+ * Refund reason strings used when recording payment rows.
+ * Centralised here so OrderRepository and test expectations stay in sync.
+ */
 export declare enum CpRefundReason {
     FULL = "Refund",
     PARTIAL = "Partial refund \u2014 manual review",
+    /** Refund notification arrived before any Pay was recorded for this order. */
     EARLY = "Refund before payment \u2014 manual review",
+    /**
+     * Refund's declared PaymentTransactionId does not match the transaction that
+     * actually funded (CONFIRMED) this order — a different/extra charge attempt was
+     * refunded. Recorded for audit; must NOT revoke the order.
+     */
     MISMATCHED_TRANSACTION = "Refund of non-funding transaction \u2014 manual review"
 }

package/build/v1/payment/schemas/cp-transaction-status.enum.js

@@ -1,6 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CpRefundReason = exports.CpTransactionStatus = void 0;
+/**
+ * CloudPayments transaction status strings returned in charge API responses.
+ * Source: https://developers.cloudpayments.ru/#statusy-tranzaktsiy
+ */
 var CpTransactionStatus;
 (function (CpTransactionStatus) {
     CpTransactionStatus["COMPLETED"] = "Completed";
@@ -8,11 +12,21 @@ var CpTransactionStatus;
     CpTransactionStatus["AUTHORIZED"] = "Authorized";
     CpTransactionStatus["CANCELLED"] = "Cancelled";
 })(CpTransactionStatus || (exports.CpTransactionStatus = CpTransactionStatus = {}));
+/**
+ * Refund reason strings used when recording payment rows.
+ * Centralised here so OrderRepository and test expectations stay in sync.
+ */
 var CpRefundReason;
 (function (CpRefundReason) {
     CpRefundReason["FULL"] = "Refund";
     CpRefundReason["PARTIAL"] = "Partial refund \u2014 manual review";
+    /** Refund notification arrived before any Pay was recorded for this order. */
     CpRefundReason["EARLY"] = "Refund before payment \u2014 manual review";
+    /**
+     * Refund's declared PaymentTransactionId does not match the transaction that
+     * actually funded (CONFIRMED) this order — a different/extra charge attempt was
+     * refunded. Recorded for audit; must NOT revoke the order.
+     */
     CpRefundReason["MISMATCHED_TRANSACTION"] = "Refund of non-funding transaction \u2014 manual review";
 })(CpRefundReason || (exports.CpRefundReason = CpRefundReason = {}));
 //# sourceMappingURL=cp-transaction-status.enum.js.map

package/build/v1/payment/schemas/cp-transaction-status.enum.js.map

@@ -1 +1 @@
-{"version":3,"file":"cp-transaction-status.enum.js","sourceRoot":"","sources":["../../../../v1/payment/schemas/cp-transaction-status.enum.ts"],"names":[],"mappings":";;;AAIA,IAAY,mBAKX;AALD,WAAY,mBAAmB;IAC3B,8CAAuB,CAAA;IACvB,4CAAqB,CAAA;IACrB,gDAAyB,CAAA;IACzB,8CAAuB,CAAA;AAC3B,CAAC,EALW,mBAAmB,mCAAnB,mBAAmB,QAK9B;AAMD,IAAY,cAWX;AAXD,WAAY,cAAc;IACtB,iCAAe,CAAA;IACf,iEAA0C,CAAA;IAE1C,sEAA+C,CAAA;IAM/C,mGAA4E,CAAA;AAChF,CAAC,EAXW,cAAc,8BAAd,cAAc,QAWzB"}
+{"version":3,"file":"cp-transaction-status.enum.js","sourceRoot":"","sources":["../../../../v1/payment/schemas/cp-transaction-status.enum.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACH,IAAY,mBAKX;AALD,WAAY,mBAAmB;IAC3B,8CAAuB,CAAA;IACvB,4CAAqB,CAAA;IACrB,gDAAyB,CAAA;IACzB,8CAAuB,CAAA;AAC3B,CAAC,EALW,mBAAmB,mCAAnB,mBAAmB,QAK9B;AAED;;;GAGG;AACH,IAAY,cAWX;AAXD,WAAY,cAAc;IACtB,iCAAe,CAAA;IACf,iEAA0C,CAAA;IAC1C,8EAA8E;IAC9E,sEAA+C,CAAA;IAC/C;;;;OAIG;IACH,mGAA4E,CAAA;AAChF,CAAC,EAXW,cAAc,8BAAd,cAAc,QAWzB"}

package/build/v1/payment/schemas/currency.enum.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Supported payment currencies.
+ * Internal amounts are stored as integer units (×100 of the base currency unit).
+ */
 export declare enum Currency {
     RUB = "RUB"
 }

package/build/v1/payment/schemas/currency.enum.js

@@ -1,6 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Currency = void 0;
+/**
+ * Supported payment currencies.
+ * Internal amounts are stored as integer units (×100 of the base currency unit).
+ */
 var Currency;
 (function (Currency) {
     Currency["RUB"] = "RUB";

package/build/v1/payment/schemas/currency.enum.js.map

@@ -1 +1 @@
-{"version":3,"file":"currency.enum.js","sourceRoot":"","sources":["../../../../v1/payment/schemas/currency.enum.ts"],"names":[],"mappings":";;;AAIA,IAAY,QAEX;AAFD,WAAY,QAAQ;IAChB,uBAAW,CAAA;AACf,CAAC,EAFW,QAAQ,wBAAR,QAAQ,QAEnB"}
+{"version":3,"file":"currency.enum.js","sourceRoot":"","sources":["../../../../v1/payment/schemas/currency.enum.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACH,IAAY,QAEX;AAFD,WAAY,QAAQ;IAChB,uBAAW,CAAA;AACf,CAAC,EAFW,QAAQ,wBAAR,QAAQ,QAEnB"}

package/build/v1/payment/schemas/decline-kind.enum.d.ts

@@ -1,3 +1,34 @@
+/**
+ * Provider-neutral classification of a payment decline.
+ *
+ * The payment module maps provider-specific reason codes to this enum
+ * before returning ChargeSavedMethodResult. All upstream consumers
+ * (subscription dunning, checkout) branch on DeclineKind only — they
+ * never see raw provider codes.
+ *
+ * HARD       — permanent failure; dunning MUST stop. The payment module also revokes the
+ *              physical card and its recurring consent (owner decision 2026-10-20, uniformly
+ *              on every path that records a decline), EXCEPT for code 5003 (invalid merchant):
+ *              it stops dunning but never touches the card — see CARD_EFFECT_EXEMPT_REASON_CODES.
+ * INSUFFICIENT_FUNDS — the card has no money for this amount (CP 5051): transient,
+ *              dunning retries per schedule. The ONLY kind the customer is told
+ *              "insufficient funds" about (smart renewal, phase 1).
+ * SOFT       — any other known transient failure (issuer unavailable, limits, generic
+ *              do-not-honour, processing errors); retried per schedule, neutral wording.
+ * UNRECOGNIZED — a definitive decline whose code is missing or not in any known set:
+ *              retried like SOFT, never described as insufficient funds. Not the same as
+ *              ChargeOutcome.UNKNOWN (no definitive answer at all).
+ * CARD_EXPIRED — card past expiry date; dunning stops + the physical card is REVOKED (5033).
+ * CARD_REVOKED — card lost/stolen/blocked; dunning stops + the physical card is REVOKED.
+ * BANK_FRAUD_SUSPECTED — bank flagged this specific charge as suspected fraud (CP 5059;
+ *              owner decision 2026-10-03). Automatic/recurring collection on this
+ *              subscription MUST stop permanently (no provider retry-grid restart, no
+ *              local dunning continuation) — but, unlike HARD/CARD_EXPIRED/CARD_REVOKED,
+ *              the card itself is NOT revoked: it is a probabilistic bank-side signal
+ *              that can be a false positive, and the cardholder may still use it
+ *              elsewhere (one-off charges, other subscriptions). Excluded from
+ *              CARD_STOPPING_DECLINE_KINDS on purpose.
+ */
 export declare enum DeclineKind {
     HARD = "HARD",
     SOFT = "SOFT",

package/build/v1/payment/schemas/decline-kind.enum.js

@@ -1,6 +1,38 @@
 "use strict";
+// libs/contracts/v1/payment/schemas/decline-kind.enum.ts
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DeclineKind = void 0;
+/**
+ * Provider-neutral classification of a payment decline.
+ *
+ * The payment module maps provider-specific reason codes to this enum
+ * before returning ChargeSavedMethodResult. All upstream consumers
+ * (subscription dunning, checkout) branch on DeclineKind only — they
+ * never see raw provider codes.
+ *
+ * HARD       — permanent failure; dunning MUST stop. The payment module also revokes the
+ *              physical card and its recurring consent (owner decision 2026-10-20, uniformly
+ *              on every path that records a decline), EXCEPT for code 5003 (invalid merchant):
+ *              it stops dunning but never touches the card — see CARD_EFFECT_EXEMPT_REASON_CODES.
+ * INSUFFICIENT_FUNDS — the card has no money for this amount (CP 5051): transient,
+ *              dunning retries per schedule. The ONLY kind the customer is told
+ *              "insufficient funds" about (smart renewal, phase 1).
+ * SOFT       — any other known transient failure (issuer unavailable, limits, generic
+ *              do-not-honour, processing errors); retried per schedule, neutral wording.
+ * UNRECOGNIZED — a definitive decline whose code is missing or not in any known set:
+ *              retried like SOFT, never described as insufficient funds. Not the same as
+ *              ChargeOutcome.UNKNOWN (no definitive answer at all).
+ * CARD_EXPIRED — card past expiry date; dunning stops + the physical card is REVOKED (5033).
+ * CARD_REVOKED — card lost/stolen/blocked; dunning stops + the physical card is REVOKED.
+ * BANK_FRAUD_SUSPECTED — bank flagged this specific charge as suspected fraud (CP 5059;
+ *              owner decision 2026-10-03). Automatic/recurring collection on this
+ *              subscription MUST stop permanently (no provider retry-grid restart, no
+ *              local dunning continuation) — but, unlike HARD/CARD_EXPIRED/CARD_REVOKED,
+ *              the card itself is NOT revoked: it is a probabilistic bank-side signal
+ *              that can be a false positive, and the cardholder may still use it
+ *              elsewhere (one-off charges, other subscriptions). Excluded from
+ *              CARD_STOPPING_DECLINE_KINDS on purpose.
+ */
 var DeclineKind;
 (function (DeclineKind) {
     DeclineKind["HARD"] = "HARD";

package/build/v1/payment/schemas/decline-kind.enum.js.map

@@ -1 +1 @@
-{"version":3,"file":"decline-kind.enum.js","sourceRoot":"","sources":["../../../../v1/payment/schemas/decline-kind.enum.ts"],"names":[],"mappings":";;;AAiCA,IAAY,WAQX;AARD,WAAY,WAAW;IACnB,4BAAa,CAAA;IACb,4BAAa,CAAA;IACb,wDAAyC,CAAA;IACzC,4CAA6B,CAAA;IAC7B,4CAA6B,CAAA;IAC7B,4CAA6B,CAAA;IAC7B,4DAA6C,CAAA;AACjD,CAAC,EARW,WAAW,2BAAX,WAAW,QAQtB"}
+{"version":3,"file":"decline-kind.enum.js","sourceRoot":"","sources":["../../../../v1/payment/schemas/decline-kind.enum.ts"],"names":[],"mappings":";AAAA,yDAAyD;;;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,IAAY,WAQX;AARD,WAAY,WAAW;IACnB,4BAAa,CAAA;IACb,4BAAa,CAAA;IACb,wDAAyC,CAAA;IACzC,4CAA6B,CAAA;IAC7B,4CAA6B,CAAA;IAC7B,4CAA6B,CAAA;IAC7B,4DAA6C,CAAA;AACjD,CAAC,EARW,WAAW,2BAAX,WAAW,QAQtB"}

package/build/v1/payment/schemas/order-kind.enum.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Discriminates the type of purchase an Order represents.
+ * Replaces PurchaseKind (which is now deleted with PurchaseIntent fold → Order).
+ *
+ * SUBSCRIPTION_NEW — first subscription purchase for the user.
+ * RENEWAL          — auto-renewal at end of subscription term.
+ * UPGRADE          — mid-term plan change requiring proration surcharge payment.
+ * PACKAGE          — one-time package purchase (no subscription required).
+ */
 export declare enum OrderKind {
     SUBSCRIPTION_NEW = "SUBSCRIPTION_NEW",
     RENEWAL = "RENEWAL",

package/build/v1/payment/schemas/order-kind.enum.js

@@ -1,6 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OrderKind = void 0;
+/**
+ * Discriminates the type of purchase an Order represents.
+ * Replaces PurchaseKind (which is now deleted with PurchaseIntent fold → Order).
+ *
+ * SUBSCRIPTION_NEW — first subscription purchase for the user.
+ * RENEWAL          — auto-renewal at end of subscription term.
+ * UPGRADE          — mid-term plan change requiring proration surcharge payment.
+ * PACKAGE          — one-time package purchase (no subscription required).
+ */
 var OrderKind;
 (function (OrderKind) {
     OrderKind["SUBSCRIPTION_NEW"] = "SUBSCRIPTION_NEW";

package/build/v1/payment/schemas/order-kind.enum.js.map

@@ -1 +1 @@
-{"version":3,"file":"order-kind.enum.js","sourceRoot":"","sources":["../../../../v1/payment/schemas/order-kind.enum.ts"],"names":[],"mappings":";;;AASA,IAAY,SAKX;AALD,WAAY,SAAS;IACjB,kDAAqC,CAAA;IACrC,gCAAmB,CAAA;IACnB,gCAAmB,CAAA;IACnB,gCAAmB,CAAA;AACvB,CAAC,EALW,SAAS,yBAAT,SAAS,QAKpB"}
+{"version":3,"file":"order-kind.enum.js","sourceRoot":"","sources":["../../../../v1/payment/schemas/order-kind.enum.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;GAQG;AACH,IAAY,SAKX;AALD,WAAY,SAAS;IACjB,kDAAqC,CAAA;IACrC,gCAAmB,CAAA;IACnB,gCAAmB,CAAA;IACnB,gCAAmB,CAAA;AACvB,CAAC,EALW,SAAS,yBAAT,SAAS,QAKpB"}

package/build/v1/payment/schemas/order-outcome.enum.d.ts

@@ -1,3 +1,15 @@
+/**
+ * What became of a purchase order, for the payer who made it (GET /payment/orders/:orderId/outcome).
+ *
+ * CHECKING         — a charge on the order is with the bank; wait.
+ * APPLIED          — paid and the purchase took effect: the one strict proof of success.
+ * REFUNDED         — the refund completed; the purchase did not take effect.
+ * REFUND_PENDING   — the purchase was deliberately not applied and the money is still owed back
+ *                    (a refund has not completed, or only partly); not payable.
+ * DECLINED         — the last charge was declined; the order may still be payable.
+ * AWAITING_PAYMENT — nothing has been charged; the order is open.
+ * CLOSED           — the order expired or failed.
+ */
 export declare enum OrderOutcome {
     CHECKING = "CHECKING",
     APPLIED = "APPLIED",

package/build/v1/payment/schemas/order-outcome.enum.js

@@ -1,6 +1,19 @@
 "use strict";
+// libs/contracts/v1/payment/schemas/order-outcome.enum.ts
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OrderOutcome = void 0;
+/**
+ * What became of a purchase order, for the payer who made it (GET /payment/orders/:orderId/outcome).
+ *
+ * CHECKING         — a charge on the order is with the bank; wait.
+ * APPLIED          — paid and the purchase took effect: the one strict proof of success.
+ * REFUNDED         — the refund completed; the purchase did not take effect.
+ * REFUND_PENDING   — the purchase was deliberately not applied and the money is still owed back
+ *                    (a refund has not completed, or only partly); not payable.
+ * DECLINED         — the last charge was declined; the order may still be payable.
+ * AWAITING_PAYMENT — nothing has been charged; the order is open.
+ * CLOSED           — the order expired or failed.
+ */
 var OrderOutcome;
 (function (OrderOutcome) {
     OrderOutcome["CHECKING"] = "CHECKING";

package/build/v1/payment/schemas/order-outcome.enum.js.map

@@ -1 +1 @@
-{"version":3,"file":"order-outcome.enum.js","sourceRoot":"","sources":["../../../../v1/payment/schemas/order-outcome.enum.ts"],"names":[],"mappings":";;;AAcA,IAAY,YAQX;AARD,WAAY,YAAY;IACpB,qCAAqB,CAAA;IACrB,mCAAmB,CAAA;IACnB,qCAAqB,CAAA;IACrB,iDAAiC,CAAA;IACjC,qCAAqB,CAAA;IACrB,qDAAqC,CAAA;IACrC,iCAAiB,CAAA;AACrB,CAAC,EARW,YAAY,4BAAZ,YAAY,QAQvB"}
+{"version":3,"file":"order-outcome.enum.js","sourceRoot":"","sources":["../../../../v1/payment/schemas/order-outcome.enum.ts"],"names":[],"mappings":";AAAA,0DAA0D;;;AAE1D;;;;;;;;;;;GAWG;AACH,IAAY,YAQX;AARD,WAAY,YAAY;IACpB,qCAAqB,CAAA;IACrB,mCAAmB,CAAA;IACnB,qCAAqB,CAAA;IACrB,iDAAiC,CAAA;IACjC,qCAAqB,CAAA;IACrB,qDAAqC,CAAA;IACrC,iCAAiB,CAAA;AACrB,CAAC,EARW,YAAY,4BAAZ,YAAY,QAQvB"}

package/build/v1/payment/schemas/order-status.enum.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Lifecycle status of an Order record.
+ *
+ * PENDING  — order created by server; awaiting payment.
+ * PAID     — payment confirmed by provider webhook and applied.
+ * EXPIRED  — order TTL elapsed without payment (set by OrderReaperWorker), closed by the system, or cancelled by the payer.
+ * REFUNDED — the payment that paid the order was refunded in full.
+ *
+ * Terminal states: EXPIRED, REFUNDED. PAID can transition to REFUNDED only.
+ * Idempotency: duplicate pay-webhook on PAID order → {code:0} without side-effects.
+ */
 export declare enum OrderStatus {
     PENDING = "PENDING",
     PAID = "PAID",

package/build/v1/payment/schemas/order-status.enum.js

@@ -1,6 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OrderStatus = void 0;
+/**
+ * Lifecycle status of an Order record.
+ *
+ * PENDING  — order created by server; awaiting payment.
+ * PAID     — payment confirmed by provider webhook and applied.
+ * EXPIRED  — order TTL elapsed without payment (set by OrderReaperWorker), closed by the system, or cancelled by the payer.
+ * REFUNDED — the payment that paid the order was refunded in full.
+ *
+ * Terminal states: EXPIRED, REFUNDED. PAID can transition to REFUNDED only.
+ * Idempotency: duplicate pay-webhook on PAID order → {code:0} without side-effects.
+ */
 var OrderStatus;
 (function (OrderStatus) {
     OrderStatus["PENDING"] = "PENDING";

package/build/v1/payment/schemas/order-status.enum.js.map

@@ -1 +1 @@
-{"version":3,"file":"order-status.enum.js","sourceRoot":"","sources":["../../../../v1/payment/schemas/order-status.enum.ts"],"names":[],"mappings":";;;AAWA,IAAY,WAKX;AALD,WAAY,WAAW;IACnB,kCAAmB,CAAA;IACnB,4BAAa,CAAA;IACb,kCAAmB,CAAA;IACnB,oCAAqB,CAAA;AACzB,CAAC,EALW,WAAW,2BAAX,WAAW,QAKtB"}
+{"version":3,"file":"order-status.enum.js","sourceRoot":"","sources":["../../../../v1/payment/schemas/order-status.enum.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;GAUG;AACH,IAAY,WAKX;AALD,WAAY,WAAW;IACnB,kCAAmB,CAAA;IACnB,4BAAa,CAAA;IACb,kCAAmB,CAAA;IACnB,oCAAqB,CAAA;AACzB,CAAC,EALW,WAAW,2BAAX,WAAW,QAKtB"}

package/build/v1/payment/schemas/payment-decline-class.enum.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Payer-facing class of a failed charge. Provider-neutral and stable: the frontend picks its copy
+ * from this value and never from a bank's own text.
+ *
+ * INSUFFICIENT_FUNDS   — not enough money (CP 5051).
+ * BANK_SECURITY_CHECK  — the bank suspects fraud on this charge (CP 5059).
+ * CARD_EXPIRED         — the card is past its expiry date.
+ * CARD_BLOCKED         — the card was lost, stolen or blocked.
+ * CARD_RELINK_REQUIRED — the bank forbids charging this card without a fresh setup.
+ * LIMIT_OR_DETAILS     — a limit was reached or the card details do not match.
+ * BANK_UNAVAILABLE     — the issuer or its switch could not process the charge.
+ * DECLINED_BY_BANK     — any other transient bank decline.
+ * OTHER                — the reason is unknown or not recognised.
+ */
 export declare enum PaymentDeclineClass {
     INSUFFICIENT_FUNDS = "INSUFFICIENT_FUNDS",
     BANK_SECURITY_CHECK = "BANK_SECURITY_CHECK",

package/build/v1/payment/schemas/payment-decline-class.enum.js

@@ -1,6 +1,21 @@
 "use strict";
+// libs/contracts/v1/payment/schemas/payment-decline-class.enum.ts
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PaymentDeclineClass = void 0;
+/**
+ * Payer-facing class of a failed charge. Provider-neutral and stable: the frontend picks its copy
+ * from this value and never from a bank's own text.
+ *
+ * INSUFFICIENT_FUNDS   — not enough money (CP 5051).
+ * BANK_SECURITY_CHECK  — the bank suspects fraud on this charge (CP 5059).
+ * CARD_EXPIRED         — the card is past its expiry date.
+ * CARD_BLOCKED         — the card was lost, stolen or blocked.
+ * CARD_RELINK_REQUIRED — the bank forbids charging this card without a fresh setup.
+ * LIMIT_OR_DETAILS     — a limit was reached or the card details do not match.
+ * BANK_UNAVAILABLE     — the issuer or its switch could not process the charge.
+ * DECLINED_BY_BANK     — any other transient bank decline.
+ * OTHER                — the reason is unknown or not recognised.
+ */
 var PaymentDeclineClass;
 (function (PaymentDeclineClass) {
     PaymentDeclineClass["INSUFFICIENT_FUNDS"] = "INSUFFICIENT_FUNDS";

package/build/v1/payment/schemas/payment-decline-class.enum.js.map

@@ -1 +1 @@
-{"version":3,"file":"payment-decline-class.enum.js","sourceRoot":"","sources":["../../../../v1/payment/schemas/payment-decline-class.enum.ts"],"names":[],"mappings":";;;AAgBA,IAAY,mBAUX;AAVD,WAAY,mBAAmB;IAC3B,gEAAyC,CAAA;IACzC,kEAA2C,CAAA;IAC3C,oDAA6B,CAAA;IAC7B,oDAA6B,CAAA;IAC7B,oEAA6C,CAAA;IAC7C,4DAAqC,CAAA;IACrC,4DAAqC,CAAA;IACrC,4DAAqC,CAAA;IACrC,sCAAe,CAAA;AACnB,CAAC,EAVW,mBAAmB,mCAAnB,mBAAmB,QAU9B"}
+{"version":3,"file":"payment-decline-class.enum.js","sourceRoot":"","sources":["../../../../v1/payment/schemas/payment-decline-class.enum.ts"],"names":[],"mappings":";AAAA,kEAAkE;;;AAElE;;;;;;;;;;;;;GAaG;AACH,IAAY,mBAUX;AAVD,WAAY,mBAAmB;IAC3B,gEAAyC,CAAA;IACzC,kEAA2C,CAAA;IAC3C,oDAA6B,CAAA;IAC7B,oDAA6B,CAAA;IAC7B,oEAA6C,CAAA;IAC7C,4DAAqC,CAAA;IACrC,4DAAqC,CAAA;IACrC,4DAAqC,CAAA;IACrC,sCAAe,CAAA;AACnB,CAAC,EAVW,mBAAmB,mCAAnB,mBAAmB,QAU9B"}

package/build/v1/payment/schemas/payment-provider.enum.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Payment gateway providers.
+ * Extends as new gateways are added.
+ */
 export declare enum PaymentProvider {
     CLOUDPAYMENTS = "CLOUDPAYMENTS"
 }

package/build/v1/payment/schemas/payment-provider.enum.js

@@ -1,6 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PaymentProvider = void 0;
+/**
+ * Payment gateway providers.
+ * Extends as new gateways are added.
+ */
 var PaymentProvider;
 (function (PaymentProvider) {
     PaymentProvider["CLOUDPAYMENTS"] = "CLOUDPAYMENTS";

package/build/v1/payment/schemas/payment-provider.enum.js.map

@@ -1 +1 @@
-{"version":3,"file":"payment-provider.enum.js","sourceRoot":"","sources":["../../../../v1/payment/schemas/payment-provider.enum.ts"],"names":[],"mappings":";;;AAIA,IAAY,eAEX;AAFD,WAAY,eAAe;IACvB,kDAA+B,CAAA;AACnC,CAAC,EAFW,eAAe,+BAAf,eAAe,QAE1B"}
+{"version":3,"file":"payment-provider.enum.js","sourceRoot":"","sources":["../../../../v1/payment/schemas/payment-provider.enum.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACH,IAAY,eAEX;AAFD,WAAY,eAAe;IACvB,kDAA+B,CAAA;AACnC,CAAC,EAFW,eAAe,+BAAf,eAAe,QAE1B"}

package/build/v1/payment/schemas/payment-status.enum.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Lifecycle status of a Payment record (docs/features/payments-v2.md §2.2).
+ *
+ * INITIATED   — a token charge in progress: the row written before the HTTP call, 3-D Secure at the payer, "the bank is thinking".
+ *               Only a charge by a saved token writes it; a widget payment appears already CONFIRMED or DECLINED.
+ * CONFIRMED   — money captured. Terminal; refunds live in the refunds table and do not change this status.
+ *               An order can have several (a duplicate capture, or the second leg of a cascade).
+ * DECLINED    — rejected by the bank, or proven not to have been sent. A later capture of the same invoice confirms it.
+ * REFUNDED    — display only: the admin order detail shows a succeeded refund as such a row. Nothing writes it to
+ *   payments; refunds live in the refunds table.
+ *
+ * Idempotency: payments.provider_transaction_id is unique.
+ */
 export declare enum PaymentStatus {
     INITIATED = "INITIATED",
     CONFIRMED = "CONFIRMED",

package/build/v1/payment/schemas/payment-status.enum.js

@@ -1,6 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PaymentStatus = void 0;
+/**
+ * Lifecycle status of a Payment record (docs/features/payments-v2.md §2.2).
+ *
+ * INITIATED   — a token charge in progress: the row written before the HTTP call, 3-D Secure at the payer, "the bank is thinking".
+ *               Only a charge by a saved token writes it; a widget payment appears already CONFIRMED or DECLINED.
+ * CONFIRMED   — money captured. Terminal; refunds live in the refunds table and do not change this status.
+ *               An order can have several (a duplicate capture, or the second leg of a cascade).
+ * DECLINED    — rejected by the bank, or proven not to have been sent. A later capture of the same invoice confirms it.
+ * REFUNDED    — display only: the admin order detail shows a succeeded refund as such a row. Nothing writes it to
+ *   payments; refunds live in the refunds table.
+ *
+ * Idempotency: payments.provider_transaction_id is unique.
+ */
 var PaymentStatus;
 (function (PaymentStatus) {
     PaymentStatus["INITIATED"] = "INITIATED";

package/build/v1/payment/schemas/payment-status.enum.js.map

@@ -1 +1 @@
-{"version":3,"file":"payment-status.enum.js","sourceRoot":"","sources":["../../../../v1/payment/schemas/payment-status.enum.ts"],"names":[],"mappings":";;;AAaA,IAAY,aAKX;AALD,WAAY,aAAa;IACrB,wCAAuB,CAAA;IACvB,wCAAuB,CAAA;IACvB,sCAAqB,CAAA;IACrB,sCAAqB,CAAA;AACzB,CAAC,EALW,aAAa,6BAAb,aAAa,QAKxB"}
+{"version":3,"file":"payment-status.enum.js","sourceRoot":"","sources":["../../../../v1/payment/schemas/payment-status.enum.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;GAYG;AACH,IAAY,aAKX;AALD,WAAY,aAAa;IACrB,wCAAuB,CAAA;IACvB,wCAAuB,CAAA;IACvB,sCAAqB,CAAA;IACrB,sCAAqB,CAAA;AACzB,CAAC,EALW,aAAa,6BAAb,aAAa,QAKxB"}

package/build/v1/payment/schemas/provider-api-outcome.enum.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Result of a call to a payment provider's recurring-billing API.
+ * OK       — the provider confirmed the call.
+ * REJECTED — the provider definitely refused (business error or a 4xx): nothing was applied.
+ * UNKNOWN  — transport failure or 5xx: it may or may not have been applied; the caller must
+ *            observe the provider state before acting again.
+ */
 export declare enum ProviderApiOutcome {
     OK = "OK",
     REJECTED = "REJECTED",