openapi: 3.0.2
info:
#---------------------------------------------------
# Information to contact the API provider
#--------------------------------------------------- 
  title: Wire Inquiry
  description: Retrieve the status and details of a wire transaction.
  contact: 
   name: "KeyBank Developer Support"
   email: "developers@keybank.com"
  version: 1.3.5

servers:
#---------------------------------------------------
# List of Environments for the API
#---------------------------------------------------
 # Non-Production environment URL (QV)
 - url: https://partner-api-qv.key.com
 # Production and Simulator environment URL
 - url: https://partner-api.key.com

paths:
#---------------------------------------------------
# List of API flows
#---------------------------------------------------    
  /wireInquiry/v1/healthCheck:
    get:
      tags: # Apigee Product: Logical group based on functionality
        - HealthCheck     
      summary: Health check            
      description: Verify you can connect to the API service. A bearer token is required. 
      operationId: healthCheck
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Successful response
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/healthResponse'
              example:
                Status: Ok
                Source: Roundtrip
                Timestamp: '2022-09-15T04:49:03'
                ClientIp: 156.77.111.28
                X-Forwarded-For: '[156.77.111.28]'   
  /wireInquiry/v1/transactions/list:
    post:
      tags:
        - Wire
      summary: Search wire transfers
      security:
        - bearerAuth: []
      operationId: searchWireTransactions
      description: Based on search criteria provided, get a list of wire transfers. The account number and date range are required for every request. 
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - accountNumber
                - fromDate
                - toDate
              properties:
                accountNumber:
                  type: string
                  description: The bank account number. This number cannot exceed 16 characters. 
                  minLength: 1
                  maxLength: 16
                  pattern: '/^\d+$/'
                  example: 3123456789
                fromDate:
                  description: 'Start date for the date range. This date can be the current day or within 180 days prior to the current date. To search for a single date, this value will be the same as the toDate. Format: YYYY-MM-DD'
                  type: string
                  format: date
                  example: 2024-02-01
                toDate:
                  description: 'End date for the date range. This date must be the same or later than the start date (fromDate). To search for a single date, this value will be the same as the fromDate.  To search for a range of dates, make sure the date range does not exceed 31 days. Format: YYYY-MM-DD'
                  type: string
                  format: date
                  example: 2024-02-01
                minimumAmount:
                  description: The minimum dollar amount of the transaction. This amount must be less than or equal to the maximum amount. Leave blank or enter zero for no minimum amount.
                  type: number
                  format: currency
                  minimum: 0
                  maximum: 1000000000
                  example: 100.00
                maximumAmount:
                  description: The maximum dollar amount of the transaction. This amount must be greater than or equal to the minimum amount. Leave blank to retrieve all amounts. This amount cannot exceed one billion dollars.
                  type: number
                  format: currency
                  minimum: 0
                  maximum: 1000000000
                  example: 75020.52
                requestReference:
                  type: string
                  description: A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 32 characters.
                  maxLength: 35
                  example: "USRSIM-0.0001"
                pageNumber:
                  type: integer
                  description: The number of the page being viewed. This number must be greater than or equal to 1.
                  example: 1
                pageSize:
                  type: integer
                  description: The total number of pages returned. This number must be greater than or equal to 1 and cannot exceed 1000.
                  example: 500
      responses:
        '200':
          description: Search results match the criteria
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain fo API operations. The ID is unique to each request. 
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactions:
                    type: array
                    items:
                      $ref: '#/components/schemas/WireListTransaction'
                  metadata:
                    $ref: '#/components/schemas/Metadata'
              example:
                transactions:  
                - transactionId: "US99999000999999"
                  transactionStatus: "COMPLETED"
                  transactionDate: "2026-01-12"
                  transactionStatusTimestamp: 2026-01-12T12:18:01
                  transactionAmount: "32772.63"
                  requestReference: "1122334455"
                  sendersReference: "US99999000999999"
                  creditor:
                    name: "Global Markets LLC"
                  creditorAccount: 
                    accountNumber: "987654321"
                    virtualAccountNumber: "98765432100015"
                  debtor:
                    name: "Paul Wilson"
                  debtorAccount:
                    accountNumber: "123456789"
                    virtualAccountNumber: "98765432100000"
                  beneficiary:
                    name: MARKET CAPITAL
                  beneficiaryAccount:
                    accountNumber: "102030405060"
                metadata:
                  page:
                    pageNumber: 1
                    pageSize: 25
                    totalPages: 3
                    totalRecords: 75
                    lastPage: true
        '400':
          description: Bad input parameter
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain fo API operations. The ID is unique to each request. 
          content:            
            application/json:
              schema:
                $ref: '#/components/schemas/Metadata'
              example:               
                messages:
                  code: "Wire-List-400-bad-input"
                  message: Bad input parameter

  /wireInquiry/v1/transactions/detail/{transactionId}:
    get:
      tags:
        - Wire
      summary: View the details of a wire transfer by the transaction ID. 
      security:
        - bearerAuth: []
      operationId: searchWireTransaction
      description: Provide the transaction ID to retrieve all available fields for that wire transfer.       
      parameters:
      - name: transactionId
        in: path
        description: The unique ID number associated with the original payment request.
        style: simple
        explode: false
        schema: 
          maxLength: 100
          type: string
        required: true
        example: US99999000999999
      responses:
        '200':
          description: A Wire transaction matches the provided transactionId
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification. 
          content:
            application/json:
              schema:
                 $ref: '#/components/schemas/WireDetailTransaction'
              example:  
                transactionId: "US99999000999999"
                transactionStatus: "COMPLETED"
                transactionDate: "2026-01-12"
                transactionStatusTimestamp: 2026-01-12T12:18:01
                transactionAmount: "32772.63"
                requestReference: "1122334455"
                sendersReference: "US99999000999999"
                creditor:
                  name: "Global Markets LLC"
                creditorAccount: 
                  accountNumber: "987654321"
                debtor:
                 name: "Paul Wilson"
                debtorAccount:
                  accountNumber: "123456789"
                remittanceInformation: "Payment 01/12/2026_Invoice - 123456789 Cust"
        '404':
          description: No Wire transaction was found with the provided transactionId
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain fo API operations. The ID is unique to each request. 
          content:            
            application/json:
              schema:
                $ref: '#/components/schemas/Metadata'
              example:               
                messages:
                  code: "Wire-Detail-404-no-records"
                  message: "Record Not Found" 
                  X-Forwarded-For: '[156.77.111.28]'
                                                            
 
