@veruna/api-contracts 20.0.0 → 20.2.0

package/build/v1/payment/payment.errors.js

@@ -1,30 +1,67 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PAYMENT_ERRORS = exports.PaymentErrorCode = void 0;
+/**
+ * Error codes for the payment module.
+ * All codes are mapped to HTTP status codes in PAYMENT_ERRORS.
+ */
 var PaymentErrorCode;
 (function (PaymentErrorCode) {
+    /** Order not found by ID. */
     PaymentErrorCode["ORDER_NOT_FOUND"] = "ORDER_NOT_FOUND";
+    /** Amount in pay/check webhook does not match server-stored order amount. */
     PaymentErrorCode["ORDER_AMOUNT_MISMATCH"] = "ORDER_AMOUNT_MISMATCH";
+    /** Attempt to fulfill an already-fulfilled order (idempotency guard). */
     PaymentErrorCode["ORDER_ALREADY_FULFILLED"] = "ORDER_ALREADY_FULFILLED";
+    /** HMAC signature on webhook request failed verification. */
     PaymentErrorCode["WEBHOOK_SIGNATURE_INVALID"] = "WEBHOOK_SIGNATURE_INVALID";
+    /** No active SavedPaymentMethod found for the user (cannot run recurrent charge). */
     PaymentErrorCode["NO_SAVED_METHOD"] = "NO_SAVED_METHOD";
+    /** Saved method exists but is not ACTIVE (revoked/expired) — cannot be set as default. */
     PaymentErrorCode["SAVED_METHOD_NOT_ACTIVE"] = "SAVED_METHOD_NOT_ACTIVE";
+    /** Recurrent charge was synchronously declined by the payment gateway. */
     PaymentErrorCode["CHARGE_DECLINED"] = "CHARGE_DECLINED";
+    /** Order has already expired (TTL elapsed). */
     PaymentErrorCode["ORDER_EXPIRED"] = "ORDER_EXPIRED";
+    /** Order cannot be cancelled because it is already paid (or otherwise non-pending). */
     PaymentErrorCode["ORDER_NOT_CANCELLABLE"] = "ORDER_NOT_CANCELLABLE";
+    /** Order is not in a refundable state (not PAID, or no confirmed payment to refund). */
     PaymentErrorCode["ORDER_NOT_REFUNDABLE"] = "ORDER_NOT_REFUNDABLE";
+    /** Gateway rejected the refund request. */
     PaymentErrorCode["REFUND_FAILED"] = "REFUND_FAILED";
+    /**
+     * The refund gateway call failed (network/timeout/non-2xx) before a definitive
+     * decision was read — the refund MAY have been processed. NOT the same as
+     * REFUND_FAILED: the admin must reconcile before retrying, not simply resubmit.
+     */
     PaymentErrorCode["REFUND_OUTCOME_UNKNOWN"] = "REFUND_OUTCOME_UNKNOWN";
+    /** Payment gateway provider value from DB is not a recognised PaymentProvider enum member. */
     PaymentErrorCode["PAYMENT_PROVIDER_UNSUPPORTED"] = "PAYMENT_PROVIDER_UNSUPPORTED";
+    /** Order acceptance check failed — see OrderAcceptanceDecision for specific reason. */
     PaymentErrorCode["ORDER_ACCEPTANCE_FAILED"] = "ORDER_ACCEPTANCE_FAILED";
+    /** Subscription linked to a refunded order not found for revocation. */
     PaymentErrorCode["SUBSCRIPTION_NOT_FOUND_FOR_REVOCATION"] = "SUBSCRIPTION_NOT_FOUND_FOR_REVOCATION";
+    /** Currency value from DB or external source is not a recognised Currency enum member. */
     PaymentErrorCode["INVALID_CURRENCY"] = "INVALID_CURRENCY";
+    /** Amount value from external webhook is not a finite number (NaN, Infinity). */
     PaymentErrorCode["INVALID_AMOUNT"] = "INVALID_AMOUNT";
+    /**
+     * cp-subscriptions-v3 (v5.0 — manual payment without a reservation): checkout-config
+     * refuses to open the widget because a server-side (dunning / one-click) charge is
+     * currently in flight for this order or its subscription. The caller should treat this
+     * exactly like the `CHARGE_PROCESSING` ChargeStatus: do not open the widget, poll
+     * `GET /subscription/me` instead.
+     */
     PaymentErrorCode["ORDER_CHARGE_IN_FLIGHT"] = "ORDER_CHARGE_IN_FLIGHT";
+    /** Payment not found by id or provider transaction id. */
     PaymentErrorCode["PAYMENT_NOT_FOUND"] = "PAYMENT_NOT_FOUND";
+    /** Refund not found by id. */
     PaymentErrorCode["REFUND_NOT_FOUND"] = "REFUND_NOT_FOUND";
+    /** A refund of this payment is already in flight (REQUESTED), or the payment already has its automatic refund. */
     PaymentErrorCode["REFUND_ALREADY_REQUESTED"] = "REFUND_ALREADY_REQUESTED";
+    /** The refund status does not allow this transition. */
     PaymentErrorCode["REFUND_INVALID_TRANSITION"] = "REFUND_INVALID_TRANSITION";
+    /** The payment status does not allow this transition. */
     PaymentErrorCode["PAYMENT_INVALID_TRANSITION"] = "PAYMENT_INVALID_TRANSITION";
 })(PaymentErrorCode || (exports.PaymentErrorCode = PaymentErrorCode = {}));
 exports.PAYMENT_ERRORS = {

package/build/v1/payment/payment.errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"payment.errors.js","sourceRoot":"","sources":["../../../v1/payment/payment.errors.ts"],"names":[],"mappings":";;;AAMA,IAAY,gBAyDX;AAzDD,WAAY,gBAAgB;IAExB,uDAAmC,CAAA;IAEnC,mEAA+C,CAAA;IAE/C,uEAAmD,CAAA;IAEnD,2EAAuD,CAAA;IAEvD,uDAAmC,CAAA;IAEnC,uEAAmD,CAAA;IAEnD,uDAAmC,CAAA;IAEnC,mDAA+B,CAAA;IAE/B,mEAA+C,CAAA;IAE/C,iEAA6C,CAAA;IAE7C,mDAA+B,CAAA;IAM/B,qEAAiD,CAAA;IAEjD,iFAA6D,CAAA;IAE7D,uEAAmD,CAAA;IAEnD,mGAA+E,CAAA;IAE/E,yDAAqC,CAAA;IAErC,qDAAiC,CAAA;IAQjC,qEAAiD,CAAA;IAEjD,2DAAuC,CAAA;IAEvC,yDAAqC,CAAA;IAErC,yEAAqD,CAAA;IAErD,2EAAuD,CAAA;IAEvD,6EAAyD,CAAA;AAC7D,CAAC,EAzDW,gBAAgB,gCAAhB,gBAAgB,QAyD3B;AAEY,QAAA,cAAc,GAA4C;IACnE,CAAC,gBAAgB,CAAC,eAAe,CAAC,EAAE;QAChC,IAAI,EAAE,gBAAgB,CAAC,eAAe;QACtC,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,gBAAgB,CAAC,qBAAqB,CAAC,EAAE;QACtC,IAAI,EAAE,gBAAgB,CAAC,qBAAqB;QAC5C,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,gBAAgB,CAAC,uBAAuB,CAAC,EAAE;QACxC,IAAI,EAAE,gBAAgB,CAAC,uBAAuB;QAC9C,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,gBAAgB,CAAC,yBAAyB,CAAC,EAAE;QAC1C,IAAI,EAAE,gBAAgB,CAAC,yBAAyB;QAChD,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,gBAAgB,CAAC,eAAe,CAAC,EAAE;QAChC,IAAI,EAAE,gBAAgB,CAAC,eAAe;QACtC,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,gBAAgB,CAAC,uBAAuB,CAAC,EAAE;QACxC,IAAI,EAAE,gBAAgB,CAAC,uBAAuB;QAC9C,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,gBAAgB,CAAC,eAAe,CAAC,EAAE;QAChC,IAAI,EAAE,gBAAgB,CAAC,eAAe;QACtC,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE;QAC9B,IAAI,EAAE,gBAAgB,CAAC,aAAa;QACpC,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,gBAAgB,CAAC,qBAAqB,CAAC,EAAE;QACtC,IAAI,EAAE,gBAAgB,CAAC,qBAAqB;QAC5C,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,gBAAgB,CAAC,oBAAoB,CAAC,EAAE;QACrC,IAAI,EAAE,gBAAgB,CAAC,oBAAoB;QAC3C,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE;QAC9B,IAAI,EAAE,gBAAgB,CAAC,aAAa;QACpC,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,gBAAgB,CAAC,sBAAsB,CAAC,EAAE;QACvC,IAAI,EAAE,gBAAgB,CAAC,sBAAsB;QAC7C,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,gBAAgB,CAAC,4BAA4B,CAAC,EAAE;QAC7C,IAAI,EAAE,gBAAgB,CAAC,4BAA4B;QACnD,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,gBAAgB,CAAC,uBAAuB,CAAC,EAAE;QACxC,IAAI,EAAE,gBAAgB,CAAC,uBAAuB;QAC9C,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,gBAAgB,CAAC,qCAAqC,CAAC,EAAE;QACtD,IAAI,EAAE,gBAAgB,CAAC,qCAAqC;QAC5D,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,gBAAgB,CAAC,gBAAgB,CAAC,EAAE;QACjC,IAAI,EAAE,gBAAgB,CAAC,gBAAgB;QACvC,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,gBAAgB,CAAC,cAAc,CAAC,EAAE;QAC/B,IAAI,EAAE,gBAAgB,CAAC,cAAc;QACrC,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,gBAAgB,CAAC,sBAAsB,CAAC,EAAE;QACvC,IAAI,EAAE,gBAAgB,CAAC,sBAAsB;QAC7C,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,gBAAgB,CAAC,iBAAiB,CAAC,EAAE;QAClC,IAAI,EAAE,gBAAgB,CAAC,iBAAiB;QACxC,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,gBAAgB,CAAC,gBAAgB,CAAC,EAAE;QACjC,IAAI,EAAE,gBAAgB,CAAC,gBAAgB;QACvC,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,gBAAgB,CAAC,wBAAwB,CAAC,EAAE;QACzC,IAAI,EAAE,gBAAgB,CAAC,wBAAwB;QAC/C,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,gBAAgB,CAAC,yBAAyB,CAAC,EAAE;QAC1C,IAAI,EAAE,gBAAgB,CAAC,yBAAyB;QAChD,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,gBAAgB,CAAC,0BAA0B,CAAC,EAAE;QAC3C,IAAI,EAAE,gBAAgB,CAAC,0BAA0B;QACjD,UAAU,EAAE,GAAG;KAClB;CACK,CAAC"}
+{"version":3,"file":"payment.errors.js","sourceRoot":"","sources":["../../../v1/payment/payment.errors.ts"],"names":[],"mappings":"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"}

