Approve a held transaction, releasing it to continue into authorization.
POST
/api/transactions/{id}/fraud-review/approve
deprecated
Requires: Transactions.FraudReview.Disposition, merchant scope.
The transaction must be awaiting a review decision. The response is the transaction as it stands after the decision was applied, so `fraudReviewData.disposition` reads `Approved` and the authorization outcome follows on the transaction rather than on this response. A transaction that has already been approved or declined, or whose review deadline has passed, is refused.
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 FraudReviewApproveInput. 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 | Optional note recording why the transaction was released. Unlike a decline, an approval needs no justification: the payment simply proceeds as the cardholder intended. 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.