# TransactionSettleData

A model the API reference uses in a request or a response. The operation pages link every field typed as this model here.

Represents settlement data for a transaction.

## Fields
- `estimatedSettleDate` (string(date-time)): The estimated settlement date for the transaction. (nullable)
- `dateSettled` (string(date-time)): The actual date when the transaction was settled. (nullable)
- `flag` ([SettleFlag](https://devportal.demo.winkpg.io/docs/api/models/SettleFlag.md)): Legacy settlement flag. Use `settlementStatus` instead. (deprecated)
  Values:
  - `Open`: The transaction is open and not yet settled.
  - `Settled`: The transaction has been successfully settled.
  - `RolledBack`: The transaction has been rolled back or reversed.
  - `InProgress`: The transaction is currently in the process of being settled.
  - `Hold`: The transaction is on hold and cannot be settled at the moment.
- `processorBatchId` (string): The processor's batch identifier for this transaction. (nullable)
- `gatewayBatchId` (string(uuid)): The gateway's batch identifier for this transaction. (nullable)
- `settlementDataJson` (string): Settlement aggregate data as a JSON string (converted from processor XML).  This contains the data needed to settle the transaction with the processor.  Encrypted at rest. (nullable)
- `settlementStatus` ([SettlementStatus](https://devportal.demo.winkpg.io/docs/api/models/SettlementStatus.md)): Current settlement status of the transaction for processor settlement tracking.  Treat null as `WaitingForSettlement`. (nullable)
  Values:
  - `WaitingForSettlement`: Transaction is waiting to be settled with the processor
  - `SettlementSucceeded`: Settlement completed successfully with the processor
  - `SettlementFailed`: Settlement failed - requires review and retry (rollback)
  - `NotEligible`: Transaction is not eligible for settlement (voided, reversed, or not yet captured)
  - `SettlementInProgress`: Settlement is currently in progress with the processor.
  - `SettlementOnHold`: Settlement is on hold and cannot proceed at the moment.
  - `SettlementRolledBack`: Settlement was rolled back or reversed after a completed attempt. Distinct from SettlementFailed which indicates a transient failure needing retry.
  - `ReversalFailed`: A reversal was attempted but the processor did not confirm that the authorization hold was voided: the contributor saw a non-Ok result code (transport failure, timeout, swallowed exception, malformed response, etc.). Distinct from NotEligible (a confirmed reversal/void) and SettlementFailed (a settlement-time failure). Operations need to confirm the hold state with the processor and reverse manually if required. The transaction's Stage is left at the pre-reversal value; the close-stage history entry is NOT written.
  - `Pending`: The provider owns settlement and reports the outcome on its own schedule, so the transaction belongs to no gateway batch. Used for ACH sales and alternative payments. A background sync moves the transaction on as the provider reports, through any of the ACH in-flight statuses, to a terminal status.
  - `Accepted`: The ACH processor has accepted the transaction for processing. VeriCheck V2 only: the entry has been received and accepted by the payment network.
  - `Originated`: The ACH transaction has been originated (submitted to the NACHA network). VeriCheck V2 only: the debit has been forwarded to the RDFI.
  - `Verifying`: The ACH processor is verifying the bank account before origination. VeriCheck V2 only: the check runs on the processor's side, before the debit reaches the ACH network.
  - `PartiallySettled`: The ACH transaction has been partially settled. VeriCheck V2 only: a portion of the funds have cleared.
- `settlementAttemptedAt` (string(date-time)): Timestamp when settlement was last attempted with the processor. (nullable)
- `settledAt` (string(date-time)): Timestamp when settlement succeeded with the processor. (nullable)
- `settlementRetryCount` (integer(int32)): Number of settlement retry attempts. Treat null as 0. (nullable)
- `settlementErrorMessage` (string): Error message if settlement failed. (nullable)
- `batchId` (string): Gateway batch identifier assigned at authorization time for batch boundary management.  Transactions are grouped into settlement batches by this ID, which is stamped from  the merchant's `CurrentBatchId` during the authorization flow.  Nullable because existing documents predate this property. (nullable)
- `closedSettlementBatchId` (string(uuid)): Identifier of the closed settlement batch that settled this transaction, set when the batch  closes. `null` until then, and on transactions settled in batches that closed before this  field was recorded.     Distinct from the other batch identifiers on this type: `batchId` / `gatewayBatchId`  are the open batch at authorization time, and `processorBatchId` is the processor's batch  reference; none of them equals the settlement batch's id. (nullable)
- `overrideHistory` (array<[SettlementStatusOverrideRecord](https://devportal.demo.winkpg.io/docs/api/models/SettlementStatusOverrideRecord.md)>): Append-only list of admin-driven manual overrides applied to `settlementStatus`.  Populated by the `Transaction.OverrideSettlementStatus` domain method.  Null, and omitted, on transactions that have never had a manual override (the default for  the vast majority of rows). (nullable)
  Fields of each item:
  - `previousStatus` ([SettlementStatus](https://devportal.demo.winkpg.io/docs/api/models/SettlementStatus.md)): The settlement status the transaction held before this override was applied. (nullable)
    Values:
    - `WaitingForSettlement`: Transaction is waiting to be settled with the processor
    - `SettlementSucceeded`: Settlement completed successfully with the processor
    - `SettlementFailed`: Settlement failed - requires review and retry (rollback)
    - `NotEligible`: Transaction is not eligible for settlement (voided, reversed, or not yet captured)
    - `SettlementInProgress`: Settlement is currently in progress with the processor.
    - `SettlementOnHold`: Settlement is on hold and cannot proceed at the moment.
    - `SettlementRolledBack`: Settlement was rolled back or reversed after a completed attempt. Distinct from SettlementFailed which indicates a transient failure needing retry.
    - `ReversalFailed`: A reversal was attempted but the processor did not confirm that the authorization hold was voided: the contributor saw a non-Ok result code (transport failure, timeout, swallowed exception, malformed response, etc.). Distinct from NotEligible (a confirmed reversal/void) and SettlementFailed (a settlement-time failure). Operations need to confirm the hold state with the processor and reverse manually if required. The transaction's Stage is left at the pre-reversal value; the close-stage history entry is NOT written.
    - `Pending`: The provider owns settlement and reports the outcome on its own schedule, so the transaction belongs to no gateway batch. Used for ACH sales and alternative payments. A background sync moves the transaction on as the provider reports, through any of the ACH in-flight statuses, to a terminal status.
    - `Accepted`: The ACH processor has accepted the transaction for processing. VeriCheck V2 only: the entry has been received and accepted by the payment network.
    - `Originated`: The ACH transaction has been originated (submitted to the NACHA network). VeriCheck V2 only: the debit has been forwarded to the RDFI.
    - `Verifying`: The ACH processor is verifying the bank account before origination. VeriCheck V2 only: the check runs on the processor's side, before the debit reaches the ACH network.
    - `PartiallySettled`: The ACH transaction has been partially settled. VeriCheck V2 only: a portion of the funds have cleared.
  - `newStatus` ([SettlementStatus](https://devportal.demo.winkpg.io/docs/api/models/SettlementStatus.md)): The settlement status the operator selected. (nullable)
    Values:
    - `WaitingForSettlement`: Transaction is waiting to be settled with the processor
    - `SettlementSucceeded`: Settlement completed successfully with the processor
    - `SettlementFailed`: Settlement failed - requires review and retry (rollback)
    - `NotEligible`: Transaction is not eligible for settlement (voided, reversed, or not yet captured)
    - `SettlementInProgress`: Settlement is currently in progress with the processor.
    - `SettlementOnHold`: Settlement is on hold and cannot proceed at the moment.
    - `SettlementRolledBack`: Settlement was rolled back or reversed after a completed attempt. Distinct from SettlementFailed which indicates a transient failure needing retry.
    - `ReversalFailed`: A reversal was attempted but the processor did not confirm that the authorization hold was voided: the contributor saw a non-Ok result code (transport failure, timeout, swallowed exception, malformed response, etc.). Distinct from NotEligible (a confirmed reversal/void) and SettlementFailed (a settlement-time failure). Operations need to confirm the hold state with the processor and reverse manually if required. The transaction's Stage is left at the pre-reversal value; the close-stage history entry is NOT written.
    - `Pending`: The provider owns settlement and reports the outcome on its own schedule, so the transaction belongs to no gateway batch. Used for ACH sales and alternative payments. A background sync moves the transaction on as the provider reports, through any of the ACH in-flight statuses, to a terminal status.
    - `Accepted`: The ACH processor has accepted the transaction for processing. VeriCheck V2 only: the entry has been received and accepted by the payment network.
    - `Originated`: The ACH transaction has been originated (submitted to the NACHA network). VeriCheck V2 only: the debit has been forwarded to the RDFI.
    - `Verifying`: The ACH processor is verifying the bank account before origination. VeriCheck V2 only: the check runs on the processor's side, before the debit reaches the ACH network.
    - `PartiallySettled`: The ACH transaction has been partially settled. VeriCheck V2 only: a portion of the funds have cleared.
  - `reason` (string): Free-text justification supplied by the operator. Required, trimmed, 5-500 chars. (nullable)
  - `operatorUserId` (string(uuid)): The user id of the operator who applied the override. (nullable)
  - `operatorUserName` (string): The display name of the operator at the time of the override (snapshot: does not  follow rename of the underlying user account). (nullable)
  - `overriddenAt` (string(date-time)): UTC timestamp the override was applied. (nullable)

## See also

- [All documentation](https://devportal.demo.winkpg.io/llms.txt): the machine-readable index of every public page on this site.