Tutorial: Create a Check with C# and the SOAP API

First, you will need to add the ACHeck21 Service Reference to your C# Visual Studio project. See this article on how to do that. 

After you have added a reference to the SOAP web service. Import it into your code by putting this at the top of your source file. 

using ACHeck21.ACHeck21Service;

After importing the package, we can create the SOAP client like this

ACHeck21GatewayVersion26SoapClient client = new ACHeck21GatewayVersion26SoapClient();

Part of the class name has been bolded to bring it to your attention that this part of the class name will be different if you are using a different version of the SOAP API. 

The minimum information needed to create a check is listed in the following table.

Username	Your ACHeck21 Global Gateway login username
Password	Your ACHeck21 Global Gateway login password
Client ID	The ACHeck21 Global Gateway ID of the client who received the check
Transit Number	The 9-digit ABA routing number of the check
DDA Number	The account number of the check
Check Number	The check number.
Account Type	Checking or Savings
Check Amount	The amount of the check
Entry Class Code	The type of check. This determines how it's processed and other rules like whether or not a check image is required

To begin creating a check we will gather the necessary data in our C# 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 transitNumber = "063100277";
string ddaNumber = "12345678912345"
string checkNumber = "0001";
string checkAmount = "1.00" // $1.00 check amount
AccountType accountType = AccountType.Checking; 
EntryClass entryClass = EntryClass.WEB;

This example uses the WEB entry class because it does not require check images. After we have gathered the necessary data, we create a check with the followng code.

  CreateCheckResult result = client.CreateCheck(username, 
                                                password, 
                                                clientID, 
                                                null, 
                                                null, 
                                                checkNumber, 
                                                transitNumber, 
                                                ddaNumber, 
                                                accountType, 
                                                checkAmount, 
                                                entryClass, 
                                                null, 
                                                null, 
                                                null, 
                                                null, 
                                                null); 

Assuming all of our data is correct and valid, this should create a new check on the ACHeck21 Global Gateway.

Notice that the function returns a CreateCheckResult. This object has a Message property we can use to check for errors. It also has a CheckID property which should contain the newly created check's ID (if there were no errors).

If (result.Message == null)
{    
    Console.Out.WriteLine("New Check ID is: " + result.CheckID);
}
else
{
    Console.Out.WriteLine("Unexpected Error: " + result.Message); 
}

Creating a Check with Images

In the above example, we used the WEB entry class code because it didn't require images to create the check. Some entry classes, like C21(Check21), require images. 

When creating a check that requires images, the images need to meet the following requirements.

• Both front and rear images must be sent.
• The images must be in TIFF format. 
• The images must be Base64 encoded. 

The Base64 encoding requirement means that you will usually have to encode the binary image data before creating a check.

For example, if you had scanned and stored front and rear images of a check and stored it on a hard drive, you would prepare them with the following code. 

// load the image data from the file system.
byte[] frontBytes = File.ReadAllBytes("FrontOfCheck.tiff");
byte[] rearBytes = File.ReadAllBytes("RearOfCheck.tiff");

// Convert the data into a base64 string
string frontBase64 = Convert.ToBase64String(frontBytes);
string rearBase64 = Convert.ToBase64String(rearBytes);

You can then use these Base64 strings in the CreateCheck function call.

  CreateCheckResult result = client.CreateCheck(username, 
                                                password, 
                                                clientID, 
                                                null, 
                                                null, 
                                                checkNumber, 
                                                transitNumber, 
                                                ddaNumber, 
                                                accountType, 
                                                checkAmount, 
                                                EntryClass.C21, // C21 Entry class
                                                frontBase64, // front image
                                                rearBase64, // rear image
                                                null, 
                                                null, 
                                                null);