@fiado/type-kit 3.450.0 → 3.452.0

package/_test_/unit/transaction/DisputeRefundEnums.test.ts

@@ -0,0 +1,35 @@
+import 'reflect-metadata';
+import { DisputeRefundType, DisputeRefundStatus } from '../../../src/transaction';
+
+describe('DisputeRefundType', () => {
+  it('expone REFUND, REVERSAL', () => {
+    expect(DisputeRefundType.REFUND).toBe('REFUND');
+    expect(DisputeRefundType.REVERSAL).toBe('REVERSAL');
+  });
+
+  it('no tiene valores de más', () => {
+    expect(Object.values(DisputeRefundType).sort()).toEqual(['REFUND', 'REVERSAL'].sort());
+  });
+});
+
+describe('DisputeRefundStatus', () => {
+  const expected = [
+    'PENDING_AUTHORIZATION',
+    'PENDING_MANUAL_EXECUTION',
+    'EXECUTED',
+    'FAILED',
+    'CANCELLED',
+  ];
+
+  it('expone los 5 estados del ciclo de vida', () => {
+    expect(DisputeRefundStatus.PENDING_AUTHORIZATION).toBe('PENDING_AUTHORIZATION');
+    expect(DisputeRefundStatus.PENDING_MANUAL_EXECUTION).toBe('PENDING_MANUAL_EXECUTION');
+    expect(DisputeRefundStatus.EXECUTED).toBe('EXECUTED');
+    expect(DisputeRefundStatus.FAILED).toBe('FAILED');
+    expect(DisputeRefundStatus.CANCELLED).toBe('CANCELLED');
+  });
+
+  it('no tiene valores de más', () => {
+    expect(Object.values(DisputeRefundStatus).sort()).toEqual(expected.sort());
+  });
+});

package/bin/remittance/dtos/RemittanceBackofficeTransaction.d.ts

@@ -1,10 +1,17 @@
 import { RemittanceTxStatus } from "../enums/RemittanceTxStatus";
 import { RemittanceCancelStageEnum } from "../enums/RemittanceCancelStageEnum";
 import { RemittanceCancelOutcomeEnum } from "../enums/RemittanceCancelOutcomeEnum";
