Lithic Chargeback API

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 Chargeback API
  version: 1.0.0
servers:
- description: Sandbox environment that provides key functionality mirroring production
  url: https://sandbox.lithic.com
security:
- ApiKeyAuth: []
tags:
- name: Chargeback
paths:
  /v1/disputes:
    get:
      description: List chargeback requests.
      operationId: getDisputes
      parameters:
      - description: Filter by status.
        in: query
        name: status
        required: false
        schema:
          enum:
          - ARBITRATION
          - CASE_CLOSED
          - CASE_WON
          - NEW
          - PENDING_CUSTOMER
          - PREARBITRATION
          - REPRESENTMENT
          - SUBMITTED
          type: string
      - description: Transaction tokens to filter by.
        explode: false
        in: query
        name: transaction_tokens
        required: false
        schema:
          items:
            format: uuid
            type: string
          maxItems: 50
          type: array
        style: form
      - $ref: '#/components/parameters/beginTime'
      - $ref: '#/components/parameters/endTime'
      - $ref: '#/components/parameters/endingBefore'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/startingAfter'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/dispute-v1'
                    type: array
                  has_more:
                    description: More data exists.
                    type: boolean
                required:
                - data
                - has_more
                type: object
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: List chargeback requests
      tags:
      - Chargeback
    post:
      description: Request a chargeback.
      operationId: postDisputes
      requestBody:
        content:
          application/json:
            examples:
              initiateDispute:
                summary: Request chargeback
                value:
                  amount: 10000
                  customer_filed_date: '2021-06-28T22:53:15Z'
                  reason: FRAUD_CARD_PRESENT
                  transaction_token: 12345624-aa69-4cbc-a946-30d90181b621
            schema:
              properties:
                amount:
                  description: Amount for chargeback
                  type: integer
                customer_filed_date:
                  description: Date the customer filed the chargeback request
                  format: date-time
                  type: string
                customer_note:
                  description: Customer description
                  maximum: 5000
                  type: string
                reason:
                  description: Reason for chargeback
                  enum:
                  - ATM_CASH_MISDISPENSE
                  - CANCELLED
                  - DUPLICATED
                  - FRAUD_CARD_NOT_PRESENT
                  - FRAUD_CARD_PRESENT
                  - FRAUD_OTHER
                  - GOODS_SERVICES_NOT_AS_DESCRIBED
                  - GOODS_SERVICES_NOT_RECEIVED
                  - INCORRECT_AMOUNT
                  - MISSING_AUTH
                  - OTHER
                  - PROCESSING_ERROR
                  - RECURRING_TRANSACTION_NOT_CANCELLED
                  - REFUND_NOT_PROCESSED
                  type: string
                transaction_token:
                  description: Transaction for chargeback
                  format: uuid
                  type: string
              required:
              - amount
              - reason
              - transaction_token
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dispute-v1'
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Request chargeback
      tags:
      - Chargeback
  /v1/disputes/{dispute_token}:
    delete:
      description: Withdraw chargeback request.
      operationId: deleteDisputeByToken
      parameters:
      - $ref: '#/components/parameters/disputeToken'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dispute-v1'
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Withdraw chargeback request
      tags:
      - Chargeback
    get:
      description: Get chargeback request.
      operationId: getDisputeByToken
      parameters:
      - $ref: '#/components/parameters/disputeToken'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dispute-v1'
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Get chargeback request
      tags:
      - Chargeback
    patch:
      description: Update chargeback request. Can only be modified if status is `NEW`.
      operationId: updateDisputeByToken
      parameters:
      - $ref: '#/components/parameters/disputeToken'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                amount:
                  description: Amount for chargeback
                  type: integer
                customer_filed_date:
                  description: Date the customer filed the chargeback request
                  format: date-time
                  type: string
                customer_note:
                  description: Customer description
                  type: string
                reason:
                  description: Reason for chargeback
                  enum:
                  - ATM_CASH_MISDISPENSE
                  - CANCELLED
                  - DUPLICATED
                  - FRAUD_CARD_NOT_PRESENT
                  - FRAUD_CARD_PRESENT
                  - FRAUD_OTHER
                  - GOODS_SERVICES_NOT_AS_DESCRIBED
                  - GOODS_SERVICES_NOT_RECEIVED
                  - INCORRECT_AMOUNT
                  - MISSING_AUTH
                  - OTHER
                  - PROCESSING_ERROR
                  - RECURRING_TRANSACTION_NOT_CANCELLED
                  - REFUND_NOT_PROCESSED
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dispute-v1'
          description: OK
        '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'
      summary: Update chargeback request
      tags:
      - Chargeback
  /v1/disputes/{dispute_token}/evidences:
    get:
      description: List evidence for a chargeback request.
      operationId: getDisputeEvidences
      parameters:
      - $ref: '#/components/parameters/beginTime'
      - $ref: '#/components/parameters/disputeToken'
      - $ref: '#/components/parameters/endTime'
      - $ref: '#/components/parameters/endingBefore'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/startingAfter'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/dispute-evidence'
                    type: array
                  has_more:
                    description: More data exists.
                    type: boolean
                required:
                - data
                - has_more
                type: object
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: List evidence
      tags:
      - Chargeback
    post:
      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.

        '
      operationId: postEvidenceDocument
      parameters:
      - $ref: '#/components/parameters/disputeToken'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                filename:
                  description: Filename of the evidence.
                  type: string
              type: object
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dispute-evidence'
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Upload evidence
      tags:
      - Chargeback
  /v1/disputes/{dispute_token}/evidences/{evidence_token}:
    delete:
      description: Soft delete evidence for a chargeback request. Evidence will not be reviewed or submitted by Lithic after it is withdrawn.
      operationId: deleteDisputeEvidenceByToken
      parameters:
      - $ref: '#/components/parameters/disputeEvidenceToken'
      - $ref: '#/components/parameters/disputeToken'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dispute-evidence'
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Delete evidence
      tags:
      - Chargeback
    get:
      description: Get evidence for a chargeback request.
      operationId: getDisputeEvidenceByToken
      parameters:
      - $ref: '#/components/parameters/disputeEvidenceToken'
      - $ref: '#/components/parameters/disputeToken'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dispute-evidence'
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Get evidence
      tags:
      - Chargeback
