openapi: 3.0.1
info:
  title: Foreign Exchange Rates Funds Transfer API API
  description: Push and pull funds to and from Visa accounts for real-time money movement use cases including person-to-person transfers, business disbursements, and account funding transactions.
  version: '1'
servers:
- url: https://sandbox.api.visa.com
  description: Sandbox server
security: []
tags:
- name: Funds Transfer API
  description: Push and pull funds to and from Visa accounts for real-time money movement use cases including person-to-person transfers, business disbursements, and account funding transactions.
paths:
  /visadirect/fundstransfer/v1/pushfundstransactions:
    post:
      operationId: pushFunds
      summary: Push Funds Transaction
      description: Pushes funds to a recipient's Visa account. This operation is used to deliver money to a recipient in real-time, supporting use cases such as person-to-person payments, payroll disbursements, insurance claims, and government benefits.
      tags:
      - Funds Transfer API
      requestBody:
        description: Push funds transaction request details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PushFundsRequest'
      responses:
        '200':
          description: Push funds transaction processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PushFundsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
  /visadirect/fundstransfer/v1/pullfundstransactions:
    post:
      operationId: pullFunds
      summary: Pull Funds Transaction
      description: Pulls funds from a sender's Visa account. This operation debits funds from the sender's account, typically as the first step in a two-step funds transfer where funds are subsequently pushed to a recipient.
      tags:
      - Funds Transfer API
      requestBody:
        description: Pull funds transaction request details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PullFundsRequest'
      responses:
        '200':
          description: Pull funds transaction processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PullFundsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
  /visadirect/fundstransfer/v1/multipushfundstransactions:
    post:
      operationId: multiPushFunds
      summary: Multi Push Funds Transaction
      description: Pushes funds to multiple recipient Visa accounts in a single request. This batch operation enables efficient disbursement to many recipients simultaneously.
      tags:
      - Funds Transfer API
      requestBody:
        description: Multi push funds transaction request details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MultiPushFundsRequest'
      responses:
        '200':
          description: Multi push funds transaction processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultiPushFundsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
  /visadirect/fundstransfer/v1/multipullfundstransactions:
    post:
      operationId: multiPullFunds
      summary: Multi Pull Funds Transaction
      description: Pulls funds from multiple sender Visa accounts in a single request. This batch operation supports scenarios requiring funds collection from many accounts simultaneously.
      tags:
      - Funds Transfer API
      requestBody:
        description: Multi pull funds transaction request details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MultiPullFundsRequest'
      responses:
        '200':
          description: Multi pull funds transaction processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultiPullFundsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
  /visadirect/fundstransfer/v1/reversefundstransactions:
    post:
      operationId: reverseFunds
      summary: Reverse Funds Transaction
      description: Reverses a previously completed push or pull funds transaction. This operation is used to return funds in cases of errors, disputes, or refund scenarios.
      tags:
      - Funds Transfer API
      requestBody:
        description: Reverse funds transaction request details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReverseFundsRequest'
      responses:
        '200':
          description: Reverse funds transaction processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReverseFundsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
