platform-types 1.10.748 → 1.10.749

package/dist/order.d.ts

@@ -1641,24 +1641,21 @@ declare global {
     interface LinkedPaymentEntry {
         source: 'mp' | 'stripe' | 'mp_movement';
         /**
-         * The amount this store CURRENTLY holds for this payment, net of refunds
-         * — **not** the amount originally settled. It is what
+         * The amount this payment counts toward the order. It is what
          * `deriveOrderFinancialAxis` sums, so it has to mean money the order can
          * still count.
          *
-         * ⚠️ It SHRINKS. A partial refund against the payment lowers it to the
-         * un-refunded remainder (`payment total − every refund so far`) and
-         * restates the order's `financialStatus` in the same write; a refund that
-         * exhausts the payment removes the entry from the map outright. It never
-         * grows — no writer on the refund path may raise it — so a reader may
-         * treat it as monotonically non-increasing after the link is created.
-         *
-         * ⚠️ **FORWARD-ONLY, and that is the reading that matters for anything
-         * historical.** Entries written before refunds began shrinking this field
-         * still carry their PRE-REFUND figure, and nothing is backfilled: an order
-         * partially refunded earlier reads as if the store kept the whole payment.
-         * A consumer reconciling against provider refund history will find those
-         * rows disagree, and the disagreement is the back catalogue, not a bug.
+         * ⚠️ **No writer shrinks it on a refund.** A refund or settled chargeback
+         * MercadoPago reports later is detected and recorded on the payment's
+         * status observation, never here: the entry keeps its linked figure until
+         * the operator mirrors the refund by hand (an unlink removes the entry).
+         * Entries on HISTORICAL orders may carry a smaller figure (or be gone):
+         * the removed outbound MercadoPago refund lowered a partially refunded
+         * entry to its un-refunded remainder and removed an exhausted one, and
+         * those rows keep what it wrote. Entries written before that refund
+         * existed carry their pre-refund figure; nothing is backfilled either way,
+         * so a consumer reconciling against provider refund history will find
+         * rows that disagree, and the disagreement is the back catalogue, not a bug.
          *
          * ⚠️ Denominated in `currency` below — the PAYMENT's denomination, not the
          * order's. Never sum this field across entries without converting.

package/dist/payment.d.ts

@@ -35,6 +35,41 @@ declare global {
             source: PaymentReceivedSource;
             paidAt: number;
         };
+        /**
+         * MercadoPago's CUMULATIVE refunded amount for this payment, in its own currency
+         * (`transaction_amount_refunded`, else the sum of `refunds[]` with status
+         * `approved`; never less than the full `amount` on `providerStatus: 'refunded'`). Written by
+         * the payment status service (`mercadopagoPaymentStatus.ts`) on every observation
+         * — the webhook and the poller's re-check alike. Absent means none observed, never
+         * an unknown. Present ⇒ a link refuses the payment (`LINK_LOCKED` `refunded-payment`).
+         */
+        refundedAmount?: number;
+        /**
+         * MercadoPago's `refunds[]` as last observed, same writer: `id` is MercadoPago's
+         * numeric refund id as a string, `amount` in the payment's currency, `status` as
+         * MercadoPago states it (`approved` once the money moved, `in_process` before), and
+         * `at` its `date_created` in epoch ms. Absent when MercadoPago listed none.
+         */
+        refunds?: {
+            id: string;
+            amount: number;
+            status: string;
+            at: number;
+        }[];
+        /**
+         * A dispute on the payment, same writer: present while `providerStatus` is
+         * `charged_back` or `in_mediation`. A later observation that shows neither clears it,
+         * except a SETTLED chargeback, which is kept through a later `approved`. On
+         * `charged_back`, `statusDetail` says what happened to the money: `settled` (taken for
+         * the full amount — reported for the operator to mirror by hand; the books are not
+         * changed), `reimbursed` (MercadoPago covered the seller) or `in_process` (still
+         * open). Any other detail, and a mediation, reads as still open. Present ⇒ a link
+         * refuses the payment.
+         */
+        chargeback?: {
+            status: string;
+            statusDetail?: string;
+        };
     }
     /** GET /payments/pending returns this page inside the standard data envelope. */
     interface MpPaymentObservationPage {

package/package.json

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