components:
  parameters:
    startingAfter:
      description: A cursor representing an item's token after which a page of results should begin. Used to retrieve the next page of results after this item.
      in: query
      name: starting_after
      required: false
      schema:
        type: string
    endingBefore:
      description: A cursor representing an item's token before which a page of results should end. Used to retrieve the previous page of results before this item.
      in: query
      name: ending_before
      required: false
      schema:
        type: string
    disputeEvidenceToken:
      examples:
        disputeEvidenceExample:
          summary: A sample evidence token
          value: 73ca53a1-ae89-491a-97d9-f64788f8b2ab
      in: path
      name: evidence_token
      required: true
      schema:
        format: uuid
        type: string
    endTime:
      description: Date string in RFC 3339 format. Only entries created before the specified time will be included. UTC time zone.
      in: query
      name: end
      schema:
        format: date-time
        type: string
    pageSize:
      description: Page size (for pagination).
      in: query
      name: page_size
      schema:
        default: 50
        maximum: 100
        minimum: 1
        type: integer
    disputeToken:
      examples:
        disputeTokenExample:
          summary: A sample chargeback request token
          value: 73ca53a1-ae89-491a-97d9-f64788f8b2ab
      in: path
      name: dispute_token
      required: true
      schema:
        format: uuid
        type: string
    beginTime:
      description: Date string in RFC 3339 format. Only entries created after the specified time will be included. UTC time zone.
      in: query
      name: begin
      schema:
        format: date-time
        type: string
  schemas:
    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
    dispute-evidence:
      title: Dispute Evidence
      description: Dispute evidence.
      properties:
        created:
          description: Timestamp of when dispute evidence was created.
          format: date-time
          type: string
        dispute_token:
          description: Dispute token evidence is attached to.
          format: uuid
          type: string
        download_url:
          description: URL to download evidence. Only shown when `upload_status` is `UPLOADED`.
          type: string
        filename:
          description: File name of evidence. Recommended to give the dispute evidence a human-readable identifier.
          type: string
        token:
          description: Globally unique identifier.
          format: uuid
          type: string
        upload_status:
          description: 'Upload status types:

            * `DELETED` - Evidence was deleted.

            * `ERROR` - Evidence upload failed.

            * `PENDING` - Evidence is pending upload.

            * `REJECTED` - Evidence was rejected.

            * `UPLOADED` - Evidence was uploaded.

            '
          enum:
          - DELETED
          - ERROR
          - PENDING
          - REJECTED
          - UPLOADED
          type: string
        upload_url:
          description: URL to upload evidence. Only shown when `upload_status` is `PENDING`.
          type: string
      required:
      - created
      - dispute_token
      - token
      - upload_status
      type: object
    dispute-v1:
      title: Dispute
      description: Dispute.
      properties:
        amount:
          description: Amount under dispute. May be different from the original transaction amount.
          type: integer
        arbitration_date:
          description: Date dispute entered arbitration.
          format: date-time
          type:
          - string
          - 'null'
        created:
          description: Timestamp of when first Dispute was reported.
          format: date-time
          type: string
        customer_filed_date:
          description: Date that the dispute was filed by the customer making the dispute.
          format: date-time
          type:
          - string
          - 'null'
        customer_note:
          description: End customer description of the reason for the dispute.
          maxLength: 10000
          type:
          - string
          - 'null'
        network_claim_ids:
          description: Unique identifiers for the dispute from the network.
          oneOf:
          - type: array
            items:
              type: string
          - type: 'null'
        network_filed_date:
          description: Date that the dispute was submitted to the network.
          format: date-time
          type:
          - string
          - 'null'
        network_reason_code:
          description: Network reason code used to file the dispute.
          type:
          - string
          - 'null'
        prearbitration_date:
          description: Date dispute entered pre-arbitration.
          format: date-time
          type:
          - string
          - 'null'
        primary_claim_id:
          description: Unique identifier for the dispute from the network. If there are multiple, this will be the first claim id set by the network
          type:
          - string
          - 'null'
        reason:
          description: 'Dispute reason:

            * `ATM_CASH_MISDISPENSE`: ATM cash misdispense.

            * `CANCELLED`: Transaction was cancelled by the customer.

            * `DUPLICATED`: The transaction was a duplicate.

            * `FRAUD_CARD_NOT_PRESENT`: Fraudulent transaction, card not present.

            * `FRAUD_CARD_PRESENT`: Fraudulent transaction, card present.

            * `FRAUD_OTHER`: Fraudulent transaction, other types such as questionable merchant activity.

            * `GOODS_SERVICES_NOT_AS_DESCRIBED`: The goods or services were not as described.

            * `GOODS_SERVICES_NOT_RECEIVED`: The goods or services were not received.

            * `INCORRECT_AMOUNT`: The transaction amount was incorrect.

            * `MISSING_AUTH`: The transaction was missing authorization.

            * `OTHER`: Other reason.

            * `PROCESSING_ERROR`: Processing error.

            * `REFUND_NOT_PROCESSED`: The refund was not processed.

            * `RECURRING_TRANSACTION_NOT_CANCELLED`: The recurring transaction was not cancelled.

            '
          enum:
          - ATM_CASH_MISDISPENSE
          - CANCELLED
          - DUPLICATED
          - FRAUD_CARD_NOT_PRESENT
          - FRAUD_CARD_PRESENT
          - FRAUD_OTHER
          - GOODS_SERVICES_NOT_AS_DESCRIBED
          - GOODS_SERVICES_NOT_RECEIVED
          - INCORRECT_AMOUNT
          - MISSING_AUTH
          - OTHER
          - PROCESSING_ERROR
          - RECURRING_TRANSACTION_NOT_CANCELLED
          - REFUND_NOT_PROCESSED
          type: string
        representment_date:
          description: Date the representment was received.
          format: date-time
          type:
          - string
          - 'null'
        resolution_date:
          description: Date that the dispute was resolved.
          format: date-time
          type:
          - string
          - 'null'
        resolution_note:
          description: Note by Dispute team on the case resolution.
          maxLength: 10000
          type:
          - string
          - 'null'
        resolution_reason:
          description: 'Reason for the dispute resolution:

            * `CASE_LOST`: This case was lost at final arbitration.

            * `NETWORK_REJECTED`: Network rejected.

            * `NO_DISPUTE_RIGHTS_3DS`: No dispute rights, 3DS.

            * `NO_DISPUTE_RIGHTS_BELOW_THRESHOLD`: No dispute rights, below threshold.

            * `NO_DISPUTE_RIGHTS_CONTACTLESS`: No dispute rights, contactless.

            * `NO_DISPUTE_RIGHTS_HYBRID`: No dispute rights, hybrid.

            * `NO_DISPUTE_RIGHTS_MAX_CHARGEBACKS`: No dispute rights, max chargebacks.

            * `NO_DISPUTE_RIGHTS_OTHER`: No dispute rights, other.

            * `PAST_FILING_DATE`: Past filing date.

            * `PREARBITRATION_REJECTED`: Prearbitration rejected.

            * `PROCESSOR_REJECTED_OTHER`: Processor rejected, other.

            * `REFUNDED`: Refunded.

            * `REFUNDED_AFTER_CHARGEBACK`: Refunded after chargeback.

            * `WITHDRAWN`: Withdrawn.

            * `WON_ARBITRATION`: Won arbitration.

            * `WON_FIRST_CHARGEBACK`: Won first chargeback.

            * `WON_PREARBITRATION`: Won prearbitration.

            '
          enum:
          - CASE_LOST
          - NETWORK_REJECTED
          - NO_DISPUTE_RIGHTS_3DS
          - NO_DISPUTE_RIGHTS_BELOW_THRESHOLD
          - NO_DISPUTE_RIGHTS_CONTACTLESS
          - NO_DISPUTE_RIGHTS_HYBRID
          - NO_DISPUTE_RIGHTS_MAX_CHARGEBACKS
          - NO_DISPUTE_RIGHTS_OTHER
          - PAST_FILING_DATE
          - PREARBITRATION_REJECTED
          - PROCESSOR_REJECTED_OTHER
          - REFUNDED
          - REFUNDED_AFTER_CHARGEBACK
          - WITHDRAWN
          - WON_ARBITRATION
          - WON_FIRST_CHARGEBACK
          - WON_PREARBITRATION
          - null
          type:
          - string
          - 'null'
        status:
          description: 'Status types:

            * `NEW` - New dispute case is opened.

            * `PENDING_CUSTOMER` - Lithic is waiting for customer to provide more information.

            * `SUBMITTED` - Dispute is submitted to the card network.

            * `REPRESENTMENT` - Case has entered second presentment.

            * `PREARBITRATION` - Case has entered prearbitration.

            * `ARBITRATION` - Case has entered arbitration.

            * `CASE_WON` - Case was won and credit will be issued.

            * `CASE_CLOSED` - Case was lost or withdrawn.

            '
          enum:
          - ARBITRATION
          - CASE_CLOSED
          - CASE_WON
          - NEW
          - PENDING_CUSTOMER
          - PREARBITRATION
          - REPRESENTMENT
          - SUBMITTED
          type: string
        token:
          description: Globally unique identifier.
          format: uuid
          type: string
        transaction_token:
          description: The transaction that is being disputed. A transaction can only be disputed once but may have multiple dispute cases.
          format: uuid
          type: string
      required:
      - amount
      - arbitration_date
      - created
      - customer_filed_date
      - customer_note
      - network_claim_ids
      - network_filed_date
      - network_reason_code
      - prearbitration_date
      - primary_claim_id
      - reason
      - representment_date
      - resolution_date
      - resolution_note
      - resolution_reason
      - status
      - token
      - transaction_token
      type: object
  responses:
    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 |

        '
    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.
    UnprocessableEntity:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
      description: Unprocessable entity.
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: Authorization
      type: apiKey