openapi: 3.1.0
info:
  title: Vantiv CNP API
  description: >-
    The Vantiv Card Not Present (CNP) API (formerly the Litle eCommerce API) enables
    online and mobile payment processing. The API supports card authorizations, sales,
    captures, credits, voids, tokenization via eProtect/Vault, recurring billing, and
    chargeback management. Communication occurs via HTTPS POST with XML payloads.
    Vantiv merged with Worldpay in 2018 and the service is now offered as Worldpay from FIS.
  version: '12.0'
  contact:
    name: Worldpay Developer Hub
    url: https://developer.worldpay.com
  termsOfService: https://developer.vantiv.com/community/ecommerce
  license:
    name: Proprietary
    url: https://developer.vantiv.com/community/ecommerce
servers:
  - url: https://payments.vantivprelive.com/vap/communicator/online
    description: Vantiv Pre-Live (Staging) Environment
  - url: https://www.testvantivcnp.com/sandbox/communicator/online
    description: Vantiv Sandbox Environment
  - url: https://payments.vantivcnp.com/vap/communicator/online
    description: Vantiv Production Environment
security:
  - basicAuth: []
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'

  /sale:
    post:
      operationId: createSale
      summary: Create Sale
      description: >-
        Process an authorization and capture in a single step. Use for transactions
        where you want to immediately settle funds without a separate capture step.
      tags:
        - Sales
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/SaleRequest'
      responses:
        '200':
          description: Sale response
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/SaleResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /capture:
    post:
      operationId: createCapture
      summary: Create Capture
      description: >-
        Capture a previously authorized transaction to initiate settlement. Must reference
        a valid authorization transaction ID. Can capture partial amounts.
      tags:
        - Captures
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/CaptureRequest'
      responses:
        '200':
          description: Capture response
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/CaptureResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /credit:
    post:
      operationId: createCredit
      summary: Create Credit
      description: >-
        Issue a refund to a cardholder. Can be a full or partial refund of a previously
        captured transaction, or an unlinked credit to any card.
      tags:
        - Credits
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/CreditRequest'
      responses:
        '200':
          description: Credit response
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/CreditResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /void:
    post:
      operationId: createVoid
      summary: Create Void
      description: >-
        Cancel a pending transaction before it is settled. Can void authorizations,
        captures, sales, and credits that have not yet been settled.
      tags:
        - Voids
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/VoidRequest'
      responses:
        '200':
          description: Void response
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/VoidResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /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'

  /recurringTransaction:
    post:
      operationId: createRecurringTransaction
      summary: Create Recurring Transaction
      description: >-
        Process a recurring billing transaction against a stored card token.
        Used for subscription billing, installment payments, and automatic renewals.
      tags:
        - Recurring
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/RecurringTransactionRequest'
      responses:
        '200':
          description: Recurring transaction response
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/RecurringTransactionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /echeckSale:
    post:
      operationId: createEcheckSale
      summary: Create eCheck Sale
      description: >-
        Process an ACH/eCheck payment using bank account and routing number.
        Initiates an electronic check transaction for one-time or recurring bank payments.
      tags:
        - eCheck
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/EcheckSaleRequest'
      responses:
        '200':
          description: eCheck sale response
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/EcheckSaleResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /echeckCredit:
    post:
      operationId: createEcheckCredit
      summary: Create eCheck Credit
      description: >-
        Issue a refund for a previously processed eCheck/ACH transaction.
      tags:
        - eCheck
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/EcheckCreditRequest'
      responses:
        '200':
          description: eCheck credit response
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/EcheckCreditResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using merchant username and password
  responses:
    BadRequest:
      description: Bad request — malformed XML or invalid transaction data
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized — invalid merchant credentials
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    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

    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)

    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

    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

    SaleRequest:
      type: object
      required:
        - merchantId
        - id
        - orderId
        - amount
        - orderSource
        - card
      properties:
        merchantId:
          type: string
        id:
          type: string
        orderId:
          type: string
        amount:
          type: integer
          description: Amount in cents
        orderSource:
          type: string
          enum:
            - ecommerce
            - moto
            - recurring
        card:
          $ref: '#/components/schemas/CardType'
        billToAddress:
          $ref: '#/components/schemas/AddressType'

    SaleResponse:
      type: object
      properties:
        id:
          type: string
        cnpTxnId:
          type: integer
          format: int64
        orderId:
          type: string
        response:
          type: string
        message:
          type: string
        authCode:
          type: string
        avsResult:
          type: string
        cardValidationResult:
          type: string

    CaptureRequest:
      type: object
      required:
        - merchantId
        - id
        - cnpTxnId
        - amount
      properties:
        merchantId:
          type: string
        id:
          type: string
        cnpTxnId:
          type: integer
          format: int64
          description: Transaction ID from original authorization
        amount:
          type: integer
          description: Amount to capture in cents (can be less than authorization)

    CaptureResponse:
      type: object
      properties:
        id:
          type: string
        cnpTxnId:
          type: integer
          format: int64
        response:
          type: string
        message:
          type: string
        postDate:
          type: string

    CreditRequest:
      type: object
      required:
        - merchantId
        - id
        - orderId
        - amount
      properties:
        merchantId:
          type: string
        id:
          type: string
        cnpTxnId:
          type: integer
          format: int64
          description: Original transaction ID for linked credit
        orderId:
          type: string
        amount:
          type: integer
          description: Refund amount in cents

    CreditResponse:
      type: object
      properties:
        id:
          type: string
        cnpTxnId:
          type: integer
          format: int64
        response:
          type: string
        message:
          type: string

    VoidRequest:
      type: object
      required:
        - merchantId
        - id
        - cnpTxnId
      properties:
        merchantId:
          type: string
        id:
          type: string
        cnpTxnId:
          type: integer
          format: int64
          description: Transaction ID to void

    VoidResponse:
      type: object
      properties:
        id:
          type: string
        cnpTxnId:
          type: integer
          format: int64
        response:
          type: string
        message:
          type: string

    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)

    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

    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

    RecurringTransactionRequest:
      type: object
      required:
        - merchantId
        - id
        - orderId
        - amount
        - token
      properties:
        merchantId:
          type: string
        id:
          type: string
        orderId:
          type: string
        amount:
          type: integer
          description: Billing amount in cents
        token:
          type: string
          description: Vault token for stored card

    RecurringTransactionResponse:
      type: object
      properties:
        id:
          type: string
        cnpTxnId:
          type: integer
          format: int64
        response:
          type: string
        message:
          type: string
        authCode:
          type: string

    EcheckSaleRequest:
      type: object
      required:
        - merchantId
        - id
        - orderId
        - amount
        - echeck
      properties:
        merchantId:
          type: string
        id:
          type: string
        orderId:
          type: string
        amount:
          type: integer
          description: Amount in cents
        echeck:
          type: object
          properties:
            accType:
              type: string
              enum:
                - Checking
                - Savings
                - Corporate
              description: Bank account type
            accNum:
              type: string
              description: Bank account number
            routingNum:
              type: string
              description: Bank routing number

    EcheckSaleResponse:
      type: object
      properties:
        id:
          type: string
        cnpTxnId:
          type: integer
          format: int64
        orderId:
          type: string
        response:
          type: string
        message:
          type: string

    EcheckCreditRequest:
      type: object
      required:
        - merchantId
        - id
        - cnpTxnId
        - amount
      properties:
        merchantId:
          type: string
        id:
          type: string
        cnpTxnId:
          type: integer
          format: int64
        amount:
          type: integer

    EcheckCreditResponse:
      type: object
      properties:
        id:
          type: string
        cnpTxnId:
          type: integer
          format: int64
        response:
          type: string
        message:
          type: string

    ErrorResponse:
      type: object
      properties:
        response:
          type: string
          description: Error response code
        message:
          type: string
          description: Error message

tags:
  - name: Authorizations
    description: Card authorization and fund verification
  - name: Sales
    description: Combined authorization and capture transactions
  - name: Captures
    description: Capture previously authorized transactions for settlement
  - name: Credits
    description: Refunds and credits to cardholder accounts
  - name: Voids
    description: Cancel pending unsettled transactions
  - name: Tokenization
    description: Card data tokenization via Vantiv Vault
  - name: Recurring
    description: Recurring and subscription billing
  - name: eCheck
    description: ACH and electronic check payment processing