openapi: 3.0.1
#---------------------------------------------------
# Information to contact the Service provider
#-------------------------------------------------
info:
  title:  ACH Inquiry
  description: Use the ACH Inquiry API to get the status on ACH transactions based on your query criteria. For clients with a non-consolidated settlement, you can receive collected (in progress), posted (processed), and returned transactions. For clients with a consolidated settlement, you only receive collected and returned transactions. Posted transactions is not an available status for consolidated settlement.
  contact: 
    name: "KeyBank Developer Support"
    email: "developers@keybank.com"
  version: 2.1.0

servers:
#---------------------------------------------------
# List of environments for the API
#---------------------------------------------------
 - url: https://partner-api-qv.key.com
 - url: https://partner-api.key.com
 
paths:
#---------------------------------------------------
# List of Environments for the API
#---------------------------------------------------
  
  /accounts/transactions/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
          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]'
  /accounts/transactions/v1/ach/detail/{parNumber}:
    get:
      security:
        - bearerAuth: []
      tags: 
        - ACH Transactions
      summary: Get details about an ACH transaction with a PAR number
      operationId: searchAchTransaction
      description: Use the PAR number to retrieve information about an ACH transaction. 
      parameters:
        - name: parNumber
          in: path
          description: The unique PAR number assigned to the the transaction by the ACH product processor.
          required: TRUE
          schema: 
            maxLength: 50
            type: string
          example: 22053010727662
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                  $ref: '#/components/schemas/AchDetailTransaction'
              example:
                parNumber: "22018007665985"
                transactionStatus: "COLLECTED"
                traceNumber: "000000000000000"
                transactionAmount: 10.01
                settlementDate: "2021-03-08"
                transactionCode: "22"
                transactionCodeDescription: "Automated Deposit"
                transactionDescription:  "DEPOSIT"
                authorizedCustomerName: "TEST CUSTOMER1"
                standardEntryClassCode: "CCD"
                standardEntryClassDescription: "Cash Concentration or Disbursement"
                receivingAccount:
                  accountNumber: "123456789012"
                  bankNumber: "0000"
                  routingNumber: "1234567890"
                receivingParty:
                  customerIdentificationNumber: "099999999"
                  companyName: "MERCHANT"
                  customerName: "TEST MERCHANT"
                originatingAccount:
                  accountNumber: "123456789012"
                  bankNumber: "0000"
                  routingNumber: "1234567890"
                originatingParty:
                  customerIdentificationNumber: "1234567"
                  companyName: "COMPANY NAME 1"
                  customerName: "CUSTOMER NAME 1"
                returnDate: "2024-02-01"
                returnReasonCode: "R02"
                returnReasonDescription: "Account Closed"
                addendaCount: 1
                notificationOfChangeAddendaCount: 1
                internationalAddendaCount: 0
                customData: "merchant:status" 
                checkSerialNumber: "4345"
                transactionDirection: "Receiving Item"
                settlementAmount: 123.45
                settlementTransactionId: "1234567890"
                addenda:
                  - sequenceNumber: 1
                    entryDetailSequenceNumber: "188"
                    paymentRelatedInformation: "Addenda Record (Applies to CCD, CTX, PPD, and WEB entries)"
                notificationOfChange:
                  - changeCode: "C02"
                    changeDescription: "Incorrect transit/routing number"
                    correctedData: "1234567890"
        '404':
          description: Resource not found
          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:
                type: object
                properties:
                  metadata:
                    description: Information about the data pages returned.
                    $ref: '#/components/schemas/Metadata'
                example:
                  metadata:
                    messages:
                      - code: "AI-Detail-404-no-records-100"
                        message: "Record Not Found"
  /accounts/transactions/v1/ach/list:
    post:
      operationId: searchAchTransactions
      security:
        - bearerAuth: []
      tags: 
        - ACH Transactions
      summary: Advanced search for ACH transactions
      description: Search for ACH transactions by passing certain search parameters.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - accountNumber
                - fromDate
                - toDate
              properties:
                accountNumber:
                  type: string
                  description: The bank account number. This field cannot exceed 16 characters.
                  minLength: 1
                  maxLength: 16
                  example: 3123456789
                fromDate:
                  description: "Start date for the date range. This date must be the current date or prior to the current date. Transaction data can be recalled within 180 days of the current date. Format: YYYY-MM-DD"
                  type: string
                  format: date
                  example: 2024-02-01
                toDate:
                  description: "End date for the date range. This date can be the current day or a later date from the start date (fromDate). The date range should not be longer than 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.50
                traceNumber:
                  description: The unique number for the transaction provided by the originator.
                  type: string
                  minLength: 1
                  maxLength: 16
                  example: "041001030016002"
                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
            example:
              accountNumber: "3123456789"
              fromDate: 2024-02-01
              toDate: 2024-02-01
              minimumAmount: 100.00
              maximumAmount: 75020.50
              traceNumber: "041001030016002"
              pageNumber: 1
              pageSize: 150
      responses:
        '200':
          description: Successful response 
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactions:
                    type: array
                    description: List of transactions from search criteria.
                    items:
                      $ref: '#/components/schemas/AchListTransaction'
                  metadata:
                    description: Information about the data pages returned.
                    $ref: '#/components/schemas/Metadata'
              example:
                transactions:
                  - parNumber: "22018007665985"
                    transactionStatus: "COLLECTED"
                    traceNumber: "000000000000000"
                    transactionAmount: 10.01
                    settlementDate: "2021-03-08"
                    transactionCode: "22"
                    authorizedCustomerName: "TEST CUSTOMER1"
                    standardEntryClassCode: 'CCD'
                    receivingAccount:
                      accountNumber: "123456789012"
                    receivingParty:
                      customerIdentificationNumber: "099999999"
                      companyName: "MERCHANT"
                    originatingAccount:
                      accountNumber: "123456789012"
                    originatingParty:
                      customerIdentificationNumber: "1234567"
                      companyName: "COMPANY NAME 1"
                    returnDate: "2024-02-01"
                    returnReasonCode: "R02"
                    returnReasonDescription: "Account Closed"
                    addendaCount: 1
                    notificationOfChangeAddendaCount: 1
                    internationalAddendaCount: 0
                    settlementAmount: 123.45
                    settlementTransactionId: "1234567890"
                metadata:
                  messages:
                    - code: "099"
                      message: "Search results match the criteria"
                  page:
                    pageNumber: 1
                    pageSize: 10
                    totalPages: 10
                    totalRecords: 28
                    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 of API operations. 
          content:
            application/json:
              schema:
                type: object
                properties:
                  metadata:
                    description: Information about the data pages returned.
                    $ref: '#/components/schemas/Metadata'
              example:
                metadata:
                  messages:
                    - code: "001"
                      message: "There are no transactions that match the parNumber."
                  page:
                    pageNumber: 1
                    pageSize: 1
                    totalPages: 1
                    totalRecords: 0
                    lastPage: false

