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