# POST /api/transactions/get-by-idempotency-key-async Looks up a transaction by the idempotency key the caller supplied. The lookup is confined to one merchant. When no transaction carries the key, the request fails with 404 Not Found. Use it after a network failure to find out whether an earlier submission was accepted before retrying: 404 means it was not, and a returned transaction means it was. Whether resending the original request would charge again depends on whether create deduplication is enabled for the merchant. Where it is, a resend with the same key returns the original transaction rather than charging. Where it is not, this lookup is the only safeguard and a resend creates a second charge. When more than one transaction carries the key, which is possible for keys sent before deduplication existed, the earliest is returned. **Operation ID:** `transactionsGetByIdempotencyKey` ## Authorization Requires: Transactions.Reports.View, merchant scope. Required permissions: - `Transactions.Reports.View` ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | merchantId | query | no | string(uuid) | The merchant the transaction belongs to. | | idempotencyKey | query | no | string | The idempotency key sent on the original request. | | 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-by-idempotency-key-async" \ -H "api-key: {{API_KEY}}" ``` ### PowerShell ```powershell $headers = @{ 'api-key' = '{{API_KEY}}' } $response = Invoke-RestMethod -Method POST -Uri '{{BASE_URL}}/api/transactions/get-by-idempotency-key-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.transactionsGetByIdempotencyKey(); ``` ### TypeScript (raw HTTP) ```typescript const response = await fetch('{{BASE_URL}}/api/transactions/get-by-idempotency-key-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.TransactionsGetByIdempotencyKeyAsync(); ``` ### C# (raw HTTP) ```csharp using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") }; var request = new HttpRequestMessage(new HttpMethod("POST"), "/api/transactions/get-by-idempotency-key-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_by_idempotency_key() ``` ### Python (raw HTTP) ```bash pip install requests ``` ```python import requests headers = { "api-key": "{{API_KEY}}", } response = requests.request( "POST", "{{BASE_URL}}/api/transactions/get-by-idempotency-key-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.