openapi: 3.1.0
info:
  title: Vantiv Chargeback Authorizations 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: Authorizations
  description: Card authorization and fund verification
paths:
  /authorization:
    post:
      operationId: createAuthorization
      summary: Create Authorization
      description: Authorize a card transaction to verify funds availability and place a hold on the cardholder's credit line. Returns an authorization code that must be captured to complete the transaction.
      tags:
      - Authorizations
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/AuthorizationRequest'
      responses:
        '200':
          description: Authorization response
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/AuthorizationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    AuthorizationResponse:
      type: object
      properties:
        id:
          type: string
          description: Request identifier echoed back
        reportGroup:
          type: string
          description: Report group identifier
        cnpTxnId:
          type: integer
          format: int64
          description: Vantiv-assigned transaction ID for capture/void
        orderId:
          type: string
          description: Merchant order ID echoed back
        response:
          type: string
          description: Response code (000 = approved)
        responseTime:
          type: string
          format: date-time
          description: Response timestamp
        postDate:
          type: string
          description: Transaction post date
        message:
          type: string
          description: Response message (e.g., Approved)
        authCode:
          type: string
          description: Authorization code from card network
        avsResult:
          type: string
          description: Address verification result code
        cardValidationResult:
          type: string
          description: CVV verification result code
        fraudResult:
          type: object
          properties:
            avsResult:
              type: string
            cardValidationResult:
              type: string
    AuthorizationRequest:
      type: object
      required:
      - merchantId
      - id
      - orderId
      - amount
      - orderSource
      - card
      properties:
        merchantId:
          type: string
          description: Vantiv merchant account identifier
        id:
          type: string
          description: Unique request identifier (max 25 chars)
        orderId:
          type: string
          description: Merchant order identifier
        amount:
          type: integer
          description: Transaction amount in cents
        orderSource:
          type: string
          enum:
          - ecommerce
          - moto
          - recurring
          - installment
          description: Order source channel
        card:
          $ref: '#/components/schemas/CardType'
        billToAddress:
          $ref: '#/components/schemas/AddressType'
        customerInfo:
          type: object
          properties:
            ssn:
              type: string
            dob:
              type: string
    AddressType:
      type: object
      description: Billing address for AVS verification
      properties:
        name:
          type: string
          description: Cardholder name
        addressLine1:
          type: string
          description: Street address
        city:
          type: string
          description: City
        state:
          type: string
          description: State/province code
        zip:
          type: string
          description: Postal code
        country:
          type: string
          description: Country code (ISO 3166-1 alpha-2)
    ErrorResponse:
      type: object
      properties:
        response:
          type: string
          description: Error response code
        message:
          type: string
          description: Error message
    CardType:
      type: object
      description: Payment card details
      properties:
        type:
          type: string
          enum:
          - VI
          - MC
          - AX
          - DI
          - JC
          description: Card type (Visa, MasterCard, Amex, Discover, JCB)
        number:
          type: string
          description: Card number (PAN) or token
        expDate:
          type: string
          pattern: ^\d{4}$
          description: Expiration date in MMYY format
        cardValidationNum:
          type: string
          description: CVV/CVV2 security code
  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'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic