Visa Customer Rules API

openapi: 3.2.0
info:
  title: Visa Transaction Controls Customer Rules API
  description: The Visa Transaction Controls (VTC) API enables issuers to offer their cardholders the ability to set spending rules and receive real-time alerts on their Visa payment cards. Cardholders can define rules to block or alert on specific transaction types, merchant categories, geographic locations, spending thresholds, and more.
  version: '1'
  contact:
    name: Visa Developer Support
    url: https://developer.visa.com/support
  termsOfService: https://developer.visa.com/capabilities/vctc/product-terms
servers:
- url: https://sandbox.api.visa.com
  description: Sandbox Server
- url: https://api.visa.com
  description: Production Server
security:
- mutualTLS: []
tags:
- name: Customer Rules API
  description: Register consumer accounts and manage payment rules and thresholds that define which transaction types to block or alert on.
paths:
  /vctc/customerrules/v1/consumertransactioncontrols:
    post:
      operationId: createCustomerRules
      summary: Create Customer Rules
      description: Registers a consumer's payment account to the VTC service and establishes the payment rules and thresholds that define which transaction types the consumer wants to block or receive alerts about.
      tags:
      - Customer Rules API
      requestBody:
        description: Customer rules configuration
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerRulesRequest'
      responses:
        '200':
          description: Customer rules created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerRulesResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
    get:
      operationId: getCustomerRules
      summary: Get Customer Rules
      description: Retrieves the current transaction control rules configured for a registered consumer account.
      tags:
      - Customer Rules API
      parameters:
      - name: primaryAccountNumber
        in: query
        required: true
        description: Primary account number of the registered card
        schema:
          type: string
      responses:
        '200':
          description: Customer rules retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerRulesResponse'
        '401':
          description: Unauthorized
        '404':
          description: No rules found for the specified account
    put:
      operationId: updateCustomerRules
      summary: Update Customer Rules
      description: Updates the transaction control rules for an existing registered consumer account.
      tags:
      - Customer Rules API
      requestBody:
        description: Updated customer rules configuration
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerRulesRequest'
      responses:
        '200':
          description: Customer rules updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerRulesResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
    delete:
      operationId: deleteCustomerRules
      summary: Delete Customer Rules
      description: Removes transaction control rules and unregisters a consumer account from the VTC service.
      tags:
      - Customer Rules API
      parameters:
      - name: primaryAccountNumber
        in: query
        required: true
        description: Primary account number to deregister
        schema:
          type: string
      responses:
        '200':
          description: Customer rules deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Account not found
components:
  schemas:
    CustomerRulesRequest:
      type: object
      required:
      - primaryAccountNumber
      properties:
        primaryAccountNumber:
          type: string
          description: Primary account number to register or update
        controls:
          type: array
          description: List of transaction controls to apply
          items:
            $ref: '#/components/schemas/TransactionControl'
    TransactionControl:
      type: object
      properties:
        controlType:
          type: string
          description: Type of transaction control
          enum:
          - TRANSACTION_AMOUNT
          - MERCHANT_CATEGORY
          - GEOGRAPHIC_LOCATION
          - TRANSACTION_TYPE
          - CHANNEL
        isDeclinedEnabled:
          type: boolean
          description: Whether to decline matching transactions
        isAlertEnabled:
          type: boolean
          description: Whether to send alerts for matching transactions
        merchantCategoryCodes:
          type: array
          description: MCC codes to control (applicable when controlType is MERCHANT_CATEGORY)
          items:
            type: string
        countryCodes:
          type: array
          description: Country codes to control (applicable when controlType is GEOGRAPHIC_LOCATION)
          items:
            type: string
        thresholdAmount:
          type: number
          format: double
          description: Threshold amount for amount-based controls
        transactionTypes:
          type: array
          description: Transaction types to control
          items:
            type: string
            enum:
            - ATM
            - ECOMMERCE
            - IN_STORE
            - INTERNATIONAL
    ErrorResponse:
      type: object
      properties:
        errorCode:
          type: string
          description: Machine-readable error code
        message:
          type: string
          description: Human-readable error description
    CustomerRulesResponse:
      type: object
      properties:
        primaryAccountNumber:
          type: string
          description: Primary account number
        status:
          type: string
          description: Registration status
        controls:
          type: array
          description: Active controls on the account
          items:
            $ref: '#/components/schemas/TransactionControl'
  securitySchemes:
    mutualTLS:
      type: mutualTLS
      description: Two-way SSL mutual authentication using a PKI certificate issued by Visa.
externalDocs:
  description: Visa Transaction Controls Documentation
  url: https://developer.visa.com/capabilities/vctc/docs