openapi: 3.0.2
info:
  title: Webhooks
  description: Payment webhook service for ACH, Wire, and RTP alert notifications.
  contact:
    name : KeyBank Developer Support
    email: developers@keybank.com
  version: 2.2.0
paths:
  /ach:
    post:
      tags:
      - ACH
      summary: ACH Alerts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/alertNotificationACHRequest'
        required: true
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/alertSuccessResponse'
        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'
  /wire:
    post:
      tags:
      - Wire
      summary: Wire Alerts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/alertNotificationWireRequest'
        required: true
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/alertSuccessResponse'
        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:
    alertNotificationACHRequest:
      type: object
      properties:
        alertNotificationRequest:
          type: array
          items:
            type: object
            properties:
              alertNotification:
                type: object
                properties:
                  alertHeader:
                    type: object
                    properties:
                      alertSentDateAndTime:
                        type: string
                        format: date-time
                      alertCode:
                        type: string
                        enum:
                        - AL00906
                      eapAlertGUID:
                        type: string
                        format: uuid
                  alertBody:
                    type: object
                    properties:
                      transactionStatus:
                        type: string
                      traceNumber:
                        type: string
                      parNumber:
                        type: string
                      transactionAmount:
                        type: string
                      collectionDate:
                        type: string
                      settlementDate:
                        type: string
                      transactionCode:
                        type: string
                      transactionDescription:
                        type: string
                      authorizedCustomerName:
                        type: string
                      standardEntryClassCode:
                        type: string
                      receivingAccountNumber:
                        type: string
                      receivingCustomerIdentificationNumber:
                        type: string
                      receivingCompanyName:
                        type: string
                      originatingAccountNumber:
                        type: string
                      originatingCustomerIdentificationNumber:
                        type: string
                      originatingCompanyName:
                        type: string
                      returnReasonCode:
                        type: string
                      returnReasonDescription:
                        type: string
                      returnDate:
                        type: string
                      notificationOfChangeAddendaCount:
                        type: string
                      internationalAddendaCount:
                        type: string
                      addendaCount:
                        type: string
      example:
        alertNotificationRequest:
        - alertNotification:
            alertHeader:
              alertSentDateAndTime: "2024-07-15T16:46:01Z"
              alertCode: "AL00906"
              eapAlertGUID: "4g0fda4b-156f-483c-98ae-bd8ccab266h0"
            alertBody:
              transactionStatus: "COLLECTED"
              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"
    alertNotificationWireRequest:
      type: object
      properties:
        alertNotificationRequest:
          type: array
          items:
            type: object
            properties:
              alertNotification:
                type: object
                properties:
                  alertHeader:
                    type: object
                    properties:
                      alertSentDateAndTime:
                        type: string
                        format: date-time
                      alertCode:
                        type: string
                        enum:
                        - AL00901
                      payType:
                        type: string
                        enum:
                        - RTP
                        - WIRE
                      eapAlertGUID:
                        type: string
                        format: uuid
                  alertBody:
                    type: object
                    properties:
                      crOrDbCode:
                        type: string
                      crArngNum:
                        type: string
                      crArngTypeCode:
                        type: string
                      crArngBankNum:
                        type: string
                      crTranCurrencyCode:
                        type: string
                      dbArngTypeCode:
                        type: string
                      dbTranCurrencyCode:
                        type: string
                      requestReferenceNumber:
                        type: string
                        maxLength: 32
                      crIpId:
                        type: string
                      crIpNm:
                        type: string
                      dbArngNum:
                        type: string
                      dbArngBankNum:
                        type: string
                      dbIpId:
                        type: string
                      dbIpNm:
                        type: string
                      payNotifyTs:
                        type: string
                      wireEventNm:
                        type: string
                      tranAmt:
                        type: string
                      tranExecutedDt:
                        type: string
                      federalReferNum:
                        type: string
                      sndngBankReferNum:
                        type: string
                      tranId:
                        type: string
                      tranBusnStatusCode:
                        type: string
                      wireDirectionCode:
                        type: string
                      tranType:
                        type: string
                      tranValueTypeCode:
                        type: string
                      wireProcessTypeCode:
                        type: string
                      benefitAba:
                        type: string
                      benefitArngNum:
                        type: string
                      benefitIpAddrLine:
                        type: string
                      benefitBicCode:
                        type: string
                      benefitBankAbaNum:
                        type: string
                      benefitBankArngNum:
                        type: string
                      benefitBankAddrLine:
                        type: string
                      benefitBankBicCode:
                        type: string
                      benefitBankNm:
                        type: string
                      intrmdryBankAbaNum1:
                        type: string
                      intrmdryBankAddrLine1:
                        type: string
                      intrmdryBankNm1:
                        type: string
                      intrmdryBicCode1:
                        type: string
                      intrmdryBankAbaNum2:
                        type: string
                      intrmdryBankAddrLine2:
                        type: string
                      intrmdryBankNm2:
                        type: string
                      intrmdryBicCode2:
                        type: string
                      intrmdryBankAbaNum3:
                        type: string
                      intrmdryBankAddrLine3:
                        type: string
                      intrmdryBankNm3:
                        type: string
                      intrmdryBicCode3:
                        type: string
                      orgntngBankAbaNum:
                        type: string
                      orgntngBankAddrLine:
                        type: string
                      orgntngBankBicCode:
                        type: string
                      orgntngBankNm:
                        type: string
                      orgntngAba1:
                        type: string
                      orgntngArngNum1:
                        type: string
                      orgntngIpNm1:
                        type: string
                      orgntngIpAddrLine1:
                        type: string
                      orgntngAba2:
                        type: string
                      orgntngArngNum2:
                        type: string
                      orgntngIpNm2:
                        type: string
                      orgntngIpAddrLine2:
                        type: string
                      orgntngAba3:
                        type: string
                      orgntngArngNum3:
                        type: string
                      orgntngIpNm3:
                        type: string
                      orgntngIpAddrLine3:
                        type: string
                      crVirtualNum:
                        type: string
                      dbVirtualNum:
                        type: string
      example:
        alertNotificationRequest:
          - alertNotification:
              alertHeader:
                alertSentDateAndTime: '2023-02-1159T10:20:56Z'
                alertCode: AL00901
                payType: WIRE
                eapAlertGUID: f4d88cd2-446c-3cc4-9330-aa123456789
              alertBody:
                crOrDbCode: C
                crArngNum: '359123456789'
                crArngTypeCode: DDA
                crArngBankNum: '0101'
                crTranCurrencyCode: USD
                dbArngTypeCode: DDA
                dbTranCurrencyCode: USD
                requestReferenceNumber: '4630123-20240212161123'
                crIpId: '999997'
                crIpNm: BANKOFTEST
                dbArngNum: '201907987654321'
                dbArngBankNum: '0101'
                dbIpId: '30472222'
                dbIpNm: Test Name
                payNotifyTs: '1673615327943'
                wireEventNm: WirePaymentTransactionEvent
                tranAmt: '12.79'
                tranExecutedDt: '20230112'
                federalReferNum: 'null'
                sndngBankReferNum: 'null'
                tranId: US23010987654321
                tranBusnStatusCode: RegulatoryFilter
                wireDirectionCode: OUTBOUND
                tranType: 'null'
                tranValueTypeCode: 'N'
                wireProcessTypeCode: 'null'
                benefitAba: 'null'
                benefitArngNum: '3435656765'
                benefitIpAddrLine: 250 Delaware Ave St
                benefitBicCode: KEYBUS33 XXX
                benefitBankAbaNum: 'null'
                benefitBankArngNum: 'null'
                benefitBankAddrLine: 250 Delaware Ave St
                benefitBankBicCode: KEYBUS33 XXX
                benefitBankNm: KeyBank National Association
                intrmdryBankAbaNum1: 'null'
                intrmdryBankAddrLine1: 'null'
                intrmdryBankNm1: KeyBank National Association
                intrmdryBicCode1: '21300077'
                intrmdryBankAbaNum2: 'null'
                intrmdryBankAddrLine2: 'null'
                intrmdryBankNm2: BANKOFTEST
                intrmdryBicCode2: KEYBUS33 XXX
                intrmdryBankAbaNum3: 'null'
                intrmdryBankAddrLine3: 'null'
                intrmdryBankNm3: 'null'
                intrmdryBicCode3: 'null'
                orgntngBankAbaNum: 'null'
                orgntngBankAddrLine: 'null'
                orgntngBankBicCode: 'null'
                orgntngBankNm: 'null'
                orgntngAba1: 'null'
                orgntngArngNum1: '123456789'
                orgntngIpNm1: 'TEST COMPANY 1, LLC'
                orgntngIpAddrLine1: '127 Public Sq, Cleveland,OH 44114,US'
                orgntngAba2: 'null'
                orgntngArngNum2: 'null'
                orgntngIpNm2: 'null'
                orgntngIpAddrLine2: 'null'
                orgntngAba3: 'null'
                orgntngArngNum3: 'null'
                orgntngIpNm3: 'null'
                orgntngIpAddrLine3: 'null'
                crVirtualNum: '953456789'
                dbVirtualNum: '953654321'
    alertSuccessResponse:
      type: object
      properties:
        alertNotificationResponse:
          type: array
          items:
            type: object
            properties:
              alertAcknowledgment:
                type: object
                properties:
                  alertStatus:
                    type: string
                    enum:
                    - SUCCESS
                  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: SUCCESS
            confirmationGUID: 5f0ada5b-056f-483c-98ae-ac6ccab269c1
            alertRecievedDateAndTime: 2021-11-19T10:31:12Z
            eapAlertGUID: 5163dee6-0b2b-4901-9f6a-4b3997ee8d77
            message: Successfully submitted the request
    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-19T10:31:12Z
            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-19T10:31:12Z
            eapAlertGUID: 3eecd293-8c45-40ba-be09-d8570c5665ed
            message: Internal Error