+import { RemittanceReconStatus } from "../enums/RemittanceReconStatus";
 /**
  * Vista operativa COMPLETA de una tx para el backoffice (F9): incluye campos
  * de trazabilidad (previewRef, idempotencyKey, marketplaceTransactionNumber
  * para correlación con el procesador) que el DTO de usuario no expone.
+ *
+ * A partir de Fase B de Uniteller también incluye los campos de enrichment
+ * poblados por el pipeline SUTWEB38 (unitellerCostTicket, netMarginUsd,
+ * reconStatus, etc.) — todos opcionales, filas creadas antes de la
+ * implementación no los tienen. Ver `RemittanceReconciliationFields` para
+ * el shape canónico.
  */
 export declare class RemittanceBackofficeTransaction {
     directoryId: string;
@@ -68,4 +75,24 @@ export declare class RemittanceBackofficeTransaction {
     updatedAt: string;
     createdBy?: string;
     updatedBy?: string;
+    /** Processing Fee (costo per-tx) reportado por Uniteller en TxDetails. */
+    unitellerCostTicket?: number;
+    /** Fx Gain reportado por Uniteller (para reconciliar contra cálculo local). */
+    unitellerFxGainReported?: number;
+    /** Liquidation Rate real que Uniteller aplicó (wholesale efectivo). */
+    liquidationRateReported?: number;
+    /** Retail Rate que Uniteller cobró al cliente. */
+    retailRateReported?: number;
+    /** serviceFee + fxGainUsdLocal − unitellerCostTicket. Redondeo 2 decimales. */
+    netMarginUsd?: number;
+    /** YYYY-MM-DD del reporte SUTWEB38 que pobló los campos anteriores. */
+    providerStatementDate?: string;
+    /** S3 key del CSV que pobló los campos (trazabilidad + idempotencia). */
+    providerStatementSourceKey?: string;
+    /** ISO UTC del enrichment. */
+    providerStatementAppliedAt?: string;
+    /** Estado de reconciliación calculado por AssertionEngine. */
+    reconStatus?: RemittanceReconStatus;
+    /** Detalle textual de los diffs cuando reconStatus !== OK. */
+    reconDiffDetail?: string;
 }

package/bin/remittance/dtos/RemittanceBackofficeTransaction.js

@@ -5,6 +5,12 @@ exports.RemittanceBackofficeTransaction = void 0;
  * Vista operativa COMPLETA de una tx para el backoffice (F9): incluye campos
  * de trazabilidad (previewRef, idempotencyKey, marketplaceTransactionNumber
  * para correlación con el procesador) que el DTO de usuario no expone.
+ *
+ * A partir de Fase B de Uniteller también incluye los campos de enrichment
+ * poblados por el pipeline SUTWEB38 (unitellerCostTicket, netMarginUsd,
+ * reconStatus, etc.) — todos opcionales, filas creadas antes de la
+ * implementación no los tienen. Ver `RemittanceReconciliationFields` para
+ * el shape canónico.
  */
 class RemittanceBackofficeTransaction {
 }

package/bin/remittance/dtos/RemittanceReconciliation.d.ts

@@ -0,0 +1,61 @@
+import { RemittanceReconStatus } from "../enums/RemittanceReconStatus";
+/**
+ * Campos de enrichment poblados en una tx local por el pipeline de ingesta
+ * SUTWEB38 del uniteller-connector, cuando aterriza el archivo TxDetails del
+ * día y matchea la tx por `txIdentifier === txNumber`. Todos son opcionales
+ * — filas de tx creadas antes de la implementación de Fase B no los tienen.
+ *
+ * Se comparte como interface (no class) para que otros DTOs (por ejemplo
+ * `RemittanceBackofficeTransaction`) la extiendan o intersecten sin duplicar
+ * definiciones.
+ *
+ * Ver spec Cap 4.2.
+ */
+export interface RemittanceReconciliationFields {
+    /**
+     * Processing Fee reportado por Uniteller en la fila TxDetails del SUTWEB38.
+     * Es el costo per-tx que Uniteller cobra a Fiado (consolida "UNITELLER
+     * processing Cost" + "Payer Cost" del Exhibit A del contrato firmado).
+     */
+    unitellerCostTicket?: number;
+    /**
+     * Fx Gain reportado por Uniteller en la fila TxDetails. Se usa para
+     * reconciliar contra el cálculo local `amountUSD × markupBps / 10000`.
+     * Diff sistemática apunta a redondeo o a que Uniteller aplicó un rate
+     * distinto al instruido.
+     */
+    unitellerFxGainReported?: number;
+    /**
+     * Liquidation Rate reportado por Uniteller (rate wholesale efectivamente
+     * aplicado). Se compara contra el `wholesaleRate` snapshot local para
+     * detectar drift silencioso de FX.
+     */
+    liquidationRateReported?: number;
+    /** Retail Rate reportado por Uniteller (rate que cobró al cliente). */
+    retailRateReported?: number;
+    /**
+     * Margen neto USD por transacción calculado como:
+     *     serviceFee + (amountUSD × markupBps / 10000) − unitellerCostTicket
+     * Redondeado a 2 decimales.
+     */
+    netMarginUsd?: number;
+    /**
+     * Fecha del reporte SUTWEB38 (YYYY-MM-DD) que pobló los campos anteriores.
+     * Derivada del filename `SUTWEBXX_TxDetails_MMDDYYYY_MMDDYYYY.csv`.
+     */
+    providerStatementDate?: string;
+    /**
+     * S3 key del archivo CSV que pobló los campos (para trazabilidad
+     * regulatoria y para la idempotencia por conditional write DDB).
+     */
+    providerStatementSourceKey?: string;
+    /** ISO UTC del momento en que se aplicó el enrichment. */
+    providerStatementAppliedAt?: string;
+    /** Estado de reconciliación calculado por AssertionEngine. */
+    reconStatus?: RemittanceReconStatus;
+    /**
+     * Descripción textual concatenada de los diffs encontrados (ej.
+     * "amountUSD 150 vs stmt 151; fx local 0.585 vs stmt 2.0").
+     */
+    reconDiffDetail?: string;
+}

package/bin/remittance/dtos/RemittanceReconciliation.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/bin/remittance/dtos/index.d.ts

@@ -31,6 +31,7 @@ export * from "./RemittanceSmsRequest";
 export * from "./RemittanceBackofficeUserView";
 export * from "./RemittanceBackofficeDashboardSummary";
 export * from "./RemittanceBackofficeTransaction";
+export * from "./RemittanceReconciliation";
 export * from "./RemittanceBackofficeUserDetail";
 export * from "./RemittanceBackofficeUserListResponse";
 export * from "./RemittanceBackofficeTxListResponse";

package/bin/remittance/dtos/index.js

@@ -47,6 +47,7 @@ __exportStar(require("./RemittanceSmsRequest"), exports);
 __exportStar(require("./RemittanceBackofficeUserView"), exports);
 __exportStar(require("./RemittanceBackofficeDashboardSummary"), exports);
 __exportStar(require("./RemittanceBackofficeTransaction"), exports);
+__exportStar(require("./RemittanceReconciliation"), exports);
 __exportStar(require("./RemittanceBackofficeUserDetail"), exports);
 __exportStar(require("./RemittanceBackofficeUserListResponse"), exports);
 __exportStar(require("./RemittanceBackofficeTxListResponse"), exports);

package/bin/remittance/enums/RemittanceReconStatus.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Estado de reconciliación de una tx local contra el reporte SUTWEB38 diario
+ * de Uniteller. Poblado por AssertionEngine del uniteller-connector al ingerir
+ * el archivo TxDetails. Ver spec de reconciliación Cap 6 (motor de aserciones).
+ *
+ * Prioridad si múltiples diffs: DIFF_COST > DIFF_FX > DIFF_RATE > DIFF_AMOUNT > OK.
+ */
+export declare enum RemittanceReconStatus {
+    OK = "OK",
+    DIFF_FX = "DIFF_FX",
+    DIFF_COST = "DIFF_COST",
+    DIFF_RATE = "DIFF_RATE",
+    DIFF_AMOUNT = "DIFF_AMOUNT",
+    MISSING_IN_PROVIDER = "MISSING_IN_PROVIDER"
+}

package/bin/remittance/enums/RemittanceReconStatus.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RemittanceReconStatus = void 0;
+/**
+ * Estado de reconciliación de una tx local contra el reporte SUTWEB38 diario
+ * de Uniteller. Poblado por AssertionEngine del uniteller-connector al ingerir
+ * el archivo TxDetails. Ver spec de reconciliación Cap 6 (motor de aserciones).
+ *
+ * Prioridad si múltiples diffs: DIFF_COST > DIFF_FX > DIFF_RATE > DIFF_AMOUNT > OK.
+ */
+var RemittanceReconStatus;
+(function (RemittanceReconStatus) {
+    RemittanceReconStatus["OK"] = "OK";
+    RemittanceReconStatus["DIFF_FX"] = "DIFF_FX";
+    RemittanceReconStatus["DIFF_COST"] = "DIFF_COST";
+    RemittanceReconStatus["DIFF_RATE"] = "DIFF_RATE";
+    RemittanceReconStatus["DIFF_AMOUNT"] = "DIFF_AMOUNT";
+    RemittanceReconStatus["MISSING_IN_PROVIDER"] = "MISSING_IN_PROVIDER";
+})(RemittanceReconStatus || (exports.RemittanceReconStatus = RemittanceReconStatus = {}));

package/bin/remittance/enums/index.d.ts

@@ -25,3 +25,4 @@ export * from "./RuleActionType";
 export * from "./AuditResult";
 export * from "./RemittanceExceptionCode";
 export * from "./RemittanceFieldBelongsTo";
+export * from "./RemittanceReconStatus";

package/bin/remittance/enums/index.js

@@ -41,3 +41,4 @@ __exportStar(require("./RuleActionType"), exports);
 __exportStar(require("./AuditResult"), exports);
 __exportStar(require("./RemittanceExceptionCode"), exports);
 __exportStar(require("./RemittanceFieldBelongsTo"), exports);
+__exportStar(require("./RemittanceReconStatus"), exports);

package/bin/transaction/dtos/DisputeRefundRecord.d.ts

@@ -0,0 +1,68 @@
+import { RefundChannelEnum } from '../enums/RefundChannelEnum';
+import { DisputeRefundType } from '../enums/DisputeRefundType';
+import { DisputeRefundStatus } from '../enums/DisputeRefundStatus';
+/**
+ * Registro canónico de un movimiento de dinero (REFUND o REVERSAL) ligado a
+ * un folio R27 de reclamación. Es el shape 1:1 de una fila de la tabla DDB
+ * `DisputeRefund_GT`.
+ *
+ * Modelo:
+ *   - Un folio R27 puede tener 0, 1 o 2 filas en DisputeRefund_GT.
+ *   - 1 fila `type=REFUND` cuando el reintegro se ejecutó.
+ *   - 2 filas (REFUND + REVERSAL) cuando el reintegro fue revertido por
+ *     dictamen tardío que confirmó 2FA original (Circular 12/2018
+ *     Disposición 35.a Banxico).
+ *   - `folioEventId` apunta al evento R27 específico (no solo al folio)
+ *     para preservar el ligado inmutable cuando un folio reingresa (103)
+ *     tras un dictamen no procedente.
+ *   - `relatedRefundId` solo aplica cuando `type=REVERSAL` — apunta al `id`
+ *     del REFUND que se está revirtiendo.
+ *   - `txId` es `null` durante `PENDING_AUTHORIZATION`; se popula al crear
+ *     la tx en el ledger (`PagoConfiadoTx_GT`).
+ */
+export interface DisputeRefundRecord {
+    id: string;
+    folioId: string;
+    folioEventId: string;
+    type: DisputeRefundType;
+    channel: RefundChannelEnum;
+    status: DisputeRefundStatus;
+    relatedRefundId: string | null;
+    txId: string | null;
+    amount: number;
+    currencyId: 'MXN';
+    caseFolio: string;
+    targetDirectoryId: string;
+    manualExecution: DisputeRefundManualExecution | null;
+    approval: DisputeRefundApproval;
+    reason: string | null;
+    createdAt: number;
+    updatedAt: number;
+    failureReason: string | null;
+}
+/**
+ * Metadatos específicos del canal SPEI_OUT_MANUAL. `null` cuando el canal es
+ * INTERNAL_PCF (transferencia intra-wallet sin salida SPEI).
+ */
+export interface DisputeRefundManualExecution {
+    targetClabe: string | null;
+    targetBankId: string | null;
+    targetName: string | null;
+    instructionS3Key: string | null;
+    confirmedTrackingKey: string | null;
+    confirmedAt: number | null;
+    confirmedByUserId: string | null;
+}
+/**
+ * Cadena de aprobación heredada de Política SP1 §10:
+ *   L1 ($5,000 MXN) → requiere checker.
+ *   L2 ($50,000 MXN) → requiere checker + minuta firmada.
+ * `pldOverrideMinuteS3Key` cubre el caso en que el titular está en lista
+ * negra PLD y el reintegro procede solo con acta de comité.
+ */
+export interface DisputeRefundApproval {
+    makerUserId: string;
+    checkerUserId: string | null;
+    minuteS3Key: string | null;
+    pldOverrideMinuteS3Key: string | null;
+}

package/bin/transaction/dtos/DisputeRefundRecord.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/bin/transaction/enums/DisputeRefundStatus.d.ts

@@ -0,0 +1,7 @@
+export declare enum DisputeRefundStatus {
+    PENDING_AUTHORIZATION = "PENDING_AUTHORIZATION",
+    PENDING_MANUAL_EXECUTION = "PENDING_MANUAL_EXECUTION",
+    EXECUTED = "EXECUTED",
+    FAILED = "FAILED",
+    CANCELLED = "CANCELLED"
+}

package/bin/transaction/enums/DisputeRefundStatus.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DisputeRefundStatus = void 0;
+var DisputeRefundStatus;
+(function (DisputeRefundStatus) {
+    DisputeRefundStatus["PENDING_AUTHORIZATION"] = "PENDING_AUTHORIZATION";
+    DisputeRefundStatus["PENDING_MANUAL_EXECUTION"] = "PENDING_MANUAL_EXECUTION";
+    DisputeRefundStatus["EXECUTED"] = "EXECUTED";
+    DisputeRefundStatus["FAILED"] = "FAILED";
+    DisputeRefundStatus["CANCELLED"] = "CANCELLED";
+})(DisputeRefundStatus || (exports.DisputeRefundStatus = DisputeRefundStatus = {}));

package/bin/transaction/enums/DisputeRefundType.d.ts

@@ -0,0 +1,4 @@
+export declare enum DisputeRefundType {
+    REFUND = "REFUND",
+    REVERSAL = "REVERSAL"
+}

package/bin/transaction/enums/DisputeRefundType.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DisputeRefundType = void 0;
+var DisputeRefundType;
+(function (DisputeRefundType) {
+    DisputeRefundType["REFUND"] = "REFUND";
+    DisputeRefundType["REVERSAL"] = "REVERSAL";
+})(DisputeRefundType || (exports.DisputeRefundType = DisputeRefundType = {}));

package/bin/transaction/enums/RefundManualExecutionStatus.d.ts

@@ -1,3 +1,9 @@
+/**
+ * @deprecated Use `DisputeRefundStatus` en su lugar. Este enum tiene scope
+ * estrecho (solo canal SPEI_OUT_MANUAL, sin estados de autorización previa,
+ * sin failure state) y se retira junto con la tabla `RefundManualExecution_GT`
+ * en el cleanup que sigue a la migración de código a `DisputeRefund_GT`.
+ */
 export declare enum RefundManualExecutionStatus {
     PENDING_MANUAL_EXECUTION = "PENDING_MANUAL_EXECUTION",
     EXECUTED = "EXECUTED",

package/bin/transaction/enums/RefundManualExecutionStatus.js

@@ -1,6 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RefundManualExecutionStatus = void 0;
+/**
+ * @deprecated Use `DisputeRefundStatus` en su lugar. Este enum tiene scope
+ * estrecho (solo canal SPEI_OUT_MANUAL, sin estados de autorización previa,
+ * sin failure state) y se retira junto con la tabla `RefundManualExecution_GT`
+ * en el cleanup que sigue a la migración de código a `DisputeRefund_GT`.
+ */
 var RefundManualExecutionStatus;
 (function (RefundManualExecutionStatus) {
     RefundManualExecutionStatus["PENDING_MANUAL_EXECUTION"] = "PENDING_MANUAL_EXECUTION";

package/bin/transaction/index.d.ts

@@ -17,6 +17,7 @@ export * from './dtos/ActivityProblemGetResponse';
 export * from './dtos/AuthorizeRefundRequest';
 export * from './dtos/ReverseRefundRequest';
 export * from './dtos/ConfirmManualExecutionRequest';
+export * from './dtos/DisputeRefundRecord';
 export * from './dtos/internal/BaseProviderTransaction';
 export * from './dtos/internal/BaseProviderTransactionQueryParams';
 export * from './dtos/internal/CentralPaymentsQueryParams';
@@ -39,3 +40,5 @@ export * from './enums/ActivityProblemStatusEnum';
 export * from './enums/RefundChannelEnum';
 export * from './enums/RefundPathTypeEnum';
 export * from './enums/RefundManualExecutionStatus';
+export * from './enums/DisputeRefundType';
+export * from './enums/DisputeRefundStatus';

package/bin/transaction/index.js

@@ -34,6 +34,7 @@ __exportStar(require("./dtos/ActivityProblemGetResponse"), exports);
 __exportStar(require("./dtos/AuthorizeRefundRequest"), exports);
 __exportStar(require("./dtos/ReverseRefundRequest"), exports);
 __exportStar(require("./dtos/ConfirmManualExecutionRequest"), exports);
+__exportStar(require("./dtos/DisputeRefundRecord"), exports);
 __exportStar(require("./dtos/internal/BaseProviderTransaction"), exports);
 __exportStar(require("./dtos/internal/BaseProviderTransactionQueryParams"), exports);
 __exportStar(require("./dtos/internal/CentralPaymentsQueryParams"), exports);
@@ -57,3 +58,5 @@ __exportStar(require("./enums/ActivityProblemStatusEnum"), exports);
 __exportStar(require("./enums/RefundChannelEnum"), exports);
 __exportStar(require("./enums/RefundPathTypeEnum"), exports);
 __exportStar(require("./enums/RefundManualExecutionStatus"), exports);
+__exportStar(require("./enums/DisputeRefundType"), exports);
+__exportStar(require("./enums/DisputeRefundStatus"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiado/type-kit",
-  "version": "3.450.0",
+  "version": "3.452.0",
   "description": "",
   "main": "bin/index.js",
   "types": "bin/index.d.ts",

package/src/remittance/dtos/RemittanceBackofficeTransaction.ts

@@ -1,11 +1,18 @@
 import { RemittanceTxStatus } from "../enums/RemittanceTxStatus";
 import { RemittanceCancelStageEnum } from "../enums/RemittanceCancelStageEnum";
 import { RemittanceCancelOutcomeEnum } from "../enums/RemittanceCancelOutcomeEnum";
+import { RemittanceReconStatus } from "../enums/RemittanceReconStatus";
 
 /**
  * Vista operativa COMPLETA de una tx para el backoffice (F9): incluye campos
  * de trazabilidad (previewRef, idempotencyKey, marketplaceTransactionNumber
  * para correlación con el procesador) que el DTO de usuario no expone.
+ *
+ * A partir de Fase B de Uniteller también incluye los campos de enrichment
+ * poblados por el pipeline SUTWEB38 (unitellerCostTicket, netMarginUsd,
+ * reconStatus, etc.) — todos opcionales, filas creadas antes de la
+ * implementación no los tienen. Ver `RemittanceReconciliationFields` para
+ * el shape canónico.
  */
 export class RemittanceBackofficeTransaction {
     directoryId!: string;
@@ -69,4 +76,30 @@ export class RemittanceBackofficeTransaction {
     updatedAt!: string;
     createdBy?: string;
     updatedBy?: string;
+
+    // ─── Enrichment SUTWEB38 (Fase B Uniteller) ─────────────────────────
+    // Poblados por Sutweb38FilePipeline en uniteller-connector al aterrizar
+    // el archivo TxDetails del día que matchea txNumber. Ver
+    // RemittanceReconciliationFields para docs por campo.
+
+    /** Processing Fee (costo per-tx) reportado por Uniteller en TxDetails. */
+    unitellerCostTicket?: number;
+    /** Fx Gain reportado por Uniteller (para reconciliar contra cálculo local). */
+    unitellerFxGainReported?: number;
+    /** Liquidation Rate real que Uniteller aplicó (wholesale efectivo). */
+    liquidationRateReported?: number;
+    /** Retail Rate que Uniteller cobró al cliente. */
+    retailRateReported?: number;
+    /** serviceFee + fxGainUsdLocal − unitellerCostTicket. Redondeo 2 decimales. */
+    netMarginUsd?: number;
+    /** YYYY-MM-DD del reporte SUTWEB38 que pobló los campos anteriores. */
+    providerStatementDate?: string;
+    /** S3 key del CSV que pobló los campos (trazabilidad + idempotencia). */
+    providerStatementSourceKey?: string;
+    /** ISO UTC del enrichment. */
+    providerStatementAppliedAt?: string;
+    /** Estado de reconciliación calculado por AssertionEngine. */
+    reconStatus?: RemittanceReconStatus;
+    /** Detalle textual de los diffs cuando reconStatus !== OK. */
+    reconDiffDetail?: string;
 }

package/src/remittance/dtos/RemittanceReconciliation.ts

@@ -0,0 +1,71 @@
+import { RemittanceReconStatus } from "../enums/RemittanceReconStatus";
+
+/**
+ * Campos de enrichment poblados en una tx local por el pipeline de ingesta
+ * SUTWEB38 del uniteller-connector, cuando aterriza el archivo TxDetails del
+ * día y matchea la tx por `txIdentifier === txNumber`. Todos son opcionales
+ * — filas de tx creadas antes de la implementación de Fase B no los tienen.
+ *
+ * Se comparte como interface (no class) para que otros DTOs (por ejemplo
+ * `RemittanceBackofficeTransaction`) la extiendan o intersecten sin duplicar
+ * definiciones.
+ *
+ * Ver spec Cap 4.2.
+ */
+export interface RemittanceReconciliationFields {
+    /**
+     * Processing Fee reportado por Uniteller en la fila TxDetails del SUTWEB38.
+     * Es el costo per-tx que Uniteller cobra a Fiado (consolida "UNITELLER
+     * processing Cost" + "Payer Cost" del Exhibit A del contrato firmado).
+     */
+    unitellerCostTicket?: number;
+
+    /**
+     * Fx Gain reportado por Uniteller en la fila TxDetails. Se usa para
+     * reconciliar contra el cálculo local `amountUSD × markupBps / 10000`.
+     * Diff sistemática apunta a redondeo o a que Uniteller aplicó un rate
+     * distinto al instruido.
+     */
+    unitellerFxGainReported?: number;
+
+    /**
+     * Liquidation Rate reportado por Uniteller (rate wholesale efectivamente
+     * aplicado). Se compara contra el `wholesaleRate` snapshot local para
+     * detectar drift silencioso de FX.
+     */
+    liquidationRateReported?: number;
+
+    /** Retail Rate reportado por Uniteller (rate que cobró al cliente). */
+    retailRateReported?: number;
+
+    /**
+     * Margen neto USD por transacción calculado como:
+     *     serviceFee + (amountUSD × markupBps / 10000) − unitellerCostTicket
+     * Redondeado a 2 decimales.
+     */
+    netMarginUsd?: number;
+
+    /**
+     * Fecha del reporte SUTWEB38 (YYYY-MM-DD) que pobló los campos anteriores.
+     * Derivada del filename `SUTWEBXX_TxDetails_MMDDYYYY_MMDDYYYY.csv`.
+     */
+    providerStatementDate?: string;
+
+    /**
+     * S3 key del archivo CSV que pobló los campos (para trazabilidad
+     * regulatoria y para la idempotencia por conditional write DDB).
+     */
+    providerStatementSourceKey?: string;
+
+    /** ISO UTC del momento en que se aplicó el enrichment. */
+    providerStatementAppliedAt?: string;
+
+    /** Estado de reconciliación calculado por AssertionEngine. */
+    reconStatus?: RemittanceReconStatus;
+
+    /**
+     * Descripción textual concatenada de los diffs encontrados (ej.
+     * "amountUSD 150 vs stmt 151; fx local 0.585 vs stmt 2.0").
+     */
+    reconDiffDetail?: string;
+}

package/src/remittance/dtos/index.ts

@@ -31,6 +31,7 @@ export * from "./RemittanceSmsRequest";
 export * from "./RemittanceBackofficeUserView";
 export * from "./RemittanceBackofficeDashboardSummary";
 export * from "./RemittanceBackofficeTransaction";
+export * from "./RemittanceReconciliation";
 export * from "./RemittanceBackofficeUserDetail";
 export * from "./RemittanceBackofficeUserListResponse";
 export * from "./RemittanceBackofficeTxListResponse";

package/src/remittance/enums/RemittanceReconStatus.ts

@@ -0,0 +1,15 @@
+/**
+ * Estado de reconciliación de una tx local contra el reporte SUTWEB38 diario
+ * de Uniteller. Poblado por AssertionEngine del uniteller-connector al ingerir
+ * el archivo TxDetails. Ver spec de reconciliación Cap 6 (motor de aserciones).
+ *
+ * Prioridad si múltiples diffs: DIFF_COST > DIFF_FX > DIFF_RATE > DIFF_AMOUNT > OK.
+ */
+export enum RemittanceReconStatus {
+    OK = "OK",
+    DIFF_FX = "DIFF_FX",
+    DIFF_COST = "DIFF_COST",
+    DIFF_RATE = "DIFF_RATE",
+    DIFF_AMOUNT = "DIFF_AMOUNT",
+    MISSING_IN_PROVIDER = "MISSING_IN_PROVIDER",
+}

package/src/remittance/enums/index.ts

@@ -25,3 +25,4 @@ export * from "./RuleActionType";
 export * from "./AuditResult";
 export * from "./RemittanceExceptionCode";
 export * from "./RemittanceFieldBelongsTo";
+export * from "./RemittanceReconStatus";

package/src/transaction/dtos/DisputeRefundRecord.ts

@@ -0,0 +1,71 @@
+import { RefundChannelEnum } from '../enums/RefundChannelEnum';
+import { DisputeRefundType } from '../enums/DisputeRefundType';
+import { DisputeRefundStatus } from '../enums/DisputeRefundStatus';
+
+/**
+ * Registro canónico de un movimiento de dinero (REFUND o REVERSAL) ligado a
+ * un folio R27 de reclamación. Es el shape 1:1 de una fila de la tabla DDB
+ * `DisputeRefund_GT`.
+ *
+ * Modelo:
+ *   - Un folio R27 puede tener 0, 1 o 2 filas en DisputeRefund_GT.
+ *   - 1 fila `type=REFUND` cuando el reintegro se ejecutó.
+ *   - 2 filas (REFUND + REVERSAL) cuando el reintegro fue revertido por
+ *     dictamen tardío que confirmó 2FA original (Circular 12/2018
+ *     Disposición 35.a Banxico).
+ *   - `folioEventId` apunta al evento R27 específico (no solo al folio)
+ *     para preservar el ligado inmutable cuando un folio reingresa (103)
+ *     tras un dictamen no procedente.
+ *   - `relatedRefundId` solo aplica cuando `type=REVERSAL` — apunta al `id`
+ *     del REFUND que se está revirtiendo.
+ *   - `txId` es `null` durante `PENDING_AUTHORIZATION`; se popula al crear
+ *     la tx en el ledger (`PagoConfiadoTx_GT`).
+ */
+export interface DisputeRefundRecord {
+    id: string;
+    folioId: string;
+    folioEventId: string;
+    type: DisputeRefundType;
+    channel: RefundChannelEnum;
+    status: DisputeRefundStatus;
+    relatedRefundId: string | null;
+    txId: string | null;
+    amount: number;
+    currencyId: 'MXN';
+    caseFolio: string;
+    targetDirectoryId: string;
+    manualExecution: DisputeRefundManualExecution | null;
+    approval: DisputeRefundApproval;
+    reason: string | null;
+    createdAt: number;
+    updatedAt: number;
+    failureReason: string | null;
+}
+
+/**
+ * Metadatos específicos del canal SPEI_OUT_MANUAL. `null` cuando el canal es
+ * INTERNAL_PCF (transferencia intra-wallet sin salida SPEI).
+ */
+export interface DisputeRefundManualExecution {
+    targetClabe: string | null;
+    targetBankId: string | null;
+    targetName: string | null;
+    instructionS3Key: string | null;
+    confirmedTrackingKey: string | null;
+    confirmedAt: number | null;
+    confirmedByUserId: string | null;
+}
+
+/**
+ * Cadena de aprobación heredada de Política SP1 §10:
+ *   L1 ($5,000 MXN) → requiere checker.
+ *   L2 ($50,000 MXN) → requiere checker + minuta firmada.
+ * `pldOverrideMinuteS3Key` cubre el caso en que el titular está en lista
+ * negra PLD y el reintegro procede solo con acta de comité.
+ */
+export interface DisputeRefundApproval {
+    makerUserId: string;
+    checkerUserId: string | null;
+    minuteS3Key: string | null;
+    pldOverrideMinuteS3Key: string | null;
+}

package/src/transaction/enums/DisputeRefundStatus.ts

@@ -0,0 +1,7 @@
+export enum DisputeRefundStatus {
+    PENDING_AUTHORIZATION = "PENDING_AUTHORIZATION",
+    PENDING_MANUAL_EXECUTION = "PENDING_MANUAL_EXECUTION",
+    EXECUTED = "EXECUTED",
+    FAILED = "FAILED",
+    CANCELLED = "CANCELLED",
+}

package/src/transaction/enums/DisputeRefundType.ts

@@ -0,0 +1,4 @@
+export enum DisputeRefundType {
+    REFUND = "REFUND",
+    REVERSAL = "REVERSAL",
+}

package/src/transaction/enums/RefundManualExecutionStatus.ts

@@ -1,3 +1,9 @@
+/**
+ * @deprecated Use `DisputeRefundStatus` en su lugar. Este enum tiene scope
+ * estrecho (solo canal SPEI_OUT_MANUAL, sin estados de autorización previa,
+ * sin failure state) y se retira junto con la tabla `RefundManualExecution_GT`
+ * en el cleanup que sigue a la migración de código a `DisputeRefund_GT`.
+ */
 export enum RefundManualExecutionStatus {
     PENDING_MANUAL_EXECUTION = "PENDING_MANUAL_EXECUTION",
     EXECUTED = "EXECUTED",

package/src/transaction/index.ts

@@ -18,6 +18,7 @@ export * from './dtos/ActivityProblemGetResponse';
 export * from './dtos/AuthorizeRefundRequest';
 export * from './dtos/ReverseRefundRequest';
 export * from './dtos/ConfirmManualExecutionRequest';
+export * from './dtos/DisputeRefundRecord';
 
 export * from './dtos/internal/BaseProviderTransaction';
 export * from './dtos/internal/BaseProviderTransactionQueryParams';
@@ -44,3 +45,5 @@ export * from './enums/ActivityProblemStatusEnum';
 export * from './enums/RefundChannelEnum';
 export * from './enums/RefundPathTypeEnum';
 export * from './enums/RefundManualExecutionStatus';
+export * from './enums/DisputeRefundType';
+export * from './enums/DisputeRefundStatus';