KeyBank’s payment webhooks provide timely and automated payment status notifications without the need for constant API polling or manual checks. We currently facilitate alerts for both ACH and wire transaction status changes. Implementing payment webhooks allow for near real-time updates whenever a specific payment event occurs, like a posted ACH transaction or a completed wire transfer. Before you begin All KeyBank APIs require certificates, user credentials, and certain permissions. Before you begin, see Key concepts to learn more about these fundamental elements as well as other recommended best practices. Alert codes Alert notifications are triggered by specific payment status events and are sent in the form of an HTTP POST request. Each alert notification contains the alert code for the payment status event that occurred. Alert Code Alert Description AL00901 Wire or RTP AL00902 ACH Collected AL00903 ACH Posted AL00904 ACH Returned AL00905 ACH Notification of Change Payment webhook alert schema The top level alertNotificationRequest object is an array of alertNotification objects. KeyBank can send up to 1000 alerts (in the form of an alertNotification) per API call. Each alertNotification object is made up of two parts: alertHeader and alertBody. alertHeader All webhook alerts have the following elements in the alertHeader object: FIELD TYPE DESCRIPTION alertSentDateAndTime string Date and time the alert was sent. Format: (YYYY-MM-DD)T(HH:MM:SS)Z alertCode string Alert code. Valid values: AL00901, AL00902, AL00903, AL00904, AL00905 eapAlertGUID string Unique alert notification identifier. Wire and RTP alert notifications have an additional element in the alertHeader object: FIELD TYPE DESCRIPTION payType string Identifies if the payment type was a Wire or RTP transaction. Valid values: WIRE, RTP alertBody The schema of the alertBody object varies by event type (ACH, Wire/RTP). Each of the fields will be present in the request but if there is no data retrieved for a particular field, the value of that field will be null. ACH alert notifications FIELD TYPE DESCRIPTION accountNumber string Bank account number bankNumber string Bank number associated with the account number. snapshotDT string Date that requested data was loaded. Format: MM-DD-YYYY tranType string Transaction type processDT string Date the transaction was processed. Format: MM/DD/YYYY tranParNum string The unique PAR number assigned to the transaction by the ACH product processor. tranAmnt string Transaction amount crOrDbCode Object Identifies the transaction type as credit or debit. Valid values: C (credit), D (debit) tranCode Object Two-digit code identifying the account type at the receiving financial institution. collRecvngCustNM Object Customer name of the person receiving the funds. collRecvngCompanyNM Object Company name of the entity receiving the funds. collOrgntngCustNM Object Customer name of the person sending the funds. collOrgntngCompanyNm number Company name of the entity sending the funds. collTranTraceID string Trace ID number from the source application. collNachaSecCode string Three-digit Standard Entry Class (SEC) code based on Nacha rules. Valid values: CCD, CTX, PPD, TEL, WEB collNachaSecDescr string Description of the Nacha SEC code. retTranCode string Two-digit code identifying the account type at the receiving financial institution. retTranCodeDescr string Description for the transaction code. retReturnReleaseDT string Release date of the returned transaction to the ACH system. Format: YYYY-MM-DD retReturnReasonCode string 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 retReturnReasonDescr string Description as to why the ACH transaction is returned. nocChangeCode string Notification of Change (NOC) code. This is a three-character code beginning with the letter 'C' used to notify the ACH sender that they need to update a customer's bank account information. nocChangeDescr string Description associated with a NOC code. productCode string Hogan product code Example payment alert ACH alert { "alertNotificationRequest": [ { "alertNotification": { "alertHeader": { "alertSentDateAndTime": "2021-11-19T10:20:56Z", "alertCode": "AL00902", "eapAlertGUID": "4g0fda4b-156f-483c-98ae-bd8ccab266h0" }, "alertBody": { "accountNumber": "00000000359123456789", "bankNumber": "0101", "snapshotDT": "06/07/2022", "tranType": "COLLECTED", "processDT": "06/07/2022", "tranParNum": "22010123456789", "tranAmnt": "287.40", "crOrDbCode": "C", "tranCode": "22", "collRecvngCustNM": "TEST CUSTOMER", "collRecvngCompanyNM": "EST COMPANY 1, LLC", "collOrgntngCustNM": "null", "collOrgntngCompanyNm": "EST COMPANY 2, INC.", "collTranTraceID": "043000987654321", "collNachaSecCode": "CCD", "collNachaSecDescr": "Cash Concentration or Disbursement", "retTranCode": "null", "retTranCodeDescr": "null", "retReturnReleaseDT": "null", "retReturnReasonCode": "null", "retReturnReasonDescr": "null", "nocChangeCode": "null", "nocChangeDescr": "null", "productCode": "DDA" } } } ] } Wire and RTP alert notifications Wire and RTP alert notifications have one alert code (AL00901) for all payment status events. The payment status event is specified in the tranBusnStatusCode field. Possible values include: Completed Pricing Returned Cancelled Future Warehouse PaymentNotification Held Requiring Cover Internal Filter Advising Funds Release Product Selection Regulatory Filter Clearing Limit Check Pre-Qualifying Abandoned Repair FIELD TYPE DESCRIPTION crOrDbCode string Identifies the transaction type as credit or debit. Valid values: C (credit), D (debit) crArngNum string Account number of the credit account. crArngTypeCode string Type code of the credit account. crArngBankNum string Bank number of the credit account. crTranCurrencyCode string Transaction currency code of the credit account. crIpId string Customer number associated with the credit account. crIpNm string Customer name associated with the credit account. dbArngNum string Account number of the debit account. dbArngBankNum string Bank number of the debit account. dbIpId string Customer number associated with the debit account. dbIpINm string Customer name associated with the debit account. payNotifyTs string Timestamp of the payment event. wireEventNm string Payment status code tranAmt string Dollar amount of the transaction. tranExecutedDt string Date the transaction is executed. Format: YYYYMMDD federalReferNum string Federal reference number sndngBankReferNum string Reference number attached to a wire, issued by the sending bank. tranId string Unique transaction identifier tranBusnStatusCode string Transaction business status code wireDirectionCode string Indicates the direction of the transaction. tranType string Type of transaction. tranValueTypeCode string Identifies the value of a transaction. wireProcessTypeCode string Wire processing type code benefitAba string ABA routing number of the beneficiary. benefitArngNum string Account number of the beneficiary. benefitIpAddrLine string Address lines 1-7 (array) of the beneficiary. benefitBicCode string BIC number of the beneficiary. benefitBankAbaNum string ABA routing number of the beneficiary's bank. benefitBankArngNum string Account number of the beneficiary's bank. benefirBankAddrLine string Address lines 1-7 (array) of the beneficiary's bank. benefitBankBicCode string BIC number of the beneficiary's bank. benefitBankNm string Name of the beneficiary's bank. intrmdryBankAbaNum1 string ABA routing number of the intermediary bank 1. intrmdryBNankAddrLine1 string Address lines 1-7 (array) of the intermediary bank 1. intrmdryBankNm1 string Name of the intermediary bank 1. intrmdryBicCode1 string BIC number of the intermediary bank 1. intrmdryBankAbaNum2 string ABA routing number of the intermediary bank 2. intramdryBankAddrLine2 string Address lines 1-7 (array) of the intermediary bank 2. intrmdryBankNm2 string Name of the intermediary bank 2. intrmdryBicCode2 string BIC number of the intermediary bank 2. intrmdryBankAbaNum3 string ABA routing number of the intermediary bank 3. intrmdryBankAddrLine3 string Address lines 1-7 (array) of the intermediary bank 3. intrmdryBankNm3 string Name of the intermediary bank 3. intrmdryBicCode3 string BIC number of the intermediary bank 3. orgntngBankAbaNum string ABA routing number of the wire originator's bank. orgntngBankAddrLine string Address lines 1-7 (array) of the wire originator's bank. orgntngBankBicCode string BIC number of the wire originator's bank. orgntngBankNm string Name of the wire originator's bank. orgntngAba1 string ABA routing number of the originator 1. orgntngArngNum1 string Account number of the originator 1. orgntngIpNm1 string Name of the originator 1. orgntngIpAddrLine1 string Address lines 1-7 (array) of the originator 1. orgntngAba2 string ABA routing number of the originator 2. orgntngArngNum2 string Account number of the originator 2. orgntngIpNm2 string Name of the originator 2. orgntngIpAddrLine2 string Address lines 1-7 (array) of the originator 2. orgntngAba3 string ABA routing number of the originator 3. orgntngArngNum3 string Account number of the originator 3. orgntngIpNm3 string Name of the originator 3. orgntngIpAddrLine3 string Address lines 1-7 (array) of the originator 3. crVirtualNum string Virtual account number of the credit account. dbVirtualNum string Virtual account number of the debit account. Example payment alert Wire/RTP alert { "alertNotificationRequest": [ { "alertNotification": { "alertHeader": { "alertSentDateAndTime": "2023-02-1159T10:20:56Z", "alertCode": "AL00901", "payType": "WIRE", "eapAlertGUID": "f4d88cd2-446c-3cc4-9330-aa123456789" }, "alertBody": { "crOrDbCode": "C", "crArngNum": "00000000359123456789", "crArngTypeCode": "DDA", "crArngBankNum": "0101", "crTranCurrencyCode": "USD", "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" } } } ] } Payment webhook response After receiving an alert notification, KeyBank expects you to send an HTTP 2XX status code in response within 10 seconds. The format of the response needs to adhere to the format specified here. The top level alertNotificationResponse object is an array of alertAcknowledgment objects. Because KeyBank can send up to 1000 alerts per API call, each alert notification sent must be responded to with its own alertAcknowledgment object. The format for this object is as follows: FIELD TYPE DESCRIPTION alertStatus string Status of the alert notification. confirmationGUID string API customer unique ID for the alert notification. alertRecievedDateAndTime string Date and time the alert was received. Format: (YYYY-MM-DD)T(HH:MM:SS)Z eapAlertGUID string Unique alert notification identifier passed through from the request. message string Free-form text field to describe the response. Example payment alert Successful response { "alertNotificationResponse": [ { "alertAcknowledgment": { "alertStatus": "SUCCESS", "confirmationGUID": "5f0ada5b-056f-483c-98ae-ac6ccab269c1", "alertRecievedDateAndTime": "2021-11-19T10:31:12Z", "eapAlertGUID": "f4d88cd2-446c-3cc4-9330-aa123456789", "message": "Successfully submitted the request" } } ] } Example payment alert Unsuccessful response { "alertNotificationResponse": [ { "alertAcknowledgment": { "alertStatus": "FAILURE", "confirmationGUID": "5f0ada5b-056f-483c-98ae-ac6ccab269c1", "alertRecievedDateAndTime": "2021-11-19T10:31:12Z", "eapAlertGUID": "f4d88cd2-446c-3cc4-9330-aa123456789", "message": "Required parameter(s) not found: [fieldName(s)]" } } ] } Payment webhook errors If your webhook receiver/handler encounters an error, KeyBank expects you to send one of the following HTTP status codes: 400 Invalid input 401 Authentication error 403 Authorization error 500 Internal error Any of these error codes will prompt the retry mechanism explained below. Payment webhook alert retry mechanism If an HTTP 2XX status code is not received within 10 seconds, or an HTTP 4XX/5XX status code is returned, KeyBank assumes the alert notification was unsuccessful. We will attempt to deliver a failed alert notification for 24 hours after the original failed notification attempt according to the following schedule: 3 attempts, each attempt every 30 seconds 6 attempts, each attempt every 90 minutes 3 attempts, each attempt every 5 hours Attempt number Time between attempts Time elapsed since first alert 1-3 30 seconds 30 seconds - 1.5 minutes 4-9 90 minutes 1.5 - 9 hours 10-12 5 hours 14 - 24 hours After the 24-hour window, the notification is failed and no additional retry attempts will be made. To inquire about a payment event after 24 hours, you must use the ACH Inquiry or Wire Inquiry APIs. YAML file