Webhooks

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 ACH, wire, and RTP 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.

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 codes)
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. There is an alert code for Wire/RTP and ACH to monitor all payment status events related to that transaction type.

Alert code types

Wire/RTP alert code: AL00901
ACH alert code: AL00906

Legacy ACH alert codes include AL00902 (ACH Collected), AL00903 (ACH Posted), AL00904 (ACH Returned), AL00905 (ACH Notification of Change). All ACH payment events are now managed with alert code AL00906.

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: AL00906
eapAlertGUID	string	Unique alert notification identifier.

BODY FIELD	TYPE	DESCRIPTION
transactionStatus	string	The status of the ACH transaction. Valid values: COLLECTED, RETURNED, SETTLED
traceNumber	string	The unique number for the transaction provided by the originator.
parNumber	string	The unique PAR number assigned to the the transaction by the ACH product processor.
transactionAmount	number	The dollar amount of the transaction.
collectionDate	string	Date the transaction was processed. Format: YYYY-MM-DD
settlementDate	string	The date the transaction settlement occurred. Format: YYYY-MM-DD
transactionCode	string	Two-digit code identifying the account type at the receiving financial institution.
transactionDescription	string	Description about the purpose of the transaction.
authorizedCustomerName	string	Authorized customer name
standardEntryClassCode	string	Three-digit Standard Entry Class (SEC) code based on Nacha rules. Valid values: CCD, CTX, PPD, TEL, WEB
receivingAccountNumber	string	Account number of the person or institution receiving the funds.
receivingCustomerIdentificationNumber	string	The customer identification number for the person receiving the transaction.
receivingCompanyName	string	Company name of the institution getting the funds.
originatingAccountNumber	string	Account number of the ACH transaction originator.
originatingCustomerIdentificationNumber	string	Originating customer identification number
returnReasonCode	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
returnReasonDescription	string	Description as to why the ACH transaction is returned.
returnDate	string	Date of the returned transaction to the ACH system. Format: YYYY-MM-DD
notificationOfChangeAddendaCount	string	Count of change notifications for addenda records.
internationalAddendaCount	string	Count of international addenda records.
addendaCount	string	Count of addenda records.

Request example (ACH)

{
  "alertNotificationRequest": [
    {
    "alertNotification": {
      "alertHeader": {
        "alertSentDateAndTime": "2024-07-07T16:25:08Z",
        "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"
        }
      }
    }
  ]
}

Wire/RTP alert notifications

The Wire/RTP alertBody identifies the status of the payment event in the tranBusnStatusCode field.

Wire/RTP statuses

The Wire and RTP statuses listed show the final status values. You may get an intermittent status that is not list in this table. Go to Data values > Wire and RTP webhook statuses to view the full list.

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

Only the HTTP 500 error codes will prompt the retry mechanism. If you have one of the HTTP 400 error codes, you are expected to troubleshoot the issue. If you cannot find a resolution, please contact your Payments Advisor or Technical Account Manager.

Payment webhook alert retry mechanism

The retry mechanism is trigger for any backend error issues, typically associated with HTTP 500's status codes. With a unsuccessful HTTP 5XX response, the KeyBank retry mechanism will attempt to deliver a failed alert notification for 24 hours after the original failed notification. The retry attempts follow this 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