openapi: 3.1.0
info:
  title: Vantiv Chargeback Authorizations Documents API
  description: The Vantiv Chargeback API provides programmatic access to chargeback and dispute management. Merchants can retrieve chargeback details, upload evidence documents, respond to disputes, and manage the entire chargeback lifecycle. This API is used to defend against fraudulent disputes and retrieve chargeback settlement information.
  version: '2.0'
  contact:
    name: Worldpay Developer Hub
    url: https://developer.worldpay.com
  license:
    name: Proprietary
    url: https://developer.vantiv.com/community/ecommerce
servers:
- url: https://services.vantivprelive.com/services/chargebacks
  description: Vantiv Pre-Live (Staging) Environment
- url: https://services.vantivcnp.com/services/chargebacks
  description: Vantiv Production Environment
security:
- basicAuth: []
tags:
- name: Documents
  description: Evidence document upload and management for chargebacks
paths:
  /chargebacks/{caseId}/documents:
    get:
      operationId: listChargebackDocuments
      summary: List Chargeback Documents
      description: List all evidence documents uploaded for a chargeback case.
      tags:
      - Documents
      parameters:
      - name: caseId
        in: path
        required: true
        schema:
          type: integer
          format: int64
        description: Unique chargeback case identifier
      responses:
        '200':
          description: List of uploaded documents
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/DocumentListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: uploadChargebackDocument
      summary: Upload Chargeback Document
      description: Upload an evidence document to support a chargeback dispute response.
      tags:
      - Documents
      parameters:
      - name: caseId
        in: path
        required: true
        schema:
          type: integer
          format: int64
        description: Unique chargeback case identifier
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: Evidence document file (PDF, JPG, PNG)
      responses:
        '200':
          description: Document uploaded successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/DocumentUploadResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /chargebacks/{caseId}/documents/{documentId}:
    delete:
      operationId: deleteChargebackDocument
      summary: Delete Chargeback Document
      description: Remove a previously uploaded evidence document from a chargeback case.
      tags:
      - Documents
      parameters:
      - name: caseId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      - name: documentId
        in: path
        required: true
        schema:
          type: string
        description: Document identifier
      responses:
        '200':
          description: Document deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Chargeback case not found
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ErrorResponse:
      type: object
      properties:
        response:
          type: string
        message:
          type: string
    DocumentListResponse:
      type: object
      properties:
        documentList:
          type: array
          items:
            $ref: '#/components/schemas/Document'
    DocumentUploadResponse:
      type: object
      properties:
        documentId:
          type: string
          description: Assigned document identifier
    Document:
      type: object
      properties:
        documentId:
          type: string
          description: Document identifier
        documentType:
          type: string
          description: Document MIME type
        size:
          type: integer
          description: Document size in bytes
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic