ACH Inquiry

Get the status for your ACH transactions

What you can do	Endpoint
Health check	get /accounts/transactions/v1/healthCheck
Search for ACH transactions	post /accounts/transactions/v1/ach/list
Get details about an ACH transaction with a PAR number	get /accounts/transactions/v1/ach/detail/{parNumber}

Key notes

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.

Requirements

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.

Health check

get /accounts/transactions/v1/healthCheck

Request

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'

Successful response

NAME	TYPE	DESCRIPTION
Statusoptional	string	Status of the health check response.
Sourceoptional	string	System 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.
Timestampoptional	string	Timestamp when the health response is being returned by this service.
ClientIpoptional	string	IP of the client from which this request for health check is received by the gateway.
X-Forwarded-Foroptional	string	Sequence of all the Ips of the systems involved between the client and the gateway.

Response example (200)

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

Advanced search for ACH transactions

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.

Request

NAME	TYPE	DESCRIPTION
accountNumberrequired	string	The bank account number. This field cannot exceed 16 characters.
fromDateoptional	string	Start 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
toDateoptional	string	End 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
minimumAmountoptional	string	The 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.
maximumAmountoptional	string	The 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.
traceNumberoptional	string	The unique number for the transaction provided by the originator.
pageNumberoptional	string	The number of the page being viewed. This number must be greater than or equal to 1.
pageSizeoptional	string	The total number of pages returned. This number must be greater than or equal to 1 and cannot exceed 1000.

Request example

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

Responses

Successful response

NAME	TYPE	DESCRIPTION
transactionsoptional	string	AchListTransaction
metadataoptional	string	Metadata

Response example (200)

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

Bad input parameter

NAME	TYPE	DESCRIPTION
metadataoptional	string	Metadata

Response example (400)