package/build/v1/payment/queries/get-checkout-config.query.d.ts

@@ -1,5 +1,13 @@
 import { z } from 'zod';
 import { HttpMethod } from '../../../shared/http-method.enum';
+/**
+ * Get CloudPayments widget initialization parameters for an Order.
+ * Used by frontend to open the payment widget after checkout.
+ * Owner derived from JWT; 404 if order not found or not owned.
+ *
+ * User-facing query: GET /v1/payment/checkout-config?orderId=
+ * Handler owns 1 repository: OrderRepository + reads ConfigService (CLOUDPAYMENTS_PUBLIC_ID).
+ */
 export declare namespace GetCheckoutConfigQuery {
     const Request: z.ZodObject<{
         userId: z.ZodString;

package/build/v1/payment/queries/get-checkout-config.query.js

@@ -6,6 +6,14 @@ const shared_1 = require("../../../shared");
 const rest_api_1 = require("../../../rest-api");
 const http_method_enum_1 = require("../../../shared/http-method.enum");
 const cloudpayments_webhook_schemas_1 = require("../schemas/cloudpayments-webhook.schemas");
+/**
+ * Get CloudPayments widget initialization parameters for an Order.
+ * Used by frontend to open the payment widget after checkout.
+ * Owner derived from JWT; 404 if order not found or not owned.
+ *
+ * User-facing query: GET /v1/payment/checkout-config?orderId=
+ * Handler owns 1 repository: OrderRepository + reads ConfigService (CLOUDPAYMENTS_PUBLIC_ID).
+ */
 var GetCheckoutConfigQuery;
 (function (GetCheckoutConfigQuery) {
     GetCheckoutConfigQuery.Request = zod_1.z.object({

package/build/v1/payment/queries/get-checkout-config.query.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-checkout-config.query.js","sourceRoot":"","sources":["../../../../v1/payment/queries/get-checkout-config.query.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,4CAA6C;AAC7C,gDAA6C;AAC7C,uEAA8D;AAC9D,4FAAgF;AAUhF,IAAiB,sBAAsB,CAiBtC;AAjBD,WAAiB,sBAAsB;IACtB,8BAAO,GAAG,OAAC,CAAC,MAAM,CAAC;QAC5B,MAAM,EAAE,OAAC;aACJ,MAAM,CAAC,EAAE,KAAK,EAAE,wCAAwC,EAAE,CAAC;aAC3D,KAAK,CAAC,mBAAU,EAAE,EAAE,OAAO,EAAE,uCAAuC,EAAE,CAAC;QAC5E,OAAO,EAAE,OAAC;aACL,MAAM,CAAC,EAAE,KAAK,EAAE,yCAAyC,EAAE,CAAC;aAC5D,KAAK,CAAC,mBAAU,EAAE,EAAE,OAAO,EAAE,wCAAwC,EAAE,CAAC;KAChF,CAAC,CAAC;IAEU,+BAAQ,GAAG,oDAAoB,CAAC;IAEhC,0BAAG,GAAG,mBAAQ,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IAC9C,6BAAM,GAAG,6BAAU,CAAC,GAAG,CAAC;AAIzC,CAAC,EAjBgB,sBAAsB,sCAAtB,sBAAsB,QAiBtC"}
+{"version":3,"file":"get-checkout-config.query.js","sourceRoot":"","sources":["../../../../v1/payment/queries/get-checkout-config.query.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,4CAA6C;AAC7C,gDAA6C;AAC7C,uEAA8D;AAC9D,4FAAgF;AAEhF;;;;;;;GAOG;AACH,IAAiB,sBAAsB,CAiBtC;AAjBD,WAAiB,sBAAsB;IACtB,8BAAO,GAAG,OAAC,CAAC,MAAM,CAAC;QAC5B,MAAM,EAAE,OAAC;aACJ,MAAM,CAAC,EAAE,KAAK,EAAE,wCAAwC,EAAE,CAAC;aAC3D,KAAK,CAAC,mBAAU,EAAE,EAAE,OAAO,EAAE,uCAAuC,EAAE,CAAC;QAC5E,OAAO,EAAE,OAAC;aACL,MAAM,CAAC,EAAE,KAAK,EAAE,yCAAyC,EAAE,CAAC;aAC5D,KAAK,CAAC,mBAAU,EAAE,EAAE,OAAO,EAAE,wCAAwC,EAAE,CAAC;KAChF,CAAC,CAAC;IAEU,+BAAQ,GAAG,oDAAoB,CAAC;IAEhC,0BAAG,GAAG,mBAAQ,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IAC9C,6BAAM,GAAG,6BAAU,CAAC,GAAG,CAAC;AAIzC,CAAC,EAjBgB,sBAAsB,sCAAtB,sBAAsB,QAiBtC"}

package/build/v1/payment/queries/get-order-outcome.query.d.ts

@@ -11,6 +11,14 @@ export declare const OrderOutcomeSchema: z.ZodObject<{
     payable: z.ZodBoolean;
     unresolvedMoney: z.ZodBoolean;
 }, z.core.$strip>;
+/**
+ * What became of the caller's own purchase order — the strict read behind a one-click
+ * CHARGE_PROCESSING: APPLIED is the only proof of success.
+ * Owner derived from JWT; 404 ORDER_NOT_FOUND for a missing order and for someone else's alike.
+ *
+ * User-facing query: GET /v1/payment/orders/:orderId/outcome
+ * Handler owns 1 repository: OrderRepository (+ the decline classifier port).
+ */
 export declare namespace GetOrderOutcomeQuery {
     const Request: z.ZodObject<{
         userId: z.ZodString;

package/build/v1/payment/queries/get-order-outcome.query.js

@@ -12,10 +12,24 @@ exports.OrderOutcomeSchema = zod_1.z.object({
     orderId: zod_1.z.string().regex(shared_1.UUID_REGEX),
     kind: zod_1.z.nativeEnum(order_kind_enum_1.OrderKind),
     outcome: zod_1.z.nativeEnum(order_outcome_enum_1.OrderOutcome),
+    /** Set for DECLINED, and for CLOSED when the last real payment was a decline. null otherwise. */
     declineClass: zod_1.z.nativeEnum(payment_decline_class_enum_1.PaymentDeclineClass).nullable(),
+    /** true while the order can still be paid in the widget (PENDING, not expired, not a provider renewal) after a decline or with no charge. */
     payable: zod_1.z.boolean(),
+    /**
+     * true while a payment of the order is unresolved (with the bank, or of unknown result). The outcome
+     * stays authoritative — APPLIED is still APPLIED — but money may still be moving.
+     */
     unresolvedMoney: zod_1.z.boolean(),
 });
+/**
+ * What became of the caller's own purchase order — the strict read behind a one-click
+ * CHARGE_PROCESSING: APPLIED is the only proof of success.
+ * Owner derived from JWT; 404 ORDER_NOT_FOUND for a missing order and for someone else's alike.
+ *
+ * User-facing query: GET /v1/payment/orders/:orderId/outcome
+ * Handler owns 1 repository: OrderRepository (+ the decline classifier port).
+ */
 var GetOrderOutcomeQuery;
 (function (GetOrderOutcomeQuery) {
     GetOrderOutcomeQuery.Request = zod_1.z.object({

package/build/v1/payment/queries/get-order-outcome.query.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-order-outcome.query.js","sourceRoot":"","sources":["../../../../v1/payment/queries/get-order-outcome.query.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,4CAA6C;AAC7C,gDAA6C;AAC7C,uEAA8D;AAC9D,gEAAuD;AACvD,sEAA6D;AAC7D,sFAA4E;AAE/D,QAAA,kBAAkB,GAAG,OAAC,CAAC,MAAM,CAAC;IACvC,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,mBAAU,CAAC;IACrC,IAAI,EAAE,OAAC,CAAC,UAAU,CAAC,2BAAS,CAAC;IAC7B,OAAO,EAAE,OAAC,CAAC,UAAU,CAAC,iCAAY,CAAC;IAEnC,YAAY,EAAE,OAAC,CAAC,UAAU,CAAC,gDAAmB,CAAC,CAAC,QAAQ,EAAE;IAE1D,OAAO,EAAE,OAAC,CAAC,OAAO,EAAE;IAKpB,eAAe,EAAE,OAAC,CAAC,OAAO,EAAE;CAC/B,CAAC,CAAC;AAUH,IAAiB,oBAAoB,CAiBpC;AAjBD,WAAiB,oBAAoB;IACpB,4BAAO,GAAG,OAAC,CAAC,MAAM,CAAC;QAC5B,MAAM,EAAE,OAAC;aACJ,MAAM,CAAC,EAAE,KAAK,EAAE,sCAAsC,EAAE,CAAC;aACzD,KAAK,CAAC,mBAAU,EAAE,EAAE,OAAO,EAAE,qCAAqC,EAAE,CAAC;QAC1E,OAAO,EAAE,OAAC;aACL,MAAM,CAAC,EAAE,KAAK,EAAE,uCAAuC,EAAE,CAAC;aAC1D,KAAK,CAAC,mBAAU,EAAE,EAAE,OAAO,EAAE,sCAAsC,EAAE,CAAC;KAC9E,CAAC,CAAC;IAEU,6BAAQ,GAAG,0BAAkB,CAAC;IAE9B,wBAAG,GAAG,mBAAQ,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;IAC5C,2BAAM,GAAG,6BAAU,CAAC,GAAG,CAAC;AAIzC,CAAC,EAjBgB,oBAAoB,oCAApB,oBAAoB,QAiBpC"}
+{"version":3,"file":"get-order-outcome.query.js","sourceRoot":"","sources":["../../../../v1/payment/queries/get-order-outcome.query.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,4CAA6C;AAC7C,gDAA6C;AAC7C,uEAA8D;AAC9D,gEAAuD;AACvD,sEAA6D;AAC7D,sFAA4E;AAE/D,QAAA,kBAAkB,GAAG,OAAC,CAAC,MAAM,CAAC;IACvC,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,mBAAU,CAAC;IACrC,IAAI,EAAE,OAAC,CAAC,UAAU,CAAC,2BAAS,CAAC;IAC7B,OAAO,EAAE,OAAC,CAAC,UAAU,CAAC,iCAAY,CAAC;IACnC,iGAAiG;IACjG,YAAY,EAAE,OAAC,CAAC,UAAU,CAAC,gDAAmB,CAAC,CAAC,QAAQ,EAAE;IAC1D,6IAA6I;IAC7I,OAAO,EAAE,OAAC,CAAC,OAAO,EAAE;IACpB;;;OAGG;IACH,eAAe,EAAE,OAAC,CAAC,OAAO,EAAE;CAC/B,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,IAAiB,oBAAoB,CAiBpC;AAjBD,WAAiB,oBAAoB;IACpB,4BAAO,GAAG,OAAC,CAAC,MAAM,CAAC;QAC5B,MAAM,EAAE,OAAC;aACJ,MAAM,CAAC,EAAE,KAAK,EAAE,sCAAsC,EAAE,CAAC;aACzD,KAAK,CAAC,mBAAU,EAAE,EAAE,OAAO,EAAE,qCAAqC,EAAE,CAAC;QAC1E,OAAO,EAAE,OAAC;aACL,MAAM,CAAC,EAAE,KAAK,EAAE,uCAAuC,EAAE,CAAC;aAC1D,KAAK,CAAC,mBAAU,EAAE,EAAE,OAAO,EAAE,sCAAsC,EAAE,CAAC;KAC9E,CAAC,CAAC;IAEU,6BAAQ,GAAG,0BAAkB,CAAC;IAE9B,wBAAG,GAAG,mBAAQ,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;IAC5C,2BAAM,GAAG,6BAAU,CAAC,GAAG,CAAC;AAIzC,CAAC,EAjBgB,oBAAoB,oCAApB,oBAAoB,QAiBpC"}

package/build/v1/payment/queries/get-order.query.d.ts

@@ -1,5 +1,13 @@
 import { z } from 'zod';
 import { HttpMethod } from '../../../shared/http-method.enum';
+/**
+ * Get a single Order by ID.
+ * Used by subscription fulfillment service and CloudPayments webhook service.
+ *
+ * Cross-module query: subscription / payment internal → payment.
+ * Handler owns 1 repository: OrderRepository.
+ * No HTTP endpoint — invoked only via TypedQueryBus.
+ */
 export declare namespace GetOrderQuery {
     const Request: z.ZodObject<{
         orderId: z.ZodString;

package/build/v1/payment/queries/get-order.query.js

@@ -5,6 +5,14 @@ const zod_1 = require("zod");
 const shared_1 = require("../../../shared");
 const http_method_enum_1 = require("../../../shared/http-method.enum");
 const cloudpayments_webhook_schemas_1 = require("../schemas/cloudpayments-webhook.schemas");
+/**
+ * Get a single Order by ID.
+ * Used by subscription fulfillment service and CloudPayments webhook service.
+ *
+ * Cross-module query: subscription / payment internal → payment.
+ * Handler owns 1 repository: OrderRepository.
+ * No HTTP endpoint — invoked only via TypedQueryBus.
+ */
 var GetOrderQuery;
 (function (GetOrderQuery) {
     GetOrderQuery.Request = zod_1.z.object({

package/build/v1/payment/queries/get-order.query.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-order.query.js","sourceRoot":"","sources":["../../../../v1/payment/queries/get-order.query.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,4CAA6C;AAC7C,uEAA8D;AAC9D,4FAA2E;AAU3E,IAAiB,aAAa,CAa7B;AAbD,WAAiB,aAAa;IACb,qBAAO,GAAG,OAAC,CAAC,MAAM,CAAC;QAC5B,OAAO,EAAE,OAAC;aACL,MAAM,CAAC,EAAE,KAAK,EAAE,gCAAgC,EAAE,CAAC;aACnD,KAAK,CAAC,mBAAU,EAAE,EAAE,OAAO,EAAE,+BAA+B,EAAE,CAAC;KACvE,CAAC,CAAC;IAEU,sBAAQ,GAAG,+CAAe,CAAC,QAAQ,EAAE,CAAC;IAEtC,oBAAM,GAAG,6BAAU,CAAC,GAAG,CAAC;AAIzC,CAAC,EAbgB,aAAa,6BAAb,aAAa,QAa7B"}
+{"version":3,"file":"get-order.query.js","sourceRoot":"","sources":["../../../../v1/payment/queries/get-order.query.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,4CAA6C;AAC7C,uEAA8D;AAC9D,4FAA2E;AAE3E;;;;;;;GAOG;AACH,IAAiB,aAAa,CAa7B;AAbD,WAAiB,aAAa;IACb,qBAAO,GAAG,OAAC,CAAC,MAAM,CAAC;QAC5B,OAAO,EAAE,OAAC;aACL,MAAM,CAAC,EAAE,KAAK,EAAE,gCAAgC,EAAE,CAAC;aACnD,KAAK,CAAC,mBAAU,EAAE,EAAE,OAAO,EAAE,+BAA+B,EAAE,CAAC;KACvE,CAAC,CAAC;IAEU,sBAAQ,GAAG,+CAAe,CAAC,QAAQ,EAAE,CAAC;IAEtC,oBAAM,GAAG,6BAAU,CAAC,GAAG,CAAC;AAIzC,CAAC,EAbgB,aAAa,6BAAb,aAAa,QAa7B"}

package/build/v1/payment/queries/get-saved-methods.query.d.ts

@@ -18,6 +18,13 @@ export declare const SavedPaymentMethodViewSchema: z.ZodObject<{
     createdAt: z.ZodString;
 }, z.core.$strip>;
 export type SavedPaymentMethodView = z.infer<typeof SavedPaymentMethodViewSchema>;
+/**
+ * List the authenticated user's saved cards: ACTIVE and UNUSABLE (REVOKED cards are not returned).
+ * Owner derived from JWT.
+ *
+ * User-facing query: GET /v1/payment/saved-methods
+ * Handler owns 1 repository: SavedPaymentMethodRepository.
+ */
 export declare namespace GetSavedMethodsQuery {
     const Request: z.ZodObject<{
         userId: z.ZodString;

package/build/v1/payment/queries/get-saved-methods.query.js

@@ -11,17 +11,29 @@ exports.SavedPaymentMethodViewSchema = zod_1.z.object({
     id: zod_1.z.string().regex(shared_1.UUID_REGEX),
     cardMask: zod_1.z.string(),
     cardType: zod_1.z.string().nullable(),
+    /** Card product type from CP (e.g. "Visa Classic"). */
     cardProduct: zod_1.z.string().nullable(),
+    /** Issuing bank name from CP (e.g. "Sberbank of Russia"). */
     cardIssuer: zod_1.z.string().nullable(),
+    /** Issuing bank country — ISO 3166-1 alpha-2 (e.g. "RU"). */
     issuerCountry: zod_1.z.string().nullable(),
+    /** Unique card identifier in CloudPayments. */
     cardId: zod_1.z.string().nullable(),
     expMonth: zod_1.z.number().int().min(1).max(12).nullable(),
     expYear: zod_1.z.number().int().positive().nullable(),
     status: zod_1.z.nativeEnum(saved_method_status_enum_1.SavedMethodStatus),
+    /** Set only for UNUSABLE cards: why the bank refused the card. */
     unusableReason: zod_1.z.nativeEnum(saved_method_unusable_reason_enum_1.SavedMethodUnusableReason).nullable(),
     isDefault: zod_1.z.boolean(),
     createdAt: zod_1.z.string().datetime({ offset: true }),
 });
+/**
+ * List the authenticated user's saved cards: ACTIVE and UNUSABLE (REVOKED cards are not returned).
+ * Owner derived from JWT.
+ *
+ * User-facing query: GET /v1/payment/saved-methods
+ * Handler owns 1 repository: SavedPaymentMethodRepository.
+ */
 var GetSavedMethodsQuery;
 (function (GetSavedMethodsQuery) {
     GetSavedMethodsQuery.Request = zod_1.z.object({

package/build/v1/payment/queries/get-saved-methods.query.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-saved-methods.query.js","sourceRoot":"","sources":["../../../../v1/payment/queries/get-saved-methods.query.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,4CAA6C;AAC7C,gDAA6C;AAC7C,uEAA8D;AAC9D,kFAAwE;AACxE,oGAAyF;AAE5E,QAAA,4BAA4B,GAAG,OAAC,CAAC,MAAM,CAAC;IACjD,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,mBAAU,CAAC;IAChC,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE;IACpB,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAE/B,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAElC,UAAU,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAEjC,aAAa,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAEpC,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE;IACpD,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC/C,MAAM,EAAE,OAAC,CAAC,UAAU,CAAC,4CAAiB,CAAC;IAEvC,cAAc,EAAE,OAAC,CAAC,UAAU,CAAC,6DAAyB,CAAC,CAAC,QAAQ,EAAE;IAClE,SAAS,EAAE,OAAC,CAAC,OAAO,EAAE;IACtB,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;CACnD,CAAC,CAAC;AAWH,IAAiB,oBAAoB,CAcpC;AAdD,WAAiB,oBAAoB;IACpB,4BAAO,GAAG,OAAC,CAAC,MAAM,CAAC;QAC5B,MAAM,EAAE,OAAC;aACJ,MAAM,CAAC,EAAE,KAAK,EAAE,sCAAsC,EAAE,CAAC;aACzD,KAAK,CAAC,mBAAU,EAAE,EAAE,OAAO,EAAE,qCAAqC,EAAE,CAAC;KAC7E,CAAC,CAAC;IAEU,6BAAQ,GAAG,OAAC,CAAC,KAAK,CAAC,oCAA4B,CAAC,CAAC;IAEjD,wBAAG,GAAG,mBAAQ,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;IAC5C,2BAAM,GAAG,6BAAU,CAAC,GAAG,CAAC;AAIzC,CAAC,EAdgB,oBAAoB,oCAApB,oBAAoB,QAcpC"}
+{"version":3,"file":"get-saved-methods.query.js","sourceRoot":"","sources":["../../../../v1/payment/queries/get-saved-methods.query.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,4CAA6C;AAC7C,gDAA6C;AAC7C,uEAA8D;AAC9D,kFAAwE;AACxE,oGAAyF;AAE5E,QAAA,4BAA4B,GAAG,OAAC,CAAC,MAAM,CAAC;IACjD,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,mBAAU,CAAC;IAChC,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE;IACpB,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,uDAAuD;IACvD,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,6DAA6D;IAC7D,UAAU,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,6DAA6D;IAC7D,aAAa,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACpC,+CAA+C;IAC/C,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE;IACpD,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC/C,MAAM,EAAE,OAAC,CAAC,UAAU,CAAC,4CAAiB,CAAC;IACvC,kEAAkE;IAClE,cAAc,EAAE,OAAC,CAAC,UAAU,CAAC,6DAAyB,CAAC,CAAC,QAAQ,EAAE;IAClE,SAAS,EAAE,OAAC,CAAC,OAAO,EAAE;IACtB,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;CACnD,CAAC,CAAC;AAIH;;;;;;GAMG;AACH,IAAiB,oBAAoB,CAcpC;AAdD,WAAiB,oBAAoB;IACpB,4BAAO,GAAG,OAAC,CAAC,MAAM,CAAC;QAC5B,MAAM,EAAE,OAAC;aACJ,MAAM,CAAC,EAAE,KAAK,EAAE,sCAAsC,EAAE,CAAC;aACzD,KAAK,CAAC,mBAAU,EAAE,EAAE,OAAO,EAAE,qCAAqC,EAAE,CAAC;KAC7E,CAAC,CAAC;IAEU,6BAAQ,GAAG,OAAC,CAAC,KAAK,CAAC,oCAA4B,CAAC,CAAC;IAEjD,wBAAG,GAAG,mBAAQ,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;IAC5C,2BAAM,GAAG,6BAAU,CAAC,GAAG,CAAC;AAIzC,CAAC,EAdgB,oBAAoB,oCAApB,oBAAoB,QAcpC"}

package/build/v1/payment/schemas/charge-initiator.enum.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Identifies which party initiated a stored-credential charge.
+ *
+ * MERCHANT_SCHEDULED — charge initiated by merchant on stored credentials
+ *                      (auto-renewal / dunning). CP fields: TrInitiatorCode=0 + PaymentScheduled=1.
+ *                      https://developers.cloudpayments.ru/#oplata-po-tokenu-rekarring
+ *
+ * CARDHOLDER         — charge initiated by the cardholder pressing a "Pay" button in the UI.
+ *                      CP fields: TrInitiatorCode=1. PaymentScheduled MUST NOT be sent.
+ *                      Legal requirement: one-click purchases for new items MUST be
+ *                      explicitly triggered by the cardholder — silent auto-charges are forbidden.
+ */
 export declare enum ChargeInitiator {
     MERCHANT_SCHEDULED = "MERCHANT_SCHEDULED",
     CARDHOLDER = "CARDHOLDER"

package/build/v1/payment/schemas/charge-initiator.enum.js

@@ -1,6 +1,19 @@
 "use strict";
+// libs/contracts/v1/payment/schemas/charge-initiator.enum.ts
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChargeInitiator = void 0;
+/**
+ * Identifies which party initiated a stored-credential charge.
+ *
+ * MERCHANT_SCHEDULED — charge initiated by merchant on stored credentials
+ *                      (auto-renewal / dunning). CP fields: TrInitiatorCode=0 + PaymentScheduled=1.
+ *                      https://developers.cloudpayments.ru/#oplata-po-tokenu-rekarring
+ *
+ * CARDHOLDER         — charge initiated by the cardholder pressing a "Pay" button in the UI.
+ *                      CP fields: TrInitiatorCode=1. PaymentScheduled MUST NOT be sent.
+ *                      Legal requirement: one-click purchases for new items MUST be
+ *                      explicitly triggered by the cardholder — silent auto-charges are forbidden.
+ */
 var ChargeInitiator;
 (function (ChargeInitiator) {
     ChargeInitiator["MERCHANT_SCHEDULED"] = "MERCHANT_SCHEDULED";

package/build/v1/payment/schemas/charge-initiator.enum.js.map

@@ -1 +1 @@
-{"version":3,"file":"charge-initiator.enum.js","sourceRoot":"","sources":["../../../../v1/payment/schemas/charge-initiator.enum.ts"],"names":[],"mappings":";;;AAcA,IAAY,eAGX;AAHD,WAAY,eAAe;IACvB,4DAAyC,CAAA;IACzC,4CAAyB,CAAA;AAC7B,CAAC,EAHW,eAAe,+BAAf,eAAe,QAG1B"}
+{"version":3,"file":"charge-initiator.enum.js","sourceRoot":"","sources":["../../../../v1/payment/schemas/charge-initiator.enum.ts"],"names":[],"mappings":";AAAA,6DAA6D;;;AAE7D;;;;;;;;;;;GAWG;AACH,IAAY,eAGX;AAHD,WAAY,eAAe;IACvB,4DAAyC,CAAA;IACzC,4CAAyB,CAAA;AAC7B,CAAC,EAHW,eAAe,+BAAf,eAAe,QAG1B"}

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

@@ -1,3 +1,23 @@
+/**
+ * Outcome of a synchronous gateway charge/refund attempt (ChargeSavedMethod, admin
+ * refund). Distinguishes a real business decline from an ambiguous technical failure
+ * where we cannot tell whether the provider actually processed the money movement.
+ *
+ * ACCEPTED     — gateway confirmed it received and is processing the request.
+ * DECLINED     — gateway responded with a definitive business rejection (e.g. Success:false
+ *                with a reason code). Safe to let the user retry / advance dunning.
+ * REQUIRES_3DS — gateway did not decline the charge; it needs 3-D Secure cardholder
+ *                authentication (Success:false, Model.AcsUrl/PaReq present, NO ReasonCode).
+ *                Not a decline: do not classify it with a DeclineKind or advance dunning
+ *                as if the card failed. A one-click (cardholder-present) caller must send
+ *                the payer through the AcsUrl/PaReq challenge; a merchant-initiated (no
+ *                cardholder present) caller cannot complete 3DS automatically and must stop
+ *                — the payer needs to pay it themselves.
+ * UNKNOWN      — the HTTP call itself failed (network error, timeout, non-2xx status) before
+ *                we could read a definitive gateway decision. The money MAY have moved.
+ *                Callers MUST NOT treat this as a clean decline: no automatic retry charge,
+ *                no new order/widget attempt for the same payment until reconciled.
+ */
 export declare enum ChargeOutcome {
     ACCEPTED = "ACCEPTED",
     DECLINED = "DECLINED",

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

@@ -1,6 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChargeOutcome = void 0;
+/**
+ * Outcome of a synchronous gateway charge/refund attempt (ChargeSavedMethod, admin
+ * refund). Distinguishes a real business decline from an ambiguous technical failure
+ * where we cannot tell whether the provider actually processed the money movement.
+ *
+ * ACCEPTED     — gateway confirmed it received and is processing the request.
+ * DECLINED     — gateway responded with a definitive business rejection (e.g. Success:false
+ *                with a reason code). Safe to let the user retry / advance dunning.
+ * REQUIRES_3DS — gateway did not decline the charge; it needs 3-D Secure cardholder
+ *                authentication (Success:false, Model.AcsUrl/PaReq present, NO ReasonCode).
+ *                Not a decline: do not classify it with a DeclineKind or advance dunning
+ *                as if the card failed. A one-click (cardholder-present) caller must send
+ *                the payer through the AcsUrl/PaReq challenge; a merchant-initiated (no
+ *                cardholder present) caller cannot complete 3DS automatically and must stop
+ *                — the payer needs to pay it themselves.
+ * UNKNOWN      — the HTTP call itself failed (network error, timeout, non-2xx status) before
+ *                we could read a definitive gateway decision. The money MAY have moved.
+ *                Callers MUST NOT treat this as a clean decline: no automatic retry charge,
+ *                no new order/widget attempt for the same payment until reconciled.
+ */
 var ChargeOutcome;
 (function (ChargeOutcome) {
     ChargeOutcome["ACCEPTED"] = "ACCEPTED";

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

@@ -1 +1 @@
-{"version":3,"file":"charge-outcome.enum.js","sourceRoot":"","sources":["../../../../v1/payment/schemas/charge-outcome.enum.ts"],"names":[],"mappings":";;;AAoBA,IAAY,aAKX;AALD,WAAY,aAAa;IACrB,sCAAqB,CAAA;IACrB,sCAAqB,CAAA;IACrB,8CAA6B,CAAA;IAC7B,oCAAmB,CAAA;AACvB,CAAC,EALW,aAAa,6BAAb,aAAa,QAKxB"}
+{"version":3,"file":"charge-outcome.enum.js","sourceRoot":"","sources":["../../../../v1/payment/schemas/charge-outcome.enum.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,IAAY,aAKX;AALD,WAAY,aAAa;IACrB,sCAAqB,CAAA;IACrB,sCAAqB,CAAA;IACrB,8CAA6B,CAAA;IAC7B,oCAAmB,CAAA;AACvB,CAAC,EALW,aAAa,6BAAb,aAAa,QAKxB"}

package/build/v1/payment/schemas/cloudpayments-webhook.schemas.d.ts

@@ -1,15 +1,41 @@
 import { z } from 'zod';
+/**
+ * CloudPayments check response codes (official table — docs.cloudpayments.ru):
+ *  0  — accepted / OK
+ * 10  — неверный номер заказа (order not found or InvoiceId absent)
+ * 11  — некорректный AccountId (present but doesn't match order owner)
+ * 12  — неверная сумма (amount / currency mismatch)
+ * 13  — платёж не может быть принят (order not in PENDING, test mode rejected, etc.)
+ * 20  — платёж просрочен (order expired)
+ *
+ * Single source-of-truth — these constants replace the divergent set in
+ * payment.constants.ts (CLOUDPAYMENTS_CODES) which is deleted.
+ */
 export declare const CLOUDPAYMENTS_CODE_OK: 0;
+/** Order not found or InvoiceId absent/invalid — неверный номер заказа */
 export declare const CLOUDPAYMENTS_CODE_ORDER_NOT_FOUND: 10;
+/** AccountId present but doesn't match order owner — некорректный AccountId */
 export declare const CLOUDPAYMENTS_CODE_INVALID_ACCOUNT: 11;
+/** Amount or currency mismatch — неверная сумма */
 export declare const CLOUDPAYMENTS_CODE_AMOUNT_MISMATCH: 12;
+/** Cannot accept: order non-PENDING, test mode rejected, other terminal reason — платёж не может быть принят */
 export declare const CLOUDPAYMENTS_CODE_CANNOT_ACCEPT: 13;
+/** Order expired — платёж просрочен */
 export declare const CLOUDPAYMENTS_CODE_EXPIRED: 20;
 export type CloudPaymentsCode = typeof CLOUDPAYMENTS_CODE_OK | typeof CLOUDPAYMENTS_CODE_ORDER_NOT_FOUND | typeof CLOUDPAYMENTS_CODE_INVALID_ACCOUNT | typeof CLOUDPAYMENTS_CODE_AMOUNT_MISMATCH | typeof CLOUDPAYMENTS_CODE_CANNOT_ACCEPT | typeof CLOUDPAYMENTS_CODE_EXPIRED;
 export declare const CloudPaymentsResponseSchema: z.ZodObject<{
     code: z.ZodNumber;
 }, z.core.$strip>;
 export type CloudPaymentsResponse = z.infer<typeof CloudPaymentsResponseSchema>;
+/**
+ * CloudPayments `check` webhook payload.
+ * Provider sends this before attempting the charge to validate the order.
+ * Server must respond {code:0} to accept; see code constants above for errors.
+ *
+ * Per CP docs InvoiceId and AccountId are optional (ЛК-initiated ops omit them).
+ * When InvoiceId is absent → respond code 10 (cannot identify order).
+ * When AccountId is present and doesn't match order owner → respond code 11.
+ */
 export declare const CloudPaymentsCheckRequestSchema: z.ZodObject<{
     Description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     PaymentMethod: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -45,6 +71,18 @@ export declare const CloudPaymentsCheckRequestSchema: z.ZodObject<{
     TokenRecipient: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$loose>;
 export type CloudPaymentsCheckRequest = z.infer<typeof CloudPaymentsCheckRequestSchema>;
+/**
+ * CloudPayments `pay` webhook payload.
+ * Sent when payment is confirmed. Server marks Order→PAID, Payment→CONFIRMED.
+ * If Token is present — upsert SavedPaymentMethod for recurrent charges.
+ *
+ * REAL CP card fields (verified against CP docs, 2026-06):
+ *   CardFirstSix  — first 6 digits of card number (string)
+ *   CardLastFour  — last 4 digits (string)
+ *   CardType      — "Visa" / "Mastercard" / "MIR" etc.
+ *   CardExpDate   — expiry in "MM/YY" format (e.g. "12/27")
+ * The legacy CardMask/ExpDateMonth/ExpDateYear fields DO NOT exist in real CP payloads.
+ */
 export declare const CloudPaymentsPayRequestSchema: z.ZodObject<{
     TotalFee: z.ZodOptional<z.ZodNullable<z.ZodCoercedNumber<unknown>>>;
     VatAboveTotalFee: z.ZodOptional<z.ZodNullable<z.ZodCoercedNumber<unknown>>>;
@@ -89,6 +127,11 @@ export declare const CloudPaymentsPayRequestSchema: z.ZodObject<{
     AuthCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$loose>;
 export type CloudPaymentsPayRequest = z.infer<typeof CloudPaymentsPayRequestSchema>;
+/**
+ * CloudPayments `fail` webhook payload.
+ * Sent when payment attempt fails. Payment→DECLINED; Order stays PENDING for retry.
+ * InvoiceId/AccountId optional per CP docs.
+ */
 export declare const CloudPaymentsFailRequestSchema: z.ZodObject<{
     FallBackScenarioDeclinedTransactionId: z.ZodOptional<z.ZodNullable<z.ZodCoercedNumber<unknown>>>;
     Reason: z.ZodOptional<z.ZodString>;
@@ -130,6 +173,15 @@ export declare const CloudPaymentsFailRequestSchema: z.ZodObject<{
     Token: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$loose>;
 export type CloudPaymentsFailRequest = z.infer<typeof CloudPaymentsFailRequestSchema>;
+/**
+ * CloudPayments `refund` webhook payload.
+ * Sent when a confirmed payment is refunded. Full refund → Order→REFUNDED, Payment→REFUNDED.
+ * Partial refund (Amount < order amount) → Payment row recorded; Order stays PAID; manual review log.
+ *
+ * CP docs (2026-06): Currency is NOT sent in refund notifications.
+ * InvoiceId and AccountId are optional in refund notifications.
+ * PaymentTransactionId refers to the original payment transaction.
+ */
 export declare const CloudPaymentsRefundRequestSchema: z.ZodObject<{
     TransactionId: z.ZodCoercedNumber<unknown>;
     InvoiceId: z.ZodOptional<z.ZodString>;