components:
  schemas:
    PullFundsRequest:
      type: object
      required:
      - systemsTraceAuditNumber
      - retrievalReferenceNumber
      - acquiringBin
      - acquirerCountryCode
      - senderPrimaryAccountNumber
      - transactionCurrencyCode
      - amount
      properties:
        systemsTraceAuditNumber:
          type: string
          description: A unique six-digit value assigned by the acquirer to identify a transaction
          maxLength: 6
        retrievalReferenceNumber:
          type: string
          description: A 12-character retrieval reference number
          maxLength: 12
        acquiringBin:
          type: string
          description: Bank Identification Number of the acquiring institution
        acquirerCountryCode:
          type: string
          description: ISO numeric country code of the acquirer
          pattern: ^\d{3}$
        senderPrimaryAccountNumber:
          type: string
          description: Primary account number of the sender
        senderCardExpiryDate:
          type: string
          description: Expiration date of the sender's card in YYYY-MM format
        transactionCurrencyCode:
          type: string
          description: ISO 4217 numeric currency code
          pattern: ^\d{3}$
        amount:
          type: number
          format: double
          description: Transaction amount in the specified currency
        cardAcceptor:
          $ref: '#/components/schemas/CardAcceptor'
    MultiPushFundsRequest:
      type: object
      required:
      - acquiringBin
      - acquirerCountryCode
      - request
      properties:
        acquiringBin:
          type: string
          description: Bank Identification Number of the acquiring institution
        acquirerCountryCode:
          type: string
          description: ISO numeric country code of the acquirer
        request:
          type: array
          description: Array of individual push funds requests
          items:
            $ref: '#/components/schemas/PushFundsRequest'
    ReverseFundsRequest:
      type: object
      required:
      - systemsTraceAuditNumber
      - retrievalReferenceNumber
      - acquiringBin
      - acquirerCountryCode
      - transactionIdentifier
      - amount
      - transactionCurrencyCode
      properties:
        systemsTraceAuditNumber:
          type: string
          description: A unique six-digit value to identify the reversal
          maxLength: 6
        retrievalReferenceNumber:
          type: string
          description: A 12-character retrieval reference number
          maxLength: 12
        acquiringBin:
          type: string
          description: Bank Identification Number of the acquiring institution
        acquirerCountryCode:
          type: string
          description: ISO numeric country code of the acquirer
        transactionIdentifier:
          type: integer
          description: Transaction identifier of the original transaction to reverse
        amount:
          type: number
          format: double
          description: Amount to reverse
        transactionCurrencyCode:
          type: string
          description: ISO 4217 numeric currency code
        originalDataElements:
          type: object
          description: Data elements from the original transaction
          properties:
            systemsTraceAuditNumber:
              type: string
              description: Original transaction STAN
            transmissionDateTime:
              type: string
              description: Original transaction transmission date-time
            acquiringBin:
              type: string
              description: Original acquiring BIN
    PushFundsRequest:
      type: object
      required:
      - systemsTraceAuditNumber
      - retrievalReferenceNumber
      - acquiringBin
      - acquirerCountryCode
      - senderAccountNumber
      - transactionCurrencyCode
      - amount
      - recipientPrimaryAccountNumber
      properties:
        systemsTraceAuditNumber:
          type: string
          description: A unique six-digit value assigned by the acquirer to identify a transaction
          maxLength: 6
        retrievalReferenceNumber:
          type: string
          description: A 12-character value used to identify a transaction uniquely
          maxLength: 12
        acquiringBin:
          type: string
          description: Bank Identification Number of the acquiring institution
        acquirerCountryCode:
          type: string
          description: ISO numeric country code of the acquirer
          pattern: ^\d{3}$
        senderAccountNumber:
          type: string
          description: Account number of the sender
        transactionCurrencyCode:
          type: string
          description: ISO 4217 numeric currency code
          pattern: ^\d{3}$
        amount:
          type: number
          format: double
          description: Transaction amount in the specified currency
        recipientPrimaryAccountNumber:
          type: string
          description: Primary account number of the recipient
        senderName:
          type: string
          description: Name of the sender
        senderAddress:
          type: string
          description: Address of the sender
        senderCity:
          type: string
          description: City of the sender
        senderCountryCode:
          type: string
          description: ISO numeric country code of the sender
        recipientName:
          type: string
          description: Name of the recipient
        businessApplicationId:
          type: string
          description: Identifies the business use case for the transaction
          enum:
          - AA
          - BB
          - BI
          - BP
          - CI
          - CP
          - FD
          - GD
          - GP
          - LO
          - MD
          - MP
          - OG
          - PD
          - PP
          - PS
          - TL
          - WT
    CardAcceptor:
      type: object
      properties:
        name:
          type: string
          description: Name of the card acceptor (merchant)
        terminalId:
          type: string
          description: Terminal identifier
        idCode:
          type: string
          description: Card acceptor identification code
        address:
          type: object
          properties:
            country:
              type: string
              description: Country code
            state:
              type: string
              description: State or province
            city:
              type: string
              description: City name
            zipCode:
              type: string
              description: Postal code
    ReverseFundsResponse:
      type: object
      properties:
        transactionIdentifier:
          type: integer
          description: Unique identifier for the reversal transaction
        actionCode:
          type: string
          description: Response code indicating the result
        approvalCode:
          type: string
          description: Authorization code
        responseCode:
          type: string
          description: Response code from the issuer
        transmissionDateTime:
          type: string
          description: Date and time of the reversal transmission
    PushFundsResponse:
      type: object
      properties:
        transactionIdentifier:
          type: integer
          description: Unique identifier assigned by Visa to the transaction
        actionCode:
          type: string
          description: Response code indicating the result of the transaction
        approvalCode:
          type: string
          description: Authorization code from the issuer
        responseCode:
          type: string
          description: Response code from the issuer
        transmissionDateTime:
          type: string
          description: Date and time of the transaction transmission
    MultiPushFundsResponse:
      type: object
      properties:
        response:
          type: array
          description: Array of individual push funds responses
          items:
            $ref: '#/components/schemas/PushFundsResponse'
    ErrorResponse:
      type: object
      properties:
        errorCode:
          type: string
          description: Machine-readable error code
        message:
          type: string
          description: Human-readable error description
    MultiPullFundsRequest:
      type: object
      required:
      - acquiringBin
      - acquirerCountryCode
      - request
      properties:
        acquiringBin:
          type: string
          description: Bank Identification Number of the acquiring institution
        acquirerCountryCode:
          type: string
          description: ISO numeric country code of the acquirer
        request:
          type: array
          description: Array of individual pull funds requests
          items:
            $ref: '#/components/schemas/PullFundsRequest'
    PullFundsResponse:
      type: object
      properties:
        transactionIdentifier:
          type: integer
          description: Unique identifier assigned by Visa to the transaction
        actionCode:
          type: string
          description: Response code indicating the result
        approvalCode:
          type: string
          description: Authorization code from the issuer
        responseCode:
          type: string
          description: Response code from the issuer
        transmissionDateTime:
          type: string
          description: Date and time of the transaction transmission
    MultiPullFundsResponse:
      type: object
      properties:
        response:
          type: array
          description: Array of individual pull funds responses
          items:
            $ref: '#/components/schemas/PullFundsResponse'
x-tagGroups:
- name: API Reference
  tags:
  - Foreign Exchange Rates API