Searching transactions

A common scenario is retrieving a list of transactions based on search criteria. The API supports searching by date and transaction status.

// direct REST call from Javascript
var username= "[email protected]",
    password = "notArealpassw0rd";

var today = new Date()
var monthAgo = new Date(new Date().setDate(today.getDate()-30));

var filter = {
	startDate : monthAgo,
  endDate : today,
  offset : 0,
  limit : 500
}
var queryString = $.param(filter);

var settings = {
  "async": true,
  "url": "https://gateway.acheck21.com/GlobalGateway/api/v1/checks/default?" + queryString,
  "method": "GET",
  "headers": {
    	// this header needs to be set on every REST call.
   		"Authorization": "Basic " + btoa(username + ":" + password)
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

// get all transactions for the last month
ChecksApi apiInstance = new ChecksApi();
long monthInMillis = 60L * 60L * 24L * 30L * 1000L;
Date now = new Date();
Date monthAgo = new Date(System.currentTimeMillis() - monthInMillis);

string clientId = "default";
Date startDate = monthAgo;
Date endDate = now;
List<String> currentStates = null;
int offset = 0;
int limit = 500;
CheckQueryResult result = apiInstance.getChecks(clientId, 
                                                startDate, 
                                                endDate, 
                                                currentStates, 
                                                offset, 
                                                limit);
System.out.println(result);

// get all transactions for the last month
NSTimeInterval monthInSec = 60 * 60 * 24 * 30;
NSDate *today = [NSDate date];
NSDate *monthAgo = [NSDate dateWithTimeIntervalSinceNow:-monthInSec];
ACHChecksApi *apiInstance = [[ACHChecksApi alloc] init];

[apiInstance getChecksWithClientId:@"default"
 startDate:monthAgo
 endDate:today
 currentStates:nil
 offset:@0
 limit:@500
 completionHandler: ^(ACHCheckQueryResult* output, NSError* error) {
   if (output) {
     NSLog(@"%@", output);
   }
   if (error) {
     NSLog(@"Error calling ACHChecksApi->getChecks: %@", error);
   }
 }];

// get all transactions for the last month
var endDate = DateTime.Now;
var startDate = endDate.AddDays(-30);

var checks = client.GetChecksAsync("default", startDate, endDate, null, 0, 500).Result;

Parameters

startDate - Inclusive start date and time to begin searching for transactions
endDate - Inclusive end date and time to stop seaching for transactions
currentStates - The transaction states to include in the search. Valid values are Pending, Deleted, Rejected, Settling, Settled, Suspect, and Returned.
- Pending - transaction received but hasn't been processed.
- Rejected - transaction failed with an error. Transactions created via this API will never have this status.
- Deleted - transaction was deleted. Transactions created via this API will never have this status.
- Settling - transaction has been sent to bank but funds have not been posted to clearing account.
- Settled - transaction has completed. Funds are available in the clearing account. NOTE: This is not the same as merchant funding.
- Suspect - transaction has been marked as suspect and been quarantined. Transactions created via this API will never have this status
- Returned - transaction has been rejected by the bank.
offset - The beginning index of the entire result set to return. This (along with limit) is used for paging through the list. See paging below
limit - The max number of results to return.

Result

The API returns a query result object.

public class CheckQueryResult   {
  private Integer recordsTotal = null;
  private Integer offset = null;
  private Integer limit = null;
  private ResourceLink first = null;
  private ResourceLink prev = null;
  private ResourceLink next = null;
  private ResourceLink last = null;
  private List<Check> checks = new ArrayList<Check>();
}

@interface ACHCheckQueryResult : ACHObject


@property(nonatomic) NSNumber* recordsTotal;

@property(nonatomic) NSNumber* offset;

@property(nonatomic) NSNumber* limit;

@property(nonatomic) ACHResourceLink* first;

@property(nonatomic) ACHResourceLink* prev;

@property(nonatomic) ACHResourceLink* next;

@property(nonatomic) ACHResourceLink* last;

@property(nonatomic) NSArray<ACHCheck>* checks;

@end

The fields of the query result object. The checks field contains the transactions and the rest of the fields relate to paging. Depending on the offset and limit passed into the search function, checks may be a subset of transactions matching the search criteria. See Paging section below for more details.

checks - List of transactions matching the search criteria. If recordsTotal > limit or offset != 0, this is a subset of matching transactions.
recordsTotal - Total number of transactions matching the search criteria.
offset - Starting offset of returned list inside of complete set of matching transactions.
limit - The limit passed into the search query.
first - A link to the REST endpoint to retrieve the first page of results.
prev - A link to the REST endpoint to retrieve the previous page of results.
next - A link to the REST endpoint to retrieve the next page of results.
last - A link to the REST endpoint to retrieve the last page of results.

Paging

A key component of retrieving search results is Paging. A search query may return 1000's of transactions but displaying these to the user is not practical. Paging allows you to retrieve small chunks of results for a query then page through the results in response to a user interaction (i.e. clicking "next page" button).

To facilitate paging, the API supports passing in an offset and limit when searching transactions. offset represents the start index where the page begins in set of all transactions that match the search criteria. limit represents the page size or the max number of results that will be returned by the API call.

For example, if you wanted to page transactions ten at a time you would set offset=0 and limit=10 for the first page, offset=10 and limit=10 for the second page, offset=20 and limit=10 for the third page, etc.