ACH Inquiry

clock 4-minute read calender 1.2.2 | updated Mar. 18, 2025

Get the status for your ACH transactions

What you can doEndpoint
Health checkget /accounts/transactions/v1/healthCheck
Search for ACH transactionspost /accounts/transactions/v1/ach/list
Get details about an ACH transaction with a PAR numberget /accounts/transactions/v1/ach/detail/{parNumber}

Before you begin

To test or use any KeyBank API, you must be fully onboarded. This means having the right certificates, user credentials, and specific permissions for the API you're accessing. 

Need help getting started? Check out our Get started guide for everything you need to know.

Account number

Use the financial institution account number (accountNumber) to look up related ACH transactions. This number cannot be more than 16 digits. 

PAR number

When looking for details about an ACH transaction, use the Payment Assigned Reference (PAR) number. This is used to identify the transaction without exposing any sensitive consumer identification information. This is a unique identifier assigned to the transaction by the ACH processor after you submit a request with the ACH Origination API. You can find the PAR number in the /ach/list response.

Learn more about how we use certain identifiers with ACH in our ACH APIs User Guide.

Interpret the response

ACH Inquiry response return two key fields with each response if it is for account information or transaction details: transaction type (transactionType) and status (transactionStatus).

Transaction type indicates if the transaction is a debit (collecting funds) or a credit (sending funds). The transaction code returns a two-digit number that indicates if it is a credit or debit for a checkings, savings, or loan account. Go to our Decoder to get additional details. 

Transaction status displays the status of the transaction if it is in progress (COLLECTED), processed (SETTLED), or returned (RETURNED).

The consolidation settlement type affects what information is returned. 

  • For clients with a non-consolidated settlement, you can receive information about collected, settled, and returned transactions.
  • For clients with a consolidated settlement, you will only receive collected and returned transactions. SETTLED is not an available status for consolidated settlement.

get /accounts/transactions/v1/healthCheck

Check the health of an API service and verify you can successfully connect. A bearer token is required.

Request example

curl "https://partner-api-qv.key.com/accounts/transactions/v1/healthCheck"
--header 'Bearer testZcKJDWnwDWmmf9qah6PJvPy8'
NAMETYPEDESCRIPTION
StatusoptionalstringStatus of the health check response.
SourceoptionalstringSystem producing the health response. Genesis of the response could either be just from “gateway” or “roundtrip” from the farthest possible system involved in generating this response.
TimestampoptionalstringTimestamp when the health response is being returned by this service.
ClientIpoptionalstringIP of the client from which this request for health check is received by the gateway.
X-Forwarded-ForoptionalstringSequence of all the Ips of the systems involved between the client and the gateway.

Response example (200)

copylink
{
  "Status": "Ok",
  "Source": "Roundtrip",
  "Timestamp": "2022-09-15T04:49:03",
  "ClientIp": "156.77.111.28",
  "X-Forwarded-For": "[156.77.111.28]"
}

post /accounts/transactions/v1/ach/list

Search for ACH transactions by passing certain search parameters. With ACH transactions, each status point has a start and end date. 

NAMETYPEDESCRIPTION
accountNumberrequiredstringThe bank account number. This field cannot exceed 16 characters.
fromDateoptionalstringStart date for the date range. This date must be the current date or prior to the current date. Transaction data can be recalled within 180 days of the current date. Format: YYYY-MM-DD
toDateoptionalstringEnd date for the date range. This date can be the current day or a later date from the start date (fromDate). The date range should not exceed 31 days. Format: YYYY-MM-DD
minimumAmountoptionalstringThe minimum dollar amount of the transaction. This amount must be less than or equal to the maximum amount. Leave blank or enter zero for no minimum amount.
maximumAmountoptionalstringThe maximum dollar amount of the transaction. This amount must be greater than or equal to the minimum amount. Leave blank to retrieve all amounts. This amount cannot exceed one billion dollars.
traceNumberoptionalstringThe unique number for the transaction provided by the originator.
pageNumberoptionalstringThe number of the page being viewed. This number must be greater than or equal to 1.
pageSizeoptionalstringThe total number of pages returned. This number must be greater than or equal to 1 and cannot exceed 1000.