{
  "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 details about an ACH transaction with a PAR number

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

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

Request

path FIELD	TYPE	DESCRIPTION
parNumberrequired	string	The 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'

Responses

Successful response

NAME	TYPE	DESCRIPTION
parNumberoptional	string	The unique PAR number assigned to the the transaction by the ACH product processor.
transactionStatusoptional	string	The status of the ACH transaction. Valid values: COLLECTED, RETURNED, SETTLED
traceNumberoptional	string	The unique number for the transaction provided by the originator.
transactionAmountoptional	number	The dollar amount of the transaction.
settlementDateoptional	string	The date the transaction settlement occurred. Format: YYYY-MM-DD
transactionCodeoptional	string	Two-digit code identifying the account type at the receiving financial institution.
transactionCodeDescriptionoptional	string	Description for the transaction code.
transactionDescriptionoptional	string	Description about the purpose of the transaction.
authorizedCustomerNameoptional	string	Authorized customer name
standardEntryClassCodeoptional	string	The three-digit Standard Entry Class code based on Nacha rules.
standardEntryClassDescriptionoptional	string	The description for the Nacha SEC code.
receivingAccountoptional	Object	AccountDetail
receivingPartyoptional	Object	PartyDetail
originatingAccountoptional	Object	AccountDetail
originatingPartyoptional	Object	PartyDetail
returnDateoptional	string	Date of the returned transaction to the ACH system. Format: YYYY-MM-DD
returnReasonCodeoptional	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
returnReasonDescriptionoptional	string	Description as to why the ACH transaction is returned.
addendaCountoptional	integer	Count of addenda records.
notificationOfChangeAddendaCountoptional	integer	Count of change notifications for addenda records.
internationalAddendaCountoptional	integer	Count of international addenda records.
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.
checkSerialNumberoptional	string	Serial number for the check converted to an ACH transaction.
transactionDirectionoptional	string	Indicates the direction of the transaction. Valid values: ORIGINATING ITEM, RECEIVING ITEM
addendaoptional	array	Addendum
notificationOfChangeoptional	array	NotificationOfChange

Response example (200)

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

Resource not found

NAME	TYPE	DESCRIPTION
metadataoptional	string	Metadata

Response example (400)

{
  "metadata": {
    "messages": [{
      "code": "AI-Detail-404-no-records-100",
      "message": "Record Not Found"
     }  
  ]
}

Schemas

AccountList

NAME	TYPE	DESCRIPTION
accountNumber	string	Bank account number.

AccountDetail

NAME	TYPE	DESCRIPTION
accountNumber	string	Bank account number of the ACH originator or receiver.
bankNumber	string	Bank number associated with the account number.
routingNumber	string	Nine-digit routing number for the account provided in the original request.

AchDetailTransaction

NAME	TYPE	DESCRIPTION
parNumber	string	The unique PAR number assigned to the the transaction by the ACH product processor.
transactionStatus	string	The status of the ACH transaction. Valid values: COLLECTED, RETURNED, SETTLED
traceNumber	string	The unique number for the transaction provided by the originator.
transactionAmount	number	The dollar amount of the transaction.
settlementDate	string	The date the transaction settlement occurred. Format: YYYY-MM-DD
transactionCode	string	Two-digit code identifying the account type at the receiving financial institution.
transactionCodeDescription	string	Description for the transaction code.
transactionDescription	string	Description about the purpose of the transaction.
authorizedCustomerName	string	Authorized customer name
standardEntryClassCode	string	The three-digit Standard Entry Class code based on Nacha rules.
standardEntryClassDescription	string	The description for the Nacha SEC code.
receivingAccount	Object	AccountDetail
receivingParty	Object	PartyDetail
originatingAccount	Object	AccountDetail
originatingParty	Object	PartyDetail
returnDate	string	Date of the returned transaction to the ACH system. Format: YYYY-MM-DD
returnReasonCode	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
returnReasonDescription	string	Description as to why the ACH transaction is returned.
addendaCount	integer	Count of addenda records.
notificationOfChangeAddendaCount	integer	Count of change notifications for addenda records.
internationalAddendaCount	integer	Count of international addenda records.
customData	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.
checkSerialNumber	string	Serial number for the check converted to an ACH transaction.
transactionDirection	string	Indicates the direction of the transaction. Valid values: ORIGINATING ITEM, RECEIVING ITEM
addendaoptional	array	Addendum
notificationOfChangeoptional	array	NotificationOfChange

AchListTransaction

NAME	TYPE	DESCRIPTION
parNumber	string	The unique PAR number assigned to the the transaction by the ACH product processor.
transactionStatus	string	The status of the ACH transaction. Valid values: COLLECTED, RETURNED, SETTLED
traceNumber	string	The unique number for the transaction provided by the originator.
transactionAmount	number	The dollar amount of the transaction.
settlementDate	string	The date the transaction settlement occurred. Format: YYYY-MM-DD
transactionCode	string	Two-digit code identifying the account type at the receiving financial institution.
authorizedCustomerName	string	Authorized customer name
standardEntryClassCode	string	The three-digit Standard Entry Class code based on Nacha rules.
receivingAccount	Object	AccountList
receivingParty	Object	PartyList
originatingAccount	Object	AccountList
originatingParty	Object	PartyList
returnDate	string	Date of the returned transaction to the ACH system. Format: YYYY-MM-DD
returnReasonCode	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
returnReasonDescription	string	Description as to why the ACH transaction is returned.
addendaCount	integer	Count of addenda records.
notificationOfChangeAddendaCount	integer	Count of change notifications for addenda records.
internationalAddendaCount	integer	Count of international addenda records.

Addendum

NAME	TYPE	DESCRIPTION
sequenceNumber	integer	The addenda record item number in order of sequence. Number cannot exceed 4 digits.
entryDetailSequenceNumber	string	The entry number in order of sequence. Number cannot exceed 7 digits.
paymentRelatedInformation	string	The related payment information from the addenda records. The maximum character limit is 255.

Message

NAME	TYPE	DESCRIPTION
code	string	Code for the related message.
message	string	Message associated with the code.

Page

NAME	TYPE	DESCRIPTION
pageNumber	integer	The number of the page being viewed.
pageSize	integer	The number of records per page.
totalPages	integer	The number of pages there are in total.
totalRecords	integer	The total number of transactions available in the result set.
lastPage	boolean	Indicates if the current page (page number) is the last page of the result set. Valid values: true, false

Metadata

NAME	TYPE	DESCRIPTION
messagesoptional	array	Message
page	Object	Page

PartyList

NAME	TYPE	DESCRIPTION
customerIdentificationNumber	string	The unique identification number associated with the customer.
companyName	string	The name of the corporation or institution making the request.

PartyDetail

NAME	TYPE	DESCRIPTION
customerIdentificationNumber	string	The unique identification number associated with the customer.
companyName	string	The name of the corporation or institution making the request.
customerName	string	The name of the customer.

NotificationOfChange

NAME	TYPE	DESCRIPTION
changeCode	string	The three-character change code begins with the letter 'C'. This code is applied to all NOCs to indicate the information that is being changed.
changeDescription	string	The description associated with the change code.
correctedData	string	The corrected data per the correction change code.

Errors

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.

API specific KeyBank codes and messages

HTTP
STATUS CODE CUSTOM
STATUS CODE DESCRIPTION

299

HTTP STATUS CODE	CUSTOM STATUS CODE	DESCRIPTION
299	W	`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.
400	F	`ECA-W-001 Request Validation failed.` There is missing mandatory information like `accountNumber`, `fromDate`, or `toDate`. Review values for mandatory request fields.
400	F	`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.

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.

400

ECA-W-001 Request Validation failed.

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

400

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.

Changelog

Release	API version	Change description	Impact
March 2025	1.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 2024	1.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 2024	1.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 2023	1.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 2023	1.1.5	The `mdmId` description has been updated to communicate that this field will soon deprecate in an upcoming release.	LOW
August 2023	1.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 2023	1.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 2023	1.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 2022	1.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

Key notes

Before you begin

Requirements

Account number

PAR number

Interpret the response

Health check

Request

Request example

Successful response

Response example (200)

Advanced search for ACH transactions

Request

Request example

Responses

Successful response

Response example (200)

Bad input parameter

Response example (400)

Get details about an ACH transaction with a PAR number

Request

Request example

Responses

Successful response

Response example (200)

Resource not found

Response example (400)

Schemas

AccountList

AccountDetail

AchDetailTransaction

AchListTransaction

Addendum

Message

Page

Metadata

PartyList

PartyDetail

NotificationOfChange

Errors

API specific KeyBank codes and messages

Changelog

Impact levels

We value your feedback