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 at any point in the payment process.
- 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 contact a KeyBank Payment Advisor to learn more.
ACH Origination API
With the ACH Origination API, you can originate a credit or debit transaction to an authorized receiver.
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 thesecCode
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 |
|
---|---|---|
CTX | Corporate Trade Exchange |
|
PPD | Prearranged Payments and Deposits |
|
TEL | Telephone |
|
WEB | Online |
|
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. (EST) | 04:00 p.m. (EST) | 05:30 p.m. (EST) |
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
Originating 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 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.
Reversal
Request to cancel a payment after it has posted. Reversals are not guaranteed.
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.
Important identifiers that are good to know
Use the account number, PAR number, or trace number from the ACH Origination transaction request to inquire about the status or get additional details of a transaction.
Account number
Use the KeyBank originator account number associated with ACH transaction to inquire about transactions that are posted. With the ACH List inquiry, all you need is an account number to look up ACH transactions.
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.
In the ACH Inquiry API request, use the PAR number (parNumber
) in the ACH Detail request to inquire about an account with this unique identifier.
Trace number
When you submit a request with the ACH Origination API, the ACH processor immediately creates a trace number unique to that transaction (traceNumber
). Save this trace number if you intend to check on the progress of the ACH transaction or to use it for verification.
Identifier by inquiry endpoint
In the table below we associate each endpoint in the ACH Inquiry API, including legacy endpoints, with the key identifiers you can use to request the status of an ACH transaction.
ENDPOINT | IDENTIFIER EXAMPLE | ||
---|---|---|---|
ACH List | /accounts/transactions/v1/ach/list | accountNumber: 222333448 | |
ACH Detail | /accounts/transactions/v1/ach/detail/{parNumber} | parNumber: 1234567891113 |
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 List
The ACH List endpoint is a comprehensive search of all ACH transactions with a single account number. Use the date parameters or identify the ACH transaction status to better define the response.
Request and response example
- If you want to search with a date range, make sure to include the
fromDate
andtoDate
. You can search up to two years of past records. We recommend that you limit the date range to 90 days for a more efficient response. - If you are want to inquire about only a certain status of ACH transaction, use the
dateSearchType
parameter. You can filter the results by Collected, Returned, or Settled transactions.
Request
"accountNumber": "3123456789", "dateSearchType": "COLLECTED", "fromDate": 2024-03-15, "toDate": 2024-05-31, "minimumAmount": 100, "maximumAmount": 75020.5, "traceNumber": "041001030016002", "pageNumber": 1, "pageSize": 150
Response
"transactions": [ { "parNumber": "22018007665985", "transactionStatus": "COLLECTED", "traceNumber": "000000000000000", "transactionAmount": 10.01, "settlementDate": "2021-03-08", "transactionCode": "22", "authorizedCustomerName": "TEST CUSTOMER1", "standardEntryClassCode": "CCD", "receivingAccount": { "accountNumber": "123456789012" }, "receivingParty": { "customerIdentificationNumber": "099999999", "companyName": "MERCHANT" }, "originatingAccount": { "accountNumber": "123456789012" }, "originatingParty": { "customerIdentificationNumber": "1234567", "companyName": "COMPANY NAME 1" }, "returnDate": "2024-02-01", "returnReasonCode": "R02", "returnReasonDescription": "Account Closed", "addendaCount": 1, "notificationOfChangeAddendaCount": 1, "internationalAddendaCount": 0 } ], "metadata": { "messages": [ { "code": "099", "message": "Search results match the criteria" } ], "page": { "pageNumber": 1, "pageSize": 10, "totalPages": 10, "totalRecords": 28, "lastPage": true } } }
What to expect
- In the transactions response, you can expect to see the status, general transaction information, identification for the originating and receiving parties involved, return reason if applicable, and addenda counts.
- A metadata object is part of the response that gives details about the inquiry results and size of response.
ACH Detail
The ACH Detail endpoint retrieves details about an ACH transaction with a single PAR number.
Details returned include transaction IDs, originating parties, receiving parties, return reasons, transaction status, and Nacha SEC data.
Request and response example
Use the parNumber
from the originating transaction to get additional details about the transaction.
Request
curl --location: '{host}/v1/ach/detail/22018007665985' --header 'Accept: application/json' --header 'Authorization: Bearer testZcKJDWnwDWmmf9qah6PJvPy8'
Response
{
"parNumber": "22018007665985",
"transactionStatus": "COLLECTED",
"traceNumber": "000000000000000",
"transactionAmount": 10.01,
"settlementDate": "2021-03-08",
"transactionCode": "22",
"transactionCodeDescription": "Automated Deposit",
"transactionDescription": DEPOSIT",
"authorizedCustomerName": "TEST CUSTOMER1",
"standardEntryClassCode": "CCD",
"standardEntryClassDescription": "Cash Concentration or Disbursement",
"receivingAccount": {
"accountNumber": "123456789012",
"bankNumber": "0000",
"routingNumber": "1234567890"
},
"receivingParty": {
"customerIdentificationNumber": "099999999",
"companyName": "MERCHANT",
"customerName": "TEST MERCHANT"
},
"originatingAccount": {
"accountNumber": "123456789012",
"bankNumber": "0000",
"routingNumber": "1234567890"
},
"originatingParty": {
"customerIdentificationNumber": "1234567",
"companyName": "COMPANY NAME 1",
"customerName": "CUSTOMER NAME 1"
},
"returnDate": "2024-02-01",
"returnReasonCode": "R02",
"returnReasonDescription": "Account Closed",
"addendaCount": 1,
"notificationOfChangeAddendaCount": 1,
"internationalAddendaCount": 0,
"customData": "merchant:status",
"checkSerialNumber": "4345",
"transactionDirection": "Receiving Item",
"addenda": [
{
"sequenceNumber": 1,
"entryDetailSequenceNumber": "188",
"paymentRelatedInformation": "Addenda Record (Applies to CCD, CTX, PPD, and WEB entries)"
}
],
"notificationOfChange": [
{
"changeCode": "C02",
"changeDescription": "Incorrect transit\/routing number",
"correctedData": "1234567890"
}
]
}
What to expect
You receive a detailed response for the transaction associated with the provided PAR number. Details include information about the parties involved. the identification and account associated with the PAR number, and additional transaction information in addenda records.
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.
To reverse a payment, you have one of two options. You cannot do both of these options if one does not work.
Option 1: Submit the file maintenance form for a payment reversal.
Option 2: 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.
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
orparNumber
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 the 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 process the transaction.
When you reverse a transaction, you missed the window to undo a request and now need to either submit the file maintenance form for a payment reversal or attempt to reverse it with another transaction.
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 and 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.
- The entry description (
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 10:30 p.m. EST. The schedule is as follows:
ACH collection/distribution schedule
- Collection only, 05:00 a.m. EST
- Collection and distribution, 06:00 a.m. EST
- Collection and distribution, 09:30 a.m. EST
- Collection and distribution, 11:30 a.m. EST
- Collection and distribution, 01:30 p.m. EST
- Collection and distribution, 03:30 p.m. EST
- Collection and distribution, 07:00 p.m. EST
- Collection and distribution, 09:30 p.m. EST
- Collection and distribution, 10:30 p.m. EST
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.- Point (
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 a 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.
- 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.