platform-types 1.10.759 → 1.10.761

package/dist/cjs/paymentAttempt.js

@@ -19,7 +19,7 @@
  * no operator write can carry it back onto the order.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ORDER_NOT_PAYABLE_REASONS = exports.PAYMENT_ATTEMPT_ERROR_CODES = exports.PAYMENT_ATTEMPT_STATES = void 0;
+exports.PAYMENT_HOLD_MINUTES_DEFAULT = exports.PAYMENT_HOLD_MINUTES_MAX = exports.PAYMENT_HOLD_MINUTES_MIN = exports.PAYMENT_ATTEMPT_RESOLUTION_CAUSES = exports.ORDER_NOT_PAYABLE_REASONS = exports.PAYMENT_ATTEMPT_ERROR_CODES = exports.PAYMENT_ATTEMPT_STATES = void 0;
 /** Every {@link PaymentAttemptState}, in lifecycle order. */
 exports.PAYMENT_ATTEMPT_STATES = [
     'created',
@@ -65,3 +65,33 @@ exports.PAYMENT_ATTEMPT_ERROR_CODES = [
  *   `storefront: 'mp-checkout-pro'`.
  */
 exports.ORDER_NOT_PAYABLE_REASONS = ['cancelled', 'paid', 'not-online'];
+/**
+ * Every reason an attempt lands in `resolution` — money that must not settle
+ * the order on its own:
+ *
+ * - `second-approval` — the checkout already took an approved payment.
+ * - `amount-mismatch` — the payment's amount or currency is not the order's.
+ * - `order-mismatch` — the payment names another order than the attempt's.
+ * - `order-already-paid` — the order was already paid by another route.
+ * - `not-settled` — the payment pipeline recorded the payment without settling
+ *   the order.
+ * - `late-capture` — the payment arrived after the hold ended: the attempt had
+ *   expired or been cancelled, or the order was already cancelled.
+ */
+exports.PAYMENT_ATTEMPT_RESOLUTION_CAUSES = [
+    'second-approval',
+    'amount-mismatch',
+    'order-mismatch',
+    'order-already-paid',
+    'not-settled',
+    'late-capture',
+];
+/**
+ * The bounds of the store's payment hold, `ecommerce.config.paymentHoldMinutes`
+ * — how long a new attempt stays payable, in whole minutes. Both writers refuse
+ * a value outside `[MIN, MAX]` (`400 VALIDATION_FAILED`); the start reads an
+ * absent or out-of-range stored value as `DEFAULT`.
+ */
+exports.PAYMENT_HOLD_MINUTES_MIN = 15;
+exports.PAYMENT_HOLD_MINUTES_MAX = 1440;
+exports.PAYMENT_HOLD_MINUTES_DEFAULT = 60;

package/dist/cjs/socket.js

@@ -525,8 +525,7 @@ exports.SOCKET_ACTIONS = [
      * minimised `OrderPaymentAttemptView`, never the stored attempt.
      *
      * ⚠️ To the order's OWN customer only (`wsPostCustomer`), never a store-wide
-     * customer broadcast. Published ahead of its producer: no api writer emits
-     * it yet.
+     * customer broadcast. Sent once per committed state move of the attempt.
      */
     'orderPaymentAttempt',
     'stripe',

package/dist/payment.d.ts

@@ -136,6 +136,18 @@ declare global {
         externalReference?: string;
         reconciled?: boolean;
         reconcileReason?: string;
+        /**
+         * MercadoPago's own money breakdown, in major units of `currency`: `gross` is
+         * `transaction_amount`, `net` is `transaction_details.net_received_amount`
+         * (what the store received), and `fee` is what MercadoPago kept
+         * (`gross − net`; the collector-paid `fee_details` when MercadoPago states no
+         * net). Each is present only when MercadoPago reported it, on MercadoPago
+         * payments recorded since these fields existed. Absent means "not recorded",
+         * never zero; a `fee` of `0` is a fee-free payment.
+         */
+        gross?: number;
+        fee?: number;
+        net?: number;
     }
     /**
      * Confidence tier for a link suggestion.

package/dist/paymentAttempt.d.ts

@@ -28,10 +28,15 @@ declare global {
      * - `rejected` — the last payment was rejected. ⚠️ NOT terminal: Checkout Pro
      *   lets the shopper retry inside the same checkout until `expiresAt`, so a
      *   later payment can move it to `pending` or `approved`.
-     * - `expired` — `expiresAt` passed with nothing approved; the order is
-     *   cancelled (`Order.cancellationSource: 'system'`).
+     * - `expired` — `expiresAt` passed with nothing approved through this
+     *   attempt. The order is cancelled (`Order.cancellationSource: 'system'`)
+     *   unless money had already reached it by another route; then the order is
+     *   left as it is and the attempt stays `expired` — not `resolution`, since
+     *   that money is not this attempt's.
      * - `cancelled` — the order was cancelled while the attempt was live.
-     * - `refunded` — the approved payment was refunded.
+     * - `refunded` — the approved payment was refunded. Only from `approved`: a
+     *   refund on a `resolution` attempt is the operator's resolution work and
+     *   leaves it `resolution`.
      * - `charged_back` — the approved payment was charged back.
      * - `resolution` — money landed that must NOT settle the order: an approval
      *   on an order already paid, on an expired or cancelled order, or for an
@@ -44,6 +49,8 @@ declare global {
     type PaymentAttemptErrorCode = (typeof PAYMENT_ATTEMPT_ERROR_CODES)[number];
     /** One of {@link ORDER_NOT_PAYABLE_REASONS}. */
     type OrderNotPayableReason = (typeof ORDER_NOT_PAYABLE_REASONS)[number];
+    /** One of {@link PAYMENT_ATTEMPT_RESOLUTION_CAUSES}. */
+    type PaymentAttemptResolutionCause = (typeof PAYMENT_ATTEMPT_RESOLUTION_CAUSES)[number];
     /**
      * The body that starts (or returns the live) payment attempt for an order.
      * The caller must be the order's customer; the store is the token's. The
@@ -90,6 +97,43 @@ declare global {
         orderId: string;
         paymentAttempt: OrderPaymentAttemptView;
     }
+    /**
+     * One payment attempt as the store's operators see it — the operator fields
+     * of the stored record, never its Mercado Pago checkout URL or Preference id.
+     */
+    interface PaymentAttemptOperatorView {
+        attemptId: string;
+        orderId: string;
+        /** The order's owner, who started the attempt. */
+        customerId: string;
+        state: PaymentAttemptState;
+        /** Why the attempt is in `resolution` — set by the move into it. */
+        resolutionCause?: PaymentAttemptResolutionCause;
+        /** The Mercado Pago payments whose approval this attempt processed, oldest first. */
+        approvedPaymentIds: string[];
+        /** The Mercado Pago payment whose notification made the last move. */
+        lastPaymentId?: string;
+        /** Decimal pesos — the order's charged total when the attempt was started. */
+        amount: number;
+        currency: 'ARS';
+        /** ISO 8601 — when the checkout stopped taking a payment. */
+        expiresAt: string;
+        /** Unix ms. */
+        createdAt: number;
+        /** Unix ms. */
+        updatedAt: number;
+    }
+    /**
+     * `data` of `GET /payments/attempts?state=resolution` (App host, admin):
+     * the store's attempts in that state, newest activity first. Page on
+     * `nextCursor`'s presence, never on the page's length — the state is a
+     * filter, so a page can be short, even empty, with more to come.
+     */
+    interface PaymentAttemptResolutionListResponse {
+        attempts: PaymentAttemptOperatorView[];
+        /** Opaque. Absent on the last page. */
+        nextCursor?: string;
+    }
 }
 /** Every {@link PaymentAttemptState}, in lifecycle order. */
 export declare const PAYMENT_ATTEMPT_STATES: readonly ["created", "pending", "approved", "rejected", "expired", "cancelled", "refunded", "charged_back", "resolution"];
@@ -119,4 +163,27 @@ export declare const PAYMENT_ATTEMPT_ERROR_CODES: readonly ["PAYMENT_PROVIDER_NO
  *   `storefront: 'mp-checkout-pro'`.
  */
 export declare const ORDER_NOT_PAYABLE_REASONS: readonly ["cancelled", "paid", "not-online"];
+/**
+ * Every reason an attempt lands in `resolution` — money that must not settle
+ * the order on its own:
+ *
+ * - `second-approval` — the checkout already took an approved payment.
+ * - `amount-mismatch` — the payment's amount or currency is not the order's.
+ * - `order-mismatch` — the payment names another order than the attempt's.
+ * - `order-already-paid` — the order was already paid by another route.
+ * - `not-settled` — the payment pipeline recorded the payment without settling
+ *   the order.
+ * - `late-capture` — the payment arrived after the hold ended: the attempt had
+ *   expired or been cancelled, or the order was already cancelled.
+ */
+export declare const PAYMENT_ATTEMPT_RESOLUTION_CAUSES: readonly ["second-approval", "amount-mismatch", "order-mismatch", "order-already-paid", "not-settled", "late-capture"];
+/**
+ * The bounds of the store's payment hold, `ecommerce.config.paymentHoldMinutes`
+ * — how long a new attempt stays payable, in whole minutes. Both writers refuse
+ * a value outside `[MIN, MAX]` (`400 VALIDATION_FAILED`); the start reads an
+ * absent or out-of-range stored value as `DEFAULT`.
+ */
+export declare const PAYMENT_HOLD_MINUTES_MIN = 15;
+export declare const PAYMENT_HOLD_MINUTES_MAX = 1440;
+export declare const PAYMENT_HOLD_MINUTES_DEFAULT = 60;
 export {};

package/dist/paymentAttempt.js

@@ -62,3 +62,33 @@ export const PAYMENT_ATTEMPT_ERROR_CODES = [
  *   `storefront: 'mp-checkout-pro'`.
  */
 export const ORDER_NOT_PAYABLE_REASONS = ['cancelled', 'paid', 'not-online'];
+/**
+ * Every reason an attempt lands in `resolution` — money that must not settle
+ * the order on its own:
+ *
+ * - `second-approval` — the checkout already took an approved payment.
+ * - `amount-mismatch` — the payment's amount or currency is not the order's.
+ * - `order-mismatch` — the payment names another order than the attempt's.
+ * - `order-already-paid` — the order was already paid by another route.
+ * - `not-settled` — the payment pipeline recorded the payment without settling
+ *   the order.
+ * - `late-capture` — the payment arrived after the hold ended: the attempt had
+ *   expired or been cancelled, or the order was already cancelled.
+ */
+export const PAYMENT_ATTEMPT_RESOLUTION_CAUSES = [
+    'second-approval',
+    'amount-mismatch',
+    'order-mismatch',
+    'order-already-paid',
+    'not-settled',
+    'late-capture',
+];
+/**
+ * The bounds of the store's payment hold, `ecommerce.config.paymentHoldMinutes`
+ * — how long a new attempt stays payable, in whole minutes. Both writers refuse
+ * a value outside `[MIN, MAX]` (`400 VALIDATION_FAILED`); the start reads an
+ * absent or out-of-range stored value as `DEFAULT`.
+ */
+export const PAYMENT_HOLD_MINUTES_MIN = 15;
+export const PAYMENT_HOLD_MINUTES_MAX = 1440;
+export const PAYMENT_HOLD_MINUTES_DEFAULT = 60;

package/dist/socket.js

@@ -522,8 +522,7 @@ export const SOCKET_ACTIONS = [
      * minimised `OrderPaymentAttemptView`, never the stored attempt.
      *
      * ⚠️ To the order's OWN customer only (`wsPostCustomer`), never a store-wide
-     * customer broadcast. Published ahead of its producer: no api writer emits
-     * it yet.
+     * customer broadcast. Sent once per committed state move of the attempt.
      */
     'orderPaymentAttempt',
     'stripe',

package/dist/store.d.ts

@@ -146,6 +146,18 @@ declare global {
              * frame), so the storefront can say the account needs approval.
              */
             registrationMode?: 'open' | 'approval';
+            /**
+             * How long a storefront online payment holds the order, in whole
+             * minutes: the payment attempt's `expiresAt` and its Checkout Pro
+             * Preference's `expiration_date_to` are this far from the start.
+             * An integer from `PAYMENT_HOLD_MINUTES_MIN` (15) to
+             * `PAYMENT_HOLD_MINUTES_MAX` (1440); absent means
+             * `PAYMENT_HOLD_MINUTES_DEFAULT` (60), and so does a stored value
+             * outside that range. Written by `PATCH /store` (ADMIN) and
+             * `PUT /platform/stores/{storeId}` (MANAGER). Never sent to shoppers:
+             * they see the attempt's `expiresAt` instead.
+             */
+            paymentHoldMinutes?: number;
             showStocks?: boolean;
         };
         sidebar?: {
@@ -188,7 +200,7 @@ declare global {
      * data: { field: 'ecommerce.config.newCustomerPriceList', value: number }; nothing written.
      */
     interface EcommercePatchInput {
-        config?: Pick<NonNullable<Ecommerce['config']>, 'showDefaultPriceList' | 'newCustomerPriceList' | 'registrationMode'> & StorefrontLiveSettingsPatch;
+        config?: Pick<NonNullable<Ecommerce['config']>, 'showDefaultPriceList' | 'newCustomerPriceList' | 'registrationMode' | 'paymentHoldMinutes'> & StorefrontLiveSettingsPatch;
         sidebar?: Ecommerce['sidebar'];
         home?: Omit<NonNullable<Ecommerce['home']>, 'displayOrders' | 'displayProfile'>;
         themeColors?: Ecommerce['themeColors'];

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "platform-types",
-	"version": "1.10.759",
+	"version": "1.10.761",
 	"description": "Shared wire and entity contracts for the platform.",
 	"type": "module",
 	"main": "dist/index.js",