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:
|
|
|
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