Request example

copylink
{
  "accountNumber": "3123456789",
  "fromDate": 1706745600,
  "toDate": 1706745600,
  "minimumAmount": 100,
  "maximumAmount": 75020.5,
  "traceNumber": "041001030016002",
  "pageNumber": 1,
  "pageSize": 150
 }
NAMETYPEDESCRIPTION
transactionsoptionalstringAchListTransaction
metadataoptionalstringMetadata

Response example (200)

copylink
{
  "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
    }
    }    
    }
NAMETYPEDESCRIPTION
metadataoptionalstringMetadata

Response example (400)

copylink
{
  "metadata": {
    "messages": [{
      "code": "001",
      "message": "There are no transactions that match the parNumber."
     }  
  ],
  "page": {
    "pageNumber": 1,
    "pageSize": 1,
    "totalPages": 1,
    "totalRecords": 0,
    "lastPage": false
   }
  }
 }

get /accounts/transactions/v1/ach/detail/{parNumber}

Use the PAR number to retrieve information about an ACH transaction.

path FIELDTYPEDESCRIPTION
parNumberrequiredstringThe unique PAR number assigned to the the transaction by the ACH product processor.

Request example

curl --location: 'https://partner-api-qv.key.com/accounts/transactions/v1/ach/detail/22018007665985'
--header 'Accept: application/json'
--header 'Authorization: Bearer testZcKJDWnwDWmmf9qah6PJvPy8'
NAMETYPEDESCRIPTION
parNumberoptionalstringThe unique PAR number assigned to the the transaction by the ACH product processor.
transactionStatusoptionalstringThe status of the ACH transaction. Valid values: COLLECTED, RETURNED, SETTLED
traceNumberoptionalstringThe unique number for the transaction provided by the originator.
transactionAmountoptionalnumberThe dollar amount of the transaction.
settlementDateoptionalstringThe date the transaction settlement occurred. Format: YYYY-MM-DD
transactionCodeoptionalstringTwo-digit code identifying the account type at the receiving financial institution.
transactionCodeDescriptionoptionalstringDescription for the transaction code.
transactionDescriptionoptionalstringDescription about the purpose of the transaction.
authorizedCustomerNameoptionalstringAuthorized customer name
standardEntryClassCodeoptionalstringThe three-digit Standard Entry Class code based on Nacha rules.
standardEntryClassDescriptionoptionalstringThe description for the Nacha SEC code.
receivingAccountoptionalObjectAccountDetail
receivingPartyoptionalObjectPartyDetail
originatingAccountoptionalObjectAccountDetail
originatingPartyoptionalObjectPartyDetail
returnDateoptionalstringDate of the returned transaction to the ACH system. Format: YYYY-MM-DD
returnReasonCodeoptionalstringThe 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
returnReasonDescriptionoptionalstringDescription as to why the ACH transaction is returned.
addendaCountoptionalintegerCount of addenda records.
notificationOfChangeAddendaCountoptionalintegerCount of change notifications for addenda records.
internationalAddendaCountoptionalintegerCount of international addenda records.
customDataoptionalstringThe 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.
checkSerialNumberoptionalstringSerial number for the check converted to an ACH transaction.
transactionDirectionoptionalstringIndicates the direction of the transaction. Valid values: ORIGINATING ITEM, RECEIVING ITEM
addendaoptionalarrayAddendum
notificationOfChangeoptionalarrayNotificationOfChange

Response example (200)

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

Response example (400)

