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.

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:

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.

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.

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.

{
"getACHStatusInquiryRequest": {
  "accountNumber": ["32123456789"],
  "parNumber": ["23074005623452"],
  "traceNumber": ["041001034453247"],
  "startRowIndex": "1",
  "endRowIndex": "1000"}
}

"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

1. 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.
2. The parNumber returns in the response. This is a key field to inquire with the ACH Returns endpoint.

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

{
  "getACHCollectedTransactionsRequest": {
    "accountNumber": [
      "3212345689"
    ],
    "fromDate": "2023-09-18",
    "toDate": "2023-09-30",
    "sourceTransactionSettledDate": "",
    "creditOrDebitCode": "",
    "fromAmount": "",
    "toAmount": "",
    "traceNumber": "",
    "parNumber": "23268007704844",
    "startRowIndex": "1",
    "endRowIndex": "1000"
  }
}

"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

1. 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.
2. The traceNumber also returns in the response which can be used in the ACH Status Inquiry endpoint.

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.

{
  "getACHReturnTransactionsRequest": {
    "accountNumber": ["359681604732"],
    "fromDate": "2022-07-26",
    "toDate": "2022-07-30",
    "creditOrDebitCode": "",
    "fromAmount": "",
    "toAmount": "",
    "parNumber": "22202011366290",
    "startRowIndex": "1",
    "endRowIndex": "10"  }  }

"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

1. The ACH Returns Inquiry endpoint response includes 50+ data elements detailing the returned item along with transaction details from the collection of the item.
2. The response includes the original parNumber and traceNumber values.

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.

{
  "getACHPostedTransactionsRequest": {
    "accountNumber": ["32123456789"],
    "fromDate": "2023-03-15",
    "toDate": "2023-03-15",
    "creditOrDebitCode": "",
    "fromAmount": "",
    "toAmount": "",
    "parNumber": "",
    "startRowIndex": "1",
    "endRowIndex": "1"  }
}

"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

1. 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. 
2. The batch level summary ACH transaction details that are returned look as how you see them on the DDA statement or in KeyNavigator.

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:

1. Complete an ACH Originate API request with the opposite credit or debit indicator in the creditDebitCode field of the request body.
2. 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.