Introduction and Overview

Overview

The variety of functionality available through the Check Commerce API is described throughout this manual. The following chart helps distinguish the purpose of each interface to help you decide if and when they should be used for your business. Further guidance in how to use the interfaces will be provided in each of the corresponding sections.

Interface	Purpose
ACH in Real-Time	To submit ACH Debits or Credits in real-time, possibly with consumer verification. To retrieve the current status of a single ACH Debit or Credit submitted previously. To submit an Authorize request, which performs consumer verification without actually creating an ACH transaction?
ACH Batch Upload	To submit a daily batch of ACH Debits or Credits. This section also describes the file formats that you may submit.
Status File Download	To retrieve the current status of many transactions. This section also describes the file formats that you may receive.
Recurring Consumers & Subscriptions	To submit consumer information and schedules for future billing on a regular basis. This section also describes the file formats used to convey this data.

Parameter Mediums

In general, there are 3 mediums by which parameters may be submitted to Check Commerce interfaces:

CGI
XML
Web Service

Certain interfaces support only certain parameter mediums, as follows:

Interface	CGI	XML	WebService
ACH in Real-Time	Yes	Yes	Yes
ACH Batch Upload	Yes	No	No
Status File Download	Yes	No	No
Recurring Consumers and Subscriptions	Yes	No	No

This chart indicates the available means of submitting parameters to start transmitting a file, not the available formats of the file itself. See later sections for details on file formats.

The example code provided with this document usually demonstrates submitting parameters via all of the available mediums.

The differences between these 3 mediums are described presently.

CGI ( Common Gateway Interface )

The CGI standard involves making a straightforward HTTPS request. Parameters are specified as name-value pairs, in a "name=value" format. Both the GET and POST paradigms are supported. Parameters designated as optional may be simply omitted from the request.

Note that if you build a CGI querystring for submission by the GET method, the parameter values must be encoded as per RFC1738. In Microsoft .NET languages, this can be achieved via the System.Web.HttpUtility.UrlEncode method.

Example CGI querystring request using the GET method:

/EpnPublic/ACH.aspx?Version=1.4.2&Method=Debit&Login=demo&Password=demo&ReferenceNumber=123456&Name=Ted+Tester&Amount=1.00&RoutingNumber=122187238&AccountNumber=123456

XML ( Extensible Markup Language )

Some interfaces accept an XML document containing the parameters which form the request. Each parameter is embedded in an XML tag, where the tag's name matches the parameter's name, and the text inside the tag hold the parameter's value. Parameters designated as optional may be simply omitted from the request. The XML is then sent using the POST method to the appropriate URL. These interfaces can also return a response in XML.

Remember that XML is, by definition, always case-sensitive.

Example XML Request:

<?xml version="1.0"?>
<ACH>
	<Method>Debit</Method>
	<Version>1.4.2.36</Version>
	<Login>demo</Login>
	<Password>demo</Password>
	<ReferenceNumber>123456</ReferenceNumber>
	<Name>Joe Blow</Name>
	<Amount>1.00</Amount>
	<RoutingNumber>122187238</RoutingNumber>
	<AccountNumber>123456</AccountNumber>
</ACH>

Web Services ( SOAP )

WebServices can be invoked through the libraries available to many programming languages.

If you're using Visual Studio .NET, you can create a reference to a WebService within your project:

Highlight your project in the Solution Explorer, and either right-click, or open the Project menu from the main menu bar. Then choose "Add Web Reference…"

Enter the URL of one of the CheckCommerce WebServices.

Once the WebService is found, give it a name that is meaningful within your project.

This essentially generates a class having static methods which conveniently wrap calls to the WebService.

Alternately, you could utilize the pre-generated C# code accompanying this document, found in the Examples\WebReferences subdirectory.

Once the wrapper class is available to your project one way or another, you simply call the static methods in order to invoke the WebService.

For optional parameters, a null value may be passed.

Web Services Using CGI

In addition to using a library to invoke WebServices, they can also be invoked using an ordinary HTTPS request. The only difference from making a normal CGI request as described above when calling a WebService URL is that the URL should have the method name appended to the path. For example, to call the "Cancel" method of the "ACH Real-Time" WebService, the URL might look like this:

/EpnWebServices/ACH_v1_4_2_18.asmx/Cancel?Version=1.4.2.36&ResponseXML=False&Test=False&Login=demo&Password=demo&Notes=&TransactionID=123

Note that WebServices require that optional parameters always be explicitly named even when no value is being passed. In the above example, the Notes field must be submitted even though it is blank.

Consumer Verification

If you have LexisNexis and/or Account Check verification enabled on your account, then extra measures will be taken as transactions are submitted. The outcomes of LexisNexis and/or Account Check verification will give scores which must total zero or greater. A negative total will cause the transaction to be Declined along with the message "Consumer Verification Negative".

ACH in general requires that the bank routing number indicate a "normal" account, such as a Checking, Savings, Credit Union, or Thrift account. Account Check will decline Government, Electronic, and Travelers’ Cheque accounts up front. Checks not valid for ACH processing will return.

Pre-Authorization

Check Commerce allows for pre-authorization of transactions. This may be required for Guarantee merchants. In some cases, you will want to pre-authorize and verify the transaction details for subsequent debits. The amount, and banking information must match. Subsequent Debits do not go through verification if the original Authorization already did.

Possible Error	Possible Remedy
Authorized dollar amount does not match amount submitted.	The amount does not match the Pre-authorization amount or “Skip Amount Validation for Previously Authed Debit” is not turned on.
Authorization not found.	The Authorization needs to be performed prior to debiting the account.
Bank account and routing number provided do not match the authorization	Please ensure the account and routing number match Authorization.
Authorization was declined.	The Authorization was declined.

Redundant Servers

Check Commerce employs redundant servers in multiple physical locations to minimize downtime in the event of a hardware failure, power outage, etc. In an emergency, we are able to reroute traffic to alternate servers within 5 minutes.

One side effect of this is that, depending on the present server configuration, transactions submitted via these interfaces may not appear on the Merchant Center website immediately. It may take up to 1 hour for new transactions to appear on the website, depending on workload/traffic, etc.

It's crucial that you access our servers by the exact host names listed for each interface, not by the IP addresses. This way we will be able to redirect your traffic to different servers as needed.

Outgoing Firewall Connectivity

If you are blocking outgoing connections from your servers, it will be necessary for you to allow access to ALL of Check Commerce’s available DNS names. Outgoing connections from your servers should be allowed for the following FQDNs:

www.CheckCommerce.com and www.CheckGateway.com

This is in contrast to our legacy IP whitelisting. We are using a content delivery network that can change IPs often. You should be whitelisting by our DNS.