Live Support Agent

Tutorial: Find Checks using the ACHeck21 PHP API

Ryan Ackley -

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

If you installed the API using Composer, you can add the API to your PHP source file using Composer's autoload

<?php 
require_once 'vendor/autoload.php';

If you manually installed it, you will need to require the path you downloaded it to as well as the path to Unirest.

<?php
// Only do this if you are NOT using Composer
require_once '/path/to/acheck21-php/acheck21.php'; require_once '/path/to/unirest-php/src/Unirest.php';

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 

UploadDate=between,2015-01-01,2015-01-31

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

UploadDate=between,2015-01-01,2015-01-31&EntryClass=equal,WEB

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 

Equal
NotEqual
LessThan
LessThanOrEqual
GreaterThan
GreaterThanOrEqual
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

$username = "nobody@domain.com"; // this is not a real username
$password = "NotARealP@ssword"; // this is not a real password
$clientID = "00000000000"; // this is not a real client id
$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

$results = ACHeck21::findChecksDetails($username, 
$password,
$clientID,
$query);

Alternatively, you could look for pending checks

$results = ACHeck21::findPendingChecksDetails($username, 
$password,
$clientID,
$query);

The API call returns the deserialized xml returned from the REST call to the Global Gateway's web service. You will need to access the CheckInfo property to access the check data. This can either be an object (in the case of a single result) or an array of objects. Use the built-in PHP function is_array to determine which one. 

$checkInfo = $results->CheckInfo;
if (is_array($checkInfo)) {
// gets the check id of the first check in the list of results
$checkId = $checkInfo[0]->CheckID;
}
else {
// gets the check id of the only check result
$checkId = $checkInfo->CheckID;
}

 

Have more questions? Submit a request

Comments