Lithic Fraud Report API
The Fraud Report API from Lithic — 1 operation(s) for fraud report.
OpenAPI Specification
openapi: 3.1.0
info:
contact:
email: support@lithic.com
description: 'The Lithic Developer API is designed to provide a predictable programmatic interface for accessing your Lithic account through an API and transaction webhooks.
Note that your API key is a secret and should be treated as such. Don''t share it with anyone, including us. We will never ask you for it.
'
termsOfService: https://lithic.com/legal/terms
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.txt
title: Lithic Developer 3DS Fraud Report API
version: 1.0.0
servers:
- description: Sandbox environment that provides key functionality mirroring production
url: https://sandbox.lithic.com
security:
- ApiKeyAuth: []
tags:
- name: Fraud Report
paths:
/v1/fraud/transactions/{transaction_token}:
get:
description: 'Retrieve a fraud report for a specific transaction identified by its unique transaction token.
'
summary: Get a fraud report for a transaction
operationId: getFraudReport
tags:
- Fraud Report
parameters:
- required: true
schema:
title: Transaction Token
type: string
format: uuid
name: transaction_token
description: The token of the transaction that the enhanced data is associated with.
in: path
example: 00000000-0000-0000-0000-000000000000
responses:
'200':
description: Fraud report for the specified transaction.
content:
application/json:
schema:
$ref: '#/components/schemas/fraud-report-response'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
post:
description: 'Report fraud for a specific transaction token by providing details such as fraud type, fraud status, and any additional comments.
'
summary: Create or update a fraud report for a transaction
operationId: createUpdateFraudReport
tags:
- Fraud Report
parameters:
- required: true
schema:
title: Transaction Token
type: string
format: uuid
name: transaction_token
description: The token of the transaction that the enhanced data is associated with.
in: path
example: 00000000-0000-0000-0000-000000000000
requestBody:
required: true
description: The details of the fraud report to create or update.
content:
application/json:
schema:
$ref: '#/components/schemas/fraud-report-request'
responses:
'200':
description: The created or updated fraud report.
content:
application/json:
schema:
$ref: '#/components/schemas/fraud-report-response'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
components:
schemas:
fraud-report-request:
title: Fraud Report Parameters
type: object
properties:
fraud_status:
type: string
enum:
- SUSPECTED_FRAUD
- FRAUDULENT
- NOT_FRAUDULENT
description: "The fraud status of the transaction, string (enum) supporting the following values:\n\n - `SUSPECTED_FRAUD`: The transaction is suspected to be fraudulent, but this hasn’t been confirmed.\n - `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.\n - `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."
fraud_type:
type: string
enum:
- FIRST_PARTY_FRAUD
- ACCOUNT_TAKEOVER
- CARD_COMPROMISED
- IDENTITY_THEFT
- CARDHOLDER_MANIPULATION
description: "Specifies the type or category of fraud that the transaction is suspected or confirmed to involve, string (enum) supporting the following values:\n\n - `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.\n - `ACCOUNT_TAKEOVER`: Account takeover fraud occurs when a fraudster gains unauthorized access to an existing account, modifies account settings, and carries out fraudulent transactions.\n - `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.\n - `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.\n - `CARDHOLDER_MANIPULATION`: This type of fraud occurs when a fraudster manipulates or coerces a legitimate cardholder into unauthorized transactions, often through social engineering tactics."
comment:
type: string
description: Optional field providing additional information or context about why the transaction is considered fraudulent.
required:
- fraud_status
error:
type: object
properties:
debugging_request_id:
type: string
format: uuid
description: Identifier to help debug an error.
message:
type: string
description: Explanation of error response.
required:
- debugging_request_id
- message
fraud-report-response:
title: Fraud Report Response
type: object
properties:
transaction_token:
type: string
format: uuid
description: The universally unique identifier (UUID) associated with the transaction being reported.
fraud_status:
type: string
enum:
- SUSPECTED_FRAUD
- FRAUDULENT
- NOT_FRAUDULENT
- NO_REPORTED_FRAUD
description: "The fraud status of the transaction, string (enum) supporting the following values:\n\n - `SUSPECTED_FRAUD`: The transaction is suspected to be fraudulent, but this hasn’t been confirmed.\n - `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.\n - `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.\n - `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."
fraud_type:
type: string
enum:
- FIRST_PARTY_FRAUD
- ACCOUNT_TAKEOVER
- CARD_COMPROMISED
- IDENTITY_THEFT
- CARDHOLDER_MANIPULATION
description: "Specifies the type or category of fraud that the transaction is suspected or confirmed to involve, string (enum) supporting the following values:\n\n - `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.\n - `ACCOUNT_TAKEOVER`: Account takeover fraud occurs when a fraudster gains unauthorized access to an existing account, modifies account settings, and carries out fraudulent transactions.\n - `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.\n - `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.\n - `CARDHOLDER_MANIPULATION`: This type of fraud occurs when a fraudster manipulates or coerces a legitimate cardholder into unauthorized transactions, often through social engineering tactics."
comment:
type: string
description: Provides additional context or details about the fraud report.
created_at:
type: string
format: date-time
description: Timestamp representing when the fraud report was created.
updated_at:
type: string
format: date-time
description: Timestamp representing the last update to the fraud report.
required:
- transaction_token
- fraud_status
responses:
Unauthorized:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: '| | |
|---|---|
| User has not been authenticated | Invalid or missing API key |
| API key is not active | The API key used is no longer active |
| Could not find API key | The API key provided is not associated with any user |
| Please provide API key in Authorization header | The Authorization header is not in the request |
| Please provide API key in the form Authorization: [api-key] | The Authorization header is not formatted properly |
| Insufficient privileges. Issuing API key required | Write access requires an Issuing API key. Reach out at [lithic.com/contact](https://lithic.com/contact) |
| Insufficient privileges to create virtual cards. | Creating virtual cards requires an additional privilege | Reach out at [lithic.com/contact](https://lithic.com/contact) |
'
BadRequest:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: A parameter in the query given in the request does not match the valid queries for the endpoint.
NotFound:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: The specified resource was not found.
TooManyRequests:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: 'Client has exceeded the number of allowed requests in a given time period.
| | |
|---|---|
| Rate limited, too many requests per second | User has exceeded their per second rate limit |
| Rate limited, reached daily limit | User has exceeded their daily rate limit |
| Rate limited, too many keys tried | One IP has queried too many different API keys |
'
UnprocessableEntity:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Unprocessable entity.
securitySchemes:
ApiKeyAuth:
in: header
name: Authorization
type: apiKey