copylink
{
  "metadata": {
    "messages": [{
      "code": "AI-Detail-404-no-records-100",
      "message": "Record Not Found"
     }  
  ]
}
NAMETYPEDESCRIPTION
accountNumberstringBank account number.
NAMETYPEDESCRIPTION
accountNumberstringBank account number of the ACH originator or receiver.
bankNumberstringBank number associated with the account number.
routingNumberstringNine-digit routing number for the account provided in the original request.
NAMETYPEDESCRIPTION
parNumberstringThe unique PAR number assigned to the the transaction by the ACH product processor.
transactionStatusstringThe status of the ACH transaction. Valid values: COLLECTED, RETURNED, SETTLED
traceNumberstringThe unique number for the transaction provided by the originator.
transactionAmountnumberThe dollar amount of the transaction.
settlementDatestringThe date the transaction settlement occurred. Format: YYYY-MM-DD
transactionCodestringTwo-digit code identifying the account type at the receiving financial institution.
transactionCodeDescriptionstringDescription for the transaction code.
transactionDescriptionstringDescription about the purpose of the transaction.
authorizedCustomerNamestringAuthorized customer name
standardEntryClassCodestringThe three-digit Standard Entry Class code based on Nacha rules.
standardEntryClassDescriptionstringThe description for the Nacha SEC code.
receivingAccountObjectAccountDetail
receivingPartyObjectPartyDetail
originatingAccountObjectAccountDetail
originatingPartyObjectPartyDetail
returnDatestringDate of the returned transaction to the ACH system. Format: YYYY-MM-DD
returnReasonCodestringThe 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
returnReasonDescriptionstringDescription as to why the ACH transaction is returned.
addendaCountintegerCount of addenda records.
notificationOfChangeAddendaCountintegerCount of change notifications for addenda records.
internationalAddendaCountintegerCount of international addenda records.
customDatastringThe 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.
checkSerialNumberstringSerial number for the check converted to an ACH transaction.
transactionDirectionstringIndicates the direction of the transaction. Valid values: ORIGINATING ITEM, RECEIVING ITEM
addendaoptionalarrayAddendum
notificationOfChangeoptionalarrayNotificationOfChange
NAMETYPEDESCRIPTION
parNumberstringThe unique PAR number assigned to the the transaction by the ACH product processor.
transactionStatusstringThe status of the ACH transaction. Valid values: COLLECTED, RETURNED, SETTLED
traceNumberstringThe unique number for the transaction provided by the originator.
transactionAmountnumberThe dollar amount of the transaction.
settlementDatestringThe date the transaction settlement occurred. Format: YYYY-MM-DD
transactionCodestringTwo-digit code identifying the account type at the receiving financial institution.
authorizedCustomerNamestringAuthorized customer name
standardEntryClassCodestringThe three-digit Standard Entry Class code based on Nacha rules.
receivingAccountObjectAccountList
receivingPartyObjectPartyList
originatingAccountObjectAccountList
originatingPartyObjectPartyList
returnDatestringDate of the returned transaction to the ACH system. Format: YYYY-MM-DD
returnReasonCodestringThe 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
returnReasonDescriptionstringDescription as to why the ACH transaction is returned.
addendaCountintegerCount of addenda records.
notificationOfChangeAddendaCountintegerCount of change notifications for addenda records.
internationalAddendaCountintegerCount of international addenda records.
NAMETYPEDESCRIPTION
sequenceNumberintegerThe addenda record item number in order of sequence. Number cannot exceed 4 digits.
entryDetailSequenceNumberstringThe entry number in order of sequence. Number cannot exceed 7 digits.
paymentRelatedInformationstringThe related payment information from the addenda records. The maximum character limit is 255.
NAMETYPEDESCRIPTION
codestringCode for the related message.
messagestringMessage associated with the code.
NAMETYPEDESCRIPTION
pageNumberintegerThe number of the page being viewed.
pageSizeintegerThe number of records per page.
totalPagesintegerThe number of pages there are in total.
totalRecordsintegerThe total number of transactions available in the result set.
lastPagebooleanIndicates if the current page (page number) is the last page of the result set. Valid values: true, false
NAMETYPEDESCRIPTION
messagesoptionalarrayMessage
pageObjectPage
NAMETYPEDESCRIPTION
customerIdentificationNumberstringThe unique identification number associated with the customer.
companyNamestringThe name of the corporation or institution making the request.
NAMETYPEDESCRIPTION
customerIdentificationNumberstringThe unique identification number associated with the customer.
companyNamestringThe name of the corporation or institution making the request.
customerNamestringThe name of the customer.
NAMETYPEDESCRIPTION
changeCodestringThe three-character change code begins with the letter 'C'. This code is applied to all NOCs to indicate the information that is being changed.
changeDescriptionstringThe description associated with the change code.
correctedDatastringThe corrected data per the correction change code.

For more information about general errors, see Error handling.

API-specific KeyBank error codes and details are in the ServiceError or errorResponse object with additional information specific to the API. The KeyBank error codes start with ECA-W with a three-digit number that follows. The number increases by one digit for each error message. For example, if you have an issue with your request that generates two error messages specific to the API, the codes will be ECA-W-001 and ECA-W-002.

HTTP
STATUS CODE
CUSTOM
STATUS CODE
DESCRIPTION
299W

ECA-W-001 Request processing completed with warnings.

This message occurs when multiple request parameters are provided, and some of the data are not available as part of response.

400F

ECA-W-001 Request Validation failed.

There is missing mandatory information like accountNumber, fromDate, or toDate. Review values for mandatory request fields.

400F

ECA-W-002 Requested records range is greater than the allowed limit - 1000

Response goes beyond 1000 transactions for the requested account. Change the request criteria to help limit returned transactions to the allowed amount.

 
ReleaseAPI versionChange descriptionImpact
March 20251.2.2
  • Deprecated dateSearchType from the request body in the /ach/list endpoint. You can no longer use the ACH status to filter your request. Look in the response body to view the AchStatus.
LOW
October 20241.2.1
  • Date parameters adjusted to support the maximum date range search limit of 180 days. Do not enter a fromDate and toDate date range that goes beyond 31 days.
LOW
May 20241.2.0
  • Two new endpoints available in all environments, including the API simulator! We have added:
    • GET /accounts/transactions/v1/ach-transactions/{parNumber}
    • POST /accounts/transactions/v1/ach-transactions
MID
December 20231.1.6
  • Deprecated the mdmID field. Backend services and processes have been enhanced to authenticate client API calls without the need for an MDM ID.
  • Removed the POSTED status from the list of valid values for the ACHStatus field in the achStatusInquiryResult object. Valid values for this field now only include COLLECTED or RETURNED.
MID
September 20231.1.5
  • The mdmId description has been updated to communicate that this field will soon deprecate in an upcoming release.
LOW
August 20231.1.4
  • Modified the format for date parameters to match with KeyBank API standard date format of YYYY-MM-DD.
  • fromDate and toDate were updated to recall transaction data from the previous 24 months.
LOW
July 20231.1.3
  • Added the settlementDate field in the response to provide you the ability to filter by date in response.
  • MDM ID (mdmId) is no longer a required field, it is now optional.
LOW
May 20231.1.2
  • Added customData to the following objects:
    • achCollectedTransactionsResult
    • achPostedTransactionsResult
    • ACHReturnTransaction
  • Added receivingCustIdentificationNumber to the request payloads.
  • In the achCollectedTransactionsResult response, we added an example for the nonIatAddendum schema.
MID
December 20221.0.0
  • Released on the Developer Portal.
 

Impact levels

  • LOW: This is a minor change or enhancement that does not alter the operations of the API. Upgrading to the latest specifications is preferable but not required.
  • MID: The previous API version is valid and operates, but does not contain latest enhancements. You need to update your specifications to get these enhancements.
  • HIGH: The previous API version is no longer operable. You must upgrade to the latest specifications to access and use this API product.

YAML file download