Visa Card on File Data Inquiry API API

openapi: 3.2.0
info:
  title: Card on File Data Inquiry API
  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
servers:
- url: https://sandbox.api.visa.com
  description: Sandbox Server
- url: https://api.visa.com
  description: Production Server
security:
- mutualTLS: []
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.
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:
  schemas:
    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
    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
    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
  securitySchemes:
    mutualTLS:
      type: mutualTLS
      description: Two-way SSL mutual authentication using a PKI certificate issued by Visa.
externalDocs:
  description: Card on File Data Inquiry Documentation
  url: https://developer.visa.com/capabilities/card-on-file-data-inquiry/docs-getting-started