openapi: 3.2.0
info:
  title: Webhooks ACH API
  description: Payment webhook service for ACH, Wire, and RTP alert notifications.
  contact:
    name: KeyBank Developer Support
    email: developers@keybank.com
  version: 3.1.0
tags:
- name: ACH
paths:
  /"Callback URL from client for ACH alerts - AL00906":
    post:
      tags:
      - ACH
      summary: Send an ACH alerts event notification to the client URI.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/alertNotificationAL00906Request'
        required: true
      responses:
        200:
          description: OK
        202:
          description: Accepted
        400:
          description: Invalid Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/alertInvalidInputResponse'
        401:
          description: Authentication Error
        403:
          description: Authorization Error
        500:
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/alertFailureResponse'
components:
  schemas:
    alertNotificationAL00906Request:
      type: object
      properties:
        alertNotificationRequest:
          type: array
          items:
            type: object
            properties:
              alertNotification:
                type: object
                properties:
                  alertHeader:
                    type: object
                    properties:
                      alertSentDateAndTime:
                        type: string
                        format: date-time
                        description: 'Date and time the alert was sent. Format: (YYYY-MM-DD)T(HH:MM:SS)Z'
                      alertCode:
                        type: string
                        enum:
                        - AL00906
                        description: For ACH alerts, the alert code is AL00906.
                      eapAlertGUID:
                        type: string
                        format: uuid
                        description: Unique alert notification identifier generated by KeyBank (UUID v4).
                  alertBody:
                    type: object
                    properties:
                      transactionStatus:
                        type: string
                        description: 'The status of the ACH transaction. Valid values: COLLECTED, RETURNED, SETTLED'
                      transactionStatusTimeStamp:
                        type: string
                        format: date-time
                        description: Timestamp for the most recent status change on the transaction.
                      traceNumber:
                        type: string
                        description: The unique number for the transaction provided by the originator.
                      parNumber:
                        type: string
                        description: The unique PAR number assigned to the the transaction by the ACH product processor.
                      transactionAmount:
                        type: string
                        description: The dollar amount of the transaction.
                      collectionDate:
                        type: string
                        description: 'Date the transaction was processed. Format: YYYY-MM-DD'
                      settlementDate:
                        type: string
                        description: 'The date the transaction settlement occurred. Format: YYYY-MM-DD'
                      transactionCode:
                        type: string
                        description: Two-digit code identifying the account type at the receiving financial institution.
                      transactionDescription:
                        type: string
                        description: Description about the purpose of the transaction.
                      authorizedCustomerName:
                        type: string
                        description: Authorized customer name
                      standardEntryClassCode:
                        type: string
                        description: 'Three-digit Standard Entry Class (SEC) code based on Nacha rules. Valid values: CCD, CTX, PPD, TEL, WEB'
                      receivingAccountNumber:
                        type: string
                        description: Account number of the person or institution receiving the funds.
                      receivingCustomerIdentificationNumber:
                        type: string
                        description: The customer identification number for the person receiving the transaction.
                      receivingCompanyName:
                        type: string
                        description: Company name of the institution getting the funds.
                      originatingAccountNumber:
                        type: string
                        description: Account number of the ACH transaction originator.
                      originatingCustomerIdentificationNumber:
                        type: string
                        description: Originating customer identification number
                      originatingCompanyName:
                        type: string
                        description: Company name of the or associated with the ACH originator.
                      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.
                      returnDate:
                        type: string
                        description: Date of the returned transaction to the ACH system. Format:YYYY-MM-DD
                      notificationOfChangeAddendaCount:
                        type: string
                        description: Count of change notifications for addenda records.
                      internationalAddendaCount:
                        type: string
                        description: Count of the international addenda records.
                      addendaCount:
                        type: string
                        description: Count of addenda records.
      example:
        alertNotificationRequest:
        - alertNotification:
            alertHeader:
              alertSentDateAndTime: '2024-07-15T16:46:01Z'
              alertCode: AL00906
              eapAlertGUID: 4g0fda4b-156f-483c-98ae-bd8ccab266h0
            alertBody:
              transactionStatus: COLLECTED
              transactionStatusTimestamp: 2024-07-15 18:18:01
              traceNumber: '41033956478656'
              parNumber: '22010008879477'
              transactionAmount: '287.40'
              collectionDate: 12-JAN-22
              settlementDate: 12-JAN-22
              transactionCode: '22'
              transactionDescription: PAYMENT
              authorizedCustomerName: HIGHMARK INC.
              standardEntryClassCode: CCD
              receivingAccountNumber: '00000000001000004133'
              receivingCustomerIdentificationNumber: 65A658990
              receivingCompanyName: LEHIGH GASTROENTEROLOG
              originatingAccountNumber: '00000000001000005244'
              originatingCustomerIdentificationNumber: '7498659450'
              originatingCompanyName: HIGHMARK INC.
              returnReasonCode: R29
              returnReasonDescription: Corporate Customer Advises Not Authorized
              returnDate: 07-DEC-21
              notificationOfChangeAddendaCount: '1'
              internationalAddendaCount: '0'
              addendaCount: '0'
    alertInvalidInputResponse:
      type: object
      properties:
        alertNotificationResponse:
          type: array
          items:
            type: object
            properties:
              alertAcknowledgment:
                type: object
                properties:
                  alertStatus:
                    type: string
                    enum:
                    - FAILURE
                  confirmationGUID:
                    type: string
                    description: API Customer Unique ID for the Alert Notification
                    format: uuid
                  alertRecievedDateAndTime:
                    type: string
                    format: date-time
                  eapAlertGUID:
                    type: string
                    description: ECHO back the value from request
                    format: uuid
                  message:
                    type: string
                    description: Free form text - can be used at API Consumer Discretion
      example:
        alertNotificationResponse:
        - alertAcknowledgment:
            alertStatus: FAILURE
            confirmationGUID: 5f0ada5b-056f-483c-98ae-ac6ccab269c1
            alertRecievedDateAndTime: 2021-11-19 10:31:12+00:00
            eapAlertGUID: ce816009-4aa9-47c7-b2ee-bacf9f0872d0
            message: 'Required parameter(s) not found: [fieldName(s)]'
    alertFailureResponse:
      type: object
      properties:
        alertNotificationResponse:
          type: array
          items:
            type: object
            properties:
              alertAcknowledgment:
                type: object
                properties:
                  alertStatus:
                    type: string
                    enum:
                    - FAILURE
                  confirmationGUID:
                    type: string
                    description: API Customer Unique ID for the Alert Notification
                    format: uuid
                  alertRecievedDateAndTime:
                    type: string
                    format: date-time
                  eapAlertGUID:
                    type: string
                    description: ECHO back the value from request
                    format: uuid
                  message:
                    type: string
                    description: Free form text - can be used at API Consumer Discretion
      example:
        alertNotificationResponse:
        - alertAcknowledgment:
            alertStatus: FAILURE
            confirmationGUID: 5f0ada5b-056f-483c-98ae-ac6ccab269c1
            alertRecievedDateAndTime: 2021-11-19 10:31:12+00:00
            eapAlertGUID: 3eecd293-8c45-40ba-be09-d8570c5665ed
            message: Internal Error