openapi: 3.0.3
info:
  title: Lithic 3DS Chargeback API
  description: The Lithic API is a card issuing and issuer-processor platform for issuing virtual and physical cards, authorizing and clearing transactions, moving money across ledgered financial accounts, and managing the full card lifecycle - KYC/KYB account holder onboarding, authorization rules and real-time Auth Stream Access (ASA) decisioning, disputes, tokenization into digital wallets, 3DS authentication, ACH payments, book transfers, external payments, settlement reporting, and fraud/transaction monitoring. This document curates the real, published Lithic OpenAPI 3.1 definitions (https://github.com/lithic-com/lithic-openapi) into the endpoint surface referenced by this apis.yml, expressed as OpenAPI 3.0.3 with lightweight response schemas. Requests are authenticated with an API key sent as the raw value of the Authorization header (not a Bearer token).
  version: 1.0.0
  contact:
    name: Lithic
    url: https://www.lithic.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.txt
servers:
- url: https://api.lithic.com
  description: Production
- url: https://sandbox.lithic.com
  description: Sandbox (mirrors production functionality)
security:
- ApiKeyAuth: []
tags:
- name: Chargeback
  description: Legacy v1 dispute (chargeback) submission and evidence.
paths:
  /v1/disputes:
    get:
      operationId: getDisputes
      tags:
      - Chargeback
      summary: List chargeback requests
      description: List chargeback requests.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chargeback'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
    post:
      operationId: postDisputes
      tags:
      - Chargeback
      summary: Request chargeback
      description: Request a chargeback.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chargeback'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/disputes/{dispute_token}:
    delete:
      operationId: deleteDisputeByToken
      tags:
      - Chargeback
      summary: Withdraw chargeback request
      description: Withdraw chargeback request.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chargeback'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
    get:
      operationId: getDisputeByToken
      tags:
      - Chargeback
      summary: Get chargeback request
      description: Get chargeback request.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chargeback'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
    patch:
      operationId: updateDisputeByToken
      tags:
      - Chargeback
      summary: Update chargeback request
      description: Update chargeback request. Can only be modified if status is `NEW`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chargeback'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/disputes/{dispute_token}/evidences:
    get:
      operationId: getDisputeEvidences
      tags:
      - Chargeback
      summary: List evidence
      description: List evidence for a chargeback request.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chargeback'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
    post:
      operationId: postEvidenceDocument
      tags:
      - Chargeback
      summary: Upload evidence
      description: Use this endpoint to upload evidence for a chargeback request. It will return a URL to upload your documents to. The URL will expire in 30 minutes. Uploaded documents must either be a `jpg`, `png` or `pdf` file, and each must be less than 5 GiB.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chargeback'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/disputes/{dispute_token}/evidences/{evidence_token}:
    delete:
      operationId: deleteDisputeEvidenceByToken
      tags:
      - Chargeback
      summary: Delete evidence
      description: Soft delete evidence for a chargeback request. Evidence will not be reviewed or submitted by Lithic after it is withdrawn.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chargeback'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
    get:
      operationId: getDisputeEvidenceByToken
      tags:
      - Chargeback
      summary: Get evidence
      description: Get evidence for a chargeback request.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chargeback'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  responses:
    Unauthorized:
      description: Missing or invalid API key.
    ValidationError:
      description: The request failed validation.
  schemas:
    Chargeback:
      type: object
      description: Legacy v1 dispute (chargeback) submission and evidence.
      properties:
        token:
          type: string
          format: uuid
          description: Globally unique identifier for the object.
        created:
          type: string
          format: date-time
      additionalProperties: true
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Raw API secret key value (not prefixed with "Bearer").