Finding Returned Transactions

After a check has been settled, it can be returned for a variety of reasons. At some point, you may need to find check transactions that have been returned. You can use the API to find transactions that were returned on a particular date or a range of dates.

C#

Client client = new Client();
client.SetBasicAuth("[e-mail]", "notArealpassw0rd");

var returns = client.FindReturnsAsync(clientid, new DateTime(2016, 12, 23), null, 0, 500).Result;

Console.WriteLine("Total Returns found: {0}", returns.RecordsTotal);
Console.WriteLine("Returns in this response: {0}" returns.Returns.Count);
Console.WriteLine("First Return Amount: {0:C}" returns.Returns[0].Amount);
Console.WriteLine("First Return Code: {0}",  returns.Returns[0].ReturnCode);
Console.WriteLine("First Return Message: {0}", returns.Returns[0].ReturnMessage);
Console.WriteLine("First Return Transaction id: {0}", returns.Returns[0].DocumentId);

// Example output
//
//Total Returns found: 1
//Returns in this response: 1
//First Return Amount: $3000.00
//First Return Code: R01
//First Return Message: Insufficent Funds
//First Return Transaction id: 109838475

Java

ApiClient defaultClient = Configuration.getDefaultApiClient();
        
HttpBasicAuth auth = (HttpBasicAuth)defaultClient.getAuthentication("basicAuth");
auth.setUsername("[e-mail]);
auth.setPassword("notArealpassw0rd");

// create a date of 12:00am 12/23/2016 in arizona time
Calendar cal = GregorianCalendar.getInstance();
cal.setTimeZone(TimeZone.getTimeZone("US/Arizona"));
cal.set(2016, 11, 23, 0, 0, 0);
cal.set(Calendar.MILLISECOND, 0);

ReturnsQueryResult returns = apiInstance.findReturns("default", cal.getTime(), cal.getTime(), 0, 500);

System.out.println("Total Returns found: " + returns.getRecordsTotal());

List<ModelReturn> returnList = returns.getReturns();
System.out.println("Returns in this response: " + returnList.size());
System.out.println("First Return Amount: " +  returnList.get(0).getAmount());
System.out.println("First Return Code: " +  returnList.get(0).getReturnCode());
System.out.println("First Return Message: " + returnList.get(0).getReturnMessage());
System.out.println("First Return Transaction id: " +  returnList.get(0).getDocumentId());

// Example output
//
//Total Returns found: 1
//Returns in this response: 1
//First Return Amount: 3000.0
//First Return Code: R01
//First Return Message: Insufficent Funds
//First Return Transaction id: 109838475

Objective-C

[[ACHConfiguration sharedConfig] username] = @"[e-mail]";
[[ACHConfiguration sharedConfig] password] = @"notArealpassword";

[NSTimeZone setDefaultTimeZone:[NSTimeZone timeZoneWithName:@"US/Arizona"]];
    
NSDateFormatter *formatter = [[NSDateFormatter alloc] init];
formatter.dateFormat = @"MM/dd/yyyy";
NSDate *start = [formatter dateFromString:@"12/23/2016"];
    
ACHChecksApi *apiInstance = [[ACHChecksApi alloc] init];

[apiInstance findReturnsWithClientId:clientid startDate:start endDate:nil offset:@0 limit:@10 completionHandler:^(ACHReturnsQueryResult *output, NSError *error) {
  if (output) {
    NSLog(@"%@", output);
  }
  if (error) {
    NSLog(@"Error calling ACHChecksApi->findReturns: %@", error);
  }
}];

//Example output below
/*{
    first =     {
        href = "https://acheck21-gateway-test.azurewebsites.net/api/v1/checks/9900000301/returns?offset=0&limit=1&startDate=12%2F23%2F2016%2000%3A00%3A00";
    };
    last =     {
        href = "https://acheck21-gateway-test.azurewebsites.net/api/v1/checks/9900000301/returns?offset=0&limit=1&startDate=12%2F23%2F2016%2000%3A00%3A00";
    };
    limit = 10;
    next =     {
        href = "https://acheck21-gateway-test.azurewebsites.net/api/v1/checks/9900000301/returns?offset=0&limit=1&startDate=12%2F23%2F2016%2000%3A00%3A00";
    };
    offset = 0;
    prev =     {
        href = "https://acheck21-gateway-test.azurewebsites.net/api/v1/checks/9900000301/returns?offset=0&limit=1&startDate=12%2F23%2F2016%2000%3A00%3A00";
    };
    recordsTotal = 1;
    returns =     (
                {
            amount = 3000;
            documentId = 91210010;
            receivedOn = "2016-09-19T00:00:00-0700";
            returnCode = R01;
            returnMessage = "Insufficient Funds";
            returnedOn = "2016-12-23T00:00:00-0700";
            traceNumber = 123456780812665;
        }
    );
}*/

Generated documentation for the REST endpoint is here