Decline a held transaction, rejecting the payment.
POST
/api/transactions/{id}/fraud-review/decline
deprecated
Requires: Transactions.FraudReview.Disposition, merchant scope.
The transaction must be awaiting a review decision and the reason is required. The park happens before authorization, so no hold on the cardholder's funds exists and nothing is reversed. The reason is recorded on the transaction for the merchant audit trail and must never carry processor or screening-provider response text or anything card-derived.
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.
The request body is a FraudReviewDeclineInput. See the Request body section below for its fields.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id
required |
path | string (uuid) | The held transaction. |
suppressNulls
required |
query | boolean | If true, omit properties with null values. |
Request body
application/json
, required
| Field | Type | Description |
|---|---|---|
reasonCode
required |
string | Why the transaction was rejected. Required. A gateway-authored code or a brief operator note only: never processor or screening-provider response text, and never anything card-derived. nullablemax length 256 |
This request body has no documented fields.
Responses
200 The decision was applied. The body is the post-disposition transaction.
Body: TransactionDto
Each item has these fields.
| Field | Type | Description |
|---|---|---|
id
required |
string (uuid) | |
creationTime
required |
string (date-time) | The date and time when this entity was created. |
creatorId
required |
string (uuid) | The ID of the user who created this entity. nullable |
lastModificationTime
required |
string (date-time) | The date and time when this entity was last modified. nullable |
lastModifierId
required |
string (uuid) | The ID of the user who last modified this entity. nullable |
isDeleted
required |
boolean | Indicates whether this entity has been deleted. |
deleterId
required |
string (uuid) | The ID of the user who deleted this entity, if it is deleted. nullable |
deletionTime
required |
string (date-time) | The date and time when this entity was deleted, if it is deleted. nullable |
displayGuid
required |
string | nullableread only |
fraudScreenResult
required |
all of FraudScreenResult | 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 |
merchantName
required |
string | nullable |
resultCode
required |
all of ResultCode | nullableread only |
cardBrand
required |
string | The card brand (e.g., "VISA", "MASTERCARD") resolved from BIN data. nullableread only |
extraProperties
required |
object | nullableread only |
currentStage
required |
TransactionStage | Represents the stage of a transaction within the transaction management workflow. one of: Created, Validated, Enriched, Screened, Authorized, Finalized, Captured, Completed, Reversed, Refunded, Voided, SplitTenderPending, Rejected, Declined, Failed, PolicyRejected |
history
required |
array of TransactionHistoryItem | nullable |
appliedPatches
required |
array of TransactionPatchSnapshot | nullable |
allowedActions
required |
array of TransactionOperationType | nullable |
concurrencyStamp
required |
string | nullable |
entityVersion
required |
integer (int32) | read only |
tenantId
required |
string (uuid) | nullableread only |
transactionType
required |
TransactionType | Represents the various types of transactions that can be performed in the system. one of: Authorization, Sale, Return, Void, Force, Capture, CaptureAll, RepeatSale, Adjustment, Activate, Deactivate, Redeem, Inquire, Reload, VoucherClear, Payout |
cardData
required |
CardData | Represents the data associated with a payment card. |
checkData
required |
CheckData | Represents the data associated with a check transaction. |
cashData
required |
all of CashPaymentDetails | 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
required |
all of ApmData | The alternative-payment instrument block for a payment the payer approved inside a provider. Null on every other tender. |
tokenData
required |
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
required |
DeviceData | Represents data related to a device in a transaction. |
fsa
required |
Fsa | Represents a Flexible Spending Account (FSA) with various amount categories and partial authorization support. |
lodging
required |
all of LodgingData | Lodging detail for a stay-related transaction, echoed back as it was submitted. Null on every transaction outside a lodging industry. |
softDescriptor
required |
SoftDescriptor | Represents a soft descriptor for a transaction, containing alternative merchant information. |
duplicateCheck
required |
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
required |
TransactionRegister | Represents a transaction register in the system. |
invoiceData
required |
Invoice | Represents an invoice in the system. |
originalTransaction
required |
OriginalTransaction | Represents an original transaction with its identifying information. |
customFields
required |
array of TrxCustomField | nullable |
signatureData
required |
SignatureData | Represents signature data for a transaction. |
level2Data
required |
Level2Data | Represents Level 2 data for a transaction, including purchase order information, transaction date, and merchant zip code. |
level3Data
required |
Level3Data | Represents Level 3 data for a transaction, including shipping information and line items. |
orderLines
required |
array of TransactionOrderLine | 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 |
ebt
required |
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
required |
boolean | nullable |
captureType
required |
CaptureTypes | Represents the types of payment capture methods available for transactions. one of: Credit, Debit, Check, EBT |
responseData
required |
TransactionResponseData | Represents the response data for a transaction, containing various details about the transaction outcome. |
settleData
required |
TransactionSettleData | Represents settlement data for a transaction. |
source
required |
all of TransactionSource | nullable |
sourceData
required |
TransactionSourceData | Encapsulates the origin of a transaction and any source-specific identifiers. |
tags
required |
array of EntityTag | nullable |
notes
required |
array of EntityNote | nullable |
merchantId
required |
string (uuid) | |
merchantTransactionId
required |
integer (int64) | nullable |
receiptIds
required |
array of string | List of receipt IDs generated for this transaction. nullable |
refundTransactionIds
required |
array of string | IDs of the linked-refund child transactions issued against this transaction (as the parent sale). Drives the detail-page reverse relationship ("Refunded by <guid>" and the Related Transactions grid). Empty/null when this transaction has no linked refunds. nullable |
decisionNotes
required |
array of TransactionDecisionNote | 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 |
linkedFeeChargeTransactionId
required |
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
required |
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
required |
all of LinkedChargeKind | 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 |
processorProfileId
required |
string (uuid) | The unique identifier of the merchant processor profile that processed this transaction. nullable |
processorKey
required |
string | The processor type key (e.g., "tsys", "fiserv") used for this transaction. nullable |
routingResult
required |
all of RoutingResult | 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
required |
all of LoopbackSimulation | 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
required |
all of SurchargeResult | 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
required |
string | The correlation ID linking this transaction to its orchestration audit trail. nullable |
cumulativeRefundedAmount
required |
number (double) | Running total of refund amounts applied to this transaction. nullable |
cumulativeReversedAmount
required |
number (double) | Running total of reversal amounts applied to this transaction. nullable |
authorizedAmount
required |
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
required |
all of PolicyRejectionData | 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
required |
all of PartialApprovalData | Durable record of a partial approval (the issuer authorized less than was requested) and the disposition decided for it. Read this (not `responseData`.`IsPartialApproval`) anywhere outside the synchronous create response: the response flag is erased by the reversal that every non-accepted disposition issues, whereas this object is top-level and survives. Its mere presence means "this transaction was partially approved". Null when the issuer approved in full. |
fraudReviewData
required |
all of FraudReviewData | 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
required |
all of ThreeDSAuthenticationData | 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
required |
all of PayloadDecryption | 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
required |
all of EnhancedDataQualificationDto | 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
required |
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
required |
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
required |
all of SplitTenderRole | 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 |
splitTenderDeclaredTotal
required |
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
required |
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 |
initiationType
required |
all of InitiationType | Identifies whether this transaction was initiated by the cardholder (CIT) or the merchant (MIT). Null on legacy transactions. nullable |
mitReason
required |
all of MITReasonCode | For MIT transactions, the reason code justifying the merchant-initiated charge. nullable |
storedCredentialConsentId
required |
string (uuid) | Reference to the stored credential consent authorizing this MIT. nullable |
schemeTransactionId
required |
string | The card network's trace ID linking this transaction to its original CIT. nullable |
description
required |
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
required |
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
required |
all of TenderKind | 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 |
cardholderPresence
required |
all of CardholderPresence | 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 |
specialCondition
required |
all of SpecialCondition | Visa/MC special-condition tag (quasi-cash, quasi-MOTO). nullable |
processorCertificationOverrides
required |
all of ProcessorCertificationOverrides | Per-processor certification override knobs. Non-null only for cert-tooling traffic. Production traffic always sees this as `null`. |
refundKind
required |
all of RefundKind | Classifies a refund transaction as linked (follow-up against a previously approved original transaction) or unlinked (standalone). `null` for non-refund transactions. nullable |
pendingRefundAmount
required |
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
required |
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
required |
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
required |
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
required |
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
required |
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
required |
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
required |
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
required |
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
required |
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
required |
string | Channel on which the surcharge disclosure was acknowledged (`"VirtualTerminal"` / `"HostedPaymentPage"` / `"Api"`). Read-only on the API surface. nullable |
surchargeReversedAmount
required |
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
required |
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
required |
string | Version hash (`sha256:{hex}`) of `achWebAuthorizationText`. Read-only. nullable |
achWebAuthorizationConsumerIp
required |
string | Consumer IP recorded at ACH WEB authorization time (required NACHA evidence). Read-only. `null` for non-ACH tenders. nullable |
achWebAuthorizationAt
required |
string (date-time) | UTC timestamp of the ACH WEB authorization (server-stamped). Read-only. `null` for non-ACH tenders. nullable |
achWebAuthorizationSecCode
required |
string | SEC code the ACH WEB authorization was captured under (always `"WEB"`). Read-only. `null` for non-ACH tenders. nullable |
achAuthorizationStatementText
required |
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
required |
string | Version hash (`sha256:{hex}`) of `achAuthorizationStatementText`. Read-only. nullable |
achAuthorizationSecCode
required |
string | SEC code the VT ACH authorization was captured under (`"TEL"` or `"PPD"`). Read-only. `null` for non-VT-ACH tenders. nullable |
achAuthorizationChannel
required |
string | Channel on which the VT ACH authorization was attested (`"VirtualTerminal"`). Read-only. `null` for non-VT-ACH tenders. nullable |
achAuthorizationAt
required |
string (date-time) | UTC timestamp of the VT ACH authorization (server-stamped). Read-only. `null` for non-VT-ACH tenders. nullable |
idempotencyStatus
required |
all of CreateIdempotencyStatus | 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 |
This response has no documented body fields.
403 Forbidden
Body: RemoteServiceErrorResponse
Each item has these fields.
| Field | Type | Description |
|---|---|---|
error
required |
RemoteServiceErrorInfo |
This response has no documented body fields.
401 Unauthorized
Body: RemoteServiceErrorResponse
Each item has these fields.
| Field | Type | Description |
|---|---|---|
error
required |
RemoteServiceErrorInfo |
This response has no documented body fields.
400 Bad Request
Body: RemoteServiceErrorResponse
Each item has these fields.
| Field | Type | Description |
|---|---|---|
error
required |
RemoteServiceErrorInfo |
This response has no documented body fields.
404 No transaction with that id is visible to this caller (`Transactions:ReviewTransactionNotFound`). A transaction that belongs to another merchant answers the same way.
Body: RemoteServiceErrorResponse
Each item has these fields.
| Field | Type | Description |
|---|---|---|
error
required |
RemoteServiceErrorInfo |
This response has no documented body fields.
501 Not Implemented
Body: RemoteServiceErrorResponse
Each item has these fields.
| Field | Type | Description |
|---|---|---|
error
required |
RemoteServiceErrorInfo |
This response has no documented body fields.
500 Internal Server Error
Body: RemoteServiceErrorResponse
Each item has these fields.
| Field | Type | Description |
|---|---|---|
error
required |
RemoteServiceErrorInfo |
This response has no documented body fields.
409 The transaction is not awaiting a review decision (`Transactions:ReviewNotPending`): it was already approved or declined, or its review deadline passed. Read the transaction; the outcome is already on it.
Body:
Each item has these fields.
| Field | Type | Description |
|---|
This response has no body.
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.
Body: RemoteServiceErrorResponse
Each item has these fields.
| Field | Type | Description |
|---|---|---|
error
required |
RemoteServiceErrorInfo |
This response has no documented body fields.
429 The request was refused because a rate limit was exceeded. 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.
Body: RateLimitProblemDetails
Each item has these fields.
| Field | Type | Description |
|---|---|---|
type
required |
string | 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
required |
string | A short, human-readable summary of the problem type. nullable |
status
required |
integer (int32) | The HTTP status code, repeated in the body as the problem-details format defines. |
detail
required |
string | A human-readable explanation of this occurrence of the problem. nullable |
retryAfterSeconds
required |
integer (int32) | 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. |
This response has no documented body fields.
Errors
A failed request returns the platform error envelope. The
error reference lists every value
error.code can carry and shows the four response shapes.