Create or update a fraud report for a transaction

Transaction Token

uuid
required
The token of the transaction that the enhanced data is associated with.

Fraud Report Details

fraud_status

string
enum
required
The fraud status of the transaction, string (enum) supporting the following values:

• SUSPECTED_FRAUD: The transaction is suspected to be fraudulent, but this hasn’t been confirmed.
• FRAUDULENT: The transaction is confirmed to be fraudulent. A transaction may immediately be moved into this state, or be graduated into this state from the SUSPECTED_FRAUD state.
• NOT_FRAUDULENT: The transaction is (explicitly) marked as not fraudulent. A transaction may immediately be moved into this state, or be graduated into this state from the SUSPECTED_FRAUD state.

Allowed:
SUSPECTED_FRAUD, FRAUDULENT, NOT_FRAUDULENT

fraud_type

string
enum
Specifies the type or category of fraud that the transaction is suspected or confirmed to involve, string (enum) supporting the following values:

• FIRST_PARTY_FRAUD: First-party fraud occurs when a legitimate account or cardholder intentionally misuses financial services for personal gain. This includes actions such as disputing legitimate transactions to obtain a refund, abusing return policies, or defaulting on credit obligations without intent to repay.
• ACCOUNT_TAKEOVER: Account takeover fraud occurs when a fraudster gains unauthorized access to an existing account, modifies account settings, and carries out fraudulent transactions.
• CARD_COMPROMISED: Card compromised fraud occurs when a fraudster gains access to card details without taking over the account, such as through physical card theft, cloning, or online data breaches.
• IDENTITY_THEFT: Identity theft fraud occurs when a fraudster uses stolen personal information, such as Social Security numbers or addresses, to open accounts, apply for loans, or conduct financial transactions in someone's name.
• CARDHOLDER_MANIPULATION: This type of fraud occurs when a fraudster manipulates or coerces a legitimate cardholder into unauthorized transactions, often through social engineering tactics.

Allowed:
FIRST_PARTY_FRAUD, ACCOUNT_TAKEOVER, CARD_COMPROMISED, IDENTITY_THEFT, CARDHOLDER_MANIPULATION

comment

string
Optional field providing additional information or context about why the transaction is considered fraudulent.

Successful Response

200

The created or updated fraud report.

transaction_token
uuid
required
The universally unique identifier (UUID) associated with the transaction being reported.

fraud_status
string
enum
required
The fraud status of the transaction, string (enum) supporting the following values:

• SUSPECTED_FRAUD: The transaction is suspected to be fraudulent, but this hasn’t been confirmed.
• FRAUDULENT: The transaction is confirmed to be fraudulent. A transaction may immediately be moved into this state, or be graduated into this state from the SUSPECTED_FRAUD state.
• NOT_FRAUDULENT: The transaction is (explicitly) marked as not fraudulent. A transaction may immediately be moved into this state, or be graduated into this state from the SUSPECTED_FRAUD state.
• NO_REPORTED_FRAUD: Indicates that no fraud report exists for the transaction. It is the default state for transactions that have not been analyzed or associated with any known fraudulent activity.

Allowed:
SUSPECTED_FRAUD, FRAUDULENT, NOT_FRAUDULENT, NO_REPORTED_FRAUD

fraud_type
string
enum
Specifies the type or category of fraud that the transaction is suspected or confirmed to involve, string (enum) supporting the following values:

Allowed:
FIRST_PARTY_FRAUD, ACCOUNT_TAKEOVER, CARD_COMPROMISED, IDENTITY_THEFT, CARDHOLDER_MANIPULATION

comment
string
Provides additional context or details about the fraud report.

created_at
date-time
Timestamp representing when the fraud report was created.

updated_at
date-time
Timestamp representing the last update to the fraud report.

Error Responses

400

A parameter in the query given in the request does not match the valid queries for the endpoint.

401

User has not been authenticated.

404

The specified resource was not found.

422

Unprocessable entity.

429

Client has exceeded the number of allowed requests in a given time period.

Example Request

curl --request POST \
     --url https://sandbox.lithic.com/v1/fraud/transactions/transaction_token \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "fraud_status": "SUSPECTED_FRAUD",
  "fraud_type": "FIRST_PARTY_FRAUD",
  "comment": "string"
}'

Example Response

{
  "transaction_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "fraud_status": "SUSPECTED_FRAUD",
  "fraud_type": "FIRST_PARTY_FRAUD",
  "comment": "string",
  "created_at": "2026-07-18T00:25:34.975Z",
  "updated_at": "2026-07-18T00:25:34.975Z"
}