# TransactionCreateDto A model the API reference uses in a request or a response. The operation pages link every field typed as this model here. Represents the data required to create a new transaction. ## Fields - `currentStage` ([TransactionStage](https://devportal.demo.winkpg.io/docs/api/models/TransactionStage.md)): Gets or sets the current stage of the transaction within the create or update workflow. Values: - `Created` - `Validated` - `Enriched` - `Screened` - `Authorized` - `Finalized` - `Captured` - `Completed` - `Reversed` - `Refunded` - `Voided` - `SplitTenderPending`: A partial approval is holding a reduced authorization and the gateway is waiting for a decision: accept the lesser amount, void it, or start a split tender for the shortfall. Non-terminal: the transaction leaves this stage once Transaction.PartialApprovalData.Disposition moves off PartialApprovalDisposition.Pending, or when the acknowledgment deadline elapses and the gateway voids it. - `Rejected` - `Declined` - `Failed` - `PolicyRejected`: Auth succeeded at the processor but a post-authorization denylist rule matched (AVS or CVV response code). A reversal or void was issued and the transaction is permanently rejected by gateway policy. - `history` (array<[TransactionHistoryItem](https://devportal.demo.winkpg.io/docs/api/models/TransactionHistoryItem.md)>): Gets or sets the transaction history entries associated with the transaction. (nullable) Fields of each item: - `id` (string(uuid)) - `transactionId` (string(uuid)) - `stage` ([TransactionStage](https://devportal.demo.winkpg.io/docs/api/models/TransactionStage.md)): Represents the stage of a transaction within the transaction management workflow. Values: - `Created` - `Validated` - `Enriched` - `Screened` - `Authorized` - `Finalized` - `Captured` - `Completed` - `Reversed` - `Refunded` - `Voided` - `SplitTenderPending`: A partial approval is holding a reduced authorization and the gateway is waiting for a decision: accept the lesser amount, void it, or start a split tender for the shortfall. Non-terminal: the transaction leaves this stage once Transaction.PartialApprovalData.Disposition moves off PartialApprovalDisposition.Pending, or when the acknowledgment deadline elapses and the gateway voids it. - `Rejected` - `Declined` - `Failed` - `PolicyRejected`: Auth succeeded at the processor but a post-authorization denylist rule matched (AVS or CVV response code). A reversal or void was issued and the transaction is permanently rejected by gateway policy. - `detailsJson` (string): (nullable) - `creatorId` (string(uuid)): The ID of the user who created this entity. - `creationTime` (string(date-time)): The date and time when this entity was created. - `operationId` (string): (nullable) - `lifecycleStatus` (string): The merchant-facing lifecycle status this entry was published under, or `null` when the entry carries none. (nullable) - `lifecycleOccurredAtUtc` (string(date-time)): When the event named by `lifecycleStatus` actually occurred, or `null` when the entry's own `creationTime` is that instant. (nullable) - `linkedReceiptId` (string(uuid)): The ID of the receipt generated for this timeline entry, if any. (nullable) - `linkedReceiptType` ([ReceiptType](https://devportal.demo.winkpg.io/docs/api/models/ReceiptType.md)): The type of the linked receipt. (nullable) Values: - `Authorization`: Receipt generated after a successful authorization. - `Capture`: Receipt generated after a capture/settlement. - `Refund`: Receipt generated after a full refund. - `PartialRefund`: Receipt generated after a partial refund. Multiple partial refund receipts may exist on a single transaction, each with a distinct sequence number. - `Void`: Receipt generated after a void. - `Reversal`: Receipt generated after a full reversal: the entire approved amount has been released back to the issuer. Distinguished from PartialReversal so the transaction-detail / explorer pages can show the lifecycle event clearly. - `OnDemand`: Receipt generated on-demand from the UI (legacy/fallback for pre-module transactions). - `PartialReversal`: Receipt generated after a partial reversal. Multiple partial reversal receipts may exist on a single transaction (one per reversal operation), each with a distinct sequence number. - `SplitTenderSummary`: Summary receipt for a completed split tender group: the order total, what each tender in the group authorized, and the combined authorized amount. Generated once per group, after the final tender completes, in addition to the per-tender receipts. - `linkedReceiptSequenceNumber` (integer(int32)): The sequence number of the linked receipt within the transaction. (nullable) - `subHistory` (array<[TransactionHistoryItem](https://devportal.demo.winkpg.io/docs/api/models/TransactionHistoryItem.md)>): (nullable) - `appliedPatches` (array<[TransactionPatchSnapshot](https://devportal.demo.winkpg.io/docs/api/models/TransactionPatchSnapshot.md)>): Gets or sets the collection of patch snapshots that have been applied to the transaction. (nullable) Fields of each item: - `appliedAtUtc` (string(date-time)) - `contributor` (string): (nullable) - `patch` ([TransactionPatchDto](https://devportal.demo.winkpg.io/docs/api/models/TransactionPatchDto.md)) - `merchantId` (string(uuid)): The unique identifier of the merchant associated with the transaction. - `transactionType` ([TransactionType](https://devportal.demo.winkpg.io/docs/api/models/TransactionType.md)): The type of transaction being performed. Conditional: When RequestedSplitTenderTotal is not null. Must equal Sale. Conditional: Conditional (see validator source). Values: - `Authorization`: Represents an authorization transaction, typically used to verify funds availability without capturing the amount. - `Sale`: Represents a sale transaction, which authorizes and captures funds in a single step. - `Return`: Represents a return transaction, used to refund money to the customer. - `Void`: Represents a void transaction, used to cancel a previously authorized transaction before it is settled. - `Force`: Represents a force transaction, typically used to manually enter a previously authorized transaction. - `Capture`: Represents a capture transaction, used to capture funds from a previously authorized transaction. - `CaptureAll`: Represents a capture all transaction, used to capture funds from multiple previously authorized transactions. - `RepeatSale`: Represents a repeat sale transaction, used to process a new sale based on a previous transaction's details. - `Adjustment`: Represents an adjustment transaction, used to modify the amount of a previous transaction. - `Activate`: Represents an activate transaction, typically used to activate a gift card or prepaid card. - `Deactivate`: Represents a deactivate transaction, typically used to deactivate a gift card or prepaid card. - `Redeem`: Represents a redeem transaction, typically used to redeem value from a gift card or loyalty program. - `Inquire`: Represents an inquire transaction, used to check the status or balance of an account or card. - `Reload`: Represents a reload transaction, typically used to add value to a gift card or prepaid card. - `VoucherClear`: Represents an offline EBT voucher clear: a terminal was offline, a paper food-stamp (SNAP) or eWIC voucher was written against a voice-obtained approval code, and the voucher is later uploaded so the benefit clears. Permitted on EBT SNAP and eWIC tenders only. - `Payout`: Represents a payout transaction, used to push funds from the merchant to an external bank account as an ACH credit. Unlike Return, which refunds a prior debit, a payout is a standalone outbound fund transfer with no originating transaction. - `description` (string): Optional free-text description of what this payment is for, at most 100 characters. (nullable, max length 100) - `merchantReference` (string): Optional merchant-supplied reference for reconciliation, at most 25 characters, letters and digits only. (nullable, max length 25, pattern ^[A-Za-z0-9]*$) - `tender` ([TenderKind](https://devportal.demo.winkpg.io/docs/api/models/TenderKind.md)): Optionally declares that this transaction is taken in cash. The only accepted value is `Cash`. Omit the field for every card, check, and token transaction. (nullable) Values: - `Cash`: Cash taken at the point of sale. Resolved against the merchant's cash processor profile, auto-approved with no processor call, and settled into its own daily cash batch. - `cardData` ([CardData](https://devportal.demo.winkpg.io/docs/api/models/CardData.md)): Card data associated with the transaction. Conditional: When CvvAlias is not empty. Conditional: When CardData is not null. Required: Conditional (see validator source). Fields: - `cardNumber` (string): The card account number. Conditional: When IsStoredPayment is not true. (nullable) - `last4CardNumber` (integer(int32)): The last 4 digits of the card number as an integer. (nullable, read only) - `expirationMonth` (integer(int32)): The expiration month of the card as an integer in the range `1` to `12`. - `expirationYear` (integer(int32)): The expiration year of the card. Either a two-digit year (e.g. `29`) or a four-digit year (e.g. `2029`); two-digit years resolve to the 2000s. - `expirationDate` (string(date-time)): The expiration date of the card. Conditional: When IsStoredPayment is not true. (nullable) - `binData` ([BinData](https://devportal.demo.winkpg.io/docs/api/models/BinData.md)): The BIN (Bank Identification Number) data associated with the card. - `cvv` (integer(int32)): Deprecated: send `cardVerificationValue` instead. The CVV (Card Verification Value) of the card as an integer. Conditional: When IsStoredPayment is not true. Range: 100 to 9999. (nullable, deprecated) - `cardVerificationValue` (string): The card verification value (CVV, CVC or CID) exactly as printed on the card: three digits, or four for American Express. Send it as a string so a leading zero is kept. Conditional: When IsStoredPayment is not true. (nullable) - `nameOnCard` (string): The name on the card. Conditional: When IsStoredPayment is not true. Max length: 25. (nullable, min length 0, max length 25) - `pin` (string): The PIN (Personal Identification Number) of the card. (nullable) - `keySerialNumber` (string): The Key Serial Number associated with the card. (nullable) - `emvData` (string): The EMV (Europay, Mastercard, and Visa) data associated with the card. (nullable) - `trackData` (string): The track data of the card. (nullable) - `encryptedTrack1Data` (string): The encrypted track 1 data of the card. (nullable) - `encryptedTrack2Data` (string): The encrypted track 2 data of the card. (nullable) - `encryptedTrack3Data` (string): The encrypted track 3 data of the card. (nullable) - `dynamicCardVerificationData` (string): A reader-generated dynamic card verification value captured at the moment the card was read. Card readers that support it derive this value from physical characteristics of the magnetic stripe, which differ between an original card and a copy, so the decryption service that fronts the processor can score whether the presented card is genuine. (nullable) - `dynamicCardVerificationStatus` (string): Status metadata the reader reported alongside `dynamicCardVerificationData` (for example whether the reader considered the dynamic verification read successful). Non-secret: it describes the read, it is not the verification value itself, so it is persisted as submitted. (nullable) - `iin` (string): The IIN (Issuer Identification Number) of the card. (nullable) - `arqc` (string): The ARQC (Authorization Request Cryptogram) of the card. (nullable) - `entryMode` ([EntryModes](https://devportal.demo.winkpg.io/docs/api/models/EntryModes.md)): The entry mode of the card. Values: - `Unknown`: The entry mode is unknown. - `NotApplicable`: The entry mode is not applicable for this transaction. - `Manual`: The transaction details were entered manually. - `UnencryptedCardReaderSwipe`: The card was swiped through an unencrypted card reader. - `EncryptedCardReaderSwipe`: The card was swiped through an encrypted card reader. - `Icc`: The transaction was processed using an ICC (Integrated Circuit Card) or chip card. - `Proximity`: The transaction was processed using a proximity or contactless payment method. - `Fallback`: The transaction was processed using a fallback method when the primary method failed. - `TechnicalFallback`: The transaction was processed using a fallback method when the primary method failed. - `EmptyCandidateFallback`: The transaction was processed using a fallback method when the primary method failed. - `DigitalWallet`: The transaction was processed using a digital wallet. - `cvPresence` ([CvPresence](https://devportal.demo.winkpg.io/docs/api/models/CvPresence.md)): The CV (Card Verification) presence status. Values: - `None`: The CV status is not specified or unknown. - `NotSubmitted`: The CV has not been submitted. - `Submitted`: The CV has been successfully submitted. - `Illegible`: The submitted CV is illegible or cannot be read. - `NotPresent`: The CV is not present or missing from the submission. - `billingAddress` ([Address](https://devportal.demo.winkpg.io/docs/api/models/Address.md)): The billing address associated with the card. Optional by default (no nested validation enforced). Conditional: When IsStoredPayment is not true. - `phone` (string): The phone number associated with the card. Conditional: When IsStoredPayment is not true. Max length: 15. Pattern: ^[0-9+()\-\s]*$. (nullable, min length 0, max length 15) - `email` (string): The email address associated with the card. Conditional: When IsStoredPayment is not true. Must be a valid email. Max length: 50. (nullable, min length 0, max length 50) - `hasEmvData` (boolean): Indicates whether EMV data was provided in the original request. The raw `emvData` value is not stored. (nullable) - `hasTrackData` (boolean): Indicates whether track data was provided in the original request. The raw `trackData` value is not stored. (nullable) - `hasEncryptedTrackData` (boolean): Indicates whether any encrypted track data (track 1, 2, or 3) was provided in the original request. The raw encrypted track values are not stored. (nullable) - `hasCvv` (boolean): Indicates whether a CVV was provided in the original request, in either `cardVerificationValue` or `cvv`. The raw value is not stored. (nullable) - `hasPin` (boolean): Indicates whether a PIN was provided in the original request. The raw `pin` value is not stored. (nullable) - `hasDynamicCardVerificationData` (boolean): Indicates whether reader-generated dynamic card verification data was provided in the original request. The raw `dynamicCardVerificationData` value is not stored. (nullable) - `emvAid` (string): (nullable) - `isDebitRouting` (boolean): (nullable) - `tenderType` ([CardTenderType](https://devportal.demo.winkpg.io/docs/api/models/CardTenderType.md)): The card-rail tender the caller is attempting to use. Drives deterministic processor routing. `null` (or absent JSON) is treated as `CreditDebit` for backward compatibility: see `EffectiveTenderType`. (nullable) Values: - `CreditDebit`: Standard credit/debit card. The current card-rail behaviour. isDebitRouting modulates whether the request prefers debit-network routing within this rail. - `EbtSnap`: EBT SNAP (food benefits). Routes through the EBT SNAP processor lane and requires PIN + card-present per program rules. - `EbtCash`: EBT Cash (cash benefits). Distinct rail from SNAP; supports cashback where SNAP does not. PIN + card-present required. - `Ewic`: eWIC (Women, Infants, and Children). Distinct rail from EBT, with item-level eligibility / voucher-select flow handled in the eWIC follow-up epic. - `isStoredPayment` (boolean): When `true`, this card data originates from a stored payment method and client-side field validation is not applicable. The server resolves actual card data from the payment token. (nullable) - `terminalCapability` ([TerminalCapability](https://devportal.demo.winkpg.io/docs/api/models/TerminalCapability.md)): The static hardware capability of the terminal. Selects the POS capability subfields on the processor wire message. Resolved once in `ProcessorSelectionApplier`: request value wins over the processor-profile default, which wins over `Unspecified`. (nullable) Values: - `Unspecified`: No capability declared. The handler emits its current default POS capability fields, preserving existing wire behavior exactly. - `MagneticStripe`: Magnetic stripe reader only (implies keyed entry). - `MagneticStripeWithPin`: Magnetic stripe reader with PIN pad (implies keyed entry). - `Chip`: Contact chip reader (EMV ICC). - `ChipWithPin`: Contact chip reader with PIN pad. - `ChipContactless`: Contactless chip reader (EMV contactless / NFC). - `ChipContactlessWithPin`: Contactless chip reader with PIN pad. - `cryptogram` (string): The payment network cryptogram recovered from wallet-token decryption (the online payment cryptogram for Apple Pay / Google Pay DPAN transactions). Sensitive: masked from logs. (nullable) - `eciIndicator` (string): The Electronic Commerce Indicator (ECI) describing the authentication context of a tokenized / wallet transaction (e.g. `"05"` for a 3DS-authenticated transaction). Drives the liability-shift indicators processors include in the network message. (nullable) - `isTokenized` (boolean): Indicates the credential is a tokenized account number (DPAN / network token) rather than a raw PAN. `null` means unknown, which is treated the same as not tokenized. (nullable) - `tokenTransactionId` (string): The provider-specific transaction identifier returned alongside a wallet token (Apple Pay `transactionIdentifier`, network-token transaction id). Used for dispute matching against the wallet provider. (nullable) - `checkData` ([CheckData](https://devportal.demo.winkpg.io/docs/api/models/CheckData.md)): Check data associated with the transaction. Conditional: When CheckData is not null. Conditional: Conditional (see validator source). Conditional: When TransactionType == VoucherClear. Required: When TransactionType == Payout. Fields: - `nameOnCheck` (string): The name printed on the check. Required: When IsStoredPayment is not true. (nullable) - `routingNumber` (string): The routing number of the bank. Required: When IsStoredPayment is not true. Conditional: When IsStoredPayment is true. (nullable) - `routingNumberLast4` (string): The last 4 digits of `routingNumber` as a string, preserving leading zeros, or `null` when no digits are available. (nullable, read only) - `accountNumber` (string): The account number associated with the check. Required: When IsStoredPayment is not true. Conditional: When IsStoredPayment is true. (nullable) - `accountNumberLast4` (string): The last 4 digits of `accountNumber` as a string, preserving leading zeros, or `null` when no digits are available. (nullable, read only) - `checkNumber` (string): The check number. (nullable) - `micr` (string): The Magnetic Ink Character Recognition (MICR) data. (nullable) - `driversLicense` (string): The driver's license number of the check writer. (nullable) - `state` (string): The state of issuance for the driver's license. (nullable) - `ssn` (string): The Social Security Number of the check writer. (nullable) - `dateOfBirth` (string): The date of birth of the check writer. (nullable) - `checkType` ([CheckType](https://devportal.demo.winkpg.io/docs/api/models/CheckType.md)): The type of check. Values: - `Personal`: Represents a personal check. This is typically issued by an individual from their personal account. - `Business`: Represents a business check. This is typically issued by a company or organization from their business account. - `accountType` ([CheckAccountType](https://devportal.demo.winkpg.io/docs/api/models/CheckAccountType.md)): The type of account associated with the check. Conditional: When IsStoredPayment is not true. Values: - `Checking`: Represents a checking account. - `Savings`: Represents a savings account. - `rawMicr` (string): The raw MICR data. (nullable) - `branchCity` (string): The city of the bank branch. (nullable) - `emailAddress` (string): The email address of the check writer. Conditional: When IsStoredPayment is not true. Must be a valid email. (nullable) - `telephoneNumber` (string): The telephone number of the check writer. Conditional: When IsStoredPayment is not true. Pattern: ^[0-9+()\-\s]*$. (nullable) - `address` ([Address](https://devportal.demo.winkpg.io/docs/api/models/Address.md)): The address associated with the check. Optional by default (no nested validation enforced). Conditional: When IsStoredPayment is not true. - `secCode` ([SecCode](https://devportal.demo.winkpg.io/docs/api/models/SecCode.md)): The Standard Entry Class (SEC) code for the transaction. (nullable) Values: - `Ccd`: Corporate Credit or Debit (CCD) - Used for business-to-business transactions. - `Ppd`: Prearranged Payment and Deposit (PPD) - Used for consumer transactions. - `Web`: Internet-Initiated/Mobile Entry (WEB) - Used for internet or mobile-initiated transactions. - `Arc`: Accounts Receivable Conversion (ARC) - Used for converting eligible checks to ACH debits. - `Tel`: Telephone-Initiated Entry (TEL) - Used for telephone-initiated transactions. - `isStoredPayment` (boolean): When `true`, this check data originates from a stored payment method and client-side field validation is not applicable. The server resolves actual account data from the payment token. (nullable) - `cashData` ([CashPaymentDetails](https://devportal.demo.winkpg.io/docs/api/models/CashPaymentDetails.md)): Cash sale details: the cash handed over, the change returned, and when the cash was taken. Fields: - `amountTendered` (number(double)): The amount of cash the customer physically handed over, in the transaction currency. May exceed the transaction total when change was returned. (nullable) - `changeGiven` (number(double)): The amount of change returned to the customer, in the transaction currency. (nullable) - `cashReceivedAt` (string(date-time)): When the cash was taken. Send it to record a sale taken earlier, for example one recorded offline; when omitted, the gateway stamps the time of authorization. (nullable) - `tokenData` ([TokenData](https://devportal.demo.winkpg.io/docs/api/models/TokenData.md)): Tokenized payment details, used to charge a stored credential instead of raw card data. Conditional: When TokenData is not null. Fields: - `token` (string): A secure token representing a stored payment method, charged in place of raw card data. Required: When ProviderType is null or ProviderType == Internal. (nullable) - `tokenSharing` (boolean): The sharing status of the token. (nullable) - `merchantOriginalId` (string(uuid)): The original merchant identifier associated with the token, typically used when token sharing is enabled. (nullable) - `providerType` ([TokenProviderType](https://devportal.demo.winkpg.io/docs/api/models/TokenProviderType.md)): Specifies the provider that generated the token. Examples include Internal, ApplePay, GooglePay, NetworkToken, and ReaderToken. This value determines how the token should be processed. (nullable) Values: - `Internal`: Internal gateway token generated by WinkPG. - `ApplePay`: Apple Pay encrypted payment token. - `GooglePay`: Google Pay encrypted payment token. - `NetworkToken`: Network token such as Visa Token Service or Mastercard MDES. - `Paze`: Paze (Early Warning) encrypted payment token. - `ReaderToken`: A reusable card token issued by a card-reader decryption service, carried on readerToken. - `readerToken` (string): A reusable card token issued by a card-reader decryption service, charged in place of a physical card read. Required when `providerType` is `ReaderToken`, and ignored otherwise. Required: When ProviderType == ReaderToken. (nullable) - `encryptedPaymentToken` (string): The encrypted payment token payload received from a digital wallet provider (for example, Apple Pay or Google Pay). Required for digital wallet transactions. Required: When ProviderType == ApplePay or ProviderType == GooglePay or ProviderType == Paze. (nullable) - `network` (string): The payment network associated with the token (for example: Visa, Mastercard, Amex). Typically provided by digital wallet transactions. (nullable) - `displayName` (string): A display-friendly name for the payment method, (nullable) - `cryptogram` (string): The cryptographic value used for transaction authorization in digital wallet or network token transactions. Required for Apple Pay, Google Pay, and network token processing. Required: When ProviderType == NetworkToken. (nullable) - `eciIndicator` (string): The Electronic Commerce Indicator (ECI) that specifies the authentication level of the transaction. Commonly used in 3D Secure and digital wallet flows. (nullable) - `transactionIdentifier` (string): A unique identifier assigned by the wallet provider for the transaction. (nullable) - `deviceData` ([DeviceData](https://devportal.demo.winkpg.io/docs/api/models/DeviceData.md)): Device data for the transaction. Conditional: When DeviceData is not null. Fields: - `sdkVersion` (string): The version of the SDK used by the device. (nullable) - `serialNumber` (string): The serial number of the device. (nullable) - `batteryLevel` (integer(int32)): The battery level of the device. The value is nullable to accommodate devices that may not report battery level. (nullable) - `isEncrypted` (boolean): Value indicating whether the device data is encrypted. - `encryptionType` (string): The type of encryption used for the device data, if applicable. (nullable) - `encryptionKeyVariant` (string): The DUKPT key variant the reader used to encrypt the card data: `Data` for the data variant or `Pin` for the PIN variant. Both variants derive from the same base key, so the decryption service needs to be told which one applies before it can decrypt. (nullable) - `cvmResults` (string): The EMV Cardholder Verification Method (CVM) result reported by the device. Values: "1" = Offline PIN, "2" = Online PIN, "3" = Signature. Used as a fallback when EMV tag 9F34 is not present in the chip data (e.g. some Ingenico/Discover contactless flows). (nullable) - `fsa` ([Fsa](https://devportal.demo.winkpg.io/docs/api/models/Fsa.md)): FSA (Flexible Spending Account) data for the transaction. Fields: - `qhpAmount` (number(double)): The Qualified Health Plan (QHP) amount for the FSA. (nullable) - `rxAmount` (number(double)): The prescription (Rx) amount for the FSA. (nullable) - `visionAmount` (number(double)): The vision care amount for the FSA. (nullable) - `dentalAmount` (number(double)): The dental care amount for the FSA. (nullable) - `clinicalAmount` (number(double)): The clinical care amount for the FSA. (nullable) - `copayAmount` (number(double)): The copay amount for the FSA. (nullable) - `transitAmount` (number(double)): The transit amount for the FSA. (nullable) - `partialAuthSupport` (boolean): Whether partial authorization is supported for this transaction. FSA/HSA card acceptance effectively requires partial auth per IRS Rev. Rul. 2003-43 / Notice 2006-69 and SIGIS merchant operating rules: cardholders frequently have mixed eligible and ineligible purchases, and partial auth lets the FSA-eligible portion approve even when the full transaction exceeds the FSA balance. - `lodging` ([LodgingData](https://devportal.demo.winkpg.io/docs/api/models/LodgingData.md)): Lodging detail for a stay-related transaction, for merchants transacting under a lodging industry. Conditional: When Lodging is not null. Fields: - `checkInDate` (string(date)): The date the guest checked in, or is expected to. (nullable) - `checkOutDate` (string(date)): The date the guest checked out, or is expected to. (nullable) - `nights` (integer(int32)): How many nights the stay covers. Conditional: When Nights is not null. Range: 1 to 99. (nullable) - `folioNumber` (string): The property's own reference for the guest's bill. (nullable, max length 22) - `saleCode` ([LodgingSaleCode](https://devportal.demo.winkpg.io/docs/api/models/LodgingSaleCode.md)): What kind of lodging charge this is. Conditional: When SaleCode is not null. (nullable) Values: - `Sale`: An ordinary stay, settled against the guest's folio. - `NoShow`: A guaranteed reservation the guest did not arrive for, charged under the property's no-show policy. - `Deposit`: An advance deposit taken against a future stay. - `DelayedCharge`: A charge added after the guest checked out, for something attributable to the stay (a bar tab posted late, a room found damaged). - `ExpressService`: Express checkout: the folio is settled without the guest presenting the card again. - `AssuredReservation`: A reservation the property guaranteed to hold, which is what makes a later NoShow chargeable. - `chargeDescriptor` ([LodgingChargeDescriptor](https://devportal.demo.winkpg.io/docs/api/models/LodgingChargeDescriptor.md)): Which part of the property the charge arose in. Conditional: When ChargeDescriptor is not null. (nullable) Values: - `Lodging`: A room charge. The ordinary case. - `Restaurant`: A restaurant charge. - `GiftShop`: A gift-shop charge. - `HealthClub`: A health-club or spa charge. - `HairSalon`: A hair-salon charge. - `ConventionFees`: A convention or meeting-room fee. - `TennisClub`: A tennis-club charge. - `GolfShop`: A golf-shop charge. - `extraCharges` ([LodgingExtraCharges](https://devportal.demo.winkpg.io/docs/api/models/LodgingExtraCharges.md)): The ancillary items the folio included beyond the room. Conditional: When ExtraCharges is not null. Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names. (nullable) Values: - `None`: Room charges only. An explicit statement, not an absent one. - `Restaurant`: Restaurant charges. - `GiftShop`: Gift-shop charges. - `MiniBar`: Mini-bar charges. - `Telephone`: Telephone charges. - `Laundry`: Laundry charges. - `Other`: Charges that fit none of the named categories. - `extraChargeAmount` (number(double)): How much of the amount is accounted for by `extraCharges`. Conditional: When ExtraChargeAmount is not null. Must be > 0. (nullable) - `preferredCustomer` (boolean): Whether the guest is enrolled in the property's loyalty programme. (nullable) - `softDescriptor` ([SoftDescriptor](https://devportal.demo.winkpg.io/docs/api/models/SoftDescriptor.md)): Soft descriptor information for the transaction. Fields: - `altMerchantName` (string): The alternative merchant name. (nullable, max length 30) - `altMerchantAddress` ([Address](https://devportal.demo.winkpg.io/docs/api/models/Address.md)): The alternative merchant address. - `duplicateCheck` (boolean): Indicates whether to perform a duplicate check for the transaction. Omit the field to let the merchant's screening configuration decide, which is what happens today. Send false to waive the check, which the merchant must have permitted. Sending true never turns screening on for a merchant who has not configured it. (nullable) - `register` ([TransactionRegister](https://devportal.demo.winkpg.io/docs/api/models/TransactionRegister.md)): Register information for the transaction. Fields: - `id` (string(uuid)): The unique identifier for the transaction register. - `name` (string): The name of the transaction register. (nullable) - `invoiceData` ([Invoice](https://devportal.demo.winkpg.io/docs/api/models/Invoice.md)): Invoice data associated with the transaction, carrying the customer and the amounts. Required: Conditional (see validator source). Fields: - `customerId` (string(uuid)): The unique identifier of the customer associated with this invoice. (nullable) - `amounts` ([TrxAmounts](https://devportal.demo.winkpg.io/docs/api/models/TrxAmounts.md)) required: The amounts associated with this invoice. - `isEstimatedAmount` (boolean): Value indicating whether the amount on this invoice is estimated. (nullable) - `isTaxExempt` (boolean): Value indicating whether this invoice is tax exempt. (nullable) - `shippingAddress` ([Address](https://devportal.demo.winkpg.io/docs/api/models/Address.md)): The shipping address for this invoice. - `originalTransaction` ([OriginalTransaction](https://devportal.demo.winkpg.io/docs/api/models/OriginalTransaction.md)): Data about the original transaction; a `Return` that names one is paid to the original's card or bank account. Fields: - `transactionId` (string): The unique identifier for the transaction. (nullable) - `pnRef` (integer(int32)): The PNRef (Processor's Reference Number) for the transaction. (nullable) - `authCode` (string): The authorization code for the transaction. (nullable) - `transactionType` ([TransactionType](https://devportal.demo.winkpg.io/docs/api/models/TransactionType.md)): The transaction type of the original transaction. (nullable) Values: - `Authorization`: Represents an authorization transaction, typically used to verify funds availability without capturing the amount. - `Sale`: Represents a sale transaction, which authorizes and captures funds in a single step. - `Return`: Represents a return transaction, used to refund money to the customer. - `Void`: Represents a void transaction, used to cancel a previously authorized transaction before it is settled. - `Force`: Represents a force transaction, typically used to manually enter a previously authorized transaction. - `Capture`: Represents a capture transaction, used to capture funds from a previously authorized transaction. - `CaptureAll`: Represents a capture all transaction, used to capture funds from multiple previously authorized transactions. - `RepeatSale`: Represents a repeat sale transaction, used to process a new sale based on a previous transaction's details. - `Adjustment`: Represents an adjustment transaction, used to modify the amount of a previous transaction. - `Activate`: Represents an activate transaction, typically used to activate a gift card or prepaid card. - `Deactivate`: Represents a deactivate transaction, typically used to deactivate a gift card or prepaid card. - `Redeem`: Represents a redeem transaction, typically used to redeem value from a gift card or loyalty program. - `Inquire`: Represents an inquire transaction, used to check the status or balance of an account or card. - `Reload`: Represents a reload transaction, typically used to add value to a gift card or prepaid card. - `VoucherClear`: Represents an offline EBT voucher clear: a terminal was offline, a paper food-stamp (SNAP) or eWIC voucher was written against a voice-obtained approval code, and the voucher is later uploaded so the benefit clears. Permitted on EBT SNAP and eWIC tenders only. - `Payout`: Represents a payout transaction, used to push funds from the merchant to an external bank account as an ACH credit. Unlike Return, which refunds a prior debit, a payout is a standalone outbound fund transfer with no originating transaction. - `entryMode` ([EntryModes](https://devportal.demo.winkpg.io/docs/api/models/EntryModes.md)): The entry mode used in the original transaction, if available. (nullable) Values: - `Unknown`: The entry mode is unknown. - `NotApplicable`: The entry mode is not applicable for this transaction. - `Manual`: The transaction details were entered manually. - `UnencryptedCardReaderSwipe`: The card was swiped through an unencrypted card reader. - `EncryptedCardReaderSwipe`: The card was swiped through an encrypted card reader. - `Icc`: The transaction was processed using an ICC (Integrated Circuit Card) or chip card. - `Proximity`: The transaction was processed using a proximity or contactless payment method. - `Fallback`: The transaction was processed using a fallback method when the primary method failed. - `TechnicalFallback`: The transaction was processed using a fallback method when the primary method failed. - `EmptyCandidateFallback`: The transaction was processed using a fallback method when the primary method failed. - `DigitalWallet`: The transaction was processed using a digital wallet. - `paymentMethodsGranular` ([PaymentMethodsGranular](https://devportal.demo.winkpg.io/docs/api/models/PaymentMethodsGranular.md)): The granular payment method used in the original transaction. (nullable) Values: - `Amex`: American Express card. - `Discover`: Discover card. - `Visa`: Visa card. - `MasterCard`: MasterCard. - `JCB`: Japan Credit Bureau card. - `CUP`: China UnionPay card. - `Diners`: Diners Club card. - `Debit`: Debit card. - `Ebt`: Electronic Benefit Transfer. - `Ach`: Automated Clearing House. - `Check`: Check payment. - `Cash`: Cash payment. - `Generic`: Generic or unspecified payment method. - `ApplePay`: Apple Pay digital wallet. - `GooglePay`: Google Pay digital wallet. - `DigitalWallet`: Generic / unspecified digital wallet. - `Paze`: Paze digital wallet. - `AlternativePayment`: An alternative payment method approved inside a provider (PayPal, Venmo, Pay Later, Affirm, Klarna, Afterpay) and presented to the gateway as an approval reference. - `sureChargeAmt` (number(double)): The surcharge amount from the original transaction. (nullable) - `authAmt` (number(double)): The authorized amount from the original transaction. (nullable) - `totalAmt` (number(double)): The total amount from the original transaction. (nullable) - `customFields` (array<[TrxCustomField](https://devportal.demo.winkpg.io/docs/api/models/TrxCustomField.md)>): Custom fields for the transaction. Conditional: When CustomFields is not null. (nullable) Fields of each item: - `id` (string(uuid)): Identifier of the custom-field entry. (nullable) - `name` (string) required: Name of the merchant's custom-field definition this value belongs to. Required, at most 50 characters, and free of control characters. On the authenticated API the name must match an enabled custom-field definition configured for the transaction's merchant. (nullable, max length 50) - `value` (string): Value captured for the field. At most 300 characters and free of control characters; printable punctuation is accepted. Any narrower format constraint comes from the regular expression and maximum length on the merchant's field definition. (nullable, max length 300) - `values` (array): The list of values captured for a multi-value field, in the order submitted. At most 250 items; each item is at most 300 characters, non-empty and free of control characters. Accepted only when the merchant's field definition is flagged multi-value, where the definition's own maximum length, regular expression and value cap apply to every item. (nullable, max items 250) - `signatureData` ([SignatureData](https://devportal.demo.winkpg.io/docs/api/models/SignatureData.md)): Signature data for the transaction. Fields: - `signatureType` ([SignatureTypes](https://devportal.demo.winkpg.io/docs/api/models/SignatureTypes.md)): The type of signature. Values: - `Signature1`: Represents the first signature type. - `Signature2`: Represents the second signature type. - `Signature3`: Represents the third signature type. - `Signature4`: Represents the fourth signature type. - `HypercomLegacy`: Represents the legacy Hypercom signature type. - `HypercomEnhanced`: Represents the enhanced Hypercom signature type. - `Receipt1`: Represents the first receipt signature type. - `data` (string): The signature data. (nullable) - `level2Data` ([Level2Data](https://devportal.demo.winkpg.io/docs/api/models/Level2Data.md)): Level 2 data for the transaction (e.g., tax, purchase order). Fields: - `poNumber` (string): The purchase order number. (nullable, max length 25) - `transactionDate` (string(date-time)): The date and time of the transaction. (nullable) - `merchantZip` (string): The zip code of the merchant. (nullable, max length 10) - `level3Data` ([Level3Data](https://devportal.demo.winkpg.io/docs/api/models/Level3Data.md)): Level 3 data for the transaction (e.g., line item details). Fields: - `shipFromZip` (string): The ZIP code from where the item is shipped. Conditional: When ShipFromZip is not null. Max length: 10. (nullable, max length 10) - `destinationZip` (string): The destination ZIP code for the shipment. Conditional: When DestinationZip is not null. Max length: 10. (nullable, max length 10) - `destinationCountryCode` (string): The destination country code for the shipment (ISO 3166-1 alpha-3 format). Conditional: When DestinationCountryCode is not empty. Pattern: ^[A-Z]{3}$. (nullable, max length 3) - `invoiceNumber` (string): The invoice number associated with the transaction. Conditional: When InvoiceNumber is not null. Max length: 25. (nullable, max length 25) - `orderNumber` (string): The order number for the transaction. Conditional: When OrderNumber is not null. Max length: 25. (nullable, max length 25) - `dutyAmount` (number(double)): The total duty amount for the transaction. Must be non-negative. Conditional: When DutyAmount is not null. Must be >= 0. (nullable) - `freightAmount` (number(double)): The total freight/shipping amount for the transaction. Must be non-negative. Conditional: When FreightAmount is not null. Must be >= 0. (nullable) - `discountAmount` (number(double)): The total discount amount applied at the header level. Must be non-negative. Conditional: When DiscountAmount is not null. Must be >= 0. (nullable) - `lineItems` (array<[Level3LineItem](https://devportal.demo.winkpg.io/docs/api/models/Level3LineItem.md)>) required: The list of line items associated with the transaction. (nullable, max items 250) - `ebt` ([EbtData](https://devportal.demo.winkpg.io/docs/api/models/EbtData.md)): EBT voucher data for the transaction (offline SNAP / Cash voucher-clear flow). Fields: - `voucherNumber` (string): The EBT voucher number captured during an offline food-stamp voucher-clear. Flows through to TSYS `CcBenefit1.VoucherNumber` and Fiserv `EbtGrp.VoucherNum`. (nullable, min length 0, max length 10) - `voucherApprovalCode` (string): The offline EBT voucher approval code (the legacy `EbtVoucherCode`). Flows through to TSYS `CcBenefit1.VoucherCode`. (nullable, min length 0, max length 10) - `useInterchangeDefaults` (boolean): Indicates whether to use interchange defaults for the transaction. (nullable) - `skipOrderDataDefaults` (boolean): When true, the server does not apply the merchant's configured Level 2/3 defaults to the transaction. Set by the Virtual Terminal when the operator chose "Enter Manually" in the BIN-driven prompt. API submissions usually leave this null. (nullable) - `captureType` ([CaptureTypes](https://devportal.demo.winkpg.io/docs/api/models/CaptureTypes.md)): The capture type for the transaction. Values: - `Credit`: Represents a credit card transaction. - `Debit`: Represents a debit card transaction. - `Check`: Represents a check transaction. - `EBT`: Represents an Electronic Benefit Transfer (EBT) transaction. - `responseData` ([TransactionResponseData](https://devportal.demo.winkpg.io/docs/api/models/TransactionResponseData.md)): Response data for the transaction. Fields: - `cardValidationData` ([CardValidationData](https://devportal.demo.winkpg.io/docs/api/models/CardValidationData.md)): The card validation data associated with the transaction. - `resultCode` ([ResultCode](https://devportal.demo.winkpg.io/docs/api/models/ResultCode.md)): The result code of the transaction. Defaults to ResultCode.Undefined. Values: - `Ok`: Indicates a successful operation. - `UserAuthenticationFailed`: Indicates that user authentication has failed. - `InvalidTransaction`: Indicates that the transaction is invalid. - `InvalidTransactionType`: Indicates that the transaction type is invalid. - `InvalidAmount`: Indicates that the amount specified in the transaction is invalid. - `InvalidMerchantInfo`: Indicates that the merchant information provided is invalid. - `InvalidRegisterInfo`: Indicates that the register information provided is invalid. - `FieldFormatError`: Indicates an error in the format of a field. - `NotATransactionServer`: Indicates that the server is not a transaction server. - `InvalidParameterStream`: Indicates that the parameter stream is invalid. - `TooManyLineItems`: Indicates that there are too many line items in the transaction. - `ClientTimeoutWaitingForResponse`: Indicates that the client timed out while waiting for a response. - `Decline`: Indicates that the transaction was declined. - `Referral`: Indicates that the transaction requires a referral. - `TransactionTypeNotSupportedInThisVersion`: Indicates that the transaction type is not supported in the current version. - `Partial`: Indicates a partial completion of the transaction. - `DuplicateBatchProcessed`: Indicates that a duplicate batch has been processed. - `IndeterminateBatchState`: Indicates that the batch state is indeterminate. - `Reject`: Indicates that the transaction was rejected. - `OriginalTransactionIdNotFound`: Indicates that the original transaction ID was not found. - `CustomerReferenceNumberNotFound`: Indicates that the customer reference number was not found. - `AccountNumberTruncated`: Indicates that the account number was truncated. - `InvalidAbaNumber`: Indicates that the ABA (American Bankers Association) number is invalid. - `InvalidAccountNumber`: Indicates that the account number is invalid. - `InvalidExpirationDate`: Indicates that the expiration date is invalid. - `TransactionTypeNotSupportedByHost`: Indicates that the transaction type is not supported by the host. - `InvalidReferenceNumber`: Indicates that the reference number is invalid. - `InvalidReceiptInformation`: Indicates that the receipt information is invalid. - `InvalidCheckHolderName`: Indicates that the check holder name is invalid. - `InvalidCheckNumber`: Indicates that the check number is invalid. - `CheckDlVerificationRequiresDlState`: Indicates that check DL verification requires a DL state. - `PaymentTypesDoNotMatch`: Indicates that the payment types do not match. - `InvalidVNumber`: Indicates that the V number is invalid. - `Submit`: Indicates that the transaction should be submitted. - `Pend`: Indicates that the transaction is pending: nothing was created and nothing went wrong, the outcome is simply not final yet. - `InsufficientFundsAvailable`: Indicates that there are insufficient funds available for the transaction. - `GeneralError`: Indicates a general error has occurred. - `TimeoutValueTooSmall`: Indicates that the timeout value is too small. - `ProcessorNotAvailable`: Indicates that the processor is not available. - `ErrorReadingResponseFromHost`: Indicates an error occurred while reading the response from the host. - `TimeoutWaitingForProcessorResponse`: Indicates a timeout occurred while waiting for the processor response. - `CreditError`: Indicates a credit error has occurred. - `HostNotAvailable`: Indicates that the host is not available. - `DuplicateSuppressionTimeout`: Indicates a timeout occurred during duplicate suppression. - `VoidError`: Indicates an error occurred during a void operation. - `TimeoutWaitingForHostResponse`: Indicates a timeout occurred while waiting for the host response. - `DuplicateTransaction`: Indicates that the transaction is a duplicate. - `CaptureError`: Indicates an error occurred during capture. - `FailedAvsCheck`: Indicates that the AVS (Address Verification System) check failed. - `CannotExceedSalesCap`: Indicates that the transaction cannot exceed the sales cap. - `NetworkNotFound`: Indicates that the network was not found. - `ReversalError`: Indicates an error occurred during reversal. - `InvalidIssuer`: Indicates that the issuer is invalid. - `InvalidIndustry`: Indicates that the industry is invalid. - `InvalidCompliance`: Indicates that the compliance is invalid. - `RegisterNotAuthenticated`: Indicates that the register is not authenticated. - `RegisterAuthenticationFailed`: Indicates that register authentication failed. - `RegisterAlreadyAuthenticated`: Indicates that the register is already authenticated. - `ProcessorNotConfigured`: Indicates that no active processor profile is configured for the transaction's payment method. This is a merchant configuration issue, not a communications failure. - `PinDebitNotSupportedOnCreditBin`: Indicates that the request carried PIN data while the resolved BIN funding source is Credit. A credit BIN cannot take a PIN debit authorization, so the request contradicts itself rather than merely being underspecified, and the gateway rejects it before the processor sees it. - `CardNotAcceptedByMerchantPolicy`: Indicates that the merchant's card acceptance policy refuses this card. The card was judged from its BIN by funding source, issued entity and issuer country, and one of those axes is one the merchant has configured itself not to take. - `ThreeDSecureAuthenticationRequired`: Indicates that the merchant requires 3-D Secure authentication on this kind of transaction and the transaction arrived without a usable authentication: none ran, the issuer did not authenticate the cardholder, or the result the pipeline was handed failed validation. - `CashAmountExceedsMerchantPolicy`: Indicates that a cash sale is above the largest cash sale the merchant's cash policy allows. - `CashRegisterRequiredByMerchantPolicy`: Indicates that a cash sale names no register (till) and the merchant's cash policy requires one. - `CashSourceNotAllowedByMerchantPolicy`: Indicates that a cash sale came from a source other than the Virtual Terminal and the merchant's cash policy takes cash at the Virtual Terminal only. - `GenericHostError`: Indicates a generic host error. - `InvalidLogin`: Indicates that the login is invalid. - `InsufficientPrivilege`: Indicates insufficient privileges for the operation. - `InvalidLoginBlocked`: Indicates that the invalid login has been blocked. - `InvalidLoginDeactivated`: Indicates that the invalid login has been deactivated. - `TransactionTypeNotAllowed`: Indicates that the transaction type is not allowed. - `UnsupportedProcessor`: Indicates that the processor is not supported. - `InvalidRequestMsg`: Indicates that the request message is invalid. - `InvalidVersion`: Indicates that the version is invalid. - `PaymentTypeNotSupported`: Indicates that the payment type is not supported. - `ErrorStartingTransaction`: Indicates an error occurred while starting the transaction. - `ErrorFinishingTransaction`: Indicates an error occurred while finishing the transaction. - `ErrorCheckingDuplicate`: Indicates an error occurred while checking for duplicates. - `NoRecordsToSettle`: Indicates that there are no records to settle. - `NoRecordsToProcess`: Indicates that there are no records to process. - `MustSettleAllPaymentTypes`: Indicates that all payment types must be settled. - `InvalidPoNumber`: Indicates that the PO (Purchase Order) number is invalid. - `FraudControlDecline`: Indicates a fraud control decline. - `FraudControlAuthAndHold`: Indicates a fraud control authorization and hold. - `FraudControlNoAuthAndHold`: Indicates a fraud control with no authorization and hold. - `FraudControlAudit`: Indicates a fraud control audit. - `PolicyRejected`: The transaction was rejected by the merchant's own address verification (AVS) or security code (CVV) policy rather than by the issuer. Not an error: the request was answered, and the answer is on the transaction. responseData.declineReasonCode says which of two shapes it took, using the published decline reason vocabulary (/docs/decline-reason-codes on the developer portal): CV_REJECTED when the processor approved and the platform then released the hold with a reversal or void, and CV_NATIVE_DECLINE when the processor applied the rule itself and declined outright, so no hold was ever placed. - `Undefined`: Indicates an undefined or unspecified result. - `resultMessage` (string): The result message of the transaction. For successful (Ok) transactions this is normalized against a case-insensitive allow-list of canonical approved messages ("Approved", "Card OK", "Partial Approval"); when the trimmed processor text matches the allow-list its original casing is preserved, otherwise the message is rewritten to "Approved" so the UI/transaction explorer does not surface processor-specific AVS/CVV chatter (e.g. TSYS host text like "NO MATCH") as if it were a transaction-level outcome. For non-Ok results the trimmed processor text passes through verbatim so decline/error reasons remain actionable. The processor's original message (leading/trailing whitespace trimmed but otherwise untouched) is preserved on `originalProcessorMessage` for audit/diagnostics. (nullable) - `originalProcessorMessage` (string): The processor's result text as returned by the processor handler, prior to approved-message normalization. Trimmed of leading/trailing whitespace but otherwise unmodified: preserves processor context (e.g. "APPROVED - {host text}", "NO MATCH") that `resultMessage` may have collapsed to a generic "Approved" for UI consumption. Null when the processor supplied no text or only whitespace. (nullable) - `debitTraceNumber` (string): The debit trace number for the transaction. (nullable) - `resultDetail` (string): Gets or sets additional details about the transaction result. (nullable) - `authorizationCode` (string): The authorization code for the transaction. (nullable) - `responseDate` (string(date-time)): The date and time when the response was received. (nullable) - `authorizingNetworkId` (string): Identifies which network authorized the transaction, as the processor labelled it. A short code from the processor's own vocabulary (Fiserv sends one to three alphanumerics; Paymentech sends a name-like token such as "VISA"), constant across every transaction that routed the same way. It is not a per-transaction identifier: to match a single authorization back to the network, read `networkReferenceId` instead. Fiserv sends this and `authorizingNetworkName`; Paymentech sends this alone. Null when the processor supplied no network identification. (nullable) - `authorizingNetworkName` (string): The authorizing network's name, when the processor sends one alongside `authorizingNetworkId`. Fiserv sends it; Paymentech sends no name, so this stays null there. Like the id, it identifies the routing, not the transaction. (nullable) - `routingIndicator` ([RoutingIndicator](https://devportal.demo.winkpg.io/docs/api/models/RoutingIndicator.md)): The routing indicator for the transaction. (nullable) Values: - `ProcessedAsCredit`: Indicates that the transaction was processed as a credit transaction. - `ProcessedAsDebit`: Indicates that the transaction was processed as a debit transaction. - `ProcessedAsStarSignatureDebit`: Indicates that the transaction was processed as a Star Signature debit transaction. - `customerSignatureRecommended` (boolean): Value indicating whether a customer signature is recommended. - `processorResponseDetail` ([ProcessorResponseDetail](https://devportal.demo.winkpg.io/docs/api/models/ProcessorResponseDetail.md)): Gets or sets detailed response information from the processor. - `associationResponseCode` ([AssociationResponseCode](https://devportal.demo.winkpg.io/docs/api/models/AssociationResponseCode.md)): The association response code for the transaction. (nullable) Values: - `ExpiredCard` - `AccountUpgrade` - `PortfolioSale` - `Conversion` - `NewAccountInfoAvailable` - `AccountClosedFraudulent` - `RetryWith3ds` - `OverCreditLimit` - `InsufficientFunds` - `responseCategoryCode` ([ResponseCategoryCode](https://devportal.demo.winkpg.io/docs/api/models/ResponseCategoryCode.md)): The response category code for the transaction. (nullable) Values: - `IssuerNeverApproves`: Indicates that the issuer never approves this type of transaction. - `IssuerCannotApprove`: Indicates that the issuer cannot approve this transaction at this time. - `DataQualityRevalidate`: Indicates that the data quality needs to be revalidated. - `cardIndicator` (string): The card indicator for the transaction. (nullable) - `detailedProductId` (string): The detailed product ID associated with the transaction. (nullable) - `clientIpAddress` (string): The client's IP address for the transaction. (nullable) - `amounts` ([ResponseAmounts](https://devportal.demo.winkpg.io/docs/api/models/ResponseAmounts.md)): The response amounts for the transaction. - `settlementXmlData` (string): Settlement data received from the processor. The stored value is a masked sentinel (`"****"`) that indicates settlement data was received and processed, without exposing the original content. (nullable) - `processorResponseCode` (string): Processor-specific response code (e.g., "00" for approved). (nullable) - `processorTraceNumber` (string): Retrieval reference number / trace number from processor. (nullable) - `networkReferenceId` (string): The per-transaction reference the card network assigned at authorization: the Visa Transaction Identifier, the Mastercard BankNet reference, or the equivalent on another network. It identifies this one authorization and is the value to quote when matching a single transaction back to the network or anchoring a stored-credential chain to it. Null when the processor returned no such reference. It is not the name or code of the network that authorized: that is `authorizingNetworkId` and `authorizingNetworkName`. Fiserv and Paymentech return no per-transaction reference at all, so this is null on those rails, except that during a transitional compatibility window it repeats their `authorizingNetworkId` so integrations reading it here keep working. Read `authorizingNetworkId` for a network identity; that window will close. (nullable) - `processorTransactionId` (string): Processor transaction identifier. (nullable) - `transactionNumber` (string): Transaction number from processor. (nullable) - `batchNumber` (string): Batch number from processor. (nullable) - `authorizationSource` (string): Authorization source indicator. (nullable) - `declineReasonCode` (string): Why the transaction did not go through, as one value from the platform's processor-agnostic decline reason vocabulary (for example `DO_NOT_HONOR`, `INSUFFICIENT_FUNDS`, `CV_REJECTED`). Populated on a declined, failed, or policy-rejected result and absent on an approval. The vocabulary is the same whichever processor handled the authorization: the processor's own code is on `processorResponseCode`. Every value, its meaning, and whether an authorization hold was placed and released, is published on the developer portal at `/docs/decline-reason-codes`. Branch on this field rather than on `declineReasonDescription`. (nullable) - `declineReasonDescription` (string): A readable description of the decline that goes with `declineReasonCode`, in the processor's or the platform's own words (for example `Insufficient Funds`). Wording can change without notice; the stable value to branch on is `declineReasonCode`, whose vocabulary is published on the developer portal at `/docs/decline-reason-codes`. (nullable) - `settlementAmount` (number(double)): Settlement amount from processor. (nullable) - `settlementDate` (string(date-time)): Settlement date from processor. (nullable) - `cardLevelResults` (string): Card level results (A/B/C for Visa/MC card levels). (nullable) - `returnedAci` (string): The Returned ACI (Authorization Characteristics Indicator) the network echoed back on the authorization response, stored as the raw single-character code. It reports how the transaction actually qualified (for CPS and related programs), which can differ from the ACI the gateway requested. Meanings are processor-specific, so the friendly description is resolved at display time from the transaction's processor key via `ReturnedAciCatalog` rather than persisted here. Null when the processor returned no ACI (blank / space-filled) and on every non-card flow. Non-sensitive protocol metadata. (nullable) - `posDataCode` (string): POS data code. (nullable) - `validationCode` (string): Validation code from processor. (nullable) - `additionalProcessorData` (object): Additional processor-specific response data, keyed by merchant-facing display label. Populated by the per-processor detail-extraction registry (`ProcessorDetailExtractionExecutor`) from the processor's settlement/detail aggregate at authorization time. Every key is governed by the registry's PCI allowlist (`ProcessorDetailPciPolicy`), which is what makes this dictionary safe on all three surfaces it reaches: the merchant-facing transaction DTO, outbound webhook projection, and the transaction history `DetailsJson` copy of the `/ResponseData` patch. Card number, track, EMV, CVV, and expiration can never land here. Size is capped by `ProcessorDetailBudget` because the history copy duplicates this value per entry. Not queryable: `/ResponseData/AdditionalProcessorData/*` is index-excluded. A field that needs server-side filtering or reporting must be promoted to a typed property instead. (nullable) - `eci` (string): Electronic Commerce Indicator returned by the network, canonicalized by the processor's detail adapter (upper-cased, whitespace-trimmed, leading zeros preserved: `05` and `5` are distinct ECI values). Promoted to a typed property because it is network-defined, normalizable across processors, and used for interchange-qualification reporting. `null` when the processor returned none. (nullable) - `entryDataSource` (string): Entry data source indicator describing how the card data reached the terminal (keyed, swiped, contactless, stored credential), canonicalized by the processor's detail adapter. Promoted because entry mode is semantically common across processors and drives downgrade/qualification analysis. `null` when the processor returned none. (nullable) - `requestedAci` (string): Authorization Characteristics Indicator the gateway requested for this authorization, extracted from the processor's settlement/detail aggregate. Promoted to a typed, queryable property rather than left in `additionalProcessorData`, because dictionary values can never be queried server-side. `null` when the processor returned none. What a difference from `returnedAci` means depends on the processor. On a processor whose requested value is an interchange qualification tier, a returned value differing from the requested one means the transaction downgraded to a costlier tier. On Fiserv it does not: the requested value there is a participation request drawn from P, I, Y, R rather than a tier, and the gateway sends Y on every Visa credit authorization and sale, so a requested Y against a returned A, E or W is the normal qualified outcome. On that rail the not-qualified signal is a returned N or T. Read the pair per processor; a single cross-processor comparison rule would report Fiserv downgrades that did not happen. (nullable) - `hostReferenceNumber` (string): An opaque, processor-assigned reference for this transaction that the gateway quotes back to the same processor on a follow-up operation. Which processor identifier it holds depends on the processor, and on TSYS on the product path as well, so neither its format nor its meaning is stable across processors. It is not a retrieval reference number on every processor, it is not an acquirer reference number, and it is not a network reference: an integrator wanting a standard identifier should read `processorTraceNumber` (the retrieval reference / trace number) or `networkReferenceId` (the network transaction reference) instead of this property. Per processor: on Fiserv it is the authorization network trace id, and the same value is also reported in `processorTraceNumber`, so the two are equal. On Paymentech it is the host retrieval reference number, which is likewise also reported in `processorTraceNumber`. On TSYS it is the host transaction id for ecommerce, retail, retail card-not-present, EMV retail, healthcare, non-EMV PIN debit and the partially approved EBT branch, and the retrieval reference number for the approved EBT branch, for EMV PIN debit and on the reversal path. On MagTek DAF it is the Magensa transaction id. On VeriCheck and VeriCheck v2 it is the provider's payment uuid. On the loopback simulator it is `null`. (nullable) - `achTraceNumber` (string): NACHA-format ACH trace number echoed back by the ACH processor (15 characters: 8-digit Originating Depository Financial Institution identifier + 7-digit sequence). Stable for the logical transaction lifecycle: capture, refund, reversal, and return responses repeat the trace assigned at authorization so downstream consumers can correlate the lifecycle to a single ACH entry. Null on card flows. (nullable) - `nachaReturnCode` (string): NACHA return code (e.g. `R01`, `R02`, `R10`) when the ACH transaction was returned by the receiving bank. `null` on approved/pending entries and on all card flows. The full canonical list is R01 through R85 per the NACHA Operating Rules. (nullable) - `nachaReturnReason` (string): Human-readable reason text paired with `nachaReturnCode` (for example "Insufficient Funds" for R01, "Account Closed" for R02). Surfaced verbatim in the audit log and transaction explorer to spare consumers from maintaining their own code-to-reason mapping. Null when `nachaReturnCode` is null. (nullable) - `effectiveEntryDate` (string(date)): The effective entry date the ACH entry will post to the receiving account, in the originator's local processing window. After the daily NACHA cutoff this rolls forward to the next banking day. Null on card flows. (nullable) - `originatingDfi` (string): ABA routing number of the Originating Depository Financial Institution that transmitted the entry on behalf of the gateway/merchant. Null on card flows. (nullable) - `secCode` (string): Standard Entry Class code echoed from the request: for example `PPD`, `CCD`, `WEB`, `TEL`, `ARC`. Mirrors `secCode` as a string so the response shape matches raw NACHA carrier fields rather than the gateway's enum representation. Null on card flows. (nullable) - `micrEcho` (string): Verbatim echo of the inbound MICR line when the request carried check-image data (POP, ARC, BOC). Null for non-image ACH flows (PPD, CCD, WEB, TEL) and on all card flows. (nullable) - `tokenResult` ([TransactionTokenResult](https://devportal.demo.winkpg.io/docs/api/models/TransactionTokenResult.md)): When the card on this transaction was vaulted (HPP / VT save-card-on-payment), the merchant-facing token the gateway generated, so it can be retrieved from the transaction response / HPP callback / webhook and charged later. `null` when the card was not tokenized. Server-produced; never accepted on a create request. The internal vault id is on `Transaction.PaymentTokenId` and is not emitted here. . - `processorTokenId` (string): Reusable processor token captured from the processor at authorization time (TSYS wire path first). Populated only on a successful tokenizing auth: an auth the gateway gated on (SaveCardRequested AND the routed processor advertises tokenization AND the merchant preference), otherwise `null`. This identifier is PAN-correlating. It is encrypted at rest, is never returned on the merchant-facing transaction, and is never included in an outbound webhook. (nullable) - `processorTokenStatus` (string): The processor's status for the token minted on this auth (e.g. active / provisioned). Non-sensitive processor metadata; `null` on non-tokenizing auths. (nullable) - `tokenRequestorId` (string): The network Token Requestor ID the token was minted under, echoed back by the processor. Non-sensitive scheme/config identifier; `null` when not applicable. (nullable) - `processorTokenProfileId` (string(uuid)): The processor profile id the token was minted under, so a later stored-credential charge can be routed through the same processor profile. `null` on non-tokenizing auths. (nullable) - `isPartialApproval` (boolean): Whether the issuer approved less than the amount requested (a partial approval). `amounts.requested` and `amounts.approved` give the two amounts, and `amounts.balanceDue` the shortfall. Absent when the issuer approved the full amount. (nullable) - `settleData` ([TransactionSettleData](https://devportal.demo.winkpg.io/docs/api/models/TransactionSettleData.md)): Settlement data for the 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) - `processorKey` (string): The processor type key (e.g. "tsys", "fiserv") that processed this transaction. Display-only: set during authorization and not modifiable via create/update. (nullable) - `sourceData` ([TransactionSourceData](https://devportal.demo.winkpg.io/docs/api/models/TransactionSourceData.md)): Gets or sets the source data associated with the transaction. Conditional: When SourceData is not null. Fields: - `source` ([TransactionSource](https://devportal.demo.winkpg.io/docs/api/models/TransactionSource.md)): The primary source of the transaction (virtual terminal, API, etc.). (nullable) Values: - `Unknown`: The source of the transaction is unknown or not specified. - `VirtualTerminal`: The transaction originated from a virtual terminal interface. - `Api`: The transaction was initiated through an API call. - `HostedPaymentPage`: The transaction was processed via a hosted payment page. - `RecurringBilling`: The transaction is part of a recurring billing cycle. - `OfflineBatch`: The transaction was processed as part of an offline batch. - `Invoicing`: The transaction is an automatic charge against an invoice (e.g. a recurring-invoice auto-charge or a smart-retry attempt) submitted by the Invoicing module. - `hostedPaymentPageId` (string(uuid)): When `source` is `HostedPaymentPage`, this is the ID of the hosted payment page where the transaction was run. (nullable) - `contractId` (string(uuid)): When `source` is `RecurringBilling`, this is the ID of the recurring billing contract. (nullable) - `offlineBatchId` (string(uuid)): When `source` is `OfflineBatch`, this is the ID of the batch which submitted the transaction. (nullable) - `invoiceId` (string(uuid)): When `source` is `Invoicing`, this is the ID of the invoice the automatic charge (or smart-retry attempt) is settling. Stamped server-side by the Invoicing module's auto-charge executor; the join key used to reconcile the resulting transaction back onto the invoice. (nullable) - `apiKeyId` (string(uuid)): When `source` is `Api`, this is the ID of the api key used to submit the transaction. (nullable) - `apiKeyName` (string): The name associated with the API key used as the source of the transaction. (nullable) - `usedHppSession` (boolean): Indicates the transaction was initiated via an HPP pre-filled session. Set to `true` when a session was resolved and consumed during form submission. (nullable) - `usedManualStoredPaymentMethodAdd` (boolean): Indicates the transaction is the internal account verification run when a payment method is manually added as a stored payment method from the Customers back office. Set by the server only. Any value a client supplies on a create request is discarded, so this field is read-only for API callers. (nullable) - `hppSessionId` (string(uuid)): The ID of the Hosted Payment Page session that produced this transaction. Populated only when the transaction was created through the HPP session flow; `null` for every other source (Virtual Terminal, API, recurring billing, offline batch, and HPP submits that did not resolve a session). This is a stable, server-supplied join key: integrators that drive transactions through the HPP session API can read it back from the transaction to correlate the originating session without subscribing to completion events. Distinct from `hostedPaymentPageId`, which identifies the reusable page template rather than the single-use session. Read-only from a client's perspective: the value is stamped server-side only on the verified HPP-session create path. Any value supplied on an inbound create request is ignored and overwritten with `null`, so it cannot be used to fabricate a session-to-transaction correlation. (nullable) - `campaignId` (string(uuid)): The campaign the payment link that produced this transaction belonged to, when it belonged to one. `null` for every transaction created outside a campaign, which is every transaction created before campaigns existed and every one whose link named no campaign. Stamped server-side on the verified HPP-session create path from the session document, exactly like `hppSessionId`, and scrubbed to `null` on every other create entrypoint. A campaign report is a claim about which links earned which money, so a value a caller could supply would let one merchant's traffic be attributed to a campaign it never ran. (nullable) - `campaignSource` (string): The per-channel source tag carried by the payment link that produced this transaction (`email`, `sms`, `qr`, `social`), when the link carried one. Bounded and normalized by `CampaignSourceRules`; `null` when the link named no source. Meaningful only alongside `campaignId`: it is the breakdown inside one campaign, not a standalone classification. Server-stamped and client-scrubbed on the same terms as `campaignId`. (nullable) - `promotionCode` (string): The promotion code that discounted this transaction, in the platform's normalized casing, or `null` when no promotion was applied, which is every transaction created before promotions existed and every one the payer entered no code on. Stamped server-side on the verified HPP-session create path from a re-evaluation the gateway performed itself, exactly like `campaignId`, and scrubbed to `null` on every other create entrypoint. A discount is money the merchant gave away, so a value a caller could supply would let anyone holding a payment link record a promotion the merchant never issued. (nullable) - `discountAmount` (number(double)): The amount the promotion took off the base of this transaction, or `null` when none was applied. A record of what was discounted, not a component of what was charged: the base on `TrxAmounts` is already the discounted figure, so this never participates in any total. It is what makes the reduction legible afterwards, on a receipt, a report and the promotion's own redemption ledger. Server-stamped and client-scrubbed on the same terms as `promotionCode`, and meaningful only alongside it. (nullable) - `clientIpAddress` (string): The IP address of the client that initiated the transaction. Null for system-initiated transactions (recurring billing, offline batch). (nullable) - `clientIpGeo` ([ClientIpGeoSnapshot](https://devportal.demo.winkpg.io/docs/api/models/ClientIpGeoSnapshot.md)): Point-in-time geolocation / ISP / ASN snapshot resolved at the enrichment stage from `clientIpAddress`. Snapshot: does NOT update if the underlying IP intelligence database changes. Once written by the enrichment pipeline this value is immutable; subsequent transaction operations (capture, refund, reversal, repeat, recurring-billing materializations) must not overwrite it. Null when no client IP was available (system-initiated transactions, or when the IP geo provider could not resolve the address: loopback / private / unrouted ranges). - `clientDevice` ([ClientDeviceSnapshot](https://devportal.demo.winkpg.io/docs/api/models/ClientDeviceSnapshot.md)): Browser context of the client that submitted the transaction: the user agent and the accept-language header, as observed at create time. Server-stamped from the request on every surface the platform hosts (hosted payment page, virtual terminal), and accepted from the request body on the API, where the caller is the only party that has seen the shopper's browser. Preserved rather than overwritten when a caller supplies it, exactly like `clientIpAddress`. Null for system-initiated transactions (recurring billing, offline batch), for every transaction created before this field existed, and for any caller that sends neither header. Absent rather than empty when there is nothing to record. Conditional: When ClientDevice is not null. - `screeningDeviceSignals` (object): Device signals collected by an external screening provider's own client-side agent, keyed by the registered screening provider id (a Riskified beacon session id under `riskified`, a FraudLabs Pro agent checksum under `fraudlabspro`). A provider's agent runs in the shopper's browser and hands back an opaque token that only that provider can interpret; the token is the join key between what the agent observed and the screening call the gateway later makes. Keyed by provider id so a merchant running two providers keeps the two tokens apart, and so the screening request builder can hand each provider only its own: see `TryGetScreeningDeviceSignal`, which is the only sanctioned read. These are provider session tokens, so they are never logged and never leave the transaction document except on the screening call to the provider that issued them. Null when no agent ran, which is every transaction created before this field existed and every transaction on a surface that renders no agent. Absent rather than empty, for the reason given on `clientDevice`. (nullable) - `createdByUserId` (string(uuid)): The user ID of the user who created the transaction. Null for anonymous or system-initiated transactions. (nullable) - `metadata` (object): Optional extra metadata for future sources or provider-specific data. (nullable) - `tags` (array<[EntityTag](https://devportal.demo.winkpg.io/docs/api/models/EntityTag.md)>): Tags associated with the transaction. (nullable) Fields of each item: - `name` (string): (nullable, min length 0, max length 50) - `value` (string): (nullable, min length 0, max length 150) - `notes` (array<[EntityNote](https://devportal.demo.winkpg.io/docs/api/models/EntityNote.md)>): Notes associated with the transaction. (nullable) Fields of each item: - `id` (string(uuid)) - `enteredBy` (string(uuid)) - `timestamp` (string(date-time)) - `enteredByName` (string): Denormalized display name of the user who created the note. Populated at creation time from `ICurrentUser` to avoid N+1 lookups when rendering. (nullable) - `content` (string): (nullable, min length 0, max length 1000) - `merchantTransactionId` (integer(int64)): The unique identifier of the merchant transaction. (nullable) - `idempotencyKey` (string): Your own identifier for this create request, used to make a retry safe. Send the same value again and the gateway returns the transaction the first request produced instead of charging a second time. This is the recommended pattern for reconciling a create whose response you never received. (nullable) - `receiptIds` (array): List of receipt IDs generated for this transaction. Used for point-read access to receipts. Stored as strings: see `receiptIds` remarks for rationale. Read-only: set by the server; ignored on the AutoMapper write maps. (nullable, read only) - `decisionNotes` (array<[TransactionDecisionNote](https://devportal.demo.winkpg.io/docs/api/models/TransactionDecisionNote.md)>): System-emitted decision explanations recorded against this transaction, surfaced read-only on the transaction-detail view. Like `receiptIds`, this is server state: it is populated on load for display but ignored on the create/update write maps, so a client can never persist decision notes. (nullable) Fields of each item: - `category` ([TransactionDecisionNoteCategory](https://devportal.demo.winkpg.io/docs/api/models/TransactionDecisionNoteCategory.md)): The subsystem that made the decision. Values: - `ConvenienceFee`: The convenience-fee evaluator (first consumer). - `Surcharge`: The surcharge eligibility pipeline. Records why a surcharge was not applied to a transaction on an enabled merchant (e.g. debit/prepaid card, restricted state, unsupported network), so the veto reason is queryable/displayable rather than buried in the /SurchargeResult snapshot. The code is a SurchargeIneligibilityReason value name. - `FraudReview`: The manual fraud-review hold. Records that a transaction was parked for human disposition and how that hold ended, so the timeline explains a gap between screening and authorization rather than leaving an operator to infer it from /FraudReviewData. The code is one of ReviewHeld, ReviewApproved, ReviewDeclined, or ReviewExpired. - `outcome` ([TransactionDecisionNoteOutcome](https://devportal.demo.winkpg.io/docs/api/models/TransactionDecisionNoteOutcome.md)): The decision's effect on the transaction. Values: - `Applied`: The thing was applied (e.g. a fee was assessed). - `Suppressed`: The thing was deliberately not applied (e.g. a fee was waived/suppressed). - `Adjusted`: The thing was applied at a modified value (e.g. a capped/percentage amount). - `Blocked`: The transaction was blocked by the decision. - `Info`: Purely informational; no effect on amounts or flow. - `severity` ([TransactionDecisionNoteSeverity](https://devportal.demo.winkpg.io/docs/api/models/TransactionDecisionNoteSeverity.md)): Display severity (styling only). Values: - `Info`: Neutral/informational styling. - `Warning`: Attention styling (e.g. an expected fee that did not apply). - `createdAt` (string(date-time)): UTC timestamp the note was recorded. - `code` (string): The discriminated reason within the `category` (e.g. `"SuppressedChannel"`). Owned by the consuming subsystem; resolved to copy with `category` at render time. (nullable) - `amountDelta` (number(double)): Signed amount impact where meaningful (e.g. the waived/assessed fee). Currency is implied by the transaction. Null when not applicable. (nullable) - `occurredOnStage` (string): Optional pipeline stage the decision occurred on, for ordering/diagnostics. (nullable) - `initiationType` ([InitiationType](https://devportal.demo.winkpg.io/docs/api/models/InitiationType.md)): Identifies whether this transaction was initiated by the cardholder (CIT) or the merchant (MIT). (nullable) Values: - `CardholderInitiated`: The cardholder is present or otherwise authorizing this specific charge contemporaneously. Default for transactions originated by the cardholder through HPP checkout, API with cardholder interaction, or virtual terminal sales with the cardholder present. - `MerchantInitiated`: The merchant is initiating this charge without contemporaneous cardholder authorization, relying on prior consent captured on an earlier cardholder-initiated transaction. Used for recurring billing, unscheduled credential-on-file charges, resubmissions, and other merchant-triggered uses of a stored credential. - `mitReason` ([MITReasonCode](https://devportal.demo.winkpg.io/docs/api/models/MITReasonCode.md)): For merchant-initiated transactions, the reason code justifying the MIT. Null for CITs. (nullable) Values: - `Recurring`: Fixed or variable charges on a scheduled basis for a subscription or ongoing service the cardholder has enrolled in. - `Installment`: A series of charges dividing a known total amount over a defined schedule. - `UnscheduledCOF`: Charges triggered by a specific, pre-agreed event (e.g. account balance threshold, usage overage). Not on a schedule. - `Resubmission`: Recharging after a declined or reversed transaction, in accordance with card network resubmission rules. Must be for the same amount as the original declined attempt and within the network's permitted resubmission window. - `Reauthorization`: Re-authorizing a prior authorization (e.g. when the original authorization has expired but the merchant still intends to capture). - `DelayedCharge`: A charge finalized after the cardholder's original authorization (e.g. tip adjustment, additional services added after checkout, or final amounts determined after service completion). - `NoShow`: No-show or cancellation fee where the cardholder made a reservation or booking and failed to cancel within the required window. - `IncrementalAuth`: Additional authorization on top of a prior authorization (e.g. hotel incidentals, car rental overages). - `storedCredentialConsentId` (string(uuid)): Reference to the `StoredCredentialConsent` that authorizes this MIT. Null for CITs. Optional, and best omitted: when it is absent the server resolves the consent from the stored credential itself (resolved from the token plus `InvoiceData.CustomerId`) and selects the most recently captured one that permits the declared MIT reason. Send a value only to pin a specific consent when the credential carries several, for example after a re-enrollment, and only when the value is a consent identifier this platform issued for that same credential (from a capture response, a consent lookup, or a webhook). A supplied value is validated strictly and is rejected if it belongs to a different credential, has been revoked, or does not permit the declared reason. Note that a credential whose consent lineage predates this platform's consent tracking has no consent record at all: an identifier minted by a prior system is never valid here, so such a charge is rejected with `stored_credential_consent_required` whether or not this field is sent. Remediate by having the merchant attest the credential, which mints a new platform consent; the charge then succeeds with the field omitted, and the newly issued identifier is accepted when sent. (nullable) - `schemeTransactionId` (string): The card network's trace ID for this transaction chain. Captured from the processor response on the initial CIT and referenced on subsequent MITs. Read-only: set by the server; ignored on the AutoMapper write maps. (nullable, read only) - `cardholderPresence` ([CardholderPresence](https://devportal.demo.winkpg.io/docs/api/models/CardholderPresence.md)): How present the cardholder is at the point of sale, separate from the physical entry mode. Drives network-level presence indicators (e.g. TSYS `POSEnvironmentIndicator`) at auth time. `null` means "let the classifier infer from EntryMode + Source". Conditional: When CardholderPresence is not null. (nullable) Values: - `Unknown`: Presence not specified by the request. Handlers fall back to entry-mode and industry-type inference, then to the legacy default for the merchant's profile. - `CardPresent`: Cardholder physically present at the point of sale (retail/in-store flow). - `MOTO`: Mail-order / telephone-order: cardholder not present and the merchant captured the account number through a non-electronic channel (fax, phone, paper form). - `ECommerce`: E-commerce: cardholder not present and the transaction was originated through a website, mobile application, or other electronic channel. - `Recurring`: Recurring / subscription: cardholder is not contemporaneously present; the merchant is charging a stored credential against a prior cardholder authorization. - `specialCondition` ([SpecialCondition](https://devportal.demo.winkpg.io/docs/api/models/SpecialCondition.md)): Visa/MC special-condition tag (quasi-cash, quasi-MOTO). `null` defaults to `None`. Drives TSYS `SpecialConditionIndicator` + `CardholderId` when set to `QuasiCash`. Conditional: When SpecialCondition is not null. (nullable) Values: - `None`: No special condition applies: standard purchase semantics. - `QuasiCash`: Quasi-cash purchase: a transaction that resembles cash equivalent (money orders, foreign currency, traveler's cheques, gaming chips, casino vouchers, etc.). Triggers TSYS SpecialConditionIndicator=8 and requires a populated CardholderId on the network request. - `QuasiMoto`: Quasi-MOTO: a card-present capture that the merchant is required to process under MOTO routing rules (e.g. cert scenarios, specific Visa product types). Distinct from QuasiCash: the merchant remains in retail context but presence flags flip to MOTO for network routing. - `processorCertificationOverrides` ([ProcessorCertificationOverrides](https://devportal.demo.winkpg.io/docs/api/models/ProcessorCertificationOverrides.md)): Per-processor certification override knobs. Production traffic must leave this `null`; `ICertificationOverridesGate` rejects requests where it is set unless the merchant is flagged as a test merchant AND the active processor profile has `AcceptCertificationOverrides` enabled. Fields: - `$processor` (string) required: Type discriminator naming the processor these certification overrides target. Required whenever processorCertificationOverrides is supplied. Accepted values: "fiserv", "paymentech", "tsys". Values are lower-case and case-sensitive. Values: - `fiserv` - `paymentech` - `tsys` - `cumulativeRefundedAmount` (number(double)): Running total of refund amounts applied to this transaction. Read-only: computed from refund operations. (nullable, read only) - `cumulativeReversedAmount` (number(double)): Running total of reversal amounts applied to this transaction. Read-only: computed from reversal operations. (nullable, read only) - `authorizedAmount` (number(double)): The immutable amount the issuer authorised at the close of the Authorization stage. Read-only: set once at `CloseAuthorization`. UI uses this rather than `ResponseData.Amounts.Approved` for remaining-balance calculations because reversal contributors overwrite `/ResponseData` with the processor's reversal-response payload. (nullable, read only) - `saveCardRequested` (boolean): Operator (VT) or cardholder (HPP) opt-in to save the card for future merchant-initiated use. Honored only from the Virtual Terminal and the Hosted Payment Page, which capture the required cardholder consent; a transaction create API request that sets it to true is rejected with a validation error. Auth-time-only: it cannot be set on updates or on subsequent operations. (nullable) - `isAccountVerification` (boolean): When `true`, this transaction is a zero-dollar account verification rather than a charge: the gateway authorizes for $0 to confirm card validity (with AVS/CVV) and immediately voids the authorization. Used by the Hosted Payment Page "save card only: don't charge me" flow to vault a card without charging it. Mutually exclusive with a non-zero amount. Auth-time-only: the AutoMapper Update and recurring-billing maps both ignore it so it cannot be set on subsequent operations. `null` (the default) is an ordinary chargeable transaction. (nullable) - `convenienceFeeDisclosureAcknowledgedAt` (string(date-time)): UTC timestamp of the moment the payer accepted the disclosed convenience fee (the confirm-click, NOT the submit). This is the caller's attestation that the fee was disclosed and agreed to, and it is required on any request charging a non-zero `invoiceData.amounts.convenience` on a card tender, alongside `convenienceFeeDisclosureChannel`. The Virtual Terminal stamps it from its confirm modal (the CSR attesting as the cardholder's proxy) and the Hosted Payment Page from the cardholder's own acceptance; a direct API integration owns its own disclosure UX and supplies the same attestation. It may not sit more than a few minutes ahead of the gateway's clock: a disclosure cannot have been accepted after the request that reports it. Auth-time-only: the AutoMapper Update and recurring-billing maps both ignore it, so it cannot be set on subsequent operations. `null` when no fee was charged. An ACH / e-check debit is out of scope; a convenience fee on an EBT / eWIC tender is prohibited outright and rejected before this field is examined. (nullable) - `convenienceFeeDisclosureChannel` (string): The surface on which the convenience-fee disclosure was shown and accepted. One of `"VirtualTerminal"`, `"HostedPaymentPage"`, or `"Api"` (a direct integration's own checkout); matched case-insensitively, and any other value is rejected. Paired with `convenienceFeeDisclosureAcknowledgedAt` and required on the same requests. Auth-time-only. (nullable, max length 64) - `convenienceFeeEligibilitySnapshot` (string): Serialized convenience-fee eligibility decision (reason code + assessed amount) captured at disclosure-acknowledgment time. Codes / amounts only: no request- or response-derived free text (PCI). Gateway-produced and optional: the Virtual Terminal and Hosted Payment Page serialize their own fee decision into it, and a direct API integration has no equivalent internal decision to record, so it is never required. Auth-time-only. (nullable, max length 2048) - `convenienceFeeCancelledAmount` (number(double)): The convenience-fee amount, in the transaction currency, the Virtual Terminal operator declined on the disclosure-confirm modal, removing it from this submission. Set by the VT cancel path (button, X, or Esc) so the authorization pipeline can record a `CsrCancelledVtModal` convenience-fee decision note carrying the amount that was waived: the fee is gone from the amounts by submit time, so the evaluator has nothing left to explain without this marker. Audit-only. It never adds to any total, never reaches the processor, and is honoured only when the submitted transaction carries no convenience fee, originates from the Virtual Terminal, and belongs to a merchant with an active convenience-fee configuration. Auth-time-only: the AutoMapper Update and recurring-billing maps both ignore it. `null` (the default) on every submission where no disclosed fee was cancelled. (nullable) - `surchargeDisclosureAcknowledgedAt` (string(date-time)): UTC timestamp captured at the surcharge disclosure confirm-click moment (NOT at submit). Set by the Virtual Terminal confirm modal / HPP acceptance when a surcharge is disclosed and agreed. Auth-time-only: the AutoMapper Update and recurring-billing maps both ignore it so it cannot be set on subsequent operations. `null` when no surcharge disclosure was acknowledged. (nullable) - `surchargeDisclosureChannel` (string): Channel on which the surcharge disclosure was acknowledged (`"VirtualTerminal"`, `"HostedPaymentPage"`, or `"Api"`). Paired with `surchargeDisclosureAcknowledgedAt`. Auth-time-only. (nullable) - `achWebAuthorizationText` (string): The NACHA WEB single-debit authorization language shown to the payer, captured verbatim at ACH submit on the Hosted Payment Page. The consent evidence NACHA requires to substantiate an internet-initiated (WEB) ACH debit. Auth-time-only: the AutoMapper Update and recurring-billing maps both ignore it so it cannot be set on subsequent operations. `null` for non-ACH tenders. PCI-safe: authorization language only. (nullable) - `achWebAuthorizationTextVersion` (string): Stable version hash (`sha256:{hex}`) of `achWebAuthorizationText`. Auth-time-only. (nullable) - `achWebAuthorizationConsumerIp` (string): Consumer IP recorded at ACH WEB authorization time (required NACHA evidence). On the anonymous Hosted Payment Page create path the server derives this from the incoming request and ignores a caller-supplied value. Auth-time-only. `null` for non-ACH tenders. (nullable) - `achWebAuthorizationAt` (string(date-time)): UTC timestamp of the ACH WEB authorization. Server-stamped on create; a client-supplied value is never trusted. Auth-time-only. `null` for non-ACH tenders. (nullable) - `achWebAuthorizationSecCode` (string): SEC code the ACH WEB authorization was captured under (always `"WEB"` for HPP ACH). Auth-time-only. `null` for non-ACH tenders. (nullable) - `achAuthorizationAttested` (boolean): Operator attestation signal for a Virtual Terminal CSR-keyed ACH debit: `true` when the operator confirmed they obtained the account holder's authorization (TEL or PPD) for the debit. This is a transient input only: the server consumes it to gate the submit (fail-closed when a VT ACH debit is not attested) and to stamp the persisted `AchAuthorization*` evidence fields; it is never persisted on its own. `null` / `false` for non-VT-ACH tenders and for callers that do not attest. (nullable) - `achAuthorizationStatementText` (string): The CSR attestation statement captured for a Virtual Terminal CSR-keyed ACH debit (NACHA TEL / PPD). Server-owned: rendered from the selected SEC code and stamped at create time, never trusted from the client. Auth-time-only: the AutoMapper Update and recurring-billing maps both ignore it so it cannot be set on subsequent operations. `null` for non-VT-ACH tenders. PCI-safe: authorization language only. (nullable) - `achAuthorizationStatementVersion` (string): Stable version hash (`sha256:{hex}`) of `achAuthorizationStatementText`. Server-recomputed from the statement text; a client-supplied value is never trusted. Auth-time-only. (nullable) - `achAuthorizationSecCode` (string): SEC code the VT ACH authorization was captured under (`"TEL"` or `"PPD"`). Server-owned from the operator's selection on `CheckData.SecCode`. Auth-time-only. `null` for non-VT-ACH tenders. (nullable) - `achAuthorizationChannel` (string): Channel on which the VT ACH authorization was attested (`"VirtualTerminal"`). Server-owned. Auth-time-only. `null` for non-VT-ACH tenders. (nullable) - `achAuthorizationAt` (string(date-time)): UTC timestamp of the VT ACH authorization. Server-stamped on create; a client-supplied value is never trusted. Auth-time-only. `null` for non-VT-ACH tenders. (nullable) - `requestedSplitTenderTotal` (number(double)): The total of the whole order, when you know before submitting that the customer will pay for it with more than one card. This transaction is charged for its own amount; once it is approved, it stays open as the first payment of a split tender collecting toward this total, and each further card is posted to `POST /api/transactions/{id}/split-tender/continuations`. Conditional: When RequestedSplitTenderTotal is not null. (nullable) - `deferPartialApprovalAcknowledgment` (boolean): Set to `true` to decide a partial approval yourself instead of having it accepted for you. When the issuer approves less than the requested amount, the transaction then waits in the `SplitTenderPending` stage, and `partialApprovalData.dispositionDeadlineUtc` says when it will be voided automatically. Before then, decide it through `POST /api/transactions/{id}/partial-approval/accept`, `/void`, or `/split-tender`. (nullable) - `cvvAlias` (string): The CVV alias for the stored card in `tokenData.token`: the `cva_` value an inbound vault route wrote in place of the CVV when it captured the card. The CVV it stands for is sent to the processor with the card, so the request carries neither the card number nor the CVV. (nullable, max length 64, pattern ^cva_[A-Za-z0-9]+$) ## See also - [All documentation](https://devportal.demo.winkpg.io/llms.txt): the machine-readable index of every public page on this site.