Guides

Creating a transaction

Suggest Edits

Unlike the introductory tutorial on creating a simple transaction, this page goes into more detail on the various options available for creating ACH and Check21 transactions.

Setting creation options

When creating a transaction, the first thing is to initialize an object with the necessary options. The code sample below initializes an object for creating a transaction. 

var createCheckParams = new CreateCheckParams()
{
  IndividualName = "Nobody J. Smith",
  RoutingNumber = "063100277",
  AccountType = AccountType.Checking,
  Amount = 100.0m,
  CheckNumber = "1001",
  AccountNumber = "12345678912345",
  EntryClass = EntryClass.C21,
  Addenda = new ObservableCollection<string>(new string[]{ "test addenda"}),
  // Base64 encoded image. Concatenated for brevity
  FrontImageEncoded = "R0lGODlhPQBEA...",
  // Base64 encoded image. Concatenated for brevity
  RearImageEncoded = "R0lGODlhPQBEA...",
  Micr = null,
  PostingDate = DateTime.Now.Date.AddDays(2);
};

createCheckParams.Attachments = 
  	new ObservableCollection<CreateAttachmentParams>();
var attachment = new CreateAttachmentParams()
{
  Id = "NY-123456789",
  // Base64 encoded image. Concatenated for brevity
  ImageEncoded = "R0lGODlhPQBEA...",
  Type = AttachmentType.DriversLicense
});
createCheckParams.Attachments.Add(attachment);

var createCheckParams = {
  "accountNumber": "123456787",
  "accountType": "Checking",
  "addenda": [
    "test addenda"
  ],
  "amount": 12.34,
  "attachments": [
    {
      "id": "NY-123456789",
      // Base64 encoded image. Concatenated for brevity 
      "imageEncoded": "R0lGODlhPQBEA...", 
      "type": "DriversLicense"
    }
  ],
  "checkNumber": "1001",
  "entryClass": "C21",
  // Base64 encoded image. Concatenated for brevity 
  "frontImageEncoded": "R0lGODlhPQBEA...", 
  // Base64 encoded image. Concatenated for brevity 
  "rearImageEncoded": @",
  "individualName": "Nobody J. Smith", 
  "micr": null,
  "routingNumber": "021000021"
}

ACHCreateCheckParams *values = [[ACHCreateCheckParams alloc] init];

[values setAmount:@100.0];
[values setAccountNumber: @"1234567890"];
[values setAddenda:@[@"Test Addenda"]];
[values setEntryClass:@"C21"];
[values setIndividualName:@"Nobody J Smith"];
[values setRoutingNumber:@"063100277"];
[values setCheckNumber:[@(checkNum) stringValue]];
[values setAccountType:@"Checking"];
[values setRearImageEncoded:@"R0lGODlhPQBEAP..."];
[values setFrontImageEncoded:@"R0lGODlhPQBEAP..."];

    
ACHCreateAttachmentParams *attachment = [[ACHCreateAttachmentParams alloc] init];
[attachment set_id:@"NY-123456789"];
[attachment setType:@"DriversLicense"];
[attachment setImageEncoded:@"R0lGODlhPQBEAP..."];
[values setAttachments:@[attachment]];

CreateCheckParams values = new CreateCheckParams(); // CreateCheckParams | 
values.setAccountNumber("1234567890");
values.setAccountType(AccountType.CHECKING);
values.addAddendaItem("Test Addenda");
values.setAmount(new BigDecimal(100.0));
values.setCheckNumber(checkNumber);
values.setEntryClass(EntryClass.C21);
// Base64 encoded image. Concatenated for brevity 
values.setFrontImageEncoded("R0lGODlhPQBEAP...");
// Base64 encoded image. Concatenated for brevity 
values.setRearImageEncoded("R0lGODlhPQBEAP...");
values.setIndividualName("Nobody J Smith");
values.setMicr(null);
values.setRoutingNumber("063100277");

CreateAttachmentParams attachment = new CreateAttachmentParams();
attachment.setId("NY-123456789");
attachment.setType(AttachmentType.DRIVERSLICENSE);
// Base64 encoded image. Concatenated for brevity 
attachment.setImageEncoded("R0lGODlhPQBEAP...");

