Tutorial: Find Checks using the ACHeck21 Java API

Ryan Ackley -

Before getting started with this tutorial, make sure you have installed the ACHeck21 Java API. 

Once you have the Java API installed, you need to import the main ACHeck21 API class at the top of the file you plan on using it from

 import com.acheck21.java.ACHeck21;

Query Language

To find checks, you will need to construct a query that specifies search criteria. The query is expressed as <Field>=<Comparison Operator>,<Field Criteria>,<Field Criteria>,...

For example, to find checks uploaded between January 1, 2015 and January 31, 2015, the query would look like 


In the above example, the Field we're setting criteria for is UploadDate. The Comparison Operator we're using is between. The Field Criteria are the two dates: 2015-01-01 and 2015-01-31.

It is possible to specify search criteria for more than one field at a time by joining multiple queries with an ampersand symbol (&). If you specify more than one query, the API will only return results that satisfy all specified queries. 

For example, you can search for checks uploaded between January 1, 2015 and January 31, 2015 and that have an EntryClass equal to "WEB" using the following query


Query-able Check fields 

UploadDate The date the batch was originally uploaded
ToFedDate The date the item was deposited
Amount  The check amount
SeqNbr The user-assigned sequence (batch) number for the batch in which the item was originally uploaded
Name The individual name on the item
TransitNbr The ABA routing / transit number
AccountNbr The bank account number (DDA)
CheckNbr The actual check number / item sequence number
ClientTag The original document client tag sent when the item was uploaded
EntryClass The ACH entry class code.  Legal values are: 937, ARC, BOC, PPD, TEL, WEB, CCD

Comparison Operators 

Basic Comparison operators. Mostly self explanatory.
Between Specifies an inclusive range of allowed values
IN Specifies a list of allowed values
Begins Specifies a single string value that the field should start with
Ends Specifies a single string value that the field should end with
Contains Specifies a single string vlaue that the field should contain
Like Specifies a single SQL string pattern that the field should contain

More information can be found in the XML query language document. Although, that document is focused on the xml version of the query language, the same concepts apply. 

Using the API to find checks

Once you have successfully constructed a query, it's time to use the API to find checks. There are two methods available in the API for finding checks: findChecksDetails and findPendingChecksDetails. 

findChecksDetails is used for finding checks that have already been processed for the gateway. findPendingChecksDetails is for finding checks that are still waiting to be processed. 

To begin finding checks we will initialize the required fields in our code

String username = "nobody@domain.com"; // this is not a real username
String password = "NotARealP@ssword"; // this is not a real password
String clientID = "00000000000"; // this is not a real client id
String query =
"UploadDate=between,2015-01-01,2015-01-31" // one of the
// examples from above.

After we have initialized the required data, we will make the API call for finding processed checks

List<CheckResult> checks = ACHeck21.findChecksDetails(username, 

Alternatively, you could look for pending checks

List<CheckResult> checks = ACHeck21.findPendingChecksDetails(username, 

The API call returns a list of CheckResult objects. The source code for this data type is here. You can use this to access all of the data contained in a Check. 


Have more questions? Submit a request