Visa Transaction Enrichment API API

openapi: 3.2.0
info:
  title: Visa Merchant Search Transaction Enrichment API
  description: The Visa Merchant Search API provides enriched and precise merchant data to create a more transparent and effective transaction process. The API supports transaction enrichment with enhanced merchant information, generic merchant search by name and location, and nearby merchant discovery for Visa-accepting locations.
  version: '1'
  contact:
    name: Visa Developer Support
    url: https://developer.visa.com/support
  termsOfService: https://developer.visa.com/capabilities/merchant_search/product-terms
servers:
- url: https://sandbox.api.visa.com
  description: Sandbox Server
- url: https://api.visa.com
  description: Production Server
security:
- mutualTLS: []
tags:
- name: Transaction Enrichment API
  description: Enrich transaction data with additional merchant information including street addresses, URLs, logos, and contact details.
paths:
  /merchantsearch/v1/transactionenrichment:
    post:
      operationId: enrichTransaction
      summary: Enrich Transaction
      description: Enriches transaction data with enhanced merchant information such as merchant street address, website URL, logo, and contact information. This operation helps improve the cardholder experience by providing clearer and more recognizable merchant details on statements.
      tags:
      - Transaction Enrichment API
      requestBody:
        description: Transaction details to enrich
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionEnrichmentRequest'
      responses:
        '200':
          description: Transaction enriched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionEnrichmentResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
components:
  schemas:
    TransactionEnrichmentRequest:
      type: object
      required:
      - acquirerCardAcceptorId
      properties:
        acquirerCardAcceptorId:
          type: string
          description: Card acceptor ID from the transaction
        acquiringBin:
          type: string
          description: Acquiring bank identification number
        merchantName:
          type: string
          description: Merchant name from the transaction
        merchantCategoryCode:
          type: string
          description: Merchant Category Code from the transaction
    TransactionEnrichmentResponse:
      type: object
      properties:
        merchantSearchServiceResponse:
          type: object
          properties:
            response:
              type: array
              description: Enriched merchant information
              items:
                $ref: '#/components/schemas/EnrichedMerchant'
    ErrorResponse:
      type: object
      properties:
        errorCode:
          type: string
          description: Machine-readable error code
        message:
          type: string
          description: Human-readable error description
    EnrichedMerchant:
      type: object
      properties:
        visaMerchantId:
          type: string
          description: Visa-assigned merchant identifier
        merchantName:
          type: string
          description: Cleaned merchant name
        merchantUrl:
          type: string
          format: uri
          description: Merchant website URL
        merchantLogoUrl:
          type: string
          format: uri
          description: URL of the merchant logo
        merchantAddress:
          type: object
          properties:
            street:
              type: string
              description: Street address
            city:
              type: string
              description: City
            state:
              type: string
              description: State or province
            postalCode:
              type: string
              description: Postal code
            country:
              type: string
              description: Country code
        merchantCategoryCode:
          type: string
          description: Merchant Category Code
        phoneNumber:
          type: string
          description: Merchant phone number
  securitySchemes:
    mutualTLS:
      type: mutualTLS
      description: Two-way SSL mutual authentication using a PKI certificate issued by Visa.
externalDocs:
  description: Merchant Search Documentation
  url: https://developer.visa.com/capabilities/merchant_search/docs