Key takeaways There are many benefits to virtual account management at KeyBank. With KeyVAM, you can: Send and receive ACH, RTP, and Wire transactions on behalf of the parent account. Instant opening and closed of sub-accounts for an individual or business. View transaction and reconciliation data for each virtual sub-account while the total funds settle in one parent account with advance reporting. Virtually amazing Check it out yourself. There is a lot of great information on the Key Virtual Account Management site. If you are ready to get started or have any questions, reach out to an Embedded Banking advisor. What is VAM? Key Virtual Account Management (KeyVAM) is an embedded service of the KeyNavigator platform. KeyVAM enhances how you manage money by linking a set of a set of virtual accounts (sub-accounts) to a single, physical account (parent). You can create and manage virtual sub-accounts in real-time. This is a great option if you need to open and close high-value virtual sub-accounts common in industries like technology, property management, or corporate cost centers. KeyVAM APIs Integrate your application with APIs. KeyVAM APIs are available to further develop your virtual account management experience with task automation for common activities like creating accounts, transferring funds, or reports. View the Key Virtual Account Management API Documentation to see what is possible.
Key takeaways Help reduce fraud by validating the owner of an account, matching the intended counterparty before moving funds Help minimize returns by confirming an account is open and valid before transacting with the account Comply with Nacha rules requiring account validation for web debits in real time without need for prenotes or micro-deposits Help save time with immediate validation for account inquiries Try it yourself If you want to use our Account Validation API, please contact us to learn more. Sign up Everyone needs validation With the Account Validation API, you can inquire about an account and a get real-time confirmation back on the status of the account and whether the ownership data matches. By real-time, we mean like 5 seconds or less on average. This is a far contrast to pre-notes or micro deposits which can take days and possibly accrue cost if there a return involved for illegitimate accounts. Account validation is simple. You send an inquiry request to evaluate the account information from a draft account item, typically a check or an ACH item. KeyBank completes Account Ownership Authentication (AOA). This is an API service that enables payment processors to verify that a payer’s name, address, and other elements match the account information in the National Shared Database (NSD) and the payer is authorized to transact on the account. This service is priced per each successful transaction. Speak with your Payments Advisor to learn more or sign up for the API product. You can also see our Getting Started Guide to learn more about how to partner with KeyBank APIs. See the specs Good to know AOA is possible at KeyBank with the Account Validation API product. We only confirm account ownership. At the moment, we do not provide a detailed account status or risk-based score. Inquire about an account owner When you make a request, you must know the following parameter information: secondaryID: This is a unique identification assigned by KeyBank to each client of the API and identifies which client is making the call. routingNumber: The routing number of the bank account holder. accountNumber: The bank account number of the account owner. If you want to include a name in your search or include more data points for verification, you can use the AcctOwner object to inquire about a personal or business account. A personal inquiry only searches by the account number, routing number, first name/last name. A business inquiry also searches the account owner information associated with the specified business name. You can also append date and time information along with a custom user note or tag in the Client object. Account Owner Search Criteria Search by… AcctOwner fields Account owner’s full name firstName + lastName Business name businessName Account owner’s first name with business name firstName + businessName Account owner’s last name with business name lastName + businessName Account owner’s full name with business name firstName + lastName + businessName Common terms AOA Account Owner Authentication matches the account owner identity to the bank account, confirming if data is accurate when compared against the NSD. EB: Embedded Banking is a sector of KeyBank dedicated to developing and delivering quality digital services integration in both traditional and modern environments. Micro deposits: Small amounts of money sent from one financial account to another to verify and authenticate account ownership. Nacha: National Automated Clearing House Association the organization responsible for managing the rules and regulations governing the ACH network in the US. NSD: National Shared Database is the collection of data contributed to by consumers and used to verify account owner information. Prenotes: Test transactions to help confirm the correct bank account information, like the penny test. Onboarding: The process of helping KeyBank partners and API consumers get familiar with our suite of API products. This can include assessment, setup, and environment access. Verify the data The AOA response includes basic account owner status and validation with a match score. If the response returns an empty field, there is no entry in the database. Account owner status The accountStatus object returns the basic status of the account. The primaryStatusCode returns a three-digit code for the current condition of the bank account and whether is it open, closed, or not found. Account Status Codes Status code Message 000 Routing number and account number combination cannot be found 012 Account is closed 096 No positive or negative information in known about the account 099 Account is present in the participant’s master account file and has no other status code Account owner validation Basic validation passes additional data points from the AcctOwner object like the address, phone number, and date of birth to compare with the NSD. The field entry case, spacing, and punctuation are ignored when matching values. The response returns: a condition code telling you the state of the account owner data provided. match codes that confirm the data is the found or not with a Y (Yes), N (No), C (Conditional), or U (Unknown). an overall match score is generated based on number of data points that did and did not match. If most of the match codes are Y, you will have a higher match score. Request and response example All requests require the secondaryId provided during KeyBank onboarding, routing number, and an account number. If this is a personal inquiry, at a minimum search by account number, routing number, and first name and/or last name. If this is a business inquiry, at a minimum search by account number, routing number, and business name. Request Response "accountValidationRequest": { "AOARequest": { "Inquiry": { "serviceType": "Owner", "secondaryID": "KeyCli01", "additionalID": "", "routingNumber": "122199983", "accountNumber": "89455", "amount":"110.99", "serialNumber": "", "AcctOwner": { "firstName": " Paul;", "lastName": "Wilson ", "middleName": "V", "businessName": "Bizness by Paul", "addressLine1": "206 GOODWIN ST", "city": "MERRIT", "state": "MI", "zipCode": "49667", "ssn": "9999", "dob": "19730801", "idType": "2", "idNo": "6788", idState": "AL" }, "Client": { "ClientDt": "2022-03-04", "ClientTime": "14:45:05", "UserDef": "123xyz" } }} "accountValidationResponse": { "AOAResponse": { "Result": { "errorCode": "000", "systemRecordId": "5934871120174384", "primaryId": "TROM122101", "secondaryId": "KeyCli01", "additionalId": "", "routingNumber": "122199983", "accountNumber": "89455", "feeAttrib": "HH", "amount": "AcctOwner": { "conditionCode": "000", "nameMatch": "Y", "firstNameMatch": "Y", "lastNameMatch": "Y", "middleNameMatch": "Y", "namePrefixMatch": "", "nameSuffixMatch": "", "businessNameMatch": "Y", "addressMatch": "Y", "cityMatch": "Y", "stateMatch": "Y", "zipCodeMatch": "Y", "homePhoneMatch": "", "workPhoneMatch": "", "ssnMatch": "Y", "dobMatch": "Y", "idTypeMatch": "Y", "idNoMatch": "Y", "idStateMatch": "Y", "overallMatchScore": "100" }, "accountStatus": { "primaryStatusCode": "099", "primMessage": "Open Valid" }, "Client": { "ClientDt": "2022-03-04", "ClientTime": "14:45:05", "UserDef": "123xyz" } } }} What to expect The data provided in the request is compared to the NSD. After evaluation, you get a response that indicates if there is a match or any discrepancies. Review the response and interpret the information according to your needs and business rules. You can consider the response data in your decision-making process, along with other risk management information. What's next? View our Getting Started Guide to get an overview of the onboarding process. Get better acquainted with our API and check out the Account Validation API reference material.
Add data or tags specific to your application or use case If you send or validate a payment with the ACH Origination API or the Wire Origination API, you can add information to the customData in the request payload. Custom data is client-specific metadata that you can: Use to append certain information or details Use as an identifier to filter certain types of transactions The customData information is not transmitted with the payment or stored in any KeyBank database. This information is only visible to you, the originator, with the ACH Inquiry API or the Wire Inquiry API. In the inquiry response, the customData field returns any custom values that were part of the payment request stored for recall after a successful ACH or wire transaction completes. This information is not visible to the recipient or any of the participating parties. Here's how it works Define the customData in the request payload. It is a free-form text field that can contain up to 500 alphanumeric characters that you can use however you like - for invoice number, product number, customer number, date/time stamp, etc. KeyBank recommends the common custom data format of name-value pairs. You can list multiple name-value pairs in the custom data field within the 500-character limit. The custom data fields will return exactly what is sent; it does not parse name-value pairs within the API response. The custom data should not contain any personal identifiable information (PII). Custom data examples //Example of name:value pairs "customData": "Type:DD; Status:Submitted; POnumber:12556" //Example of regular text "customData": "General products" //Example of timestamp "customData": "05-MAR-2023:12:19:53EST" As the originator, you can use the ACH Inquiry API or Wire Inquiry API to retrieve the custom data information. Review the response for the customData field. If there is custom data, it returns any custom values that were part of the payment request stored for recall after a successful ACH or wire transaction completes. If no custom data is defined, the response returns an empty field. Available for these APIs ACH Origination API ACH Inquiry API Wires Origination API Wire Inquiry API
Is it you? Is it me? Is it us? Let's figure it out. An error can indicate a problem with the request, the network, or the API itself. Use the error handling information to get a better understanding of what went wrong and possible corrective actions. HTTP status codes Each error response returns the standard HTTP code number with the exception schema. KeyBank utilized the standard HTTP messaging so nothing too fancy. Code Status Description 200 OK; Successful The action was successful. No additional actions are needed. 400 Missing mandatory information Request is missing required information. 401 Unauthorized request Invalid credentials for the request. 403 Forbidden request access You do not have permission to complete the request. 404 Resource not found The resource for the request cannot be found. 405 Invalid request method The wrong request method was used. 415 Invalid request type The wrong media type submitted with the request. 429 Request timeout There are too many requests to the API and a timeout goes into effect. 500 Unknown error There was an unknown error with the server. 502 Bad gateway The servers cannot talk to each other or there is a miscommunication. 503 Unavailable service The service is temporarily down. 504 Unable to process request Request needs more time to be processed. Standard error message format The exception schema includes the error message, your unique X-CorrelationId, and additional information like TransactionId and TransactionTime. The transaction ID and timestamp are helpful in diagnosing the issue. The X-CorrelationId is helpful for transaction traceability and may help determine where did the error occurred. The exception schema may also contain the ServiceError field for API-specific errors or problems with backend services. This object can contain a few different values, depending on the API or circumstance: connectError - error information of the connectivity with downstream service. detailMessage - an error code with a detailed message. serviceErrorData - API-specific error details about the failed transaction. variable field based on API - custom messages about API-related functional business messages or faults. Standard error format { "ErrorMessage": string, "X-CorrelationId": string, "TransactionId": string, "TransactionTime": string, "ServiceError": object } Response header status messages Some APIs contain status messages in the responseHeader object of the response payload. Review the status field to see if the transaction was successful (S), was successful but has a warning (W), or failed (F). Additional information is shared in the statusDescription field. S: A successful response. (HTTP 200) W: The transaction was not not processed as expected. A warning message means the request was successfully received, but there was a minor issue that requires your attention. (HTTP 299) F: The transaction was not processed. (HTTP 400s/500s) API-specific status messages are explained in depth on the API doc pages where applicable. Status message example { "responseHeader": { "status": "S", "statusDescription": "Successfully returned results for the requested range 1 to 1", "retrivedRows": "1", "totalRows": "1", "dataLoadDate": "2022-07-13" }, }
It's a real page-turner You can use pagination parameters to manage a response with large amounts of data. Adjusting these parameters can improve system performance. You can limit or parse data to prevent a lag or delay in a response. You can control how much information is returned in a response. Pagination parameters are usually available on APIs that return lists of transactions like the ACH Inquiry API, Wire Inquiry API, Previous Day API, Intraday API, and RTP Send Payment API. There are several pagination parameters that can help you control how an endpoint will return the information requested. Endpoints with Pagination PAGINATION PARAMETER API ENDPOINT REQUIRED OR OPTIONAL startRowIndex endRowIndex ACH Inquiry POST /accounts/transactions/v1/returnACHtransactions/list POST /accounts/transactions/v1/collectedACHtransactions/list POST /accounts/transactions/v1/postedACHtransactions/list POST /accounts/transactions/v1/ACHStatusInquiry/list Optional startRowIndex endRowIndex Wire Inquiry POST /wireInquiry/v1/transactions/details Optional startRowIndex endRowIndex Previous Day POST /ddaReports/accounts/v1/transactions/list Optional startRowIndex endRowIndex Intraday POST /ddaReports/accounts/v1/transactions/intraday/list Optional limit offset RTP Send Payment GET /rtp/v1/payment/rtp/participant Required Common pagination controls Row pagination There are common pagination parameters like startRowIndex and endRowIndex that help retrieve and organize large data sets into separate, scrollable pages. This is commonly used with information reporting and transaction inquiry APIs. These are optional fields and not required for the request. The startRowIndex query string parameter sets the first row of data of the response. The default value is 1. The endRowIndex query string parameter sets the final row of data of the response. The default value is 1000 records and is also the maximum number of records allowed in a single transaction. If the startRowIndex or endRowIndex parameters are blank, all the rows of data return up to the maximum limit of the endRowIndex value for transaction records. In the response header of the API, an endpoint may return totalRows or retrievedRows. These parameters provide a summary of the total number of transactions that match the request criteria or were retrieved based on the request criteria. Example Here is an example of a request with general pagination parameters applied in the query string for the Previous Day API: POST /ddaReports/accounts/v1/transactions/list?startRowIndex=1&endRowIndex=20 In this example, the startRowIndex is 5 so the first row of data is the fifth row, skipping the first four rows of data. The endRowIndex is 20 so that there is only 20 records per page following the fifth row. Offset pagination The offset pagination parameters are limit and offset. These parameters tell the server how many records to search for at a time and what records to skip. This parameter is not reliant on the sort controls and is not a recommended parameter for very large sets of data. Offset pagination is available with the RTP Send Payment API and is required for the RTP list of participants endpoint. The limit is a query string parameter field that tells the server what items to return during a search. The limit restricts how many rows are returned. There is no maximum limit to this parameter. The offset is a query string parameter field that specifies which set of rows to return. You can use this field to set the starting row for the data that is returned, and control what rows of data to skip. The default value is zero (0). Be cautious when you use these parameters because if the data set changes it can affect the result and may return an incorrect response. Example Here is an example of a request with the offset pagination parameters applied in the query string for the RTP Send Payment API: GET /rtp/v1/payment/rtp/participant?limit=15&offset=0 In this example, the offset is 0 so that no items are skipped, and the limit is 15 meaning the request will search 15 items at a time.
Key takeaways TL;DR? We got you. Here are the highlights to this guide: You need to be an authenticated and authorized user with our developer portal to use our APIs. To get started, see our overview of the onboarding process. After you onboard, you get your own private API keys and can access our test environment. Get an access token to connect to your APIs and start building. Want in? Join the waitlist to sign up for the KeyBank API developer portal and we'll have someone contact you with more information! Sign up Quick overview of the onboarding process 01 Contact and consult If you are interested in a particular API product or a group of APIs, sign up for our waitlist. KeyBank will follow-up with you to help get you started. To work with KeyBank APIs, there needs to be an established agreement between the service provider (KeyBank) and the client (you). This agreement details the API services you want, its services, and settings. It also gathers important system information needed for the KeyBank onboarding team to configure and secure the provisioned app. 02 Determine API needs Determine which APIs are needed, define the frequency of use, and the transaction activity timeframe. Some APIs require specific configurations and may have a certain object to include in the call. Also, be mindful of our rate limiting. For each API, provide the following information: General details like transaction volume Call frequency (number of calls per second, number of calls per minute, etc.) Call timeframe (e.g., 24 hours a day or only during business hours) The KeyBank onboarding team will reach out via email communication for additional details, if necessary. 03 Set up security It is essential to have a secure connection before we start exchanging data, especially data as sensitive as financial data. For us to trust one another and verify that our pathways are safe, private, and guarded, we need to know your IP address and exchange certificates. A digital certificate verifies your identity and keeps your data safe. Think of it like a virtual ID card for a website, or in this case the developer portal. When you connect to the site, the certificate legitimizes your identity. Then, when making API requests and transferring data on a cloud network, the certificate helps encrypt the data. We use a mTLS authentication mechanism. This means when you request a mTLS certificate, you will get a public certificate chain and a private key. On your end, configure your application with the private key and certificate. You do not need to share your private key with KeyBank. After we exchange certificates, you will use the private key to encrypt the exchange and KeyBank uses the public certificate chain to verify it. Certificate requirements: Must have a CSR and private key. Do not share the private key. Must include the root, intermediate, and leaf. File format can be *.pem, *.crt, or *.cer. Certificates cannot be self-signed. Issued by a trusted certificate authority organization like DigiCert. Only one certificate is required for all APIs. 04 Grant access KeyBank sets up your account entitlements. Entitlements authenticate your identity and contain the authorization rules for the APIs you need to access. Part of the account entitlements are the API keys. KeyBank shares the API keys needed to create an access token and make an API call. KeyBank will set you up with a test environment to start and help you get a better idea of how the API functions and how it can integrate with your application. We share the environment details to you once setup is complete. Common terms Access token A temporary token to that gives you permission to use the API. Use your API keys to generate the token. This is also known as a bearer token. API consumer: An authenticated developer portal user that has completed the onboarding process, has access to API services and possibly the KeyBank test environment. API keys: There are two sets of API keys that we privately share with you to authenticate and authorize your ability to use and access our API products. Can’t turn that engine without a key. Authentication: A method of identifying you and your application as a trusted and accepted source to exchange data. With authentication, we use your KeyBank client credentials (part of your API keys) to identify you. Authorization: A method of permitting access to certain APIs and services. Certificates: A digital exchange of several encrypted codes that verify your ability to connect with our API products safely, securely, and cautiously. These certificates typically expire annually. CSR: Certificate signing request is an encoded message that contains the information needed by the Certificate Authority (CA) to create your certificate. This can include your name, domain, organization information, or location. Domain: A human-readable name for an application or web address that identifies the name of the online application. Domain names are used to help set up web servers, communication, and other online services. IP address: The internet protocol address is a numerical label assigned to each device or application connected to the internet. Addresses can uniquely identify devices and route data to its intended destination. mTLS: Mutual Transport Layer Security is mechanism for the mutual authentication between the service provider and the client. No catfishing here. Digital certificates are exchanged and signed with the PKI framework. Onboarding: The process of helping KeyBank partners and API consumers get familiar with our suite of API products. This can include assessment, setup, and environment access. PKI: A public key infrastructure is a system to create, store, and distributes digital certificates. This framework matches the public keys to digital entities to authenticate the identity of users, devices, and services. Pre-production: A test environment that allows you try the API product using sample data. Production: KeyBank’s live environment that exchanges real proprietary data between your application and our API products. Service agreement: A contract between KeyBank and financial businesses and applications that intend to use and integrate with KeyBank’s suite of APIs. The service agreement identifies the API products allowed, data volume, and other specifics require to ensure a proper configuration of services. Using our APIs Health checks We recommend that you always start your API builds with a health check. To perform a health check, you must have valid certificates exchanged with KeyBank and API keys to request an access token. Rate limiting To ensure efficient and consistent API performance, we've placed a limit of 5 transactions per second (TPS) across all KeyBank APIs. API requests that exceed the rate limit receive an HTTP 429 response status code. If you've exceeded this limit, wait for at least 2 minutes before making another API call. While we established the 5 TPS threshold to maximize stability and performance, we understand that your consumption needs might not fit within those limits. To request an increased rate limit, contact your KeyBank Client Success Manager. X-CorrelationId The X-CorrelationId is a unique 36-digit alphanumeric identification code generated automatically for each API transaction. This field helps support teams at KeyBank quickly track down an inquiry or issue. The ID stays with the transaction so we can trace the chain of API operations in the event logs. If you see different X-CorrelationId values for the same transaction, this could indicate that duplicate requests. Request an access token KeyBank requires an OAuth 2.0 access token to authorize API calls. To make a call for a token, you must have access to our environments, your certificates, private key, and API keys. Copy and modify the cURL command template. Be sure to replace the curly brackets {{xxxx}} with your specific information. For line 1, identify the certificates. For client.crt, enter the location of your certificate signing request (CSR). The file must be in one of these formats *.pem, *.crt, or *.cer. For client.key, enter the name of your certificate’s private key file. For ca.crt, enter the name of your certificate authority (CA) certificate. For line 2, identify the host. Enter the URL address for the KeyBank environment. Make sure to add scope=rs-read as a path parameter in the URL. For line 3, enter your application credentials (consumer_key and consumer_secret) API keys in Base64 encoded format. Use a trusted site to generate an encoded string for your consumer key and secret. For line 6, enter your client credentials from KeyBank. For client id enter your client_id API key and for client password, enter the client_secret API key from KeyBank. cURL command template curl -X POST --cert {{client.crt}} --key {{client.key}} --cacert {{ca.crt}} \ ‘{{host}}/oauth/v1/token?scope=rs-read' -H 'Authorization: Basic {{base64 encoded consumer key and secret}}' -H 'Content-type: application/x-www-form-urlencoded' -H 'Accept: application/json' -d 'Id={{client id}}&Key={{client password}}&grant_type=client_credentials' Request and response example The response contains a field named access_token. Use this access token in the Authorization header when you call the API over a secure mTLS connection. If you are unable to retrieve an access code, reassess your setup, review your API keys, and make sure you are properly connected to the environment before you try again. Request Response curl -X POST --cert client.crt --key client.key --cacert ca.crt \ 'https://api.qv.keybank.com/oauth/v1/token’ -H 'Authorization: Basic KFddrcHQwQ3JDGQTamdqRUI0bEFHVVlHQcg' -H 'Content-type: application/x-www-form-urlencoded' -H 'Accept: application/json' -d 'Id=b1194a183b8e01&Key=165a15dfanqf1d60&grant_type=client_credentials' curl -X POST --cert {{client.crt}} --key {{client.key}} --cacert {{ca.crt}} \ { "refresh_token_expires_in": "0", "api_product_list": "[API 1, API 2, API 3]", "api_product_list_json": [ "API Inquiry", "API test product", ], "organization_name": "keybank-non-prod", "developer.email": "yourEmail", "token_type": "BearerToken", "issued_at": "2255448892" "client_id": "KBConsumerKey”, "access_token": "gPd4ZXMi927aoWhvmc", "application_name": "9IIa42-134320dk32s", "scope": "apiauth-read apiauth-write rs-create rs-delete rs-oauth rs-read rs-update rs-write", "Id": "KBClientId", "expires_in": "86399", "refresh_count": "0", "status": "approved" } What to expect You get a response with access token and information about which API products you can use, the refresh token time cycle, expiration time, etc. Select and copy the access_token value to use with your API requests. The access token remains valid for 24 hours. If it expires, try the refresh token to receive a new access token and pass in the API request. What's next? If this all sounds nice to you, sign up for our waitlist. Our people will reach out to your people. Read our API documentation to learn more about KeyBank’s API products. Or if you prefer to look under the hood, download an API specification file in YAML format.
Decrypting and decoding API parameters There are fields present across KeyBank APIs, in both request and response objects, that have predefined values. Some of these values are specific to KeyBank and others are industry-standard values. The purpose of this page is to catalog as many of these data values as possible and provide definitions for their usage within our APIs. Each data value definition contains a brief description, the specific fields and APIs where the data value can be found, and a tabular listing of possible values and what these values mean. Data values Field names Applicable APIs Description Addenda type codes addendaTypeCode ACH Origination, ACH Inquiry A two-digit code that defines the specific interpretation and format for the addenda information contained in the addenda record. BAI codes baiCode, amountTypeCode, derivedBaiCode,transactionCodeBAI2 ACH Inquiry, Intraday Reporting, Previous Day Reporting A BAI (Bank Administration Institute) code is a three-digit code identifying a banking transaction and are divided into balance codes and transaction codes. Change codes changeCode, nocChangeCode ACH Inquiry, Webhooks (ACH alerts) In the case of a Notification of Change (NOC), this is a three-character code beginning with the letter 'C' that indicates the information being changed. Foreign bank type codes foreignBankSystemType Wire Origination, RTP Send Payment Five-character global routing/clearing codes for payments in foreign countries. Pay subtype codes paySubType Wire Inquiry A four-digit code that corresponds to a particular wire drawdown scenario. Return reason codes returnReasonCode, retReturnReasonCode ACH Inquiry, Webhooks (ACH alerts) In the case of a returned ACH payment, this is a three-character code beginning with the letter 'R' that identify a reason an ACH payment was returned. Transaction codes transactionCode, retTranCode, tranCode ACH Inquiry, ACH Origination, Intraday Reporting, Webhooks (ACH alerts) A two-digit code identifying various types of debit and credit entries. Addenda type codes A two-digit code that defines the specific interpretation and format for the addenda information contained in the addenda record. Addenda type codes can be found in the following fields: addendaTypeCode: ACH Origination, ACH Inquiry Code Description 02 Point of Sale Entry (POS), Shared Network Transaction (SHR), or Machine Transfer Entry (MTE) 05 Corporate Credit or Debit (CCD), Customer Initiated Entries (CIE), Corporate Trade Exchange (CTX), Prearranged Payment and Deposit (PPD), Internet Initiated/Mobile Entries (WEB) 10-16 1st-7th addenda records for International ACH Transaction (IAT) 17 IAT Remittance Information addenda record 18 IAT Foreign Correspondent Bank addenda record 98 Used for Notification of Change (NOC) entries 99 Used for Return entries BAI codes A BAI (Bank Administration Institute) code is a three-digit code identifying a banking transaction and are divided into balance codes and transaction codes. BAI codes can be found in the following fields: baiCode: ACH Inquiry, Previous Day Reporting, Intraday Reporting amountTypeCode: Intraday Reporting derivedBaiCode: Intraday Reporting transactionCodeBAI2: Intraday Reporting Balance codes Code Description 010 Opening Ledger 015 Closing Ledger 040 Opening Available 045 Closing Available 072 One Day Float 074 Two or More Day Float 100 Total Credits 109 Current Day Total Lockbox Deposits 111 Lockbox Deposit - Zero Day Float 112 Lockbox Deposit - One Day Float 113 Lockbox Deposit - Two Day Float 115 Lockbox Deposit 140 Total ACH Credits 190 Total Incoming Money Transfers 400 Total Debits 450 Total ACH Debits 490 Total Outgoing Money Transfers 580 Total Controlled Disbursement Debits 584 Total Disbursements Late Amount 585 Disbursing Funding Requirement 602 Total CDA Adjustments Transaction codes Code Description 158 Real Time Payment Credit 165 Pre-authorized ACH Credit 171 Individual Loan Deposit 172 Deposit Correction 195 Incoming Money Transfer 201 Individual Automatic Transfer Credit 206 Book Transfer Credit 213 Letter of Credit 214 Foreign Exchange Credit 229 Miscellaneous International Credit 237 Individual Collection Credit 238 Collection of Dividends 244 Interest / Matured Principle Payment 252 Debit Reversal 258 ACH Reversal Credit 275 ZBA Credit 295 ATM Credit 301 Commercial Deposit 306 Fed Funds Sold 351 Individual Investment Sold 354 Interest Credit 357 Credit Adjustment 359 Interest Adjustment Credit 395 Check Reversal 398 Miscellaneous Fee Refund 399 Miscellaneous Credit 451 ACH Debit Received 455 Pre-authorized ACH Debit 458 Real Time Payment Debit 475 Check Paid 481 Individual Loan Payment 495 Outgoing Money Transfer 501 Individual Automatic Transfer Debit 506 Book Transfer Debit 512 Letter of Credit Debit 513 Letter of Credit 514 Foreign Exchange Debit 529 Miscellaneous International Debit 544 Interest / Matured Principle Payment 552 Credit Reversal 555 Deposited Item Returned 558 ACH Reversal Debit 564 Overdraft Fee 567 Return Item Fee 575 ZBA Debit 595 ATM Debit 627 Fed Funds Purchased 631 Debit Adjustment 651 Individual Investment Purchased 654 Interest Debit 659 Interest Adjustment Debit 661 Account Analysis Fee 666 Currency and Coin Shipped 690 Miscellaneous Debit 694 Deposit Reversal 695 Deposit Correction Debit 698 Miscellaneous Fees 699 Miscellaneous Debit 760 Commercial Loan Debit Change codes In the case of a Notification of Change (NOC), this is a three-character code beginning with the letter 'C' that indicates the information being changed. Change codes can be found in the following fields: changeCode: ACH Inquiry nocChangeCode: Webhooks (ACH alerts) Code Description C01 Incorrect bank account number C02 Incorrect transit/routing number C03 Incorrect transit/routing number and bank account number C04 Bank account name change C05 Incorrect transaction code C06 Incorrect bank account number and transaction code C07 Incorrect transit/routing number, bank account number, and transaction code C08 Incorrect Receiving DFI Identification (IAT only) C09 Incorrect individual identification C10 Incorrect company name C11 Incorrect company identification C12 Incorrect company name and identification C13 Addenda format error Foreign bank type codes Five-character global routing/clearing codes for payments in foreign countries. Foreign bank type codes can be found in the following field: foreignBankSystemType: Wire Origination, RTP Send Payment Code Description ATBLZ Austria AUBSB Australia CACPA Canada CHSIC Switzerland DEBLZ Germany ESNCC Spain GBDSC Great Britain HKNCC Hong Kong IENCC Ireland INFSC India ITNCC Italy NZNCC New Zealand PTNCC Portugal USABA US FedWire ZANCC South Africa Pay subtype codes A four-digit code that corresponds to a particular wire drawdown scenario. Pay subtype codes can be found in the following field: paySubType: Wire Inquiry Code Description 1031 Request for customer drawdown 1032 Transfer honoring customer drawdown request 1033 Refusal of customer drawdown request 1631 Request for bank-to-bank drawdown 1632 Transfer honoring bank-to-bank drawdown request 1633 Refusal of bank-to-bank drawdown request Return reason codes In the case of a returned ACH payment, this is a three-character code beginning with the letter 'R' that identify a reason an ACH payment was returned. Return reason codes can be found in the following fields: returnReasonCode: ACH Inquiry retReturnReasonCode: Webhooks (ACH alerts) Code Description R01 Insufficient funds - The available and/or cash reserve balance is not sufficient to cover the dollar value of the debit entry. R02 Account closed – A previously active account has been closed by action of the customer or the RDFI. R03 No account/unable to locate account – The account number structure is valid and it passes the check digit validation, but the account number does not correspond to the individual identified in the entry, or the account number designated is not an existing account. R04 Invalid account number structure – The account number structure is not valid. R05 Unauthorized debit to consumer account using corporate SEC code – CCD or CTX debit entry was transmitted to a Consumer Account of the receiver and was not authorized by the receiver. R06 Returned per ODFI’s request – The ODFI has requested that the RDFI return an erroneous entry. R07 Authorization revoked by customer – The RDFI’s customer (the receiver) revoked the authorization previously provided to the originator for this debit entry. R08 Payment stopped – The receiver has placed a stop payment order on this debit entry. R09 Uncollected funds – A sufficient ledger balance exists to satisfy the dollar value of the transaction, but the available balance is below the dollar value of the debit entry. R10 Customer advises unauthorized, improper, ineligible, or part of an incomplete transaction – The RDFI has been notified by the receiver that the entry is unauthorized, improper, ineligible, or part of an Incomplete Transaction. Transaction codes A two-digit code identifying various types of debit and credit entries. Transaction codes can be found in the following fields: transactionCode: ACH Inquiry, ACH Origination, Intraday Reporting retTranCode: Webhooks (ACH alerts) tranCode: Webhooks (ACH alerts) DDA credits Code Description 20 Reserved 21 Return or Notification of Change for original transaction code 22, 23, or 24 22 Demand credit (checking deposit) 23 Prenotification for a demand credit; death notification (non-dollar); automated enrollment entry (non-dollar) 24 Zero dollar with remittance data (for CCD, CTX, and IAT entries); acknowledgement entries (ACK and ATX entries) DDA debits Code Description 25 Reserved 26 Return or Notification of Change for original transaction code 27, 28, or 29 27 Demand debit (checking withdrawal) 28 Prenotification for a demand debit (non-dollar) 29 Zero dollar with remittance data (for CCD, CTX, and IAT entries) Savings credits Code Description 30 Reserved 31 Return or Notification of Change for original transaction code 32, 33, or 34 32 Savings credit (savings deposit) 33 Prenotification for a savings credit; death notification (non-dollar); automated enrollment entry (non-dollar) 34 Zero dollar with remittance data (for CCD, CTX, and IAT entries); acknowledgement entries (ACK and ATX entries) Savings debits Code Description 35 Reserved 36 Return or Notification of Change for original transaction code 37, 38, or 39 37 Savings debit (savings withdrawal) 38 Prenotification for a savings debit (non-dollar) 39 Zero dollar with remittance data (for CCD, CTX, and IAT entries) Loan credits Code Description 51 Return or Notification of Change for original transaction code 52, 53, or 54 52 Loan account credit 53 Prenotification for a loan account credit 54 Zero dollar with remittance data (for CCD, CTX, and IAT entries) Loan debits Code Description 55 Loan account debit (reversals only) 56 Return or Notification of Change for original transaction code 55
Key takeaways TL;DR so here are the hits: Use our ACH Origination API to make or collect authorized payments. You can also inquire on the transactions before they are officially submitted for processing. Sometimes we make mistakes. With ACH you can undo a payment typically within a period of 10 minutes from origination. Inquiring minds want to know? Monitor and report on ACH transactions that are collected, posted, or returned. Look at our Webhooks specs to learn more about automatic push notifications for ACH transactions. Try it out! Wanna check out our ACH APIs? You first need to complete the KeyBank onboarding process. Check out our Getting Started Guide. Or sign up for our waitlist and someone will contact you to learn more! Sign up ACH Origination API With the ACH Origination API, you can originate a credit or debit transaction to an authorized receiver. See the specs It’s cool if you take my money To make or collect a payment there has to be an authorized agreement between the originator and the receiver. An authorized agreement means that the payee has an agreement with their financial institution or commercial entity that funds can be exchanged between the originator and the receiver. Submit an ACH request The ACH Origination API uses only POST methods to generate new ACH transactions. In the request, you indicate if you are pushing or pulling funds and the method of authorization to transfer funds. The creditDebitCode defines the action of the request, if you are taking funds (debit) or receiving funds (credit). The secCode defines the authorized method to transfer funds, like from a corporate account, online account, by phone, etc. There is a path for each SEC code. Use the correct endpoint path and identify the secCode in the request. Some more details about SEC codes All ACH payments, credit or debit, must include a SEC code. The code is implicit in how payment authorization is arranged (by standing, written, oral, online, etc.). A SEC code also helps determine the rules and requirements that apply to the transaction, including timing of settlement and eligibility for same-day processing. KeyBank allows ACH origination payment types for the following SEC codes: CCD, CTX, PPD, TEL, and WEB. SEC Codes CCD Corporate Credit or Debit Deposits and withdrawals to corporate accounts. Does not require individual consumer authorization for each payment. Remittance information available with the transaction as an addendum record. CTX Corporate Trade Exchange One business pays another for goods or services. An electronic payment that includes an invoice (addenda) intended for the receiving financial institution. PPD Prearranged Payments and Deposits Specify a certain amount to be transferred from one financial account to another. Requires consumer authorization or prearrangement for the payment or deposit to occur. Some examples are direct deposit of payroll, pension, and dividends, or payment of utility bills, mortgages, rent, membership dues, loans and other recurring payments. TEL Telephone Send a payment via the telephone. Must provide verbal consent during the phone call to initiate the payment transaction. WEB Online Initiate a transaction through the web or online banking. Requires consumer authorization for the payment or deposit to occur. Nacha business, not your problem With ACH, transaction processing happens in real-time while the file processing for Nacha occurs behind the scenes. We follow Nacha standards and recommend there are no more than 100 transactions per request. The Nacha file format is the standard file format used for ACH electronic fund transfers (EFT) in the United States. Nacha stands for National Automated Clearing House Association, the organization responsible for managing the rules and regulations governing the ACH network in the US. The Nacha file format is used to create batch files that contain multiple transactions, like direct deposits, bill payments, and other types of electronic payments. These files are commonly used by businesses, financial institutions, and other organizations to initiate and process ACH transactions. Addenda records An addendum is an ACH record type that carries supplemental data like remittance information. This data may be needed to identify an electronic payment to the receiving financial institution and the payee, or it may contain additional information relating to the prior entry detail record. This addenda record is optional. It is primarily used for business-to-business transactions, like CCD and CTX. Addenda record settings and limitations: CCD, PPD, and WEB payment transactions can have one addenda record. The addenda record displays as one line, not to exceed the 88-character limit. A CTX payment transaction can have multiple addenda records, up to 9,999 records to be exact. KeyBank does not allow more than 20 addenda records per request. If you need additional records, there is a different request available to add addenda records and that endpoint is limited to 100 records per request. To manage the status of the addenda records, our system tracks it for the entire business day. The status changes from Waiting to Completed, indicating that the addenda records were successfully received, and the ACH transaction is ready to be processed. Same-day ACH funds Same-day ACH transactions are when the receiving depository financial institution (RDFI) posts the credit or debit to the payee account on the same day the transaction originated. Same-day ACH transactions cannot exceed a set maximum dollar amount per day. Typically, the total same-day ACH transactions cannot exceed $100,000 in a single business day. This is an automatic setting for our clients. If you do not want the default option of same-day ACH transactions, you can choose to opt out. There is a surcharge for same-day transactions. For the ACH Origination API, there are cutoff times for the ACH transaction to be posted the same day it originated: Same-day Time Schedule SAME-DAY FLOW Window 1 Window 2 Window 3 Client cutoff 09:15 a.m. (EST) 11:15 a.m. (EST) 03:00 p.m. (EST) File sent from KeyBank to the ACH operator 09:30 a.m. (EST) 11:30 a.m. (EST) 03:45 p.m. (EST) ACH transaction to RDFI 12:00 p.m. (local) 04:00 p.m. (local) 05:30 p.m. (local) Posted to payee account 01:30 p.m. (local) 05:00 p.m. (local) RDFI end of day Did you know? With the ACH Origination API, you can inquire on the transactions before they are officially submitted for processing. The status endpoint tells you if the transaction was accepted (transaction request data is valid), rejected (there is missing or erroneous data in the request), or extracted (transaction received by the ACH core processing system). Common terms ACH operator The central clearing facility managed by the Federal Reserve Bank. ACH processor The ACH core processing system takes the incoming transactions from the originating financial institution, which are then sorted, batched, and verified. After the transaction is legitimized, the funds are forwarded to the receiver’s financial institution. Collected The status when the originating transaction is received by the ACH processor. Credit To push funds to other accounts. Debit To pull funds from an account. ODFI Origination Depository Financial Institution is the financial institution of the originator. This ODFI has an active relationship with ACH services and sends transactions to the ACH network on behalf of the originator. Originator The company or business that initiates a credit (payment) transaction to the receiver (payee). Before a transaction can be sent, the originator has authorized the receiver to credit or debit their account. PAR number Payment Assigned Reference number is a unique identifier assigned by the ACH processor used to identify the transaction without exposing any sensitive consumer identification information. When you submit a request with the ACH Origination API, it creates a PAR number and returns the value in the response. Posted The status when a transaction is received by the ACH processor, reviewed by the ACH operator, and currently with core banking applications to secure and transfer funds. It could also indicate that the funds have been completely settled between originator and receiver. RDFI Receiving Depository Financial Institution is the financial institution of the receiver. The ACH operator processes the transactions and sends the funds to the financial institution before the money is posted to the receiver's account. Receiver The individual or company that receives the funds. Before a transaction can be received, the receiver has authorized the originator to credit or debit their account. The receiver may also be referred to as the payee. Returned The status when a transaction is reviewed by the ACH operator and the transaction is not cleared for transfer for reasons like insufficient funds or erroneous data. Reversed Cancel a payment after it has reached the ACH operator but not yet settled funds. Trace number The trace number is a unique identifier for an ACH transaction generated by the ACH Origination API. Use this number for your ACH Inquiry API requests. Undo Stop a transaction before it is received by the ACH processor. This window is typically 10 minutes in length. ACH Inquiry API With the ACH Inquiry API, you can check on the progress of a payment transaction after the ACH processor receives them. There is a status call for general inquiry and three additional endpoints that provide detailed information for each stage of an ACH transaction - collected, returned, and posted. See the specs Important identifiers that are good to know Use the PAR number or trace number from the ACH Origination transaction request to inquire about the status of a transaction before it is posted. Use the KeyBank originator account number associated with ACH transaction to inquire about transactions that are posted. PAR number The PAR (Payment Assigned Reference) number is a unique identifier assigned by the ACH processor after you submit a request with the ACH Origination API. This is used to identify the transaction without exposing any sensitive consumer identification information. Use the PAR number as an ACH Inquiry API request parameter to inquire about the unique transaction identifier. You can use the parNumber to inquire about ACH transactions with the following ACH Inquiry API endpoints: ACH Status ACH Collected ACH Returns Trace number The trace number is a unique identifier for an ACH transaction generated assigned by the ACH processor after you submit a request with the ACH Origination API. The trace number is useful for the transaction inquiries and traceability. Save this trace number if you intend to check on the progress of the ACH transaction. To get the status of multiple transactions with either identifying number, separate the numbers with a comma. You can use the traceNumber to inquire about ACH transactions with the following ACH Inquiry API endpoints: ACH Status ACH Collected In the table below we associate each endpoint in the ACH Inquiry API with the key identifiers you can use to request the status of an ACH transaction. Identifier by ACH status ENDPOINT IDENTIFIER EXAMPLE ACH Status /accounts/transactions/v1/ACHStatusInquiry/list traceNumber: 021300012341234 parNumber: 1234567891113 ACH Collected /accounts/transactions/v1/collectedACHtransactions/list ACH Returned /accounts/transactions/v1/returnACHtransactions/list parNumber: 1234567891113 ACH Posted /accounts/transactions/v1/postedACHtransactions/list accountNumber: 321234567890 A good reminder... We recommend that you check on the status after 06:00 a.m. EST the following business day. By this time, the ACH processor has run the batch and consolidation processes. ACH Status Inquiry Your ACH inquiry should begin with the ACH Status Inquiry or ACH Collected Inquiry endpoints. The ACH Status Inquiry endpoint provides a status along with a reduced subset of data. Request and response example If you have originated an ACH transaction, utilize the accountNumber and traceNumber fields in your request. The traceNumber is a key field returned from the ACH Origination API. If you are inquiring about an ACH transaction, utilize parNumber, accountNumber, and traceNumber fields in your request. The parNumber could be a better choice in this situation depending on the available data. Request { "getACHStatusInquiryRequest": { "accountNumber": ["32123456789"], "parNumber": ["23074005623452"], "traceNumber": ["041001034453247"], "startRowIndex": "1", "endRowIndex": "1000"} } Response "ACHStatus": "COLLECTED", "ACHCollectedTransaction": { "transactionParNumber": "23074005623452", "transactionCode": "22", "transactionAmount": "712.54", "creditOrDebitCode": "C", "receivingAccountNumber": "32123456789", "receivingCompanyName": "KINNEY DRUGS #11", "originatingAccountNumber": "45987654321", "originatingCompanyName": "COMPANY,LLC", "nachaSecCode": "CCD", "traceNumber": "041001034453247", "transactionDescription": "DCSETL0315"} What to expect In the response, you can expect to see a status of Collected or Returned. If you get the Collected status, use the ACH Collected endpoint for more details. If you get the Returned status, use the ACH Returns endpoint next. The parNumber returns in the response. This is a key field to inquire with the ACH Returns endpoint. ACH Collected Inquiry The ACH Collected inquiry endpoint has all the available data elements at the time an ACH transaction is collected. Request and response example The request field recommendation for the ACH Collected inquiry is similar to the ACH Status Inquiry request. One of the fields or a combination will result in a response with details for a specific item. For originators, utilize the accountNumber and traceNumber fields in your request. The traceNumber is a key field returned from the ACH Origination API. For receivers, utilize accountNumber and traceNumber fields in your request. You could also use the parNumber as it could be a better choice depending on the available data. To further filter your results, use the date range fields (fromDate, toDate), amount range (fromAmount, toAmount), and pagination controls (startRowIndex, endRowIndex). Request { "getACHCollectedTransactionsRequest": { "accountNumber": [ "3212345689" ], "fromDate": "2023-09-18", "toDate": "2023-09-30", "sourceTransactionSettledDate": "", "creditOrDebitCode": "", "fromAmount": "", "toAmount": "", "traceNumber": "", "parNumber": "23268007704844", "startRowIndex": "1", "endRowIndex": "1000" } } Response "ACHCollectedTransaction": [ { "transactionParNumber": "23268007704844", "sourceBankNumber": "0101", "sourceAccountNumber": "32123456889", "transactionCodeDescription": "Automated Payment", "transactionFlowTypeDescription": "Outbound", "transactionAmount": "0.03", "transactionDescription": "ST10021702", "creditOrDebitCode": "D", "sourceTransactionProcessDate": "2023-09-25", "sourceTransactionSettledDate": "2023-09-25", "sourceTransactionPostDate": "2023-09-25", "receivingAccountNumber": "32123456889", "receivingCompanyName": "COMPANY INC", "originatingAccountNumber": "45987654321", "originatingCompanyName": "ABC COMPANY", "nachaSecCode": "WEB", ...ect. What to expect In the response, you can expect 50-100 data elements for each transaction. This includes the parNumber which is an essential field for the ACH Returns Inquiry endpoint. The traceNumber also returns in the response which can be used in the ACH Status Inquiry endpoint. ACH Returns Inquiry ACH Returns are made available during our end-of-day processes and can be inquired upon at approximately 01:00 a.m. EST for the previous business day. Request and response example To inquire about one or more transactions, use the accountNumber and date range fields (fromDate, toDate) to look up information. To look up a specific returned transaction, use the parNumber returned in the ACH Status Inquiry and ACH Collected endpoints. It is a unique identifier that matches the returned transaction to the original Collected transaction. Request { "getACHReturnTransactionsRequest": { "accountNumber": ["359681604732"], "fromDate": "2022-07-26", "toDate": "2022-07-30", "creditOrDebitCode": "", "fromAmount": "", "toAmount": "", "parNumber": "22202011366290", "startRowIndex": "1", "endRowIndex": "10" } } Response "ACHReturnTransaction": [ { "returnTransactionParNumber": "22207010038422", "sourceAccountNumber": "359681604732", "snapshotDate": "2022-07-27", "originalACHTransactionParNumber": "22202011366290", "originalTransactionProcessDate": "2022-07-21", "originatingReceiverDescription": "Originating Return", "transactionCode": "26", "transactionCodeDescription": "Automated Return", "transactionFlowTypeDescription": "Outbound", "transactionAmount": "181.98", "transactionDescription1": "PYMNT", "transactionDescription2": "S", "creditOrDebitCode": "D", "sourceTransactionCreatedDate": "2022-07-21", "sourceTransactionProcessDate": "2022-07-21", "sourceTransactionSettledDate": "2022-07-22", "receivingAccountNumber": "2133478", "receivingCompanyName": "Joann Cockrell", "originatingAccountNumber": "359681604732", "returnReleaseDate": "2022-07-26", "returnReasonCode": "R07", "returnReasonDescription": "Authorization Revoked", "nachaSecCode": "PPD", "traceId": "041001030038422", ...ect. What to expect The ACH Returns Inquiry endpoint response includes 50+ data elements detailing the returned item along with transaction details from the collection of the item. The response includes the original parNumber and traceNumber values. ACH Posted Inquiry A transaction received for processing is considered Posted to the receivers account once it completes processing through all participants in the ACH network like the ODFI and RFDI. Request and response example The transaction availability is based on the effective date (effectiveDate) provided in the ACH Origination API request. There is no association between the ACH Posted inquiry endpoint and the ACH Status Inquiry or ACH Collected Inquiry endpoints at the individual item level. You cannot use the parNumber or traceNumber associated with the ACH Status Inquiry or ACH Collected Inquiry endpoints in the ACH Posted inquiry. Request { "getACHPostedTransactionsRequest": { "accountNumber": ["32123456789"], "fromDate": "2023-03-15", "toDate": "2023-03-15", "creditOrDebitCode": "", "fromAmount": "", "toAmount": "", "parNumber": "", "startRowIndex": "1", "endRowIndex": "1" } } Response "ACHPostedTransaction": [ { "snapshotDate": "2023-03-15", "processDate": "2023-03-15", "sourceAccountNumber": "32123456789", "transactionParNumber": "23072003214013", "transactionAmount": "2078.09", "creditOrDebitCode": "C", "baiCode": "165", "transactionCode": "22", "regulationDescription1": "DIRECT DEPOSIT ", "regulationDescription2": "ABC COMPANY", "postingWindow": "0600"}] What to expect The ACH Posted endpoint returns results for a client at the account posting level. All results for the ACH origination transactions display at the batch level. The batch level summary ACH transaction details that are returned look as how you see them on the DDA statement or in KeyNavigator. Moonwalk back those transactions We all make mistakes. Sometimes we need to pull things back before we can move forward. KeyBank understands and our API Origination API has a few ways to do that. Undo a payment You can undo a payment before it is collected by the ACH processor. Use the undo endpoint to stop the transaction before it is received by the ACH processor. The time window to undo is dependent upon the collection windows. The typical window to undo a payment is about 10 minutes but it can be more depending on when the payment is submitted and the collection schedule. Reverse a payment If the payment was collected and you still need to delete the payment, you can reverse the transaction within five banking days from the original effective date. When you reverse the transaction, it generates a reversal to the receiver’s account to pull back payments that were originated erroneously. While reversals are not a guaranteed success, it is an option to undo the original payment submitted after collection. You must submit the file maintenance form for a payment reversal. If you are a client of the ACH Origination API, Key Bank recommends the following guidelines for reversing a transaction: Complete an ACH Originate API request with the opposite credit or debit indicator in the creditDebitCode field of the request body. Update the companyEntryDescription in the request body to reflect REVERSAL. Returned transactions A payment can be returned for various reasons like insufficient funds, unable to verify accounts, incorrect data in the request, or a security concern. KeyBank recommends that you inquire about returns daily with the ACH Inquiry API. Here’s how: To inquire about one or more transactions, use the account number and date fields to look up information. To look up a specific returned transaction, use the PAR number. The PAR number is generated by the API and provided in the response. It is a unique identifier that matches the returned transaction to the original transaction. Unauthorized returns Unauthorized returns apply mainly to disputed transactions where the person or company being charged does not consent to the funds transfer. There are different return time frames by SEC code so consider the exposure to unauthorized returns when you originate a payment with a certain SEC code. As the originator, if you are debiting an account to collect payments, use the CCD or CTX SEC code. PPD transactions have a longer window for unauthorized returns than CCD and CTX. Unauthorized Return Windows Consumer transactions Commercial transactions SEC code PPD, TEL, WEB CCD, CTX Unauthorized returns window up to 60 calendar days 24 hours (two banking days) Gets the facts with FAQs Does ACH stand for Actual Common Help? It sure doesn’t, but we can answer some questions for you! Where is my transaction? How can I get more information? You submitted a request with the ACH Origination API to send or get money. Get the traceNumber or parNumber from the ACH Origination API response and use that identifier with the ACH Inquiry API request to track the status of the ACH transaction (or batch of transactions). See our information on the ACH Inquiry API to learn more. I got an error. What went wrong? Everything went wrong. And you forgot to send that birthday card too! OK, it’s not that serious. We can’t fix the birthday card situation, but we can help with that API error. Check out more information in Errors section of the API documentation for the ACH Origination API or the ACH Inquiry API. What’s the difference between undo, reversal, and returned? When you undo a transaction, you stop the ACH processor from receiving the request before the collection window. For example, let’s say there is a 10-minute window to undo a payment before it is received by the ACH processor. You submit a transaction with the API at 08:15 a.m. EST. You have until 08:25 a.m. EST to undo this transaction before the ACH processor begins to the process the transaction. When you reverse a transaction, you missed the window to undo a request and now need to submit the file maintenance form for a payment reversal. When a transaction is returned, it means that something was not right when going through core banking applications for review and settlement. The transaction is returned to the originator without ever being posted. CCD and PPD seem similar. What is the difference? PPD transactions are typically from a corporate account to an individual account. Like if you are sending payroll to your employees, you are sending money from a corporate account to a personal account of the employee. CCD transactions are usually from one commercial or business account to another. It could also be an individual account sending money to a vendor account. One example could be a renter (individual account) sending their rent check to the property management office (business account). Is there a way to input a value in the request that I recall when using the ACH Inquiry API? There are two fields available to attached additional information to a transaction. The entry description (companyEntryDescripiton) describes the purpose of the payment as defined by you. This is required for reporting and helps identify any differences between the transactions. This information is visible to the originator and the receiver. Use the custom data (customData) field to append specific information to a payment transaction. This information is only visible to the originator can be recalled by the originator after a payment is collected. The custom data does not transmit with the payment as it is processed. The custom data is safely stored in KeyBank’s database. The traceNumber links the incoming collected or posted payment to the custom data, recalled from the request input. What is the timing with payments? ACH transactions are collected/distributed several times throughout the day. KeyBank’s final cutoff time for clients to send us an ACH file is 09:00 p.m. EST. The schedule is as follows: ACH collection schedule # ACH transmission Time (EST) 1 Collection/Distribution 06:00 a.m. 2 Collection 09:30 a.m. 3 Collection/Distribution 11:30 a.m. 4 Collection 02:00 p.m. 5 Collection/Distribution 04:30 p.m. 6 Collection/Distribution 07:00 p.m. 7 Collection/Distribution 09:00 p.m. Can I do same-day payment? For an additional fee, you can make same-day payments until approximately 03:00 p.m. EST. Funds are withdrawn the date the payment is processed and delivered by the following business day. The account’s available balance is updated when the payment is processed. The account ledger is updated the day after the payment is sent. What about future date payments? You can future date a transaction. The payment transaction is processed as normal and collected, but the payment does not post to the bank until the date specified. Use effectiveDate in the request to specify when a collected transaction is posted. The effective date can be up to 30 days in the future. Typically, the effective date is set 1-2 days before it is posted. When setting the effective date, consider the schedule for collection windows and supporting processes. Is there a limit to how many transactions I can send in a single request? The ACH Origination API request is limited to 100 transactions per request for each of KeyBank’s clients. For each of the requests submitted, the clients will receive a message acknowledging either a successful transaction or a transaction error. Is there a limit to how much money I can send in a same-day transaction? Total same-day ACH payments cannot exceed $100,000 in a single business day. Are there client requirements I should know about? There are some required fields to initiate an ACH transaction. After you complete the KeyBank onboarding process, we will assign you values for point and collection application ID parameters that map to a legitimate bank account. Point (point) is a short name specific to your company that’s assigned by KeyBank. The point name is nine characters long, but KeyBank limits the assigned name to eight characters. One character is used to match the input data of the request associated with this point value to the shared services payment system before batch processing. The point value is included in the file name and improves security for file transfers. Collection application ID (collectionApplicationId) is a sub-level to the point value assigned by KeyBank. Every point requires at least one collection application identifier. The ID must not exceed 9 characters. If you have different settlement accounts, you'll need multiple collection application IDs, each connected to a specific settlement account. There is another important parameter that is not required, but strongly encouraged. The universal unique identifier (uuid) is a custom value used to identify each transaction created by you. The UUID is required to undo a payment. The ID must not exceed 45 alphanumeric characters. The UUID is only part of the ACH Originate API and is not used to trace a transaction across its lifecycle, meaning it cannot be used as a lookup field in the ACH Inquiry API. The UUID is at the transaction level and provides the status of a specific transaction as Accepted, Waiting for Addenda, Consolidated, or Failed. How do I send a prenote versus a live transaction? A prenote (or as my grandfather calls it formerly - the prenotification entry) is a non-monetary entry submitted by an originator to an RDFI before sending a credit or debit entry to the receiver’s account with the RDFI. A live transaction is a monetary entry submitted by an originator to a RDFI to send a credit or debit to the receiver’s account with the RDFI. Word soup, right? Basically, a prenote is a notification the tells the RDFI to verify the account information. A live transaction is an actual payment. In the request, define if the transaction is a prenote (P) or a live (L) transaction with the transactionType field. What's next Look at our API reference and specs to get the details about how our API is structured and any API requirements. ACH Origination API ACH Inquiry API Webhooks If you want to use our APIs, you need to be an authenticated and authorized user with our developer portal. Check out our Getting Started Guide.
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: 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. 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
Transfer money by wire for urgent payments or large volume transactions Wire Origination API Endpoints What you can do Endpoint Health check get /rtp/v1/payment/healthCheck Get the status with the transaction ID get /rtp/v1/payment/status/transactionId/{transactionId} Get the status with the request reference number get /rtp/v1/payment/status/debitAccount/{debitAccount}/reference/{reference} Send a wire transfer post /rtp/v1/payment/initiate Perform validation checks post /rtp/v1/payment/validate Before you begin All KeyBank APIs require certificates, user credentials, and certain permissions. Check out our Getting Started Guide to learn more. Two in one At KeyBank, the RTP and wire payment APIs are a single API product with two service capabilities. You need specific permissions to access either the RTP Send Payment API or the Wires Origination API. Overview Wire transfers are great for urgent payments and suitable for large volume transactions. Use the Wire Origination API for urgent or time-sensitive transactions, such as large business payments or real estate transactions. Wire transfers move money from one bank account to another. KeyBank transfers your funds using the secure SWIFT (Society for Worldwide Interbank Financial Telecommunication) system and Fedwire Clearing House. Through our secure network, wire transfers typically involve a processing time that can vary from a few hours to several business days depending on factors such as banks involved and any other intermediary institutions. Banks typically initiate and process wire transfers to provide a direct and expedited method of transferring funds. Usually, wire transfers involve a fee per transmission which can vary depending on the banks involved and the currency used. The main difference between RTP payments and wire transfers is in their speed and settlement process. RTP payments are designed for real-time transfers, providing immediate availability of funds, while wire transfers may take longer to process and settle. Payment chain parties The two calls - initiate a payment and validate a payment - have the party object. This is a reusable object that has details about the person or entity sending a payment and the one receiving the payment. The party object reflects the payment chain of events. Use the request fields to direct the payment transaction from one account to another. ORDER PAYMENT CHAIN REQUEST FIELDS TO USE 1 The individual or organization sends the payment. Enter the debit account number of the individual or organization in debitParty. 2 The financial institution of the debit account holder transfers the funds. We assume this is KeyBank. Enter the ABA or routing number for the financial institution in debitPartyBank. 3 The financial institution that services the recipient’s account receives the funds. Enter the US ABA number for the financial institution in creditPartyBank. 4 The beneficiary party receives the funds. Enter the account number of the beneficiary in creditParty. API requirements KeyClientId: When you initiate or validate a payment, you are required to provide the KeyClientId in the request header. The KeyClientId is a 32-character string provided by KeyBank during the onboarding process. This field is not the same as your client credentials (part of your API keys needed to obtain an access token). Psst...pass this note Want to apply a custom message or tags to your transaction? The custom data feature is available when you send or validate a payment. Define the custom data in the request payload. Learn more about our custom data feature here. Health check get /rtp/v1/payment/healthCheck Verify you can connect to the API service. A bearer token is required. Responses Successful response NAME TYPE DESCRIPTION Statusoptional string The status of the health check response. Sourceoptional string The system that produces the health response. The origin of the response can be 'Gateway' or 'Roundtrip.' Roundtrip returns a response from the farthest system involved. Timestampoptional string The date (YYYY-MM-DD) and time (HH:MM:SS) of response from the API service. ClientIpoptional string The client IP address the gateway receives from the request. X-Forwarded-Foroptional string The sequence of the IP addresses for systems between the client and the gateway. Addresses are separated by a comma. Response example (200) { "Status": "Ok", "Source": "Roundtrip", "Timestamp": "2022-09-16T02:36:20", "ClientIp": "156.77.111.28", "X-Forwarded-For": "[156.77.111.28]" } Get the status with the transaction ID get /rtp/v1/payment/status/transactionId/{transactionId} Get the status of a wire transfer. With GET methods, use a cURL command to generate your request. Select Copy code for easy copy and paste into your command line. Modify the required fields with your information. Request header FIELD TYPE DESCRIPTION KeyClientIdoptional string This value is provided by KeyBank during onboarding and is different from your client credentials. This is required for each call for RTP or Wire transactions. path FIELD TYPE DESCRIPTION transactionIdrequired string The unique ID number associated with the original payment request. Request example curl --location: 'https://partner-api-qv.keybank.com/rtp/v1/payment/status/transactionId/test123321' --header 'KeyClientId: testwUhSQADUD4DwYyZz2hZkwLqsoFGK' --header 'Accept: application/json' --header 'Authorization: Bearer testZcKJDWnwDWmmf9qah6PJvPy8' Responses Successful response NAME TYPE DESCRIPTION statusrequired Object paymentStatus transactionIdoptional string The unique ID number associated with the original payment request. requestReferenceoptional string A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters. sendersReferenceoptional string A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters. receiversReferenceoptional string A reference value for the beneficiary. This value cannot exceed 140 characters. debitAccountNumberoptional string Debit account number creditAccountNumberoptional string Credit account number valueDateoptional string The date (YYYY-MM-DD) the transfer occurred. transferAmountoptional integer Amount of money to transfer in the correct currency format. transferCurrencyoptional string Currency code for the transfer amount. erroroptional Object paymentError doddFrankoptional Object noYesType clearingSystemReferenceoptional string Enter a reference value for the beneficiary. This value cannot exceed 140 characters. Response example (200) { "status": "COMPLETED", "transactionId": "US21052400000000", "requestReference": "RR-KEY-999999-01", "sendersReference": "SR-KEY-999999-01", "receiversReference": "INVC0054321", "debitAccountNumber": "12345", "creditAccountNumber": "987654321", "valueDate": "2023-05-08", "transferAmount": 10, "transferCurrency": "USD", "doddFrank": "NO" } Missing data in the request NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (400) { "ErrorMessage": "Error received from backend service.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "US21052400000000", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "status": "FAILED", "transactionId": "rrt-770941720727587-2383364-1", "requestReference": "RR-220818-01", "sendersReference": "SR-220818-01", "valueDate": 1683676800, "error": { "code": "KEY-1006", "title": "Required field missing", "description": "The object creditPartyBank is required in the request." } } } Received request is unauthorized NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (401) { "ErrorMessage": "Error received from backend service.", "TransactionId": "rrt-621075741872460927-c-gce-9129-15867185-4", "X-CorrelationId": "80457bcb-2c3b-8c55-8cd6-3520c3157e8f", "TransactionTime": "2022-04-04T11:41:13.754Z", "ServiceError": { "status": "ERROR", "transactionId": "rrt-621075741872460927", "requestReference": "REQUEST-REF-220314.1", "sendersReference": "SENDER-REF-220314.1", "valueDate": "06-10-2023", "error": { "code": "KEY-0006", "title": "Not authorized for requested service", "description": "Check your credentials." }, "doddFrank": "NO" } } Request is forbidden to access the resource NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (403) { "ErrorMessage": "Access to requested resource is forbidden.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" } Requested resource is not found NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (404) { "ErrorMessage": "Requested resource is not found, please verify the resource and resubmit the request.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" } Requested method is not allowed NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (405) { "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" } Requested unsupported media type NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (415) { "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" } Too many requests received NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (429) { "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" } Internal server error NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (500) { "ErrorMessage": "Error received from backend service.", "TransactionId": "359681587523_SR-RMC-210729-11081", "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688", "TransactionTime": "2022-04-05T07:59:15.422Z", "ServiceError": { "status": "ERROR", "transactionId": "rrt-621075741872460927", "requestReference": "REQUEST-REF-220314.1", "sendersReference": "SENDER-REF-220314.1", "valueDate": "06-10-2023", "error": { "code": "KEY-9999", "title": "Unknown error", "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials." }, "doddFrank": "NO" } } Bad Gateway NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (502) { "ErrorMessage": "Error received from backend service", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ConnectError": "Connectivity error occurred with the downstream service (unexpected EOF at target). Please check with application support team before resubmitting the request" } } Service Unavailable NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (503) { "ErrorMessage": "Error received from backend service.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request." } } Gateway timeout NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (504) { "ErrorMessage": "Your request took too long to process. Please try again.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ConnectError": "Request could not be processed on time (gateway timeout). Please wait a moment and resubmit the request." } } Get the status with the request reference number get /rtp/v1/payment/status/debitAccount/{debitAccount}/reference/{reference} Get the status of a payment with the debit account number of the payment originator and the request reference number. This call is typically used for troubleshooting an issue with timing or a technical error with a payment transaction. You can assign a request reference number when you initiate or validate a payment. This number is metadata for backend traceability and is not sent with the payment. Use this number with the debit account number for the originating payment. The account number and request reference number must be unique; you cannot use the same request reference number for different transactions. With GET methods, use a cURL command to generate your request. Select Copy code for easy copy and paste into your command line. Modify the required fields with your information. Request header FIELD TYPE DESCRIPTION KeyClientIdoptional string This value is provided by KeyBank during onboarding and is different from your client credentials. This is required for each call for RTP or Wire transactions. path FIELD TYPE DESCRIPTION debitAccountrequired string The debit account number of the originator. referencerequired string The unique request reference number from the original payment request. Request example curl --location: 'https://partner-api-qv.keybank.com/rtp/v1/payment/status/debitAccount/12345/reference/RR-KEY-999999-01' --header 'KeyClientId: testwUhSQADUD4DwYyZz2hZkwLqsoFGK' --header 'Accept: application/json' --header 'Authorization: Bearer testZcKJDWnwDWmmf9qah6PJvPy8' Responses Successful response NAME TYPE DESCRIPTION statusrequired Object paymentStatus transactionIdoptional string The unique ID number associated with the original payment request. requestReferenceoptional string A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters. sendersReferenceoptional string A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters. receiversReferenceoptional string A reference value for the beneficiary. This value cannot exceed 140 characters. debitAccountNumberoptional string Debit account number creditAccountNumberoptional string Credit account number valueDateoptional string The date (YYYY-MM-DD) the transfer occurred. transferAmountoptional integer Amount of money to transfer in the correct currency format. transferCurrencyoptional string Currency code for the transfer amount. erroroptional Object paymentError doddFrankoptional Object noYesType clearingSystemReferenceoptional string Enter a reference value for the beneficiary. This value cannot exceed 140 characters. Response example (200) { "status": "COMPLETED", "transactionId": "US21052400000000", "requestReference": "RR-KEY-999999-01", "sendersReference": "SR-KEY-999999-01", "receiversReference": "INVC0054321", "debitAccountNumber": "12345", "creditAccountNumber": "987654321", "valueDate": "2023-05-08", "transferAmount": 10, "transferCurrency": "USD", "doddFrank": "NO" } Missing data in the request NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (400) { "ErrorMessage": "Error received from backend service.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "US21052400000000", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "status": "FAILED", "transactionId": "rrt-770941720727587-2383364-1", "requestReference": "RR-220818-01", "sendersReference": "SR-220818-01", "valueDate": 1683676800, "error": { "code": "KEY-1006", "title": "Required field missing", "description": "The object creditPartyBank is required in the request." } } } Received request is unauthorized NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (401) { "ErrorMessage": "Error received from backend service.", "TransactionId": "rrt-621075741872460927-c-gce-9129-15867185-4", "X-CorrelationId": "80457bcb-2c3b-8c55-8cd6-3520c3157e8f", "TransactionTime": "2022-04-04T11:41:13.754Z", "ServiceError": { "status": "ERROR", "transactionId": "rrt-621075741872460927", "requestReference": "REQUEST-REF-220314.1", "sendersReference": "SENDER-REF-220314.1", "valueDate": "06-10-2023", "error": { "code": "KEY-0006", "title": "Not authorized for requested service", "description": "Check your credentials." }, "doddFrank": "NO" } } Request is forbidden to access the resource NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (403) { "ErrorMessage": "Access to requested resource is forbidden.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" } Requested resource is not found NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (404) { "ErrorMessage": "Requested resource is not found, please verify the resource and resubmit the request.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" } Requested method is not allowed NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (405) { "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" } Requested unsupported media type NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (415) { "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" } Too many requests received NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (429) { "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" } Internal server error NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (500) { "ErrorMessage": "Error received from backend service", "TransactionId": "359681587523_SR-RMC-210729-11081", "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688", "TransactionTime": "2022-04-05T07:59:15.422Z", "ServiceError": { "status": "ERROR", "transactionId": "rrt-621075741872460927", "requestReference": "REQUEST-REF-220314.1", "sendersReference": "SENDER-REF-220314.1", "valueDate": "06-10-2023", "error": { "code": "KEY-9999", "title": "Unknown error", "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials." }, "doddFrank": "NO" } } Bad Gateway NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (502) { "ErrorMessage": "Error received from backend service", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ConnectError": "Connectivity error occurred with the downstream service (unexpected EOF at target). Please check with application support team before resubmitting the request" } } Service Unavailable NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (503) { "ErrorMessage": "Error received from backend service.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request." } } Gateway timeout NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (504) { "ErrorMessage": "Error received from backend service", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ConnectError": "Request could not be processed on time (gateway timeout). Please wait a moment and resubmit the request." } } Send a real-time payment or a wire transfer post /rtp/v1/payment/initiate Send a wire transfer. Use the requestedService parameter to define the transaction as Wire. With the party object, you can define the receiver as an individual, corporation, or financial institution in the payment chain. Request header FIELD TYPE DESCRIPTION KeyClientIdrequired string This value is provided by KeyBank during onboarding and is different from your client credentials. This is required for each call for RTP or Wire transactions. BODY FIELD TYPE DESCRIPTION requestedServicerequired string The type of payment transaction. The transaction request is valid only for the API products with granted access. Valid values: RTP, WIRE requestReferencerequired string A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters. typerequired string Indicates if the transaction type is a PAYMENT or a DRAFT. requestedValueDaterequired string Date (YYYY-MM-DD) the transfer will occur. originatorReferenceoptional string An additional reference value that is meaningful to the party originating the payment. sendersReferencerequired string A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters. receiversReferenceoptional string A reference value for the beneficiary. This value cannot exceed 140 characters. bankToBankInstructionsoptional string Area to share messages or instructions from one bank to another bank. ultimateDebitPartyoptional Object ultParty debitPartyrequired Object party debitPartyBankoptional Object party intermediaryBank1optional Object party intermediaryBank2optional Object party intermediaryBank3optional Object party creditPartyBankrequired Object party creditPartyrequired Object party transferAmountrequired number Amount of money to transfer in the correct currency format. transferCurrencyrequired string Currency code for the transfer amount. externalTemplateNameoptional string TBD customDataoptional string The values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle. Request example { "requestedService": "WIRE", "requestReference": "AZX01234567891011", "type": "PAYMENT", "sendersReference": "INVC0012345", "receiversReference": "INVC0054321", "requestedValueDate": 1621814400, "debitParty": { "name": "YOUR COMPANY NAME HERE", "accountNumber": "001122334455" }, "creditPartyBank": { "name": "BENEFICIARY BANK NAME", "aba": "000000000" }, "creditParty": { "name": "BENEFICIARY NAME", "accountNumber": "987654321", "postalAddress": { "adrLine": [ "BENEFICIARY ADDRESS LINE 1", "BENEFICIARY ADDRESS LINE 2" ] } }, "transferAmount": 10, "transferCurrency": "USD" } Responses Successful response NAME TYPE DESCRIPTION statusrequired Object paymentStatus transactionIdoptional string The unique ID number associated with the original payment request. requestReferenceoptional string A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters. sendersReferenceoptional string A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters. receiversReferenceoptional string A reference value for the beneficiary. This value cannot exceed 140 characters. debitAccountNumberoptional string Debit account number creditAccountNumberoptional string Credit account number valueDateoptional string The date (YYYY-MM-DD) the transfer occurred. transferAmountoptional integer Amount of money to transfer in the correct currency format. transferCurrencyoptional string Currency code for the transfer amount. erroroptional Object paymentError doddFrankoptional Object noYesType clearingSystemReferenceoptional string Enter a reference value for the beneficiary. This value cannot exceed 140 characters. Response example (200) { "status": "IN_PROCESS", "transactionId": "US23050800214592", "requestReference": "AZX01234567891011", "sendersReference": "INVC0012345", "receiversReference": "INVC0054321", "debitAccountNumber": "001122334455", "creditAccountNumber": "987654321", "valueDate": "2023-05-08", "transferAmount": 10, "transferCurrency": "USD" } Missing data in the request NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (400) { "ErrorMessage": "Error received from backend service.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "US21052400000000", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "status": "FAILED", "transactionId": "rrt-770941720727587-2383364-1", "requestReference": "RR-220818-01", "sendersReference": "SR-220818-01", "valueDate": 1683676800, "error": { "code": "KEY-1006", "title": "Required field missing", "description": "The object creditPartyBank is required in the request." } } } Received request is unauthorized NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (401) { "ErrorMessage": "Error received from backend service.", "TransactionId": "rrt-621075741872460927-c-gce-9129-15867185-4", "X-CorrelationId": "80457bcb-2c3b-8c55-8cd6-3520c3157e8f", "TransactionTime": "2022-04-04T11:41:13.754Z", "ServiceError": { "status": "ERROR", "transactionId": "rrt-621075741872460927", "requestReference": "REQUEST-REF-220314.1", "sendersReference": "SENDER-REF-220314.1", "valueDate": "06-10-2023", "error": { "code": "KEY-0006", "title": "Not authorized for requested service", "description": "Check your credentials." }, "doddFrank": "NO" } } Request is forbidden to access the resource NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (403) { "ErrorMessage": "Access to requested resource is forbidden.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" } Requested resource is not found NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (404) { "ErrorMessage": "Requested resource is not found, please verify the resource and resubmit the request.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" } Requested method is not allowed. NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (405) { "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" } Requested unsupported media type NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (415) { "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" } Too many requests received NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (429) { "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" } Internal server error NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (500) { "ErrorMessage": "Error received from backend service.", "TransactionId": "359681587523_SR-RMC-210729-11081", "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688", "TransactionTime": "2022-04-05T07:59:15.422Z", "ServiceError": { "status": "ERROR", "transactionId": "rrt-621075741872460927", "requestReference": "RR-RMC-210720-0123458981", "sendersReference": "SR-RMC-210729-11081", "valueDate": "06-10-2023", "error": { "code": "KEY-9999", "title": "Unknown error", "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials." }, "doddFrank": "NO" } } Bad Gateway NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (502) { "ErrorMessage": "Error received from backend service.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ConnectError": "Connectivity error occurred with the downstream service (unexpected EOF at target). Please check with application support team before resubmitting the request" } } Service Unavailable NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (503) { "ErrorMessage": "Error received from backend service.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request." } } Gateway timeout NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (504) { "ErrorMessage": "Error received from backend service", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ConnectError": "Request could not be processed on time (gateway timeout). Please wait a moment and resubmit the request." } } Perform validation checks post /rtp/v1/payment/validate This call performs all the validation checks needed to initiate a payment without creating a payment. Request header FIELD TYPE DESCRIPTION KeyClientIdrequired string This value is provided by KeyBank during onboarding and is different from your client credentials. This is required for each call for RTP or Wire transactions. BODY FIELD TYPE DESCRIPTION requestedServicerequired string The type of payment transaction. The transaction request is valid only for the API products with granted access. Valid values: RTP, WIRE requestReferencerequired string A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters. typerequired string Indicates if the transaction type is a PAYMENT or a DRAFT. requestedValueDaterequired string Date (YYYY-MM-DD) the transfer will occur. originatorReferenceoptional string An additional reference value that is meaningful to the party originating the payment. sendersReferencerequired string A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters. receiversReferenceoptional string A reference value for the beneficiary. This value cannot exceed 140 characters. bankToBankInstructionsoptional string Area to share messages or instructions from one bank to another bank. ultimateDebitPartyoptional Object ultParty debitPartyrequired Object party debitPartyBankoptional Object party intermediaryBank1optional Object party intermediaryBank2optional Object party intermediaryBank3optional Object party creditPartyBankrequired Object party creditPartyrequired Object party transferAmountrequired number Amount of money to transfer in the correct currency format. transferCurrencyrequired string Currency code for the transfer amount. externalTemplateNameoptional string TBD customDataoptional string The values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle. Request example { "requestedService": "WIRE", "requestReference": "AZX01234567891011", "type": "PAYMENT", "requestedValueDate": 1621814400, "originatorReference": "", "sendersReference": "INVC0012345", "receiversReference": "INVC0054321", "ultimateDebitParty": { "name": "" }, "debitParty": { "name": "YOUR COMPANY NAME HERE", "accountNumber": "001122334455" }, "debitPartyBank": { "name": "" }, "creditPartyBank": { "name": "BENEFICIARY BANK NAME", "aba": "000000000" }, "creditParty": { "name": "BENEFICIARY NAME", "accountNumber": "987654321", "postalAddress": { "adrLine": [ "BENEFICIARY ADDRESS LINE 1", "BENEFICIARY ADDRESS LINE 2" ] } }, "transferAmount": 10, "transferCurrency": "USD", "customData": "" } Responses Successful response NAME TYPE DESCRIPTION statusrequired Object paymentStatus transactionIdoptional string The unique ID number associated with the original payment request. requestReferenceoptional string A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters. sendersReferenceoptional string A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters. receiversReferenceoptional string A reference value for the beneficiary. This value cannot exceed 140 characters. debitAccountNumberoptional string Debit account number creditAccountNumberoptional string Credit account number valueDateoptional string The date (YYYY-MM-DD) the transfer occurred. transferAmountoptional integer Amount of money to transfer in the correct currency format. transferCurrencyoptional string Currency code for the transfer amount. erroroptional Object paymentError doddFrankoptional Object noYesType clearingSystemReferenceoptional string Enter a reference value for the beneficiary. This value cannot exceed 140 characters. Response example (200) { "status": "VALID", "transactionId": "XZ23050714000000", "requestReference": "testWBB25889710252", "sendersReference": "INVC0012345", "receiversReference": "INVC0054321", "debitAccountNumber": "12345", "creditAccountNumber": "987654321", "transferAmount": 10, "transferCurrency": "USD" } Missing data in the request NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (400) { "ErrorMessage": "Error received from backend service.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "US21052400000000", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "status": "FAILED", "transactionId": "rrt-770941720727587-2383364-1", "requestReference": "RR-220818-01", "sendersReference": "SR-220818-01", "valueDate": 1683676800, "error": { "code": "KEY-1006", "title": "Required field missing", "description": "The object creditPartyBank is required in the request." } } } Received request is unauthorized NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (401) { "ErrorMessage": "Error received from backend service.", "TransactionId": "rrt-621075741872460927-c-gce-9129-15867185-4", "X-CorrelationId": "80457bcb-2c3b-8c55-8cd6-3520c3157e8f", "TransactionTime": "2022-04-04T11:41:13.754Z", "ServiceError": { "status": "ERROR", "transactionId": "rrt-621075741872460927", "requestReference": "REQUEST-REF-220314.1", "sendersReference": "SENDER-REF-220314.1", "valueDate": "06-10-2023", "error": { "code": "KEY-0006", "title": "Not authorized for requested service", "description": "Check your credentials." }, "doddFrank": "NO" } } Request is forbidden to access the resource NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (403) { "ErrorMessage": "Access to requested resource is forbidden.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" } Requested resource is not found NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (404) { "ErrorMessage": "Requested resource is not found, please verify the resource and resubmit the request.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" } Requested method is not allowed NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (405) { "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" } Requested unsupported media type NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (415) { "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" } Too many requests received NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (429) { "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" } Internal server error NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (500) { "ErrorMessage": "Error received from backend service.", "TransactionId": "359681587523_SR-RMC-210729-11081", "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688", "TransactionTime": "2022-04-05T07:59:15.422Z", "ServiceError": { "status": "ERROR", "transactionId": "rrt-621075741872460927", "requestReference": "REQUEST-REF-220314.1", "sendersReference": "SENDER-REF-220314.1", "valueDate": "06-10-2023", "error": { "code": "KEY-9999", "title": "Unknown error", "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials.", "detail": { "code": "KEY-1005", "title": "Error", "description": "Additional information about error code." } }, "doddFrank": "NO" } } Bad Gateway NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (502) { "ErrorMessage": "Error received from backend service.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ConnectError": "Connectivity error occurred with the downstream service (unexpected EOF at target). Please check with application support team before resubmitting the request" } } Service Unavailable NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (503) { "ErrorMessage": "Error received from backend service.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request." } } Gateway timeout NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError Response example (504) { "ErrorMessage": "Your request took too long to process. Please try again.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ConnectError": "Request could not be processed on time (gateway timeout). Please wait a moment and resubmit the request." } } Schemas connectError NAMETYPEDESCRIPTIONConnectErroroptionalstringAPI connectivity error information, if available. detail NAMETYPEDESCRIPTIONcoderequiredstringA static code assigned by the network or payment system.titlerequiredstringBrief title about the error associated with the status code.descriptionoptionalstringDescription of the error. exception NAME TYPE DESCRIPTION ErrorMessageoptional string A human-readable message that describes the type or source of the error. TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability. TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. ServiceErroroptional oneOf serviceErrorData connectError healthResponse NAMETYPEDESCRIPTIONStatusoptionalstringThe status of the health check response.SourceoptionalstringThe system that produces the health response. The origin of the response can be 'Gateway' or 'Roundtrip.' Roundtrip returns a response from the farthest system involved.TimestampoptionalstringThe date (YYYY-MM-DD) and time (HH:MM:SS) of response from the API service.ClientIpoptionalstringThe client IP address the gateway receives from the request.X-Forwarded-ForoptionalstringThe sequence of the IP addresses for systems between the client and the gateway. Addresses are separated by a comma. noYesType NAMETYPEDESCRIPTIONnoYesTypeoptionalstringThis field indicates whether the transaction qualifies for Dodd-Frank. participantListResponse NAMETYPEDESCRIPTIONcountrequiredstringThe count of records that match the initial query.limitrequiredintegerThe maximum number of records returned in the response.offsetrequiredintegerThe number of records skipped before the response is returned.partiesoptionalObjectparty party NAME TYPE DESCRIPTION namerequired string Name of the party. This can be an individual, a financial institution, or a beneficiary. The name cannot exceed 140 characters. accountNumberoptional string Account number of the party. abaoptional string If the party is a financial institution, this is the ABA number or routing number. bicoptional string The bank identifier code (BIC) for the party. This is a combination code that identifies the bank, country, location, and possibly the bank branch. txidoptional string The tax identification number for the party. adrLineoptional array An unstructured address line. You can have up to three lines of text. paymentError NAMETYPEDESCRIPTIONcoderequiredstringStatus code assigned to each error type.titlerequiredstringBrief title about the error associated with the status code.descriptionoptionalstringDescription of the error.detailoptionalObjectdetail paymentTransactionRequestV1 NAMETYPEDESCRIPTIONrequestedServicerequiredstringThe type of payment transaction. The transaction request is valid only for the API products with granted access. Valid values: RTP, WIRErequestReferencerequiredstringA reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.typerequiredstringIndicates if the transaction type is a PAYMENT or a DRAFT.requestedValueDaterequiredstringDate (YYYY-MM-DD) the transfer will occur.originatorReferenceoptionalstringAn additional reference value that is meaningful to the party originating the payment.sendersReferencerequiredstringA reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.receiversReferenceoptionalstringA reference value for the beneficiary. This value cannot exceed 140 characters.bankToBankInstructionsoptionalstringArea to share messages or instructions from one bank to another bank.ultimateDebitPartyoptionalObjectultParty debitPartyrequiredObjectparty debitPartyBankoptionalObjectparty intermediaryBank1optionalObjectparty intermediaryBank2optionalObjectparty intermediaryBank3optionalObjectparty creditPartyBankrequiredObjectparty creditPartyrequiredObjectparty transferAmountrequirednumberAmount of money to transfer in the correct currency format.transferCurrencyrequiredstringCurrency code for the transfer amount.externalTemplateNameoptionalstringTBDcustomDataoptionalstringThe values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle. paymentTransactionResponse NAMETYPEDESCRIPTIONstatusrequiredObjectpaymentStatus transactionIdoptionalstringThe unique ID number associated with the original payment request.requestReferenceoptionalstringA reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.sendersReferenceoptionalstringA reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.receiversReferenceoptionalstringA reference value for the beneficiary. This value cannot exceed 140 characters.debitAccountNumberoptionalstringDebit account numbercreditAccountNumberoptionalstringCredit account numbervalueDateoptionalstringThe date (YYYY-MM-DD) the transfer occurred.transferAmountoptionalintegerAmount of money to transfer in the correct currency format.transferCurrencyoptionalstringCurrency code for the transfer amount.erroroptionalObjectpaymentError doddFrankoptionalObjectnoYesType clearingSystemReferenceoptionalstringEnter a reference value for the beneficiary. This value cannot exceed 140 characters. paymentStatus NAMETYPEDESCRIPTIONpaymentStatusoptionalstringThe status of the payment transaction. Valid values: IN_PROCESS, IN_REVIEW, COMPLETED, FAILED, RETURNED, ERROR, VALID serviceErrorData NAMETYPEDESCRIPTIONstatusrequiredObjectpaymentStatus transactionIdoptionalstringThe unique ID number associated with the original payment request.requestReferenceoptionalstringA reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.sendersReferenceoptionalstringA reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.receiversReferenceoptionalstringThe sender reference value from the original request. This is useful for traceability and reporting.debitAccountNumberoptionalstringThe sender reference value from the original request. This is useful for traceability and reporting.creditAccountNumberoptionalstringThe sender reference value from the original request. This is useful for traceability and reporting.valueDateoptionalstringThe date (YYYY-MM-DD) the transferred occurred.erroroptionalObjectpaymentError doddFrankoptionalObjectnoYesType ultParty NAMETYPEDESCRIPTIONnameoptionalstringTypically this is the name of the party that instructed the debit party to initiate a payment. This value cannot exceed 140 characters. foreignBankSystemType NAMETYPEDESCRIPTIONtypeoptionalstringThe five-digit global routing code for a foreign financial institution.idoptionalstringThe identification number associated with the foreign financial institution. Errors When an error occurs, the paymentTransactionResponse object returns with the paymentStatus of ERROR. Some errors are reported with the standard HTTP error response. Certain violations report with an HTTP 200 response for issues where the API service successfully receives the request, but it encounters errors. KeyBank may include additional information about the error in API-specific error messages. For more information about errors, see Error handling. API-specific KeyBank error codes and details are in the error object of the response payload. Issues can be about account restrictions, network timeout, invalid data in the request, etc., and represent a failed payment. API specific KeyBank codes and messages CODE MESSAGE KEY-0001 Not authorized KEY-0002 Not authorized for requested action KEY-0003 Request exceeds authorized limit KEY-0004 Unauthorized for account KEY-0005 Internal use only fields KEY-0006 Not authorized for requested service KEY-0008 NSF KEY-1000 Transformation Error KEY-1001 Invalid Data KEY-1002 Invalid Bank Identifier KEY-1003 Invalid or unknown template KEY-1004 Invalid account KEY-1005 Invalid Currency KEY-1006 Required field missing KEY-1007 Transaction Not Found KEY-1008 Insufficient Funds KEY-1009 Account has restrictions KEY-1010 Duplicate Request KEY-1011 Payor Account Restrictions KEY-1012 Payee Account Restrictions KEY-3003 Payment network timeout. Please retry. KEY-3004 Payment rejected by payment network KEY-9997 Failed payment review KEY-9998 Payment failed during processing KEY-9999 Unknown error API-specific error example paymentTransactionResponse: { "status": "FAILED", "requestReference": "RR-999999-01", "sendersReference": "SR-999999-01", "error": { "code": "KEY-1002", "title": "Invalid Bank Identifier", "description": "Credit Party Bank must be a valid USRTP Participant" } } YAML file