components:
#---------------------------------------------------
# Data definitions
#--------------------------------------------------- 
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    WireDetailTransaction:
      type: object
      description: Contains the response payload with details about a Wire transfer.
      properties:
        transactionId:
          type: string
          description: The unique ID number associated with the original payment request.
          maxLength: 100
        transactionStatus:
          type: string
          enum:
          - CANCELLED
          - COMPLETED
          - FAILED
          - IN PROCESS
          - IN REVIEW
          - RETURNED
          description: 'The status of the wire transfer. Valid values: CANCELLED, COMPLETED, FAILED, IN PROCESS, IN REVIEW, RETURNED'
          maxLength: 50
        transactionStatusTimestamp:
          description: Timestamp for the most recent status change on the transaction.
          type: string
          format: date-time
          example: 2026-01-12T12:18:01
        transactionDate:
          description: 'Date the transfer occurred. Format: YYYY-MM-DD'
          type: string
          format: date
          example: 2024-01-12   
        transactionAmount:
          description: The dollar amount of the transaction.
          type: number
          format: currency
        requestReference:
          type: string
          description: A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
          maxLength: 64
        sendersReference:
          type: string
          description: A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
          maxLength: 35
        creditor:
          $ref: '#/components/schemas/PartyList'
        creditorAccount:
          $ref: '#/components/schemas/AccountList'
        debtor:
          $ref: '#/components/schemas/PartyList'
        debtorAccount:
          $ref: '#/components/schemas/AccountList'
        originator:
          $ref: '#/components/schemas/PartyList'
        originatorAccount: 
          $ref: '#/components/schemas/AccountList'
        beneficiary:
          $ref: '#/components/schemas/PartyList'
        beneficiaryAccount:
          $ref: '#/components/schemas/AccountList'  
        ultimateCreditor:
          $ref: '#/components/schemas/PartyList' 
        ultimateCreditorAccount:
          $ref: '#/components/schemas/AccountList'
        ultimateDebtor:
          $ref: '#/components/schemas/PartyList' 
        ultimateDebtorAccount:
          $ref: '#/components/schemas/AccountList'
        remittanceInformation:
          type: string
          description: Information that stays with a payment as it is transferred from one party to another. This field only displays if there is remittance information for the transaction. Message length cannot exceed 256 characters.
          maxLength: 256
        bankToBankInstructions:
          type: string
          description: Messages or instructions shared from one bank to another. Data retrieved if part of the original wire transfer. 
          maxLength: 2048
        customData:
          type: string
          description: A client-defined free-form text field (up to 500 alphanumeric characters) that remains associated with the transaction throughout its lifecycle in the KeyBank network.
          pattern: '^\s*'
          minLength: 0
          maxLength: 500
    WireListTransaction:
      type: object
      description: Contains the response payload for Wire inquiries. 
      properties:
        transactionId:
          type: string
          description: The unique ID number associated with the original payment request
          maxLength: 100
        transactionStatus:
          type: string
          enum:
          - CANCELLED
          - COMPLETED
          - FAILED
          - IN PROCESS
          - IN REVIEW
          - RETURNED
          description: 'The status of the wire transfer. Valid values: CANCELLED, COMPLETED, FAILED, IN PROCESS, IN REVIEW, RETURNED'
          maxLength: 50
        transactionStatusTimestamp:
          description: Timestamp for the most recent status change on the transaction.
          type: string
          format: date-time
          example: 2026-01-12T12:18:01
        transactionDate:
          description: 'Date the transfer occurred. Format: YYYY-MM-DD'
          type: string
          format: date
          example: 2026-01-12
        transactionAmount:
          type: number
          description: The dollar amount of the transaction.
          format: currency
        requestReference:
          type: string
          description: A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
          maxLength: 64
        sendersReference:
          type: string
          description: A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
          maxLength: 35
        creditor:
          $ref: '#/components/schemas/PartyList'
        creditorAccount:
          $ref: '#/components/schemas/AccountList'
        debtor:
          $ref: '#/components/schemas/PartyList'
        debtorAccount:
          $ref: '#/components/schemas/AccountList'
    healthResponse:
      type: object
      description: The response for the API health check.
      title: healthResponse
      properties:
        Status:
          type: string
          description: Status of the health check response.
        Source:
          type: string
          description: The origin of the system response can be 'Gateway' or 'Roundtrip'. Roundtrip returns a response from the farthest system involved.
        Timestamp:
          type: string
          description: The date (YYYY-MM-DD) and time (HH:MM:SS) of the response from the API service. 
        ClientIp:
          type: string
          description: The client IP address the gateway gets from the request.
        X-Forwarded-For:
          type: string
          description: The sequence of all the IP addresses for systems involved between the client and the gateway.
    AccountList:
      type: object
      properties:
        accountNumber:
          type: string
          description: Account number of the party.
          maxLength: 20
        virtualAccountNumber:
          type: string
          description: Account number for the virtual account (VAM).
    PartyList:
      type: object
      properties:
        name:
          type: string 
          description: Contains the customer identification number and the company name. 
          maxLength: 255  
    Message:
      type: object
      description: Informational code and message from the server. 
      properties:
        code:
          type: string
          description: Static code assigned by the network or payment system.
        message:
          type: string
          description: A human-readable message associated with the code. 
    Page:
      type: object
      properties:
        pageNumber:
          type: integer
          description: The number of the page being viewed. 
        pageSize:
          type: integer
          description: The number of records per page.
        totalPages:
          type: integer
          description: The total number of pages available.
        totalRecords:
          type: integer
          description: The total number of the transactions (records) available in the result set. 
        lastPage:
          type: boolean
          description: Indicates the last page of the total pages.
      description: Page information returned from the server.
    Metadata:
      type: object
      description: Data information returned as a message or page information retrieved from the server. 
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
        page:
          $ref: '#/components/schemas/Page' 