Tutorial: Find Checks using the ACHeck21 PHP API

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;
}