openapi: 3.1.0
info:
  title: Vantiv Chargeback Authorizations Tokenization 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: Tokenization
  description: Card data tokenization via Vantiv Vault
paths:
  /registerTokenRequest:
    post:
      operationId: registerToken
      summary: Register Token
      description: Tokenize a payment card number into a secure token via the Vantiv Vault. The token can be used for subsequent transactions without storing raw card data, reducing PCI scope.
      tags:
      - Tokenization
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/RegisterTokenRequest'
      responses:
        '200':
          description: Token registration response
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/RegisterTokenResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /updateCardValidationNumRequest:
    post:
      operationId: updateCardValidationNumber
      summary: Update Card Validation Number
      description: Update the CVV/CVV2 validation number associated with a stored token.
      tags:
      - Tokenization
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/UpdateCardValidationRequest'
      responses:
        '200':
          description: Card validation update response
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/UpdateCardValidationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Unauthorized — invalid merchant credentials
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request — malformed XML or invalid transaction data
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ErrorResponse:
      type: object
      properties:
        response:
          type: string
          description: Error response code
        message:
          type: string
          description: Error message
    UpdateCardValidationRequest:
      type: object
      required:
      - merchantId
      - id
      - orderId
      - token
      - cardValidationNum
      properties:
        merchantId:
          type: string
        id:
          type: string
        orderId:
          type: string
        token:
          type: string
          description: Existing vault token
        cardValidationNum:
          type: string
          description: New CVV value
    UpdateCardValidationResponse:
      type: object
      properties:
        id:
          type: string
        response:
          type: string
        message:
          type: string
    RegisterTokenResponse:
      type: object
      properties:
        id:
          type: string
        cnpTxnId:
          type: integer
          format: int64
        orderId:
          type: string
        response:
          type: string
        message:
          type: string
        litleToken:
          type: string
          description: The generated payment token
    RegisterTokenRequest:
      type: object
      required:
      - merchantId
      - id
      - orderId
      - accountNumber
      properties:
        merchantId:
          type: string
        id:
          type: string
        orderId:
          type: string
        accountNumber:
          type: string
          description: Card PAN to tokenize
        cardValidationNum:
          type: string
          description: CVV (optional, not stored)
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic