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