In the example above, we used almost every available parameter for demonstration purposes.

  • Amount - transaction amount
  • Micr - optional micr line from a check. If this value is set, the routing number, account number, and check number should not be set. The scenario for using this parameter is when you are reading the micr line from a physical check. This was set to null or an empty string in the example code because we are setting the account, routing, and check numbers.
  • Account Number - The identifying number of the bank account you wish to debit or credit. The length of this number is bank specific.
  • Routing Number - The ABA routing number of the bank account you wish to debit or credit. This is a nine digit code used to identify financial institutions.
  • Check Number - The identifying number of the "check". This should be unique per transaction. The account, routing, and check numbers uniquely identify a transaction. These fields are used to detect duplicate transactions.
  • Individual Name - The name of the other party in the transaction (i.e. not you).
  • Addenda - Arbitrary text data to attach to the transaction.
  • Account Type - The account type. In general, banks will have different account types attached to a single account number. The valid values are "Savings" or "Checking".
  • Entry Class - The ACH entry class for the transaction or in the case of a Check21 transaction this should be "C21". The entry class you use depends on your particular use case.
  • Front Image Encoded - A base64 encoded tif image of the front of the check. This is only required for Check21 transactions (entry class of "C21").
  • Rear Image Encoded - A base64 encoded tif image of the rear of the check. This is only required for Check21 transactions (entry class of "C21").
  • Attachments - Optional supporting documents. See the attachments section below for more info.
  • PostingDate - Optional date to process the check. If left blank, the processing date is set to the current date. If it falls on a weekend or holiday and the merchant isn't set up to process on the weekend, it will process on the next business day.
  • ClientTag - Optional user defined date to attach to the transaction. This field can't be used for transactions with images. That is why it isn't in the example above.

Attachments

Attachments represent optional supporting documents for a transaction. For now, only driver's licenses and payment stubs are explicitly supported by the API. Attachment parameters are

  • Id - an attachment specific identifier. For driver's licenses, this should be two digit state code followed by a dash followed by the driver's license number with no dashes. In the example above this is "NY-123456789". Issuing state is NY (New York) and the driver's license is 123456789. For stubs this can be blank or any arbitrary string.
  • Type - This can be DriversLicense or Stub
  • Image Encoded - The base64 encoded tif image of the attachment.

Creating the transaction

Once all the parameters are set, we are ready to go ahead and create the transaction. 

Client client = new Client();
client.BaseUrl = "https://gateway.acheck21.com/GlobalGateway";
client.SetBasicAuth("[email protected]", "notArealpassw0rd");
var check = client.CreateCheckAsync("default", createCheckParams).Result;

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

var settings = {
  "async": true,
  "url": "https://gateway.acheck21.com/GlobalGateway/api/v1/checks/default",
  "method": "PUT",
  "headers": {
    	// this header needs to be set on every REST call.
   		"Authorization": "Basic " + btoa(username + ":" + password)
  },
  "processData": false,
  "data" : JSON.stringify(createCheckParams),
  "contentType" : "application/json"
}

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

ACHConfiguration *config = [ACHConfiguration sharedConfig];
[config setUsername:@"[email protected]"];
[config setPassword:@"notArealpassw0rd"];

ACHChecksApi *apiInstance = [[ACHChecksApi alloc] init];
[apiInstance createCheckWithClientId:@"default"
	values:values
 	completionHandler: ^(ACHCheck* output, NSError* error) {
   	if (output) {
    	NSLog(@"%@", output);
   	}
   	if (error) {
    	NSLog(@"Error calling ACHChecksApi->createCheck: %@", error);
   	}

}];

ApiClient defaultClient = Configuration.getDefaultApiClient();
        

