Timely and automated payment status notifications Overview 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. You get near real-time updates whenever a specific payment event occurs, like a posted ACH transaction or a completed wire transfer. How to subscribe for notifications Subscribe to webhook alert notifications if you are a commercial customer or fintech partner with KeyBank. It takes about 5-10 days to complete the alert notification setup. To subscribe for payment notifications, you have to onboard with KeyBank (see our Getting Started Guide for the basic process) and share some information about your application/system. For existing clients, reach out to your Payments Advisor to start the subscription process. For new clients, you will need to provide a few more details like: Basic client information (name, phone, email, etc.) Bank account number and routing number Type of alert subscription (see alert code table) A decision if the pre-production and production subscriptions accounts will be the same or different Expected volumes per day/month/year Estimated schedule to start testing in the pre-production environment and to go live in the production environment Got you hooked? Check out some more content about our webhooks: Alert codes Payment webhook specifications Retry mechanism Payment webhooks Alert notifications are triggered by specific payment status events and are sent in the form of an HTTP POST request. KeyBank can send up to 100 alerts per API call. After receiving an alert notification, KeyBank expects you to send an HTTP 2XX status code in response within 10 seconds and the response needs to adhere to KeyBank's format for an alert response. Payment webhook alert notifications Each payment webhook alert notification has an alertNotification object that is made up of two parts: alertHeader: The header information gives you basic information about the request: date and time sent, the alert code, and a unique notification identifier. alertBody: The body information contains transaction details. Each of the fields will be present in the request even if there is no data retrieved for a particular field. Fields that have no data show the null value. Both the alertHeader and alertBody can vary by event type, ACH or Wire/RTP. The alertHeader for Wire/RTP notification contains the payType field that specifies if is a wire or RTP alert while the ACH alert header does not have a payType field. The alertBody fields are different based on each event type as defined by the alert code. Alert codes Each alert notification contains the alert code for the payment status event that occurred. Wire and RTP alert notifications have one alert code (AL00901) for all payment status events. Alert Code Types Alert Code Alert Description AL00901 Wire or RTP AL00902 ACH Collected AL00903 ACH Posted AL00904 ACH Returned AL00905 ACH Notification of Change Before you begin All KeyBank APIs require certificates, user credentials, and certain permissions. Check out our Getting Started Guide to learn more. ACH alert notifications ACH Notification Request HEADER 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. BODY 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 Request example (ACH) { "alertNotificationRequest": [ { "alertNotification": { "alertHeader": { "alertSentDateAndTime": "2021-11-19T10:20:56Z", "alertCode": "AL00902", "eapAlertGUID": "4g0fda4b-156f-483c-98ae-bd8ccab266h0" }, "alertBody": { "accountNumber": "359123456789", "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/RTP alert notifications The Wire/RTP alertBody identifies the status of the payment event in the tranBusnStatusCode field. Possible values include: Wire and RTP Status Codes STATUS DESCRIPTION Abandoned Payment is manually forced to not complete payment processing. Payment will not complete workflow. Cancelled Payment was cancelled. Payment will not complete workflow. Completed Payment processed successfully and completes the workflow. Fatal A serious error has occurred. Payment will not complete workflow. Future Warehouse Cancelled Payment was cancelled from Future Warehouse queue. Payments enter the Future Warehouse queue if the payment missed the payment network cutoff time and moves to a future business date. When the future business date arrives, the payment network re-enters the payment in the workflow to reach Future Warehouse Cancelled. Rejected Payment was rejected by the network. Payment will not complete workflow. Returned Payment was returned by receiving bank. Wire/RTP Notification Request HEADER 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 payType string Identifies if the payment type was a Wire or RTP transaction. Valid values: WIRE, RTP eapAlertGUID string Unique alert notification identifier. BODY 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. dbArngTypeCode string Type code of the debit account dbTranCurrencyCode string Transaction currency code of the debit account. requestReferenceNumber string Unique identification number for an originating wire or RTP transaction. This number is limited to 32 characters. 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. Request example (Wire/RTP) { "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" } } } ] } Payment webhook response The top level alertNotificationResponse object is an array of alertAcknowledgment objects. Because KeyBank can send up to 100 alerts per API call, each alert notification sent must be responded to with its own alertAcknowledgment object. The format of the response needs to adhere to the format specified here. Response 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. 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" } } ] } 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. 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 fails and there are no more additional retry attempts. Notify your KeyBank Client Success Manager if there is an outage for more than 24 hours or if you have an outage planned for your systems that extends past a 24-hour period. You can also notify us with our Support form. To inquire about a payment event after 24 hours, you must use the ACH Inquiry or Wire Inquiry APIs. YAML file