# POST /api/transactions/get-transaction-by-id-async Retrieves a single transaction by its identifier. The lookup is confined to the caller's own scope. When no transaction matches, the request fails with 404 Not Found, so a successful response always carries a transaction. **Operation ID:** `transactionsGetTransactionById` ## Authorization Requires: Transactions.Reports, merchant scope. Required permissions: - `Transactions.Reports` ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | transactionId | query | no | string(uuid) | The transaction to read. | | suppressNulls | query | no | boolean | If true, omit properties with null values. | ## Responses ### 200 OK **Content type:** `application/json` Schema: `TransactionDto` 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. - `lastModificationTime` (string(date-time)): The date and time when this entity was last modified. - `lastModifierId` (string(uuid)): The ID of the user who last modified this entity. - `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. - `deletionTime` (string(date-time)): The date and time when this entity was deleted, if it is deleted. - `displayGuid` (string) - `fraudScreenResult` (object): 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. - `merchantName` (string) - `resultCode` (object) - `cardBrand` (string): The card brand (e.g., "VISA", "MASTERCARD") resolved from BIN data. - `extraProperties` (object) - `currentStage` (TransactionStage): Represents the stage of a transaction within the transaction management workflow. - `history` (array) - `appliedPatches` (array) - `allowedActions` (array) - `concurrencyStamp` (string) - `entityVersion` (integer(int32)) - `tenantId` (string(uuid)) - `transactionType` (TransactionType): Represents the various types of transactions that can be performed in the system. - `cardData` (CardData): Represents the data associated with a payment card. - `checkData` (CheckData): Represents the data associated with a check transaction. - `cashData` (object): 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. - `apmData` (object): The alternative-payment instrument block for a payment the payer approved inside a provider. Null on every other tender. - `tokenData` (TokenData): 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. - `deviceData` (DeviceData): Represents data related to a device in a transaction. - `fsa` (Fsa): Represents a Flexible Spending Account (FSA) with various amount categories and partial authorization support. - `lodging` (object): Lodging detail for a stay-related transaction, echoed back as it was submitted. Null on every transaction outside a lodging industry. - `softDescriptor` (SoftDescriptor): Represents a soft descriptor for a transaction, containing alternative merchant information. - `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. - `register` (TransactionRegister): Represents a transaction register in the system. - `invoiceData` (Invoice): Represents an invoice in the system. - `originalTransaction` (OriginalTransaction): Represents an original transaction with its identifying information. - `customFields` (array) - `signatureData` (SignatureData): Represents signature data for a transaction. - `level2Data` (Level2Data): Represents Level 2 data for a transaction, including purchase order information, transaction date, and merchant zip code. - `level3Data` (Level3Data): Represents Level 3 data for a transaction, including shipping information and line items. - `orderLines` (array): 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. - `ebt` (EbtData): 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. - `useInterchangeDefaults` (boolean) - `captureType` (CaptureTypes): Represents the types of payment capture methods available for transactions. - `responseData` (TransactionResponseData): Represents the response data for a transaction, containing various details about the transaction outcome. - `settleData` (TransactionSettleData): Represents settlement data for a transaction. - `source` (object) - `sourceData` (TransactionSourceData): Encapsulates the origin of a transaction and any source-specific identifiers. - `tags` (array) - `notes` (array) - `merchantId` (string(uuid)) - `merchantTransactionId` (integer(int64)) - `receiptIds` (array): List of receipt IDs generated for this transaction. - `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. - `decisionNotes` (array): 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. - `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`. - `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`. - `linkedChargeKind` (object): 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. - `processorProfileId` (string(uuid)): The unique identifier of the merchant processor profile that processed this transaction. - `processorKey` (string): The processor type key (e.g., "tsys", "fiserv") used for this transaction. - `routingResult` (object): 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. - `loopbackSimulation` (object): 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. - `surchargeResult` (object): 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). - `correlationId` (string): The correlation ID linking this transaction to its orchestration audit trail. - `cumulativeRefundedAmount` (number(double)): Running total of refund amounts applied to this transaction. - `cumulativeReversedAmount` (number(double)): Running total of reversal amounts applied to this transaction. - `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. - `policyRejection` (object): 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. - `partialApprovalData` (object): 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. - `fraudReviewData` (object): 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. - `threeDSAuthentication` (object): 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. - `payloadDecryption` (object): 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. - `enhancedDataQualification` (object): 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. - `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. - `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. - `splitTenderRole` (object): 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. - `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. - `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. - `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. - `initiationType` (object): Identifies whether this transaction was initiated by the cardholder (CIT) or the merchant (MIT). Null on legacy transactions. - `mitReason` (object): For MIT transactions, the reason code justifying the merchant-initiated charge. - `storedCredentialConsentId` (string(uuid)): Reference to the stored credential consent authorizing this MIT. - `schemeTransactionId` (string): The card network's trace ID linking this transaction to its original CIT. - `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. - `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. - `tender` (object): 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. - `cardholderPresence` (object): How present the cardholder is at the point of sale, separate from the physical entry mode. Drives network-level presence indicators at auth time. - `specialCondition` (object): Visa/MC special-condition tag (quasi-cash, quasi-MOTO). - `processorCertificationOverrides` (object): Per-processor certification override knobs. Non-null only for cert-tooling traffic. Production traffic always sees this as `null`. - `refundKind` (object): Classifies a refund transaction as linked (follow-up against a previously approved original transaction) or unlinked (standalone). `null` for non-refund transactions. - `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. - `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). - `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. - `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. - `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. - `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. - `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. - `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. - `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. - `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. - `surchargeDisclosureChannel` (string): Channel on which the surcharge disclosure was acknowledged (`"VirtualTerminal"` / `"HostedPaymentPage"` / `"Api"`). Read-only on the API surface. - `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. - `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. - `achWebAuthorizationTextVersion` (string): Version hash (`sha256:{hex}`) of `achWebAuthorizationText`. Read-only. - `achWebAuthorizationConsumerIp` (string): Consumer IP recorded at ACH WEB authorization time (required NACHA evidence). Read-only. `null` for non-ACH tenders. - `achWebAuthorizationAt` (string(date-time)): UTC timestamp of the ACH WEB authorization (server-stamped). Read-only. `null` for non-ACH tenders. - `achWebAuthorizationSecCode` (string): SEC code the ACH WEB authorization was captured under (always `"WEB"`). Read-only. `null` for non-ACH tenders. - `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. - `achAuthorizationStatementVersion` (string): Version hash (`sha256:{hex}`) of `achAuthorizationStatementText`. Read-only. - `achAuthorizationSecCode` (string): SEC code the VT ACH authorization was captured under (`"TEL"` or `"PPD"`). Read-only. `null` for non-VT-ACH tenders. - `achAuthorizationChannel` (string): Channel on which the VT ACH authorization was attested (`"VirtualTerminal"`). Read-only. `null` for non-VT-ACH tenders. - `achAuthorizationAt` (string(date-time)): UTC timestamp of the VT ACH authorization (server-stamped). Read-only. `null` for non-VT-ACH tenders. - `idempotencyStatus` (object): 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. - `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. ### 403 Forbidden **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 401 Unauthorized **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 400 Bad Request **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 404 Not Found **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 501 Not Implemented **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 500 Internal Server Error **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 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. See the error-code reference in this document's description for the values `error.code` can take. **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 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` 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. - `title` (string) required: A short, human-readable summary of the problem type. - `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. - `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` Properties: - `error` (RemoteServiceErrorInfo) ## 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 POST "{{BASE_URL}}/api/transactions/get-transaction-by-id-async" \ -H "api-key: {{API_KEY}}" ``` ### PowerShell ```powershell $headers = @{ 'api-key' = '{{API_KEY}}' } $response = Invoke-RestMethod -Method POST -Uri '{{BASE_URL}}/api/transactions/get-transaction-by-id-async' ` -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.transactionsGetTransactionById(); ``` ### TypeScript (raw HTTP) ```typescript const response = await fetch('{{BASE_URL}}/api/transactions/get-transaction-by-id-async', { method: 'POST', 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.TransactionsGetTransactionByIdAsync(); ``` ### C# (raw HTTP) ```csharp using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") }; var request = new HttpRequestMessage(new HttpMethod("POST"), "/api/transactions/get-transaction-by-id-async"); 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_transaction_by_id() ``` ### Python (raw HTTP) ```bash pip install requests ``` ```python import requests headers = { "api-key": "{{API_KEY}}", } response = requests.request( "POST", "{{BASE_URL}}/api/transactions/get-transaction-by-id-async", headers=headers, ) response.raise_for_status() data = response.json() ``` ## See also - [All documentation](https://devportal-simpay-sbx.winkpg.io/llms.txt): the machine-readable index of every public page on this site.