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.RequirementsTo subscribe to webhook alert notifications for ACH, Wire, or RTP transactions, you must be a commercial customer or fintech partner of KeyBank. Only authorized API consumers can subscribe to this feature. For existing clients, reach out to your Payments Advisor to start the subscription process.For new clients, you will first need to onboard with KeyBank (see our Getting Started Guide for the basic process). In addition, you will be asked to provide a few more details like:Type of alert subscription (see alert codes)A decision if the pre-production and production subscriptions accounts will be the same or differentExpected volumes per day/month/yearSubscribeKeyBank recommends that destination application always have authentication. To reduce setup time for webhook subscriptions while maintaining system integrity and security, we recommend these guidelines:Use Basic Authentication (BasicAuth) which involves providing KeyBank with a unique username and password for your application. KeyBank will send a Base64 encoded version of the credential to Authorization header of your HTTP request. Connect securely with a TLS connection for an encrypted, safe exchange of data. If you have a specialized needs or circumstances that require secure alternatives rather than BasicAuth, speak with your KeyBank Payment Advisor. This may extend setup time. Got you hooked?Check out some more content about our webhooks:Alert codesPayment webhook specificationsRetry 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 notificationsEach 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 like 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 this field. The alertBody fields are also different based on each event type as defined by the alert code.Alert codesEach 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 typesWire/RTP alert code = AL00901ACH alert code = AL00906Note, with a latest specification update, all ACH payment events are now managed with alert code AL00906. This one code consolidates the legacy ACH alert codes: AL00902 (ACH Collected), AL00903 (ACH Posted), AL00904 (ACH Returned), AL00905 (ACH Notification of Change). Before you beginAll KeyBank APIs require certificates, user credentials, and certain permissions. Check out our Getting Started Guide to learn more. ACH alert notifications ACH Notification RequestHEADER FIELDTYPEDESCRIPTIONalertSentDateAndTimestringDate and time the alert was sent. Format: (YYYY-MM-DD)T(HH:MM:SS)ZalertCodestringAlert code. Valid values: AL00906eapAlertGUIDstringUnique alert notification identifier.BODY FIELDTYPEDESCRIPTIONtransactionStatusstringThe status of the ACH transaction. Valid values: COLLECTED, RETURNED, SETTLEDtraceNumberstringThe unique number for the transaction provided by the originator.parNumberstringThe unique PAR number assigned to the the transaction by the ACH product processor.transactionAmountnumberThe dollar amount of the transaction.collectionDatestringDate the transaction was processed. Format: YYYY-MM-DDsettlementDatestringThe date the transaction settlement occurred. Format: YYYY-MM-DDtransactionCodestringTwo-digit code identifying the account type at the receiving financial institution.transactionDescriptionstringDescription about the purpose of the transaction.authorizedCustomerNamestringAuthorized customer namestandardEntryClassCodestringThree-digit Standard Entry Class (SEC) code based on Nacha rules. Valid values: CCD, CTX, PPD, TEL, WEBreceivingAccountNumberstringAccount number of the person or institution receiving the funds. receivingCustomerIdentificationNumberstringThe customer identification number for the person receiving the transaction.receivingCompanyNamestringCompany name of the institution getting the funds. originatingAccountNumberstringAccount number of the ACH transaction originator.originatingCustomerIdentificationNumberstringOriginating customer identification numberreturnReasonCodestringThe 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: R00returnReasonDescriptionstringDescription as to why the ACH transaction is returned.returnDatestringDate of the returned transaction to the ACH system. Format: YYYY-MM-DDnotificationOfChangeAddendaCountstringCount of change notifications for addenda records.internationalAddendaCountstringCount of international addenda records.addendaCountstringCount 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": "2024-01-12", "settlementDate": "2024-01-12", "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": "2024-01-03", "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 statusesThe 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.STATUSDESCRIPTIONAbandonedPayment is manually forced to not complete payment processing. Payment will not complete workflow.CancelledPayment was cancelled. Payment will not complete workflow.CompletedPayment processed successfully and completes the workflow.FatalA serious error has occurred. Payment will not complete workflow.Future Warehouse CancelledPayment 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.RejectedPayment was rejected by the network. Payment will not complete workflow.ReturnedPayment was returned by receiving bank.Wire/RTP Notification RequestHEADER FIELDTYPEDESCRIPTIONalertSentDateAndTimestringDate and time the alert was sent. Format: (YYYY-MM-DD)T(HH:MM:SS)ZalertCodestringAlert code. Valid values: AL00901payTypestringIdentifies if the payment type was a Wire or RTP transaction. Valid values: WIRE, RTPeapAlertGUIDstringUnique alert notification identifier.BODY FIELDTYPEDESCRIPTIONcrOrDbCodestringIdentifies the transaction type as credit or debit. Valid values: C (credit), D (debit)crArngNumstringAccount number of the credit account.crArngTypeCodestringType code of the credit account.crArngBankNumstringBank number of the credit account.crTranCurrencyCodestringTransaction currency code of the credit account.dbArngTypeCodestringType code of the debit accountdbTranCurrencyCodestringTransaction currency code of the debit account.requestReferenceNumberstringUnique identification number for an originating wire or RTP transaction. This number is limited to 32 characters.crIpIdstringCustomer number associated with the credit account.crIpNmstringCustomer name associated with the credit account.dbArngNumstringAccount number of the debit account.dbArngBankNumstringBank number of the debit account.dbIpIdstringCustomer number associated with the debit account.dbIpINmstringCustomer name associated with the debit account.payNotifyTsstringTimestamp of the payment event.wireEventNmstringPayment status codetranAmtstringDollar amount of the transaction.tranExecutedDtstringDate the transaction is executed. Format: YYYYMMDDfederalReferNumstringFederal reference numbersndngBankReferNumstringReference number attached to a wire, issued by the sending bank.tranIdstringUnique transaction identifiertranBusnStatusCodestringTransaction business status codewireDirectionCodestringIndicates the direction of the transaction.tranTypestringType of transaction.tranValueTypeCodestringIdentifies the value of a transaction.wireProcessTypeCodestringWire processing type codebenefitAbastringABA routing number of the beneficiary.benefitArngNumstringAccount number of the beneficiary.benefitIpAddrLinestringAddress lines 1-7 (array) of the beneficiary.benefitBicCodestringBIC number of the beneficiary.benefitBankAbaNumstringABA routing number of the beneficiary's bank.benefitBankArngNumstringAccount number of the beneficiary's bank.benefirBankAddrLinestringAddress lines 1-7 (array) of the beneficiary's bank.benefitBankBicCodestringBIC number of the beneficiary's bank.benefitBankNmstringName of the beneficiary's bank.intrmdryBankAbaNum1stringABA routing number of the intermediary bank 1.intrmdryBNankAddrLine1stringAddress lines 1-7 (array) of the intermediary bank 1.intrmdryBankNm1stringName of the intermediary bank 1.intrmdryBicCode1stringBIC number of the intermediary bank 1.intrmdryBankAbaNum2stringABA routing number of the intermediary bank 2.intramdryBankAddrLine2stringAddress lines 1-7 (array) of the intermediary bank 2.intrmdryBankNm2stringName of the intermediary bank 2.intrmdryBicCode2stringBIC number of the intermediary bank 2.intrmdryBankAbaNum3stringABA routing number of the intermediary bank 3.intrmdryBankAddrLine3stringAddress lines 1-7 (array) of the intermediary bank 3.intrmdryBankNm3stringName of the intermediary bank 3.intrmdryBicCode3stringBIC number of the intermediary bank 3.orgntngBankAbaNumstringABA routing number of the wire originator's bank.orgntngBankAddrLinestringAddress lines 1-7 (array) of the wire originator's bank.orgntngBankBicCodestringBIC number of the wire originator's bank.orgntngBankNmstringName of the wire originator's bank.orgntngAba1stringABA routing number of the originator 1.orgntngArngNum1stringAccount number of the originator 1.orgntngIpNm1stringName of the originator 1.orgntngIpAddrLine1stringAddress lines 1-7 (array) of the originator 1.orgntngAba2stringABA routing number of the originator 2.orgntngArngNum2stringAccount number of the originator 2.orgntngIpNm2stringName of the originator 2.orgntngIpAddrLine2stringAddress lines 1-7 (array) of the originator 2.orgntngAba3stringABA routing number of the originator 3.orgntngArngNum3stringAccount number of the originator 3.orgntngIpNm3stringName of the originator 3.orgntngIpAddrLine3stringAddress lines 1-7 (array) of the originator 3.crVirtualNumstringVirtual account number of the credit account.dbVirtualNumstringVirtual 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": "20240112", "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.ResponseFIELDTYPEDESCRIPTIONalertStatusstringStatus of the alert notification.confirmationGUIDstringAPI customer unique ID for the alert notification.alertRecievedDateAndTimestringDate and time the alert was received. Format: (YYYY-MM-DD)T(HH:MM:SS)ZeapAlertGUIDstringUnique alert notification identifier passed through from the request.messagestringFree-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 input401 Authentication error403 Authorization error500 Internal errorThe HTTP 5XX 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 sends a failed alert notification if the transaction encounters any backend related issues. If you get a HTTP 5XX error code, the retry mechanism will send up to three alerts to retry over a period of 24 hours after the original failed notification. Attempt numberAlert sent atTime between each attempt15 minutesInitial alert21 hour55 minutes312 hours11 hours424 hours12 hoursAfter the 24-hour window, the notification fails and there are no more additional retry attempts. Notify your Payments Advisor 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. Changelog ReleaseAPI versionChange descriptionImpactJanuary 20252.2.0The retry mechanism logic has been updated to send three alerts over the period of a 24 hours. This is a reduction from the initial design of 12 attempts over 24 hours. This change helps us avoid sending too many alerts for ACH batch type requests if it encounters a HTTP 5XX error.LOWAugust 20242.2.0We introduce the version 2 of our Webhooks. This API is sleek! For ACH alerts, the alert codes (AL00902, AL00903, AL00904, AL00905) have been consolidated into a single and new code, AL00906.HIGHApril 20241.1.0For Wire and RTP webhook alert notifications, dbTranCurrencyCode and dbAngTypeCode are in the alert body.Added the requestReferenceNumber to the alert body for Wire and RTP alert notification. If this parameter has a value, it will return in the alert body for RTP or Wire notifications.MIDDecember 20231.1.0Remove all leading zeros for the following account parameters:crArngNumdbArngNumaccountNumberLOWAugust 20231.0.1Published on the Developer Portal. Impact levelsLOW: This is a minor change or enhancement that does not alter the operations of the API. Upgrading to the latest specifications is preferable but not required.MID: The previous API version is valid and operates, but does not contain latest enhancements. You need to update your specifications to get these enhancements.HIGH: The previous API version is no longer operable. You must upgrade to the latest specifications to access and use this API product. YAML file