components:
  schemas:  
    AccountList:
      type: object
      description: List of accounts
      properties:
        accountNumber:
          type: string
          description: Bank account number.
    AccountDetail:
      type: object
      description: Contains details about the account like number, bank number, and routing number. 
      properties:
        accountNumber:
          type: string
          description: Bank account number of the ACH originator or receiver.
        bankNumber:
          type: string
          description: Bank number associated with the account number.
        routingNumber:
          type: string
          description: Nine-digit routing number for the account provided in the original request.
    AchDetailTransaction:
      type: object
      description: Contains transaction details associated with the queried PAR number.
      properties:
        parNumber:
          type: string
          description: The unique PAR number assigned to the the transaction by the ACH product processor.
        transactionStatus:
          type: string
          description: "The status of the ACH transaction. Valid values: COLLECTED, RETURNED, SETTLED"
        traceNumber:
          type: string
          description: The unique number for the transaction provided by the originator.
        transactionAmount:
          type: number
          description: The dollar amount of the transaction.
          format: currency
        settlementDate:
          type: string
          description: "The date the transaction settlement occurred. Format: YYYY-MM-DD"
          format: date
          example: 2024-02-01
        transactionCode:
          type: string
          description: Two-digit code identifying the account type at the receiving financial institution.
        transactionCodeDescription:
          type: string
          description: Description for the transaction code.
        transactionDescription:
          type: string
          description: Description about the purpose of the transaction. 
        authorizedCustomerName:
          type: string
          description: Authorized customer name
        standardEntryClassCode:
          type: string
          description: The three-digit Standard Entry Class code based on Nacha rules.
        standardEntryClassDescription:
          type: string 
          description: The description for the Nacha SEC code.        
        receivingAccount:
          $ref: '#/components/schemas/AccountDetail'
          description: Details about the account receiving the funds.
        receivingParty:
          $ref: '#/components/schemas/PartyDetail'
          description: Details about the party receiving the funds.
        originatingAccount:
          $ref: '#/components/schemas/AccountDetail'
          description: Details about the originating account.
        originatingParty:
          $ref: '#/components/schemas/PartyDetail'
          description: Details about the originating party.
        returnDate:
          type: string
          description: "Date of the returned transaction to the ACH system. Format: YYYY-MM-DD"
          format: date
          example: 2024-02-01
        returnReasonCode:
          type: string
          description: "The code associated with the reason for returning the ACH transaction. The code is the letter 'R' for reason followed by a two-digit numeric code. Format: R00"
        returnReasonDescription:
          type: string
          description: Description as to why the ACH transaction is returned.
        addendaCount:  
          type: integer  
          description: Count of addenda records.
        notificationOfChangeAddendaCount:
          type: integer
          description: Count of change notifications for addenda records.
        internationalAddendaCount:
          type: integer
          description: Count of international addenda records.
        customData:
          type: string
          description: The values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle. 
        checkSerialNumber:
          type: string
          description: Serial number for the check converted to an ACH transaction. 
        transactionDirection:
          type: string
          description: "Indicates the direction of the transaction. Valid values: ORIGINATING ITEM, RECEIVING ITEM"
        addenda:
          type: array
          description: List of addenda records
          items:
            $ref: '#/components/schemas/Addendum'
        notificationOfChange:
          type: array
          description: Applicable change notifications associated with the ACH transaction.
          items: 
            $ref: '#/components/schemas/NotificationOfChange'
        settlementAmount:
            type: number
            description: The dollar amount of the settlement.
            format: currency
        settlementTransactionId:
            type: string
            description: The unique ID of the settlement batch tied to the transaction     
    AchListTransaction:
      type: object
      description: Results from ACH transaction or account search.
      properties:
        parNumber:
          type: string
          description: The unique PAR number assigned to the the transaction by the ACH product processor.
        transactionStatus:
          type: string
          description: "The status of the ACH transaction. Valid values: COLLECTED, RETURNED, SETTLED"
        traceNumber:
          type: string
          description: The unique number for the transaction provided by the originator.
        transactionAmount:
          type: number
          description: The dollar amount of the transaction.
          format: currency
        settlementDate:
          type: string
          description: "The date the transaction settlement occurred. Format: YYYY-MM-DD"
          format: date
          example: 2024-02-01
        transactionCode:
          type: string
          description: Two-digit code identifying the account type at the receiving financial institution.
        authorizedCustomerName:
          type: string
          description: Authorized customer name
        standardEntryClassCode:
          type: string
          description: The three-digit Standard Entry Class code based on Nacha rules.
        receivingAccount:
          $ref: '#/components/schemas/AccountList'
          description: Details about the account receiving the funds.
        receivingParty:
          $ref: '#/components/schemas/PartyList'
          description: Details about the party receiving the funds.
        originatingAccount:
          $ref: '#/components/schemas/AccountList'
          description: Details about the originating account.
        originatingParty:
          $ref: '#/components/schemas/PartyList'
          description: Details about the originating party.
        returnDate:
          type: string
          description: "Date of the returned transaction to the ACH system. Format: YYYY-MM-DD"
          format: date
          example: 2024-02-01
        returnReasonCode:
          type: string
          description: "The code associated with the reason for returning the ACH transaction. The code is the letter 'R' for reason followed by a two-digit numeric code. Format: R00"
        returnReasonDescription:
          type: string
          description: Description as to why the ACH transaction is returned.
        addendaCount:  
          type: integer  
          description: Count of addenda records.
        notificationOfChangeAddendaCount:
          type: integer
          description: Count of change notifications for addenda records.
        internationalAddendaCount:
          type: integer
          description: Count of international addenda records.
        settlementAmount:
            type: number
            description: The dollar amount of the settlement.
            format: currency
        settlementTransactionId:
           type: string
           description: The unique ID of the settlement batch tied to the transaction.
    Addendum:
      type: object
      description: Contains addenda record information.
      properties:
        sequenceNumber: 
          type: integer
          description: The addenda record item number in order of sequence. Number cannot exceed 4 digits.
          maxLength: 4
        entryDetailSequenceNumber:
          type: string
          description: The entry number in order of sequence. Number cannot exceed 7 digits.
          maxLength: 7
        paymentRelatedInformation:
          type: string
          description: The related payment information from the addenda records. The maximum character limit is 255. 
          maxLength: 255
    Message:
      type: object
      description: Informational message returned from the server. 
      properties:
        code:
          type: string
          description: Code for the related message. 
        message:
          type: string
          description: Message associated with the code.
    Page:
      type: object
      description: Page information returned from the server.
      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 number of pages there are in total. 
        totalRecords:
          type: integer
          description: The total number of transactions available in the result set. 
        lastPage:
          type: boolean
          description: "Indicates if the current page (page number) is the last page of the result set. Valid values: true, false"
    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'
    PartyList:
      type: object
      description: Contains the customer identification number and company name.
      properties:
        customerIdentificationNumber:
          type: string
          description: The unique identification number associated with the customer. 
        companyName:
          type: string    
          description: The name of the corporation or institution making the request.
    PartyDetail:
      type: object
      description: Contains details about the party like ID number, company name, and the customer name. 
      properties:
        customerIdentificationNumber:
          type: string
          description: The unique identification number associated with the customer. 
        companyName:
          type: string
          description: The name of the corporation or institution making the request.
        customerName:
          type: string
          description: The name of the customer.
    NotificationOfChange:
      type: object
      description: Contains change details and corrected data.
      properties:
        changeCode:
          description: The three-character change code begins with the letter 'C'. This code is applied to all NOCs to indicate the information that is being changed.
          type: string
          maxLength: 50
        changeDescription: 
          description: The description associated with the change code.
          type: string
          maxLength: 255
        correctedData:
          description: The corrected data per the correction change code.
          type: string
          maxLength: 50
    healthResponse:
      type: object
      title: healthResponse
      properties:
        Status:
          type: string
          description: Status of the health check response.
        Source:
          type: string
          description: System producing the health response. Genesis of the response could either be just from “gateway” or “roundtrip” from the farthest possible system involved in generating this response.
        Timestamp:
          type: string
          description: Timestamp when the health response is being returned by this service.
        ClientIp:
          type: string
          description: IP of the client from which this request for health check is received by the gateway.
        X-Forwarded-For:
          type: string
          description: Sequence of all the Ips of the systems involved between the client and the gateway.
  securitySchemes:    
    bearerAuth:    # security scheme for authentication based on F5 APM token
      type: http
      scheme: bearer
