openapi: 3.1.0
info:
  title: Vantiv Chargeback Authorizations Chargebacks 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: Chargebacks
  description: Chargeback dispute retrieval and response management
paths:
  /chargebacks:
    get:
      operationId: listChargebacks
      summary: List Chargebacks
      description: Retrieve a list of chargebacks with optional date range and status filters.
      tags:
      - Chargebacks
      parameters:
      - name: date
        in: query
        schema:
          type: string
          format: date
        description: Filter chargebacks by activity date (YYYY-MM-DD)
      - name: financialImpact
        in: query
        schema:
          type: boolean
        description: Filter to only return chargebacks with financial impact
      - name: responded
        in: query
        schema:
          type: boolean
        description: Filter by whether the chargeback has been responded to
      responses:
        '200':
          description: List of chargebacks
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ChargebackListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /chargebacks/{caseId}:
    get:
      operationId: getChargeback
      summary: Get Chargeback
      description: Retrieve detailed information about a specific chargeback case.
      tags:
      - Chargebacks
      parameters:
      - name: caseId
        in: path
        required: true
        schema:
          type: integer
          format: int64
        description: Unique chargeback case identifier
      responses:
        '200':
          description: Chargeback details
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ChargebackResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /chargebacks/{caseId}/response:
    put:
      operationId: respondToChargeback
      summary: Respond To Chargeback
      description: Submit a merchant response to a chargeback dispute. The response may include accepting the chargeback or providing a rebuttal.
      tags:
      - Chargebacks
      parameters:
      - name: caseId
        in: path
        required: true
        schema:
          type: integer
          format: int64
        description: Unique chargeback case identifier
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/ChargebackResponseRequest'
      responses:
        '200':
          description: Response submitted successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ChargebackUpdateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '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
    Chargeback:
      type: object
      properties:
        caseId:
          type: integer
          format: int64
          description: Unique case identifier
        merchantId:
          type: string
          description: Merchant account identifier
        cnpTxnId:
          type: integer
          format: int64
          description: Original transaction ID
        amount:
          type: integer
          description: Disputed amount in cents
        reasonCode:
          type: string
          description: Card network chargeback reason code
        reasonCodeDescription:
          type: string
          description: Description of the dispute reason
        disputeDate:
          type: string
          format: date
          description: Date dispute was initiated
        replyByDate:
          type: string
          format: date
          description: Deadline to respond to the chargeback
        activity:
          type: string
          enum:
          - ASSIGNED
          - CONTESTED
          - WITHDRAWN
          - REPRESENTMENT
          - PRE_ARB
          - ARBITRATION
          - ISSUER_DECLINED
          - MERCHANT_ACCEPTED
          description: Current chargeback lifecycle activity
        financialImpact:
          type: boolean
          description: Whether this chargeback has a financial impact
    ChargebackUpdateResponse:
      type: object
      properties:
        transactionId:
          type: integer
          format: int64
          description: Response transaction ID
    ChargebackListResponse:
      type: object
      properties:
        chargebackCase:
          type: array
          items:
            $ref: '#/components/schemas/Chargeback'
    ChargebackResponseRequest:
      type: object
      required:
      - activity
      properties:
        activity:
          type: string
          enum:
          - MERCHANT_ACCEPTS
          - MERCHANT_CONTESTS
          description: Merchant response type
        note:
          type: string
          description: Optional response note or rebuttal
    ChargebackResponse:
      type: object
      properties:
        chargebackCase:
          $ref: '#/components/schemas/Chargeback'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic