openapi: 3.1.0
info:
  title: Card on File Data Inquiry
  description: >-
    The Card on File Data Inquiry API enables issuers and merchants to retrieve
    information about where a cardholder's Visa credentials are stored on file
    with merchants. This service helps issuers provide cardholder transparency
    into which merchants have their card details stored, supporting card
    lifecycle management and fraud prevention.
  version: '1'
  contact:
    name: Visa Developer Support
    url: https://developer.visa.com/support
  termsOfService: https://developer.visa.com/capabilities/card-on-file-data-inquiry/product-terms
externalDocs:
  description: Card on File Data Inquiry Documentation
  url: https://developer.visa.com/capabilities/card-on-file-data-inquiry/docs-getting-started
servers:
  - url: https://sandbox.api.visa.com
    description: Sandbox Server
  - url: https://api.visa.com
    description: Production Server
tags:
  - name: Card on File Data Inquiry API
    description: >-
      Retrieve information about where a cardholder's Visa payment credentials
      are stored on file with participating merchants.
security:
  - mutualTLS: []
paths:
  /cofds/v1/dataInquiry:
    post:
      operationId: inquireCardOnFileData
      summary: Inquire Card on File Data
      description: >-
        Retrieves a list of merchants that have the specified Visa card stored on
        file. This allows issuers to provide cardholders with visibility into
        where their credentials are being used for recurring or stored-credential
        transactions.
      tags:
        - Card on File Data Inquiry API
      requestBody:
        description: Request body containing the card details to inquire
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CardOnFileInquiryRequest'
      responses:
        '200':
          description: Card on file data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardOnFileInquiryResponse'
        '400':
          description: Bad request - invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - authentication failure
        '404':
          description: No card on file data found for the specified account
components:
  securitySchemes:
    mutualTLS:
      type: mutualTLS
      description: >-
        Two-way SSL mutual authentication using a PKI certificate issued by
        Visa.
  schemas:
    CardOnFileInquiryRequest:
      type: object
      required:
        - primaryAccountNumber
      properties:
        primaryAccountNumber:
          type: string
          description: >-
            The 16-digit primary account number (PAN) of the Visa card to
            inquire about
          minLength: 13
          maxLength: 19
        paymentAccountReference:
          type: string
          description: >-
            Payment Account Reference (PAR) as an alternative identifier to the
            PAN
        requestTimeStamp:
          type: string
          format: date-time
          description: Timestamp of the inquiry request in ISO 8601 format
    CardOnFileInquiryResponse:
      type: object
      properties:
        status:
          type: string
          description: Status of the inquiry
          enum:
            - SUCCESS
            - NO_DATA_FOUND
            - PARTIAL_DATA
        merchants:
          type: array
          description: List of merchants with the card stored on file
          items:
            $ref: '#/components/schemas/MerchantCardOnFile'
        totalCount:
          type: integer
          description: Total number of merchants with the card on file
    MerchantCardOnFile:
      type: object
      properties:
        merchantName:
          type: string
          description: Name of the merchant storing the card on file
        merchantId:
          type: string
          description: Unique identifier for the merchant
        merchantCategoryCode:
          type: string
          description: Merchant Category Code (MCC)
          pattern: '^\d{4}$'
        lastTransactionDate:
          type: string
          format: date
          description: Date of the last transaction with this merchant
        enrollmentDate:
          type: string
          format: date
          description: Date the card was stored on file with this merchant
        transactionType:
          type: string
          description: Type of stored credential usage
          enum:
            - RECURRING
            - INSTALLMENT
            - UNSCHEDULED
            - SUBSCRIPTION
    ErrorResponse:
      type: object
      properties:
        errorCode:
          type: string
          description: Machine-readable error code
        message:
          type: string
          description: Human-readable error description