Timely and automated payment status notifications Overview KeyBank’s payment webhooks provide timely and automated payment status notifications without the need for continuous API polling or manual checks.We currently facilitate alerts for payment transactions status changes like ACH, RTP, and wire. You receive near real-time updates whenever a payment event occurs, such as 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 clients can subscribe to this feature. Existing clients: Contact your Technical Account Manager to begin the subscription process.New clients: You must first complete onboarding with KeyBank (see the Get Started Guide for an overview). During the setup, you will be asked to provide additional information, including:The type of alert subscription you require (see alert codes)Whether your pre-production and production subscriptions accounts will be the same or separateExpected transaction volumes per day, month, and yearSubscribeTo maintain system integrity and security, KeyBank recommends that your destination application use authentication that follows these guidelines:Use Basic Authentication (BasicAuth). Provide KeyBank with a unique username and password for your application.Credentials are encoded for transmission. KeyBank sends a Base64 encoded version of your credentials in the Authorization header of the webhook HTTP request.Use a secure TLS connection. This is necessary for encrypted and safe exchange of data. If you have a specialized needs or circumstances that require secure alternatives to Basic Authentication, speak with your KeyBank Technical Account Manager. Note, using alternative methods may extend setup time. Got you hooked?Check out some more content about our webhooks:Alert codesWebhook responseRetry mechanism Webhook notification structure Each webhook alert includes an alertNotification object with two components: alertHeader and alertBody. These components may differ slightly depending on whether the event relates to ACH or Wire/RTP.alertHeaderThe header contains metadata about the notification, including:the date and time the alert was sentthe alert code identifying the payment rail (ACH vs Wire/RTP)a unique notification identifieralertBodyThe body contains detailed transaction information. All fields appear in the request even when there is no value available. Fields with no applicable data will contain the null value.For Wire/RTP alerts, look at the tranBusnStatusCode to see where the transaction is in the process. Go to Data values > Wire and RTP webhook statuses to view the full list.When payments talks...webhooks listenAlert notifications are triggered by specific payment-status events and delivered as HTTP POST requests. KeyBank may include up to 100 alerts per API call.Alert codesAlert codes identify the payment-status event that triggered the notification. There are alert codes for Wire/RTP and ACH to monitor all payment status events related to that transaction type.Wire/RTP alert codesAL00901 - Full transaction detailsThis alert code returns the most detailed view of the transaction with identifying data for:the originatorthe beneficiaryany intermediary banksrelated parties and referencesAL00907 - Summary transaction detailsThis alert code returns a simplified status notification providing:transaction stationdebtor/creditor informationreference and identification numbersACH alert codesAL00906 - ACH status notificationThis alert code returns ACH-specific status information for collected, posted, or returned transactions and any related references. AL00901 - Wire/RTP alerts RequestHEADER FIELDTYPEDESCRIPTIONalertSentDateAndTimestringDate and time the alert was sent. Format: (YYYY-MM-DD)T(HH:MM:SS)ZalertCodestringFor Wire and RTP alerts, the alert code is AL00901.payTypestringIdentifies 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 (AL00901){ "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" } } } ] } AL00907 - Wire/RTP alerts RequestHEADER FIELDTYPEDESCRIPTIONalertSentDateAndTimestringDate and time the alert was sent. Format: (YYYY-MM-DD)T(HH:MM:SS)ZalertCodestringFor Wire and RTP alerts, the alert code is AL00907.payTypestringIdentifies if the payment type was a Wire or RTP transaction. Valid values: WIRE, RTPeapAlertGUIDstringUnique alert notification identifier.BODY FIELDTYPEDESCRIPTIONtransactionIdstringThe unique ID number associated with the original payment request.transactionStatusstringStatus of the transaction.transactionDatestringDate the transaction occurred. Format: YYYY-MM-DDtransactionAmountstringThe dollar amount of the transaction.requestReferencestringA reference value for the original request that is useful for traceability and reporting. sendersReferencestringSender tracking reference number returned from the request. channelstringIndicates if the transaction is from the API or a batch channel. Valid values: API, BATCHtransactionDirectionstringIndicates if the transaction is incoming or outgoing. Valid values: INBOUND, OUTBOUNDcreditorobjectCustomer number associated with the credit account.namestringContains the customer identification number and the company name.creditorAccountobjectDetails about the creditor account.accountNumberstringAccount number of the party.virtualAccountNumberstringAccount number for the virtual account (VAM).currencyCodestringIndicates type of currency for the transaction amount.debtorobjectCustomer name associated with the debit account.namestringContains the customer identification number and the company name.debtorAccountobjectDetails about the debtor account.accountNumberstringAccount number of the party.virtualAccountNumberstringAccount number for the virtual account (VAM).currencyCodestringIndicates type of currency for the transaction amount.Request example (AL00907){ "alertNotificationRequest": [ { "alertNotification": "alertHeader": { "alertSentDateAndTime": "2023-02-1159T10:20:56Z", "alertCode": "AL00907", "payType": "WIRE", "eapAlertGUID": "f4d88cd2-446c-3cc4-9330-aa123456789" }, "alertBody": { "transactionId": "US25032500068519", "transactionStatus": "IN_PROCESS", "transactionDate": "2025-03-25" "transactionAmount": "6.48" "requestReference": "36691398-42" "sendersReference": "01234" "channel": "API or BATCH" "transactionDirection": "OUTBOUND" "creditor": "name": "RTP GL Clearing Account" "creditorAccount": "accountNumber": "1120108811111" "virtualAccountNumber": "953006666798343" "currencyCode": "USD" "debtor": "name": "LINCOLN ELECTRIC CO" "debtorAccount": "accountNumber": "149222222" "virtualAccountNumber": "953006666796016" "currencyCode": "USD" } } } ] } AL00906 - ACH alerts 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.originatingCompanyNamestringCompany name of the or associated with the ACH 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 (AL00906){ "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" } } } ] } 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 alertAcknowledgment response needs to adhere to the format specified here.The confirmationGUID is a unique identifier that you, the client, create and include in the response. It links the transaction from KeyBank (identified by the eapAlertGUID) to your record of receiving the transaction.Response exampleFIELDTYPEDESCRIPTIONalertStatusstringIndicates if the alert was a success or failure. Typically "SUCCESS" when your application processes the alert without issue.confirmationGUIDstringA unique ID generated by your system to identify your receipt of the alert. alertRecievedDateAndTimestringDate and time the alert was received. Format: (YYYY-MM-DD)T(HH:MM:SS)ZeapAlertGUIDstringThe KeyBank‑generated unique alert identifier. You must copy this value unchanged from the corresponding alert in the incoming request.messagestringOptional, human-readable message about the processing outcome. Successful response{ "alertNotificationResponse": [ { "alertAcknowledgment": { "alertStatus": "FAILURE", "confirmationGUID": "5f0ada5b-056f-483c-98ae-ac6ccab269c1", "alertRecievedDateAndTime": "2021-11-19T10:31:12.000Z", "eapAlertGUID": "ce816009-4aa9-47c7-b2ee-bacf9f0872d0", "message": "Required parameter(s) not found: [fieldName(s)]" } } ] }Error handlingIf 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 errors504: Gateway timeout (set to 30 seconds)The HTTP 500 codes prompt the retry mechanism. If you have one of the HTTP 400 codes, you are expected to troubleshoot the issue. If you cannot find a resolution, please contact your Technical Account Manager.Alert retry mechanismThe retry mechanism sends a failed alert notification if the transaction encounters any backend related issues. If KeyBank receives an HTTP 5XX error code, it triggers the retry mechanism and sends 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 3.0.0June 2025 | MID impactWe have a new Wire/RTP alert event - AL00907. This event is a simple, straight-forward alert notification that shares transaction and party information.2.2.0January 2025 | LOW impactThe 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.2.1.0August 2024 | HIGH impactWe 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.1.2.0April 2024 | MID impactFor 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.1.1.0December 2023 | LOW impactRemove all leading zeros for the following account parameters:crArngNumdbArngNumaccountNumber1.0.1August 2023Released 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