HttpBasicAuth auth = (HttpBasicAuth)defaultClient.getAuthentication("basicAuth");
auth.setUsername("[email protected]);
auth.setPassword("notArealpassw0rd");

ChecksApi apiInstance = new ChecksApi();
Check result = apiInstance.createCheck(clientId, values);
System.out.println(result);

Check object

On successful creation of a transaction, the api will return a Check object. It's described below as a data structure for each respective programming language.

public partial class Check
{ 
	public string Href; 
  public long DocumentId; 
  public string ClientId; 
  public string IndividualName; 
  public string CompanyName; 
  public string ClientTag;
  public AccountType AccountType; 
  public decimal Amount; 
  public string RoutingNumber; 
  public string AccountNumber; 
  public string CheckNumber; 
  public EntryClass EntryClass; 
  public string EntryDescription; 
  public System.DateTime ReceivedOn; 
  public System.DateTime? EditedOn; 
  public string EditedBy; 
  public System.DateTime? DeletedOn; 
  public string DeletedBy; 
  public System.DateTime? EffectiveDate;
  public System.DateTime? PostingDate;
  public System.Collections.ObjectModel.ObservableCollection<string> Addenda; 
  public string Error; 
  public TransactionState CurrentState; 
  public string FrontImageUrl; 
  public string RearImageUrl; 
  public ResourceLink Settlements; 
  public ResourceLink Returns; 
  public ResourceLink Attachments;
}

{
        href : <String>,
        documentId : <Number>,
        clientId : <Number>,
        individualName : <String>
        companyName : <String>,
        accountType : <String>,
        amount : <Number>,
        routingNumber : <String>,
        accountNumber : <String>,
        checkNumber : <String>,
        entryClass : <String>,
        entryDescription : <String>,
        receivedOn : <Date>,
        editedOn : <Date>,
        editedBy : <String>,
        deletedOn : <Date>,
        deletedBy : <String>,
        error : <String>,
        currentState : <String>,
        frontImageUrl : <String>,
        rearImageUrl : <String>,
        settlements : <Object>,
        returns : <Object>,
        attachments : <Object> 
    }

public class Check   {
  private String href = null;
  private Long documentId = null;
  private String clientId = null;
  private String individualName = null;
  private String companyName = null;
  private AccountType accountType = null;
  private BigDecimal amount = null;
  private String routingNumber = null;
  private String accountNumber = null;
  private String checkNumber = null;
  private EntryClass entryClass = null;
  private String entryDescription = null;
  private Date receivedOn = null;
  private Date editedOn = null;
  private String editedBy = null;
  private Date deletedOn = null;
  private String deletedBy = null;
  private List<String> addenda = new ArrayList<String>();
  private String error = null;
  private TransactionState currentState = null;
  private String frontImageUrl = null;
  private String rearImageUrl = null;
  private ResourceLink settlements = null;
  private ResourceLink returns = null;
  private ResourceLink attachments = null;
}

@interface ACHCheck : ACHObject
  
@property(nonatomic) NSString* href;
@property(nonatomic) NSNumber* documentId;
@property(nonatomic) NSString* clientId;
@property(nonatomic) NSString* individualName;
@property(nonatomic) NSString* companyName;
@property(nonatomic) NSString* accountType;
@property(nonatomic) NSNumber* amount;
@property(nonatomic) NSString* routingNumber;
@property(nonatomic) NSString* accountNumber;
@property(nonatomic) NSString* checkNumber;
@property(nonatomic) NSString* entryClass;
@property(nonatomic) NSString* entryDescription;
@property(nonatomic) NSDate* receivedOn;
@property(nonatomic) NSDate* editedOn;
@property(nonatomic) NSString* editedBy;
@property(nonatomic) NSDate* deletedOn;
@property(nonatomic) NSString* deletedBy;
@property(nonatomic) NSArray<NSString*>* addenda;
@property(nonatomic) NSString* error;
@property(nonatomic) NSString* currentState;
@property(nonatomic) NSString* frontImageUrl;
@property(nonatomic) NSString* rearImageUrl;
@property(nonatomic) ACHResourceLink* settlements;
@property(nonatomic) ACHResourceLink* returns;
@property(nonatomic) ACHResourceLink* attachments;

@end
  • href - REST url for this object
  • documentId - Unique identifier for the transaction
  • clientId - Unique identifier for the owner of the transaction
  • individualName - Name of other party in the transaction
  • companyName - Corporate name of the other party in the transaction
  • accountType - Checking or Savings.
  • amount - Amount of the transaction. Negative values are credits.
  • routingNumber - ABA routing number.
  • accountNumber - Bank account number. See description in creation options above.
  • checkNumber - Check number. See description in creation options above.
  • entryClass - ACH entry class or in the case of Check21 transactions "C21". See descriptions in creation options above for more information.
  • entryDescription - Additional field for describing entry class.
  • receivedOn - Date transaction was received.
  • editedOn - It's possible for authorized users to edit transactions in the ACHeck21 web portal. If they do, this field holds the date it was last edited on.
  • editedBy - It's possible for authorized users to edit transactions in the ACHeck21 web portal. If they do, this field holds the user it was last edited by.
  • deletedOn - If the current state of this transaction is Deleted, this holds the date it was deleted.
  • deletedBy - If the current state of this transaction is Deleted, this holds the user it was deleted by.
  • effectiveDate - The date this transaction was processed on.
  • postingDate - The date this transaction is scheduled to post on. Note that this field is only relevant for pending items. Once it leaves the pending state, this field will be null.
  • addenda - arbitrary strings attached to this transaction.
  • error - If the transaction has a current state of Rejected, the error message associated with this transaction.
  • currentState - As a transaction is processed, it's state changes to represent the stage of the processing workflow it's in. This field represents the current state. The following are the possible states
  • Pending - Initial state of a transaction.
  • Rejected - There was a problem with this transaction. See the error field.
  • Deleted - This transaction was deleted.
  • Suspect - This transaction has been quarantined for going over a preset limit. Note that this is an optional feature enabled per customer. The system doesn't do this without customer approval.
  • Settling - This transaction has been sent to the bank
  • Settled - This transaction should be complete.
  • Returned - This transaction has been returned by the bank.
  • frontImageUrl - the url of the front check image. Note that this field will always be present even if there are no images for the transaction.
  • rearImageUrl - the url of the rear check image. Note that this field will always be present even if there are no images for the transaction.
  • settlements - the REST resource url to retrieve the settlements for this transaction. This field will always be present even if there are no settlements for the transaction
  • returns - the REST resource url to retrieve the returns for this transaction. This field will always be present even if there are no returns for the transaction.
  • attachments - the REST resource url the retrieve the attachments for this transaction. This field will always be present even there are no attachments for this transaction.

Updated over 5 years ago