# GET /api/transactions/{id} Get transaction by ID Retrieves detailed information about a specific transaction by its unique identifier. **Operation ID:** `transactionsGet` ## Authorization Requires: Transactions.Reports, merchant scope. Requires API key scope: `transactions:read` Required permissions: - `Transactions.Reports` ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | id | path | yes | string(uuid) | | | suppressNulls | query | no | boolean | If true, omit properties with null values. | ## Responses ### 200 OK **Content type:** `application/json` Schema: [`TransactionDto`](https://devportal.demo.winkpg.io/docs/api/models/TransactionDto.md) Properties: - `id` (string(uuid)) - `creationTime` (string(date-time)): The date and time when this entity was created. - `creatorId` (string(uuid)): The ID of the user who created this entity. (nullable) - `lastModificationTime` (string(date-time)): The date and time when this entity was last modified. (nullable) - `lastModifierId` (string(uuid)): The ID of the user who last modified this entity. (nullable) - `isDeleted` (boolean): Indicates whether this entity has been deleted. - `deleterId` (string(uuid)): The ID of the user who deleted this entity, if it is deleted. (nullable) - `deletionTime` (string(date-time)): The date and time when this entity was deleted, if it is deleted. (nullable) - `displayGuid` (string): (nullable, read only) - `fraudScreenResult` ([FraudScreenResult](https://devportal.demo.winkpg.io/docs/api/models/FraudScreenResult.md)): Deprecated. This object is never populated: no screening provider writes it, and it is always null on the wire. It is retained for schema compatibility only. External screening outcomes are not exposed through this property. (deprecated) Fields: - `clientIpGeoLocation` ([ClientIpGeoLocation](https://devportal.demo.winkpg.io/docs/api/models/ClientIpGeoLocation.md)): The geolocation information of the client's IP address. - `shippingAddressEvaluation` ([ShippingAddressEvaluation](https://devportal.demo.winkpg.io/docs/api/models/ShippingAddressEvaluation.md)): The evaluation results for the shipping address. - `billingAddressEvaluation` ([BillingAddressEvaluation](https://devportal.demo.winkpg.io/docs/api/models/BillingAddressEvaluation.md)): The evaluation results for the billing address. - `emailAddressEvaluation` ([EmailAddressEvaluation](https://devportal.demo.winkpg.io/docs/api/models/EmailAddressEvaluation.md)): The evaluation results for the email address. - `phoneNumberEvaluation` ([PhoneNumberEvaluation](https://devportal.demo.winkpg.io/docs/api/models/PhoneNumberEvaluation.md)): The evaluation results for the customer phone number, if provided. - `usernameEvaluation` ([UsernameEvaluation](https://devportal.demo.winkpg.io/docs/api/models/UsernameEvaluation.md)): The evaluation results for the customer username, if provided. - `cardEvaluation` ([CardEvaluation](https://devportal.demo.winkpg.io/docs/api/models/CardEvaluation.md)): The evaluation results for the card used in the transaction. - `deviceEvaluation` ([DeviceEvaluation](https://devportal.demo.winkpg.io/docs/api/models/DeviceEvaluation.md)): The evaluation results for the device used in the transaction, if applicable. - `serviceId` (string): The unique identifier for the fraud screening service. (nullable) - `transactionId` (string): The unique identifier for the transaction being evaluated. (nullable) - `result` (string): The overall result/recommendation from the fraud screening service. This does not represent the approval status of the transaction at the processor, nor does it definitively indicate fraud; it is a recommendation based on the service's evaluation. (nullable) - `score` (integer(int32)): The fraud risk score for the transaction as returned by the screening service. - `merchantName` (string): (nullable) - `resultCode` ([ResultCode](https://devportal.demo.winkpg.io/docs/api/models/ResultCode.md)): (nullable, read only) 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. - `cardBrand` (string): The card brand (e.g., "VISA", "MASTERCARD") resolved from BIN data. (nullable, read only) - `extraProperties` (object): (nullable, read only) - `currentStage` ([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. - `history` (array<[TransactionHistoryItem](https://devportal.demo.winkpg.io/docs/api/models/TransactionHistoryItem.md)>): (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)>): (nullable) Fields of each item: - `appliedAtUtc` (string(date-time)) - `contributor` (string): (nullable) - `patch` ([TransactionPatchDto](https://devportal.demo.winkpg.io/docs/api/models/TransactionPatchDto.md)) - `allowedActions` (array<[TransactionOperationType](https://devportal.demo.winkpg.io/docs/api/models/TransactionOperationType.md)>): (nullable) Values: - `Capture`: Finalizes a previously-approved authorization by sending an online capture / clearing message to the processor. Moves the transaction from "funds held" to "marked for the next batch close": settlement still happens later when the merchant's batch cuts. Valid only against approved, uncaptured TransactionType.Authorization transactions; the action matrix removes Capture once the transaction is settled (Refund is the post-settlement undo). Partial captures (less than the authorized amount) are supported and release the unused portion of the issuer hold per network rules. - `Refund`: Returns funds to the cardholder by spawning a new standalone TransactionType.Return transaction linked back to the parent via OriginalTransaction.TransactionId. The new transaction flows through the normal auth + settlement pipeline rather than mutating the parent in place. Used once the parent has settled (post-batch-close), at which point Reversal and Void are no longer applicable. Refund capacity is reserved against the parent's PendingRefundAmount with optimistic concurrency so concurrent partial refunds from different callers cannot collectively exceed the parent's available balance. - `Void`: Offline ledger-only cancel: marks the transaction for exclusion from the next batch close without sending any processor message. Used pre-settlement. Acts as the fallback when the configured processor does not support online Reversal (or the reversal window has expired). The action evaluator's mutual-exclusion step drops Void from the candidate set when Reversal is also eligible: Reversal is a strict superset of Void on the same stage. Terminal once approved. - `Reversal`: Online undo: sends a processor message (0420-equivalent on card networks) that releases the issuer hold on a captured-but-not-cleared transaction and pulls the transaction from the next clearing. Distinct from Void in that an actual rails-level message is exchanged with the processor; the processor can decline. Eligible post-auth and pre-settlement against Authorization, Sale, RepeatSale, and captured Authorization stages. Per-processor support is advertised via ProcessorCapabilities.SupportsReversal and gated by ReversalWindowSeconds; the gateway falls back to Void when the processor opts out. Partial reversals (strictly less than the remaining authorized balance) are supported when the processor also advertises SupportsPartialReversal; a partial reversal leaves the transaction non-terminal until cumulative reversed equals the authorized ceiling. Once settlement has cleared, Reversal is no longer valid and Refund is the only available undo. - `Repeat`: Re-runs a previously-approved transaction with the same payment data by spawning a new transaction linked back to the parent via OriginalTransaction.TransactionId. Authorizations repeat as Authorization (re-hold funds); Sale and RepeatSale both repeat as RepeatSale. Used for recurring billing, card-on-file scenarios, and operator-initiated re-charges. The caller may supply a different amount than the original; the new transaction flows through the normal auth + settlement pipeline. Available against approved transactions in any settlement state: once an authorization has settled, Repeat is the only re-charge path (Capture is no longer eligible). - `Retry`: Re-attempts a previously declined or failed transaction with the same TransactionType and the same amount as the original: changing either would violate retry semantics. Spawns a new transaction linked back to the parent via OriginalTransaction.TransactionId. Available only when the parent ended in a non-approved result code (decline, processing error, gateway failure). Distinct from Repeat, which preserves type-mapping rules (Sale → RepeatSale) and allows a caller-specified amount; Retry is intended to recover from a transient failure on the original attempt without altering its commercial intent. - `OfflineAdjustment`: An offline adjustment to a previously-authorized transaction's settlement record: tip (gratuity), tax, level-3 data, PO number, or AVS fields. Modifies the settlement amount/data before batch close without contacting the processor network. Tip and other amount-bearing fields are constrained to industry types that allow post-auth adjustments (restaurant, retail, e-commerce). Online amount changes (incremental authorization) belong to IncrementalAuthorization. - `IncrementalAuthorization`: An online incremental (or "estimated → final") authorization on top of a previously authorized (but uncaptured) transaction. The processor sends a fresh auth message to the brand network; on approve, the transaction's Total_Auth_Amt is bumped and a new auth response (with its own customer-facing receipt) replaces the prior one. Distinct from OfflineAdjustment in that an actual rails round-trip is performed and the issuer can decline. Valid only against TransactionType.Authorization transactions that have not yet been captured. Per-processor support is advertised via ProcessorCapabilities.SupportedAdjustmentTypes; the gateway rejects the operation up front when the configured processor lacks the capability. - `AcceptPartialApproval`: Acknowledges a partial approval by keeping the reduced authorization as-is. The issuer approved less than the gateway asked for, and the operator (or the cardholder) has decided the lesser amount is acceptable, so no reversal is issued and the transaction proceeds through the normal capture / settlement path for the approved amount. Valid only while the transaction is parked at TransactionStage.SplitTenderPending with PartialApprovalData.Disposition still Pending; a late acknowledgment against a disposition the deadline sweep has already resolved is expected traffic and is rejected. Its counterpart is Void, which rejects the reduced amount instead. - `SplitTender`: Acknowledges a partial approval by keeping the reduced authorization and collecting the shortfall on a second tender. The continuation transaction carries the same SplitTenderGroupId with the next SplitTenderSequence. Valid only while the transaction is parked at TransactionStage.SplitTenderPending, and only when the merchant permits split tender and the group has not reached VirtualTerminalSettings.SplitTenderMaxTenders. - `concurrencyStamp` (string): (nullable) - `entityVersion` (integer(int32)): (read only) - `tenantId` (string(uuid)): (nullable, read only) - `transactionType` ([TransactionType](https://devportal.demo.winkpg.io/docs/api/models/TransactionType.md)): Represents the various types of transactions that can be performed in the system. 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. - `cardData` ([CardData](https://devportal.demo.winkpg.io/docs/api/models/CardData.md)): Represents the data associated with a payment card. 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)): Represents the data associated with a check transaction. 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)): The cash sale details: the cash handed over, the change returned, and when the cash was taken. Null when the transaction's request carried none. 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) - `apmData` ([ApmData](https://devportal.demo.winkpg.io/docs/api/models/ApmData.md)): The alternative-payment instrument block for a payment the payer approved inside a provider. Null on every other tender. Fields: - `providerKey` (string): The processor key of the provider that owns the approval (for example `loopback`, `paypal`). Recorded so the routing trail and every read surface can name the provider without quoting a reference. (nullable) - `fundingSource` (string): The wallet or scheme the cardholder chose inside the provider, as a `PaymentMethodKeys` alternative-payment key (`paypal`, `venmo`, `paylater`, `affirm`, `klarna`, `afterpay`). (nullable) - `providerOrderId` (string): The provider's identifier for the order or checkout session the approval belongs to. (nullable) - `approvalToken` (string): The bearer value the provider handed back for the approval, exchanged for a charge. (nullable) - `payerReference` (string): The provider's identifier for the payer, typically the email address the payer holds their provider account under. (nullable) - `providerAuthorizationId` (string): The provider's authorization identifier, written from `ProcessorOutcome.References` after the processor answers. A capture or a void quotes it. (nullable) - `providerCaptureId` (string): The provider's capture identifier, written from `ProcessorOutcome.References` after the processor answers. A refund quotes it. (nullable) - `providerRefundId` (string): The provider's refund identifier, on a refund transaction. Written by the processor when the platform asks for a refund, or by the webhook receiver when it records a refund the provider initiated; a refund webhook is matched to its refund transaction by it. (nullable) - `providerInitiatedRefund` (boolean): True on a refund transaction the platform recorded from a provider webhook rather than asked for: the merchant refunded in the provider's own dashboard, or the provider refunded on its own account. No processor was called for it; the money had already moved. (nullable) - `refundExceededCapacity` (boolean): True on a provider-initiated refund that exceeded the parent's remaining refundable amount when it was recorded. Recorded rather than rejected, because the provider has already returned the money; flagged so an operator can reconcile it. (nullable) - `providerFeeAmount` (number(double)): The fee the provider charged for the transaction, when it reported one on the response. (nullable) - `approvedAtUtc` (string(date-time)): When the provider reported the approval, in UTC. (nullable) - `clientParameters` (object): The values the provider's own button produced in the cardholder's browser, carried onto the begin-approval request the processor is dispatched with. (nullable) - `clientPassthrough` (object): Opaque provider values the processor produced that the surface which began the approval has to hand back to the provider's own script. (nullable) - `returnUri` (string): Where the provider returns the cardholder on approval, as the surface that started the approval supplied it. (nullable) - `cancelUri` (string): Where the provider returns the cardholder on cancellation, as the surface that started the approval supplied it. (nullable) - `tokenData` ([TokenData](https://devportal.demo.winkpg.io/docs/api/models/TokenData.md)): Represents tokenized payment information used to process a transaction. This model supports internal stored tokens as well as digital wallet tokens such as Internal, Apple Pay, Google Pay, and network tokens. 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)): Represents data related to a device in a transaction. 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)): Represents a Flexible Spending Account (FSA) with various amount categories and partial authorization support. 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, echoed back as it was submitted. Null on every transaction outside a lodging industry. 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)): Represents a soft descriptor for a transaction, containing alternative merchant information. 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): The duplicate-check intent the submitting request carried, echoed back as it was submitted. Null means the request expressed no opinion and the merchant's screening configuration decided, which is the value a request that omitted the field carries. False means the request asked to waive the check, and it was waived only if the merchant permits per-transaction overrides. Transactions written before this field became nullable read as false regardless of what the caller intended. (nullable) - `register` ([TransactionRegister](https://devportal.demo.winkpg.io/docs/api/models/TransactionRegister.md)): Represents a transaction register in the system. 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)): Represents an invoice in the system. 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)): Represents an original transaction with its identifying information. 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)>): (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)): Represents signature data for a 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)): Represents Level 2 data for a transaction, including purchase order information, transaction date, and merchant zip code. 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)): Represents Level 3 data for a transaction, including shipping information and line items. 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) - `orderLines` (array<[TransactionOrderLine](https://devportal.demo.winkpg.io/docs/api/models/TransactionOrderLine.md)>): The product lines of the order this transaction paid for, when it paid for one: a hosted page selling catalog products records each product, quantity, unit price and line total here for per-SKU reporting. `null` on every other transaction. Read-only: the platform writes it from the order it priced itself. (nullable) Fields of each item: - `productId` (string(uuid)): The catalog product this line sold. Indexed for per-SKU reporting. - `quantity` (number(double)): Quantity sold. - `unitPrice` (number(double)): Price per unit the payer was charged. - `lineTotal` (number(double)): `unitPrice` times `quantity`, rounded to cents. - `name` (string): Product name at the time of sale. Always written by the platform; nullable on the type so the published contract does not infer it as required on the create request the member is kept off of. (nullable) - `productCode` (string): Optional SKU. (nullable) - `unitOfMeasure` (string): Optional unit label. (nullable) - `discountAmount` (number(double)): Discount attributed to this line, if any. (nullable) - `taxAmount` (number(double)): Tax attributed to this line, if any. (nullable) - `ebt` ([EbtData](https://devportal.demo.winkpg.io/docs/api/models/EbtData.md)): Transaction-level EBT (Electronic Benefit Transfer) data for the offline SNAP / Cash food-stamp voucher-clear flow. This is the first-class home for the voucher fields that the legacy gateway stuffed into `ExtData`; it carries the scalar voucher identifiers from the request through to the processor handlers. 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): (nullable) - `captureType` ([CaptureTypes](https://devportal.demo.winkpg.io/docs/api/models/CaptureTypes.md)): Represents the types of payment capture methods available for transactions. 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)): Represents the response data for a transaction, containing various details about the transaction outcome. 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)): Represents settlement data for a transaction. Fields: - `estimatedSettleDate` (string(date-time)): The estimated settlement date for the transaction. (nullable) - `dateSettled` (string(date-time)): The actual date when the transaction was settled. (nullable) - `flag` ([SettleFlag](https://devportal.demo.winkpg.io/docs/api/models/SettleFlag.md)): Legacy settlement flag. Use `settlementStatus` instead. (deprecated) Values: - `Open`: The transaction is open and not yet settled. - `Settled`: The transaction has been successfully settled. - `RolledBack`: The transaction has been rolled back or reversed. - `InProgress`: The transaction is currently in the process of being settled. - `Hold`: The transaction is on hold and cannot be settled at the moment. - `processorBatchId` (string): The processor's batch identifier for this transaction. (nullable) - `gatewayBatchId` (string(uuid)): The gateway's batch identifier for this transaction. (nullable) - `settlementDataJson` (string): Settlement aggregate data as a JSON string (converted from processor XML). This contains the data needed to settle the transaction with the processor. Encrypted at rest. (nullable) - `settlementStatus` ([SettlementStatus](https://devportal.demo.winkpg.io/docs/api/models/SettlementStatus.md)): Current settlement status of the transaction for processor settlement tracking. Treat null as `WaitingForSettlement`. (nullable) Values: - `WaitingForSettlement`: Transaction is waiting to be settled with the processor - `SettlementSucceeded`: Settlement completed successfully with the processor - `SettlementFailed`: Settlement failed - requires review and retry (rollback) - `NotEligible`: Transaction is not eligible for settlement (voided, reversed, or not yet captured) - `SettlementInProgress`: Settlement is currently in progress with the processor. - `SettlementOnHold`: Settlement is on hold and cannot proceed at the moment. - `SettlementRolledBack`: Settlement was rolled back or reversed after a completed attempt. Distinct from SettlementFailed which indicates a transient failure needing retry. - `ReversalFailed`: A reversal was attempted but the processor did not confirm that the authorization hold was voided: the contributor saw a non-Ok result code (transport failure, timeout, swallowed exception, malformed response, etc.). Distinct from NotEligible (a confirmed reversal/void) and SettlementFailed (a settlement-time failure). Operations need to confirm the hold state with the processor and reverse manually if required. The transaction's Stage is left at the pre-reversal value; the close-stage history entry is NOT written. - `Pending`: The provider owns settlement and reports the outcome on its own schedule, so the transaction belongs to no gateway batch. Used for ACH sales and alternative payments. A background sync moves the transaction on as the provider reports, through any of the ACH in-flight statuses, to a terminal status. - `Accepted`: The ACH processor has accepted the transaction for processing. VeriCheck V2 only: the entry has been received and accepted by the payment network. - `Originated`: The ACH transaction has been originated (submitted to the NACHA network). VeriCheck V2 only: the debit has been forwarded to the RDFI. - `Verifying`: The ACH processor is verifying the bank account before origination. VeriCheck V2 only: the check runs on the processor's side, before the debit reaches the ACH network. - `PartiallySettled`: The ACH transaction has been partially settled. VeriCheck V2 only: a portion of the funds have cleared. - `settlementAttemptedAt` (string(date-time)): Timestamp when settlement was last attempted with the processor. (nullable) - `settledAt` (string(date-time)): Timestamp when settlement succeeded with the processor. (nullable) - `settlementRetryCount` (integer(int32)): Number of settlement retry attempts. Treat null as 0. (nullable) - `settlementErrorMessage` (string): Error message if settlement failed. (nullable) - `batchId` (string): Gateway batch identifier assigned at authorization time for batch boundary management. Transactions are grouped into settlement batches by this ID, which is stamped from the merchant's `CurrentBatchId` during the authorization flow. Nullable because existing documents predate this property. (nullable) - `closedSettlementBatchId` (string(uuid)): Identifier of the closed settlement batch that settled this transaction, set when the batch closes. `null` until then, and on transactions settled in batches that closed before this field was recorded. Distinct from the other batch identifiers on this type: `batchId` / `gatewayBatchId` are the open batch at authorization time, and `processorBatchId` is the processor's batch reference; none of them equals the settlement batch's id. (nullable) - `overrideHistory` (array<[SettlementStatusOverrideRecord](https://devportal.demo.winkpg.io/docs/api/models/SettlementStatusOverrideRecord.md)>): Append-only list of admin-driven manual overrides applied to `settlementStatus`. Populated by the `Transaction.OverrideSettlementStatus` domain method. Null, and omitted, on transactions that have never had a manual override (the default for the vast majority of rows). (nullable) - `source` ([TransactionSource](https://devportal.demo.winkpg.io/docs/api/models/TransactionSource.md)): (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. - `sourceData` ([TransactionSourceData](https://devportal.demo.winkpg.io/docs/api/models/TransactionSourceData.md)): Encapsulates the origin of a transaction and any source-specific identifiers. 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)>): (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)>): (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) - `merchantId` (string(uuid)) - `merchantTransactionId` (integer(int64)): (nullable) - `receiptIds` (array): List of receipt IDs generated for this transaction. (nullable) - `refundTransactionIds` (array): IDs of the linked-refund child transactions issued against this transaction (as the parent sale). Drives the detail-page reverse relationship ("Refunded by " and the Related Transactions grid). Empty/null when this transaction has no linked refunds. (nullable) - `decisionNotes` (array<[TransactionDecisionNote](https://devportal.demo.winkpg.io/docs/api/models/TransactionDecisionNote.md)>): System-emitted decision explanations recorded against this transaction, e.g. why the convenience-fee evaluator applied or suppressed a fee. Read-only on the wire: written only by server-side contributors, never by an update. Rendered on the transaction detail view via the decision-note copy resolver. (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) - `linkedFeeChargeTransactionId` (string): On a primary charge: the id of the separate convenience-fee charge linked to it (the reverse link, primary → fee), when a card-brand program required the fee to settle as its own authorization. Null when there is no linked fee charge. Server-state; read-only on the wire. See `Transaction.LinkedFeeChargeTransactionId`. (nullable) - `primaryChargeTransactionId` (string): On a convenience-fee charge: the id of the primary charge this fee is linked to (the forward link, fee → primary). Null for an ordinary transaction. Server-state; read-only on the wire. See `Transaction.PrimaryChargeTransactionId`. (nullable) - `linkedChargeKind` ([LinkedChargeKind](https://devportal.demo.winkpg.io/docs/api/models/LinkedChargeKind.md)): Why this transaction exists as a separate linked charge (currently only `ConvenienceFee`), or null when it is not a linked charge. Server-state; read-only on the wire. (nullable) Values: - `ConvenienceFee`: A separate charge submitted to carry a convenience fee that a card-brand program requires to settle as its own authorization (its own approval code), linked to the primary payment it was assessed against. - `processorProfileId` (string(uuid)): The unique identifier of the merchant processor profile that processed this transaction. (nullable) - `processorKey` (string): The processor type key (e.g., "tsys", "fiserv") used for this transaction. (nullable) - `routingResult` ([RoutingResult](https://devportal.demo.winkpg.io/docs/api/models/RoutingResult.md)): The recorded processor routing decision: the selected processor and profile, the ordered audit trail, and every evaluated candidate with its score and eliminated flag. Server-owned; never accepted on a create or update. Back-office only: always null in responses to API-key callers, and never included in outbound webhook payloads. `null` for transactions that were not routed. Fields: - `selectedProcessorKey` (string): The selected processor key. (nullable) - `selectedProcessorProfileId` (string(uuid)): The selected processor profile ID. - `routingIndicator` ([RoutingIndicator](https://devportal.demo.winkpg.io/docs/api/models/RoutingIndicator.md)): Optional routing indicator applied to 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. - `matchedRuleName` (string): The name of the merchant processor routing rule that selected the processor profile, when a rule did. `null` on every transaction a routing rule did not route. (nullable) - `auditTrail` (array<[RoutingRationale](https://devportal.demo.winkpg.io/docs/api/models/RoutingRationale.md)>): Full audit trail from the evaluation pipeline. (nullable) - `candidateSummaries` (array<[RoutingOptionSummary](https://devportal.demo.winkpg.io/docs/api/models/RoutingOptionSummary.md)>): All candidates evaluated with their final scores. (nullable) - `loopbackSimulation` ([LoopbackSimulation](https://devportal.demo.winkpg.io/docs/api/models/LoopbackSimulation.md)): What the sandbox simulator did on this transaction: the published triggers your request fired, and the response values it filled in from a default because nothing matched. Read it when a sandbox answer is not the one you expected and you want to know which trigger the sandbox saw. Each entry carries `isDefault`, which separates a trigger you sent from a value the sandbox supplied. A card-verification entry reports the response code the sandbox returned and never the security code you submitted. Server-owned: it is never accepted on a create or update, and nothing in it changes what the transaction did. `null` on every transaction the sandbox simulator did not answer, which includes every transaction a live processor handled, and on every row written before the trace existed. Fields: - `entries` (array<[LoopbackSimulationEntry](https://devportal.demo.winkpg.io/docs/api/models/LoopbackSimulationEntry.md)>): One entry per trigger the simulator honoured, plus one per response value it filled in from a default. Ordered as the simulator resolved them. (nullable) - `surchargeResult` ([SurchargeResult](https://devportal.demo.winkpg.io/docs/api/models/SurchargeResult.md)): The surcharge evaluation decision produced by the surcharge eligibility pipeline: the verdict, applied rate, cap provenance, and the per-stage audit trail. Server-owned (mapped entity -> DTO by convention; never accepted on a create/update). Back-office only: stripped for public API-key callers and anonymous callers, mirroring `routingResult`. `null` when the surcharge decision was never evaluated (no active surcharge configuration, non-card tender, or a legacy row). Fields: - `surcharged` (boolean): Whether this transaction was surcharged. - `ineligibilityReason` (string): Stable string reason code (e.g. `nameof(SurchargeIneligibilityReason.DebitCard)`) for why the transaction was not surcharged; `null` when `surcharged` is true. (nullable) - `baseAmount` (number(double)): The transaction base amount the surcharge rate was applied against, in the transaction currency. (nullable) - `baseComponents` (string): Which amount components formed `baseAmount`: `Base` (the base amount alone, the default) or `Base+Shipping` (the merchant elected a shipping-inclusive surcharge base). `null` on a decision recorded before the component was captured, which was always the base amount alone. (nullable) - `surchargeAmount` (number(double)): The computed surcharge amount, in the transaction currency; null when not surcharged. (nullable) - `appliedRate` (number(double)): The rate actually applied, as a decimal fraction (0.03 = 3%): the lesser of `merchantRate` and the caps below. (nullable) - `merchantRate` (number(double)): The merchant-configured surcharge rate at evaluation time, as a decimal fraction (0.03 = 3%). (nullable) - `networkCap` (number(double)): The card network's rate cap at evaluation time, as a decimal fraction, if applicable. (nullable) - `stateCap` (number(double)): The governing state's rate cap at evaluation time, as a decimal fraction, if applicable. (nullable) - `costOfAcceptanceCap` (number(double)): The merchant's cost-of-acceptance rate cap at evaluation time, as a decimal fraction, if applicable. (nullable) - `winningCapSource` (string): Which of `merchantRate`/`networkCap`/`stateCap`/`costOfAcceptanceCap` produced `appliedRate`. (nullable) - `cardFundingSource` (string): The card's funding source at evaluation time (e.g. "Credit", "Debit", "Prepaid"). (nullable) - `cardBrand` (string): The card brand at evaluation time (e.g. "Visa", "Mastercard"). (nullable) - `billingStateCode` (string): The cardholder billing address state code at evaluation time. (nullable) - `merchantStateCode` (string): The merchant's state code at evaluation time. (nullable) - `governingStateCode` (string): The state whose surcharge rules actually governed this evaluation. (nullable) - `channel` (string): The originating channel (e.g. "VirtualTerminal", "HostedPaymentPage", "Api"). (nullable) - `configurationId` (string(uuid)): The surcharge configuration evaluated against. (nullable) - `configurationVersion` (integer(int32)): The version of the surcharge configuration evaluated against, for audit reproducibility. (nullable) - `requiresDisclosure` (boolean): Whether the caller must present a surcharge disclosure to the cardholder. - `evaluatedAt` (string(date-time)): UTC timestamp of when the evaluation was performed. - `auditTrail` (array<[SurchargeStageOutcome](https://devportal.demo.winkpg.io/docs/api/models/SurchargeStageOutcome.md)>): Full per-stage audit trail from the eligibility pipeline, in execution order. (nullable) - `correlationId` (string): The correlation ID linking this transaction to its orchestration audit trail. (nullable) - `cumulativeRefundedAmount` (number(double)): Running total of refund amounts applied to this transaction. (nullable) - `cumulativeReversedAmount` (number(double)): Running total of reversal amounts applied to this transaction. (nullable) - `authorizedAmount` (number(double)): The immutable amount the issuer authorised at the close of the Authorization stage. UI should read this (not `responseData`.`Amounts.Approved`) when computing remaining-reversible / remaining-refundable balances, because the processor's reversal-response payload overwrites `/ResponseData` in place. Null on legacy rows that pre-date. (nullable) - `policyRejection` ([PolicyRejectionData](https://devportal.demo.winkpg.io/docs/api/models/PolicyRejectionData.md)): Audit record of the post-authorization denylist match that policy-rejected this transaction. Top-level (not nested under `responseData`) because the auto-reversal flow Sets `/ResponseData` wholesale, so anything stored there is clobbered. Null for any transaction that was not policy-rejected. Fields: - `deniedCode` (string): The AVS or CVV response code that matched the denylist (e.g. "N", "P", "S"). This is a processor result code, not the cardholder's CVV input value. (nullable) - `deniedCodeType` (string): Whether the triggering code was an AVS or CVV result. Expected values: `"Avs"` or `"Cvv"`. (nullable) - `deniedCodeDescription` (string): The logical key identifying which card verification rule fired (e.g. `"AVNoMatch"`, `"CVNoMatch"`, `"AVZipOnly"`). This is a stable machine identifier, not a user-facing sentence. The merchant detail page renders this value verbatim alongside the human-readable rule label. Safe to display to merchants: it does not reveal the cardholder's actual input. (nullable) - `ruleSource` (string): Identifies which denylist configuration rule triggered the rejection (e.g., "AvsDeclineCodes", "CvvDeclineCodes", or a merchant-specific rule name). (nullable) - `rejectedAt` (string(date-time)): UTC timestamp of the denylist evaluation that triggered this rejection. (nullable) - `reversalResultCode` ([ResultCode](https://devportal.demo.winkpg.io/docs/api/models/ResultCode.md)): The result code from the reversal or void issued after the denylist match. `null` if no reversal/void was attempted. (nullable) 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. - `reversalResultMessage` (string): The result message from the reversal or void. `null` if no reversal/void was attempted. (nullable) - `reversalAttemptedAt` (string(date-time)): UTC timestamp of the reversal or void attempt. `null` if no reversal/void was attempted. (nullable) - `requiresReversal` (boolean): Whether the orchestrator should schedule an auto-reversal for this policy rejection. `null` (the default for historical gateway-side rejections written before the field existed) is treated as "yes, reverse": the original behaviour. The native AVS/CVV decline path sets `false` because the processor declined at auth time and never placed a hold, so there is nothing to reverse and the `reversalResultCode` / `reversalAttemptedAt` fields stay null. (nullable) - `partialApprovalData` ([PartialApprovalData](https://devportal.demo.winkpg.io/docs/api/models/PartialApprovalData.md)): Durable record of a partial approval (the issuer authorized less than was requested) and the disposition decided for it. Its presence means the transaction was partially approved; null when the issuer approved in full. Fields: - `disposition` ([PartialApprovalDisposition](https://devportal.demo.winkpg.io/docs/api/models/PartialApprovalDisposition.md)): Where the partial approval currently sits in its decision lifecycle. `null` is equivalent to `Pending`: the shape a document written by the detection step alone can take. (nullable) Values: - `Pending`: The partial approval has been detected and recorded, but nobody has decided its fate yet. The transaction is holding a reduced authorization at the issuer and is waiting on an operator/cardholder acknowledgment until dispositionDeadlineUtc elapses. - `Accepted`: The reduced authorization was accepted as-is. No reversal is issued and the transaction proceeds through the normal capture/settlement path for the approved (lesser) amount. - `Voided`: The reduced authorization was rejected and reversed, so the issuer hold is released. The reason is recorded on voidReason (operator choice, acknowledgment timeout, or an automatic gateway policy void). - `SplitTenderInitiated`: The reduced authorization was kept and a follow-up tender was started to collect the shortfall. The continuation transaction carries the same SplitTenderGroupId with the next SplitTenderSequence. - `dispositionSetAtUtc` (string(date-time)): UTC timestamp of the moment `disposition` last moved. Set alongside every disposition write, including the initial transition to `Pending` at detection time, so the age of a stuck pending disposition is measurable. (nullable) - `dispositionDeadlineUtc` (string(date-time)): UTC instant by which a `Pending` disposition must be resolved before the gateway voids the reduced authorization on the operator's behalf. (nullable) - `voidReason` (string): Why the reduced authorization was voided, for the merchant audit trail. Only meaningful when `disposition` is `Voided`; `null` otherwise. (nullable) - `requestedAmount` (number(double)): The amount the gateway asked the issuer to authorize, in major currency units, snapshotted at detection time. Kept here rather than read back from the response because a subsequent reversal overwrites `/ResponseData`. (nullable) - `approvedAmount` (number(double)): The lesser amount the issuer actually authorized, in major currency units, snapshotted at detection time. The shortfall a split tender needs to collect is `requestedAmount` minus this value. (nullable) - `fraudReviewData` ([FraudReviewData](https://devportal.demo.winkpg.io/docs/api/models/FraudReviewData.md)): Durable hold state when this transaction was parked for manual fraud review: when the hold started, when it expires, what triggered it, and the disposition that was reached. Top-level rather than nested under the screening results, which are rewritten wholesale on every screening retry. Server-owned and read-only on the API surface. Null when the transaction was never held for review. Fields: - `heldAtUtc` (string(date-time)): UTC instant the transaction was parked for review. Stamped once by the screening stage. (nullable) - `deadlineUtc` (string(date-time)): UTC instant by which a `Pending` hold must be resolved before the expiry sweep dispositions it on the merchant's behalf. (nullable) - `triggeringProviderId` (string): Identifier of the screening provider whose verdict triggered the hold, matching `ExternalScreeningResult.ProviderId`. `null` when the hold came from a platform rule rather than an external provider. (nullable) - `triggeringProviderName` (string): Display name of the triggering provider as it stood at park time, snapshotted so the record still reads correctly after the merchant renames or removes the profile. (nullable) - `score` (number(double)): The normalized risk score that drove the hold, when the trigger reported one. (nullable) - `disposition` ([FraudReviewDisposition](https://devportal.demo.winkpg.io/docs/api/models/FraudReviewDisposition.md)): Where the hold currently sits in its disposition lifecycle. (nullable) Values: - `Pending`: Held and awaiting a human decision. The state the park step writes. - `Approved`: An operator released the transaction to continue processing. - `Declined`: An operator rejected the transaction. - `ExpiredApproved`: The hold deadline elapsed with no reviewer decision and the merchant's configured expiry action released the transaction to continue processing. Only the parked flow itself can produce this: approving on expiry means going on to authorize the payment. - `ExpiredDeclined`: The hold deadline elapsed with no reviewer decision and the transaction was rejected. Either the merchant configured a decline on expiry, or the backstop sweep reclaimed a hold whose flow did not survive to honor an approval. DispositionReasonCode tells the two apart. - `dispositionAtUtc` (string(date-time)): UTC instant `disposition` last moved off `Pending`. `null` while the hold is still awaiting a decision. (nullable) - `dispositionByUserId` (string(uuid)): The operator who dispositioned the hold. `null` when the expiry sweep decided it, which is exactly what distinguishes a human decision from an automatic one in the audit trail. (nullable) - `dispositionReasonCode` (string): Why the hold was dispositioned the way it was: a stable gateway-authored code, or short operator-entered text. (nullable) - `threeDSAuthentication` ([ThreeDSAuthenticationData](https://devportal.demo.winkpg.io/docs/api/models/ThreeDSAuthenticationData.md)): The 3-D Secure authentication record when this transaction was authenticated: the status the issuer reported, the ECI, whether liability shifted, the directory-server and ACS transaction identifiers, the message version, and the CAVV result code. Top-level rather than on `cardData`, whose cryptogram and ECI describe a wallet authentication instead. Server-owned and read-only on the API surface. The credential itself (CAVV / AAV) is never returned: those members are always null here. Null when no 3-D Secure authentication ran. Fields: - `providerType` ([ThreeDSProviderType](https://devportal.demo.winkpg.io/docs/api/models/ThreeDSProviderType.md)): Which 3-D Secure provider produced this authentication. (nullable) Values: - `Fake`: Deterministic in-memory provider that performs no network calls. The local-dev, CI, and default-selection provider, and the safe landing spot for an absent configuration value. - `Paay`: Paay (API brand "3DS Integrator"), reached over its Direct API. Supports authentication, the 3DS Method step, the cardholder challenge, and 3RI; it documents no decoupled or Secure Payment Confirmation capability, so the registry refuses those. - `messageCategory` ([ThreeDSMessageCategory](https://devportal.demo.winkpg.io/docs/api/models/ThreeDSMessageCategory.md)): The EMVCo message category the authentication ran under: a payment authentication or a non-payment one (adding a card on file, verifying an account). (nullable) Values: - `Payment`: Wire value 01: a payment authentication. - `NonPayment`: Wire value 02: a non-payment authentication, such as adding a card on file or verifying an account without an amount. - `threeDSVersion` (string): The 3DS message version the flow negotiated, in EMVCo dotted form (for example `2.2.0`). A string because the wire field is a string and a new version must not need a code change here. (nullable) - `threeDSServerTransactionId` (string): The 3DS server transaction identifier that correlates every message in this authentication. The one identifier a support agent needs to trace a 3DS flow end to end with the provider. (nullable) - `dsTransactionId` (string): The directory server transaction identifier, which most schemes require on the authorization and which a later merchant-initiated (3RI) authentication quotes as its prior reference. (nullable) - `acsTransactionId` (string): The access control server (issuer) transaction identifier, used to correlate a challenge with its authentication. (nullable) - `transactionStatus` ([ThreeDSTransactionStatus](https://devportal.demo.winkpg.io/docs/api/models/ThreeDSTransactionStatus.md)): The normalized EMVCo `transStatus` (wire values `Y`, `N`, `U`, `A`, `C`, `D`, `R`, `I`). This, not `liabilityShifted`, is the protocol answer; the liability flag is the interpretation. (nullable) Values: - `Unknown`: No status was reported, or the value could not be mapped. Treated as "no authentication happened": never liability-shifting. - `Authenticated`: Wire value Y: authentication or account verification succeeded. - `NotAuthenticated`: Wire value N: not authenticated, or the transaction was denied. - `Unavailable`: Wire value U: authentication could not be performed (technical or other problem). - `AttemptsProcessed`: Wire value A: an authentication attempt was performed and proof is supplied, but the cardholder was not actually authenticated (the "attempts" / stand-in path). - `ChallengeRequired`: Wire value C: a cardholder challenge is required to complete authentication. - `DecoupledChallengeRequired`: Wire value D: a decoupled cardholder challenge is required (3DS 2.2 and later). - `Rejected`: Wire value R: authentication was rejected by the issuer. - `InformationalOnly`: Wire value I: informational only. The 3DS requestor asked for information and no authentication was performed. - `transactionStatusReason` (string): The EMVCo `transStatusReason`, present when the issuer explains a non-authenticated status. (nullable) - `eci` (string): The electronic commerce indicator to forward on the authorization. Scheme-specific: Visa and Amex use `05` / `06` / `07`, Mastercard uses `02` / `01` / `00`. Distinct from the wallet `CardData.EciIndicator`, which a wallet decryption writes. (nullable) - `cavvResultCode` (string): The scheme's CAVV result code, describing how the issuer validated the credential. Metadata about the credential, not the credential, so it is merchant-safe. (nullable) - `cavvAlgorithm` (string): The algorithm the issuer used to generate the credential, where the scheme reports one. Metadata about the credential, not the credential, so it is merchant-safe. (nullable) - `liabilityShifted` (boolean): `true` when this outcome shifts chargeback liability to the issuer under the scheme's rules for the reported status and ECI. Set by the provider so the rule lives in one place per vendor; readers must not re-derive it. (nullable) - `challengeRequired` (boolean): `true` when the issuer required a cardholder challenge to complete the authentication. (nullable) - `challengeCompleted` (boolean): `true` when a required challenge ran to completion and the issuer reported its result; `false` when the cardholder abandoned it or it timed out; `null` when no challenge was required. (nullable) - `authenticationType` ([ThreeDSAuthenticationType](https://devportal.demo.winkpg.io/docs/api/models/ThreeDSAuthenticationType.md)): How the authentication reached its outcome: frictionless, challenged, an attempts stand-in, or merchant-initiated. (nullable) Values: - `Frictionless`: The issuer authenticated the cardholder from the risk data alone; no challenge was presented. - `Challenge`: The issuer required a cardholder challenge and the flow completed it (or the challenge was attempted and the issuer reported its result). - `Attempt`: The directory server or the scheme stood in for an issuer that could not authenticate and produced attempts proof (wire status A). Liability may still shift under scheme rules. - `RequestorInitiated`: A merchant-initiated (3RI) authentication with no cardholder present, run against a prior authentication. - `authenticatedAtUtc` (string(date-time)): UTC instant the authentication outcome was recorded on the transaction. (nullable) - `cavv` (string): The base64-encoded cardholder authentication verification value the issuer returned (Visa, Discover, Amex). Always sensitive: never logged, never delivered on a webhook, never written into transaction history, and masked on every read surface. `null` on a Mastercard authentication, which carries `aav` instead. (nullable) - `aav` (string): The base64-encoded accountholder authentication value (Mastercard's spelling of the same credential as `cavv`). Handled identically: always sensitive. (nullable) - `payloadDecryption` ([PayloadDecryption](https://devportal.demo.winkpg.io/docs/api/models/PayloadDecryption.md)): The provenance of the payload decryption the gateway performed through the merchant's payment encryption provider before authorization: the provider, the scheme (`DUKPT` or `ONGUARD`), the key serial identifier the request matched, the operator's key label, the outcome, the provider's region and result code, the retry count and the latency. Server-owned and read-only on the API surface. Carries no cardholder data and no key material. Null when the gateway did not decrypt the payload through a provider. Fields: - `providerName` (string): The provider that performed the decryption, as its registered name. (nullable) - `scheme` (string): The scheme that was dispatched: `DUKPT` or `ONGUARD`. (nullable) - `ksi` (string): The key serial identifier the request's key serial number matched. (nullable) - `keyLabel` (string): The operator's label for the matched key entry. Never the key reference. (nullable) - `outcome` (string): `Succeeded` or `Failed`. (nullable) - `failureCode` (string): The `Decryption:` error code when `outcome` is `Failed`; otherwise `null`. (nullable) - `providerResultCode` (string): The provider's own sanitized result code (a Futurex `AM` code, an HTTP status), carried for triage. Never the provider's error text. (nullable) - `regionUsed` (string): Which of the provider's regions or endpoints answered, as the provider labels it. (nullable) - `retryCount` (integer(int32)): How many failover retries the provider ran before answering. (nullable) - `latencyMilliseconds` (integer(int64)): How long the provider call took, in whole milliseconds. (nullable) - `decryptedAtUtc` (string(date-time)): When the decryption completed, in UTC. (nullable) - `enhancedDataQualification` ([EnhancedDataQualificationDto](https://devportal.demo.winkpg.io/docs/api/models/EnhancedDataQualificationDto.md)): The gateway's own assessment of how well this transaction's enhanced data met the commercial-card requirements, recorded when it settled. Server-owned and read-only on the API surface. Null for a transaction that has not settled, that built no enhanced-data addendum, or that settled before the gateway began recording this. Null is not the same as a clean result: a present node with a finding count of zero is the clean one. Fields: - `isPreview` (boolean): `true` when this node is a preview computed at request time rather than the record of a settlement. Absent (or `false`) on every stored result. (nullable) - `attemptedLevel` ([CedpQualificationLevel](https://devportal.demo.winkpg.io/docs/api/models/CedpQualificationLevel.md)): The addendum level the settlement set out to build from the data supplied on the transaction. (nullable) Values: - `None`: No enhanced-data addendum was attempted; the row settles at Level 1. - `Level2`: A Level 2 addendum was attempted (tax, tax-exempt flag, purchase order). - `Level3`: A Level 3 addendum was attempted (Level 2 header plus itemized line detail). - `emittedLevel` ([CedpQualificationLevel](https://devportal.demo.winkpg.io/docs/api/models/CedpQualificationLevel.md)): The addendum level that actually went to the processor. Equal to `attemptedLevel` unless the addendum was withheld, in which case `gateReason` says why. (nullable) Values: - `None`: No enhanced-data addendum was attempted; the row settles at Level 1. - `Level2`: A Level 2 addendum was attempted (tax, tax-exempt flag, purchase order). - `Level3`: A Level 3 addendum was attempted (Level 2 header plus itemized line detail). - `gateReason` (string): A stable code for the emission decision, or `null` when the addendum was sent as attempted. Never free text. (nullable) - `findings` (array<[EnhancedDataQualificationFindingDto](https://devportal.demo.winkpg.io/docs/api/models/EnhancedDataQualificationFindingDto.md)>): Every finding, in evaluation order: line-level findings first, ordered by line index. (nullable) - `findingCount` (integer(int32)): The number of findings, counting a code once per line that raised it. Zero on a transaction that was evaluated and came back clean. (nullable) - `processor` (string): The processor whose settlement produced this result, as its gateway processor key. Findings are not comparable across processors that build different addenda. (nullable) - `evaluatorVersion` (integer(int32)): The evaluator rule-set revision that produced this result. It is bumped whenever a rule is added, removed or changed, so a qualification rate trended across releases can tell a data improvement from a rule change. Absent on a result recorded before the revision was stamped. (nullable) - `evaluatedAt` (string(date-time)): When the evaluation ran, in UTC. (nullable) - `splitTenderGroupId` (string(uuid)): Groups this transaction with the other tenders that together collect one order total after a partial approval left a shortfall. Server-owned; read-only on the API surface. Null when the transaction is not part of a split tender. (nullable) - `splitTenderSequence` (integer(int32)): 1-based position within the `splitTenderGroupId` group, so the tenders can be presented in the order they were taken. Null when the transaction is not part of a split tender. (nullable) - `splitTenderRole` ([SplitTenderRole](https://devportal.demo.winkpg.io/docs/api/models/SplitTenderRole.md)): Whether this transaction is the primary tender of its split-tender group or a continuation collecting part of the remaining balance. Null when the transaction is not part of a split tender. (nullable) Values: - `Primary`: The first tender in the group: the transaction whose partial approval created the shortfall. Exactly one member of a group holds this role, and it always carries SplitTenderSequence = 1. - `Continuation`: A follow-up tender collecting part of the remaining balance. A group may hold several, ordered by SplitTenderSequence (2, 3, ...). A continuation can itself be partially approved, which starts the disposition cycle again. - `splitTenderDeclaredTotal` (number(double)): The order total a planned split tender collects toward, as declared by `requestedSplitTenderTotal` on this transaction's create request. Set on the first tender of a planned split tender only; null on every other transaction, including the first tender of a split tender started after a partial approval. (nullable) - `splitTenderDeadlineUtc` (string(date-time)): When an open planned split tender closes on its own, keeping what its payments collected, if no further payment is being authorized. Restarted each time a payment leaves the order short. Server-owned; read-only on the API surface. Null on every transaction that is not the first tender of an open planned split tender; a split tender started after a partial approval reports its deadline on `partialApprovalData` instead. (nullable) - `deferPartialApprovalAcknowledgment` (boolean): Whether this transaction's create request asked to decide a partial approval itself, as sent in `deferPartialApprovalAcknowledgment`. Null when the request did not set it. (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). Null on legacy transactions. (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 MIT transactions, the reason code justifying the merchant-initiated charge. (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 stored credential consent authorizing this MIT. (nullable) - `schemeTransactionId` (string): The card network's trace ID linking this transaction to its original CIT. (nullable) - `description` (string): The merchant-supplied free-text payment description recorded on this transaction, echoed back exactly as it was submitted. `null` when the create request carried none, in which case the processor received the gateway's own reference instead. (nullable) - `merchantReference` (string): The merchant-supplied reconciliation reference recorded on this transaction, echoed back exactly as it was submitted. `null` when the create request carried none, in which case the clearing record carried the gateway's fallback instead. (nullable) - `tender` ([TenderKind](https://devportal.demo.winkpg.io/docs/api/models/TenderKind.md)): The tender the create request explicitly declared, echoed back as it was submitted. `null` when the request declared nothing, which includes every card, check, and token transaction and any cash transaction submitted without the declaration. (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. - `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 at auth time. (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). (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. Non-null only for cert-tooling traffic. Production traffic always sees this as `null`. 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` - `refundKind` ([RefundKind](https://devportal.demo.winkpg.io/docs/api/models/RefundKind.md)): Classifies a refund transaction as linked (follow-up against a previously approved original transaction) or unlinked (standalone). `null` for non-refund transactions. (nullable) Values: - `None`: Not a refund, or kind has not been classified. Default for all non-refund transactions. - `Linked`: A refund run as a follow-up action against a previously approved and settled original transaction. The refund is a new transaction in its own right and flows through the normal auth + settlement pipeline, but carries a reference to its parent via OriginalTransaction and debits the parent's refund capacity. - `Unlinked`: A standalone refund with no parent transaction in the gateway. Submitted directly as a Return transaction without an OriginalTransaction reference. Flows through the normal auth + settlement pipeline with no capacity tracking against any prior transaction. - `pendingRefundAmount` (number(double)): Reserved-but-not-yet-completed refund amount for this transaction (as a parent), tracked separately from `cumulativeRefundedAmount` so UI can show "refund pending settlement" vs "refund completed". `null` means zero. (nullable) - `saveCardRequested` (boolean): Operator (VT) or cardholder (HPP) opt-in to save the card for future merchant-initiated use, captured at create time. Read-only on the API surface: the consumer cannot mutate it through Update calls (server-side AutoMapper ignores the field on the Update map). (nullable) - `tokenizedPaymentMethodId` (string(uuid)): The id of the customer's stored payment method created when a customer-initiated transaction was approved with `saveCardRequested` = `true`. `null` on transactions that did not request save-card, were declined, or where saving the card failed. (nullable) - `isAccountVerification` (boolean): When `true`, this transaction is a zero-dollar account verification (the HPP "save card only" flow) rather than a charge: the card was authorized for $0 to confirm it, vaulted with consent, and not charged. Read-only on the API surface; create-time-only (the Update map ignores it). `null` on ordinary chargeable transactions. (nullable) - `convenienceFeeDisclosureAcknowledgedAt` (string(date-time)): UTC timestamp when the convenience-fee disclosure was accepted (CSR-as-proxy in the Virtual Terminal, cardholder on the Hosted Payment Page, or the integrator's own checkout on a direct API create), captured at confirm-click time. Echoed back as submitted: this is the caller's attestation, set on create and never editable afterwards (the Update map ignores it). `null` when no non-zero convenience fee was charged. See `TransactionCreateOrUpdateDtoBase.ConvenienceFeeDisclosureAcknowledgedAt` for when it is required. (nullable) - `convenienceFeeDisclosureChannel` (string): The surface on which the convenience-fee disclosure was shown and accepted: `"VirtualTerminal"`, `"HostedPaymentPage"`, or `"Api"`. Set on create and never editable afterwards. (nullable) - `convenienceFeeEligibilitySnapshot` (string): Serialized convenience-fee eligibility decision (reason code + assessed amount) captured at disclosure-acknowledgment time. Codes / amounts only. Produced by the Virtual Terminal and Hosted Payment Page; optional on a direct API create. Set on create and never editable afterwards. (nullable) - `convenienceFeeCancelledAmount` (number(double)): The convenience-fee amount, in the transaction currency, the Virtual Terminal operator declined on the disclosure-confirm modal, removing it from the submission. Audit-only: it was never charged, and the matching `CsrCancelledVtModal` convenience-fee decision note carries the same amount. Read-only on the API surface. `null` when no disclosed fee was cancelled. (nullable) - `surchargeRate` (number(double)): The surcharge rate actually applied to this transaction, as a decimal fraction (0.03 = 3%). The same value as `surchargeResult`.AppliedRate, carried at the top level so it can be filtered on. `null` when no surcharge was assessed. (nullable) - `surchargeDisclosureAcknowledgedAt` (string(date-time)): UTC timestamp when the surcharge disclosure was acknowledged, captured at confirm-click time. Read-only on the API surface. `null` when no surcharge was disclosed. (nullable) - `surchargeDisclosureChannel` (string): Channel on which the surcharge disclosure was acknowledged (`"VirtualTerminal"` / `"HostedPaymentPage"` / `"Api"`). Read-only on the API surface. (nullable) - `surchargeReversedAmount` (number(double)): The portion of the assessed surcharge amount reversed by a subsequent void or refund, in the transaction currency. Read-only on the API surface. `null` when nothing has been reversed. (nullable) - `achWebAuthorizationText` (string): NACHA WEB single-debit authorization language shown to the payer, captured verbatim at ACH submit. Read-only on the API surface; delivered on the ACH completion webhook. PCI-safe. `null` for non-ACH tenders. (nullable) - `achWebAuthorizationTextVersion` (string): Version hash (`sha256:{hex}`) of `achWebAuthorizationText`. Read-only. (nullable) - `achWebAuthorizationConsumerIp` (string): Consumer IP recorded at ACH WEB authorization time (required NACHA evidence). Read-only. `null` for non-ACH tenders. (nullable) - `achWebAuthorizationAt` (string(date-time)): UTC timestamp of the ACH WEB authorization (server-stamped). Read-only. `null` for non-ACH tenders. (nullable) - `achWebAuthorizationSecCode` (string): SEC code the ACH WEB authorization was captured under (always `"WEB"`). Read-only. `null` for non-ACH tenders. (nullable) - `achAuthorizationStatementText` (string): CSR attestation statement captured for a Virtual Terminal CSR-keyed ACH debit (NACHA TEL / PPD). Read-only on the API surface; delivered on the ACH completion webhook. PCI-safe. `null` for non-VT-ACH tenders. (nullable) - `achAuthorizationStatementVersion` (string): Version hash (`sha256:{hex}`) of `achAuthorizationStatementText`. Read-only. (nullable) - `achAuthorizationSecCode` (string): SEC code the VT ACH authorization was captured under (`"TEL"` or `"PPD"`). Read-only. `null` for non-VT-ACH tenders. (nullable) - `achAuthorizationChannel` (string): Channel on which the VT ACH authorization was attested (`"VirtualTerminal"`). Read-only. `null` for non-VT-ACH tenders. (nullable) - `achAuthorizationAt` (string(date-time)): UTC timestamp of the VT ACH authorization (server-stamped). Read-only. `null` for non-VT-ACH tenders. (nullable) - `idempotencyStatus` ([CreateIdempotencyStatus](https://devportal.demo.winkpg.io/docs/api/models/CreateIdempotencyStatus.md)): What create idempotency did to the request that produced this response: whether a `idempotencyKey` was sent, whether deduplication was in effect for the merchant, and whether this response replays an earlier create. (nullable) Values: - `NotRequested`: The request carried no idempotencyKey, so there was nothing to deduplicate. A repeat send will charge again. - `KeyIgnored`: The request carried an idempotencyKey, but deduplication is not enabled for this merchant, so the key had no deduplication effect. It is stored with the transaction and remains available through the lookup-by-idempotency-key operation, but a repeat send with the same key will charge again. Ask your provider to enable deduplication for the merchant. - `KeyAccepted`: The request carried an idempotencyKey, deduplication is enabled, and this request claimed the key. This is the original create; a repeat send with the same key inside the deduplication window replays this transaction instead of charging again. - `Replayed`: The idempotencyKey matched a create that had already completed for this merchant, so nothing was charged. The response body is that original transaction exactly as it stands, original identifiers and timestamps included. - `idempotencyKey` (string): The idempotency key this transaction was created with, exactly as stored. `null` when the create request carried none. Read-only: the key is fixed at create time and an update never changes it. (nullable) _Example: Approved authorization_ A card-not-present Visa authorization the processor approved. The funds are on hold and nothing has been captured yet, so the allowed actions are to capture it, reverse it, or run it again. ```json { "id": "7d1f3a52-0c4e-4b8a-9e21-5a6b7c8d9e01", "displayGuid": "UjoffU4MikueIVprfI2eAQ", "merchantName": "Sample Merchant", "resultCode": "Ok", "cardBrand": "Visa", "extraProperties": { }, "currentStage": "Finalized", "history": [ ], "appliedPatches": [ ], "allowedActions": [ "Capture", "Reversal", "Repeat" ], "concurrencyStamp": "5b0c9e2f8d3a4f6e9a1b2c3d4e5f6a7b", "entityVersion": 0, "transactionType": "Authorization", "cardData": { "cardNumber": "************1111", "last4CardNumber": 1111, "expirationMonth": 12, "expirationYear": 2030, "binData": { "bin": 411111, "issuedEntity": "Personal", "brand": "Visa", "type": "Credit", "panLength": 16, "fundingSource": "Credit" }, "nameOnCard": "Jane Smith", "entryMode": "Manual", "cvPresence": "Submitted", "hasCvv": true }, "invoiceData": { "amounts": { "base": 25, "total": 25 } }, "customFields": [ ], "captureType": "Credit", "responseData": { "resultCode": "Ok", "resultMessage": "Approved", "authorizationCode": "A12345", "responseDate": "2026-01-15T14:30:02.0000000+00:00", "customerSignatureRecommended": false, "amounts": { "requested": 25, "approved": 25 }, "processorResponseCode": "00" }, "source": "Api", "tags": [ ], "notes": [ ], "merchantId": "00000000-0000-0000-0000-000000000001", "merchantTransactionId": 1001, "authorizedAmount": 25, "initiationType": "CardholderInitiated", "cardholderPresence": "ECommerce", "isDeleted": false, "creationTime": "2026-01-15T14:30:00.0000000+00:00" } ``` _Example: Declined sale_ A card-not-present Mastercard sale the issuer declined. responseData carries the result and the normalized decline reason; a do-not-honor decline offers no follow-up action. ```json { "id": "7d1f3a52-0c4e-4b8a-9e21-5a6b7c8d9e02", "displayGuid": "UjoffU4MikueIVprfI2eAg", "merchantName": "Sample Merchant", "resultCode": "Decline", "cardBrand": "Mastercard", "extraProperties": { }, "currentStage": "Declined", "history": [ ], "appliedPatches": [ ], "allowedActions": [ ], "concurrencyStamp": "6c1d0f3a9e4b4a7f8b2c3d4e5f6a7b8c", "entityVersion": 0, "transactionType": "Sale", "cardData": { "cardNumber": "************5454", "last4CardNumber": 5454, "expirationMonth": 12, "expirationYear": 2030, "binData": { "bin": 545454, "issuedEntity": "Personal", "brand": "Mastercard", "type": "Credit", "panLength": 16, "fundingSource": "Credit" }, "nameOnCard": "John Doe", "entryMode": "Manual", "cvPresence": "Submitted", "hasCvv": true }, "invoiceData": { "amounts": { "base": 250, "total": 250 } }, "customFields": [ ], "captureType": "Credit", "responseData": { "resultCode": "Decline", "resultMessage": "Do not honor", "responseDate": "2026-01-15T15:00:02.0000000+00:00", "customerSignatureRecommended": false, "amounts": { "requested": 250 }, "processorResponseCode": "05", "declineReasonCode": "DO_NOT_HONOR", "declineReasonDescription": "Do not honor" }, "source": "Api", "tags": [ ], "notes": [ ], "merchantId": "00000000-0000-0000-0000-000000000001", "merchantTransactionId": 1002, "initiationType": "CardholderInitiated", "cardholderPresence": "ECommerce", "isDeleted": false, "creationTime": "2026-01-15T15:00:00.0000000+00:00" } ``` _Example: Captured sale with a settlement reference_ A Visa sale that was approved, captured and settled. settleData carries the settlement state and the processor batch the sale settled in; once settled, a refund is the way to return the funds. ```json { "id": "7d1f3a52-0c4e-4b8a-9e21-5a6b7c8d9e03", "displayGuid": "UjoffU4MikueIVprfI2eAw", "merchantName": "Sample Merchant", "resultCode": "Ok", "cardBrand": "Visa", "extraProperties": { }, "currentStage": "Completed", "history": [ ], "appliedPatches": [ ], "allowedActions": [ "Refund" ], "concurrencyStamp": "7d2e1a4b0f5c4b8a9c3d4e5f6a7b8c9d", "entityVersion": 0, "transactionType": "Sale", "cardData": { "cardNumber": "************1111", "last4CardNumber": 1111, "expirationMonth": 12, "expirationYear": 2030, "binData": { "bin": 411111, "issuedEntity": "Personal", "brand": "Visa", "type": "Credit", "panLength": 16, "fundingSource": "Credit" }, "nameOnCard": "Jane Smith", "entryMode": "Manual", "cvPresence": "Submitted", "hasCvv": true }, "invoiceData": { "amounts": { "base": 45, "tax": 3.5, "total": 48.5 } }, "customFields": [ ], "captureType": "Credit", "responseData": { "resultCode": "Ok", "resultMessage": "Approved", "authorizationCode": "A67890", "responseDate": "2026-01-14T18:45:02.0000000+00:00", "customerSignatureRecommended": false, "amounts": { "requested": 48.5, "approved": 48.5 }, "processorResponseCode": "00" }, "settleData": { "dateSettled": "2026-01-15T03:00:00.0000000+00:00", "flag": "Settled", "processorBatchId": "000042", "gatewayBatchId": "3e8a6c14-2b5d-4f70-8a9c-0d1e2f3a4b05", "settlementStatus": "SettlementSucceeded", "settlementAttemptedAt": "2026-01-15T03:00:00.0000000+00:00", "settledAt": "2026-01-15T03:00:00.0000000+00:00" }, "source": "Api", "tags": [ ], "notes": [ ], "merchantId": "00000000-0000-0000-0000-000000000001", "merchantTransactionId": 1003, "authorizedAmount": 48.5, "initiationType": "CardholderInitiated", "cardholderPresence": "ECommerce", "isDeleted": false, "creationTime": "2026-01-14T18:45:00.0000000+00:00" } ``` ### 403 Forbidden **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) ### 401 Unauthorized **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) ### 400 Bad Request **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) _Example: Request failed validation_ One or more fields were rejected before any rule ran. error.code is null on the envelope and the causes are in validationErrors, one entry per failure. An entry carries code when the validator declared a publishable one, and memberPaths when the full path says more than members does (an element inside a collection, for example). Both keys are omitted when they would add nothing. ```json { "error": { "code": "null", "message": "Your request is not valid!", "details": "The following errors were detected during validation.", "data": { "correlationId": "0123456789abcdef0123456789abcdef" }, "validationErrors": [ { "message": "'Amount' must be greater than 0.", "members": [ "amount" ] }, { "message": "The card has expired.", "members": [ "expirationDate" ], "code": "CardData:CardExpired" }, { "message": "'Value' must not be empty.", "members": [ "value" ], "memberPaths": [ "customFields[2].value" ] } ] } } ``` ### 404 Not Found **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) _Example: Resource not found_ The id in the path names no record the caller can see. Most resources answer with a null error.code and a message naming the resource type and the id; a resource that publishes a not-found code in the catalog above carries it in error.code instead, so check for one before matching on the message. ```json { "error": { "code": "null", "message": "There is no entity Transaction with id = 7d1f3a52-0c4e-4b8a-9e21-5a6b7c8d9e00!", "details": "null", "data": { "correlationId": "0123456789abcdef0123456789abcdef" }, "validationErrors": "null" } } ``` ### 501 Not Implemented **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) ### 500 Internal Server Error **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) ### default The request failed. The body carries the standard error envelope: a machine-readable `error.code`, a human-readable `error.message`, and `error.validationErrors` when the failure was a validation rejection. The [error reference](https://devportal.demo.winkpg.io/docs/errors.md) lists the values `error.code` can take. **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) _Example: Business rule refused the request_ The request was understood and rejected by a platform rule. This is the shape that carries a code from the catalog above, so branch on error.code rather than on the message text. The HTTP status is the one listed against the code. ```json { "error": { "code": "Transactions:OperationNotAllowed", "message": "The operation 'Void' is not allowed on a Sale transaction with result 'Approved' and settlement state 'Settled'.", "details": "null", "data": { "correlationId": "0123456789abcdef0123456789abcdef" }, "validationErrors": "null" } } ``` ### 429 The request was refused because a rate limit was exceeded, or because something a later retry can clear stopped it. A rate limit refusal carries an `application/problem+json` body: wait at least the interval `Retry-After` names before retrying, then back off. Limits are tuned per deployment, so read the allowance from the response headers rather than assuming a fixed ceiling. Any other refusal carries the standard error envelope as `application/json`, and its `error.code` names the cause. **Content type:** `application/problem+json` Schema: [`RateLimitProblemDetails`](https://devportal.demo.winkpg.io/docs/api/models/RateLimitProblemDetails.md) Properties: - `type` (string) required: The problem type identifier. Always the same value: the failure is the status code itself, so there is no sub-type for a caller to branch on. (nullable) - `title` (string) required: A short, human-readable summary of the problem type. (nullable) - `status` (integer(int32)) required: The HTTP status code, repeated in the body as the problem-details format defines. - `detail` (string) required: A human-readable explanation of this occurrence of the problem. (nullable) - `retryAfterSeconds` (integer(int32)) required: How long to wait before retrying, in whole seconds, carrying the same figure as the `Retry-After` header. Always at least one: a value of zero would invite an immediate retry that is certain to be rejected again. **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) ## Example request Every block below sends the same request. Replace {{BASE_URL}} with the address of the API you are calling and {{API_KEY}} with your own key. ### cURL ```bash curl -X GET "{{BASE_URL}}/api/transactions/{id}" \ -H "api-key: {{API_KEY}}" ``` ### PowerShell ```powershell $headers = @{ 'api-key' = '{{API_KEY}}' } $response = Invoke-RestMethod -Method GET -Uri '{{BASE_URL}}/api/transactions/{id}' ` -Headers $headers ``` ### TypeScript (SDK) ```bash npm install @winkpg/winkpg-api ``` ```typescript import { Configuration, TransactionsApi } from '@winkpg/winkpg-api'; const api = new TransactionsApi(new Configuration({ basePath: '{{BASE_URL}}', apiKey: '{{API_KEY}}', })); const { data } = await api.transactionsGet("3fa85f64-5717-4562-b3fc-2c963f66afa6"); ``` ### TypeScript (raw HTTP) ```typescript const response = await fetch('{{BASE_URL}}/api/transactions/{id}', { method: 'GET', headers: { "api-key": "{{API_KEY}}", }, }); const data = await response.json(); ``` ### C# (SDK) ```bash dotnet add package WinkPg.Api.Client ``` ```csharp using WinkPg.Api.Client.Api; using WinkPg.Api.Client.Client; var config = new Configuration { BasePath = "{{BASE_URL}}" }; config.AddApiKey("api-key", "{{API_KEY}}"); var api = new TransactionsApi(config); var result = await api.TransactionsGetAsync(Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6")); ``` ### C# (raw HTTP) ```csharp using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") }; var request = new HttpRequestMessage(new HttpMethod("GET"), "/api/transactions/{id}"); request.Headers.Add("api-key", "{{API_KEY}}"); var response = await http.SendAsync(request); response.EnsureSuccessStatusCode(); var json = await response.Content.ReadAsStringAsync(); ``` ### Python (SDK) ```bash pip install winkpg-api ``` ```python import winkpg_api configuration = winkpg_api.Configuration(host="{{BASE_URL}}") configuration.api_key["ApiKey"] = "{{API_KEY}}" with winkpg_api.ApiClient(configuration) as client: api = winkpg_api.TransactionsApi(client) result = api.transactions_get("3fa85f64-5717-4562-b3fc-2c963f66afa6") ``` ### Python (raw HTTP) ```bash pip install requests ``` ```python import requests headers = { "api-key": "{{API_KEY}}", } response = requests.request( "GET", "{{BASE_URL}}/api/transactions/{id}", headers=headers, ) response.raise_for_status() data = response.json() ``` ## See also - [All documentation](https://devportal.demo.winkpg.io/llms.txt): the machine-readable index of every public page on this site.