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

Request and response example

• If you want to search with a date range, make sure to include the fromDate and toDate. You can search up to two years of past records. We recommend that you limit the date range to 31 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.

{
  "accountNumber": "3123456789",
  "dateSearchType": "COLLECTED",
  "fromDate": "2024-02-01T00:00:00.000Z",
  "toDate": "2024-02-01T00:00:00.000Z",  
  "minimumAmount": 100,
  "maximumAmount": 75020.5,
  "traceNumber": "041001030016002",
  "pageNumber": 1,
  "pageSize": 150  
}

{
  "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

1. 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. 
2. A metadata object is part of the response that gives details about the inquiry results and size of response.

Request and response example

Use the parNumber from the originating transaction to get additional details about the transaction. 

curl --location: '{host}/v1/ach/detail/22018007665985'
--header 'Accept: application/json'
--header 'Authorization: Bearer testZcKJDWnwDWmmf9qah6PJvPy8'

{
  "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"
    }
  ]
 }

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: Use ACH Direct to reverse a payment. You can search for the transaction by batch or account. Reversals are available within 5 banking days of the effective date for the current transactions. After you submit this request, the status for the transaction will be pending until it is fully processed as reversed.

Option 3: 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.