Reading and writing x9 files can quickly become a complex process. To help with that, the X9Utilities Write-Translate functions are designed with the purpose of making the process of writing and reading x9 files as easy as possible.
- There are a large number of record types and data fields, all of which have very specific value and alignment requirements.
- There are variable length records (especially for images) that must have their data elements and lengths correctly formatted to allow the file to be parsed.
- There are multiple formats associated with the insertion of credits, since they were not covered by the early x9.37 standards. This impacts the credit format, where they are inserted into the x9 file, and their impact on trailer record counts and amounts.
- Most x9 files must be created using the EBCDIC character set (not ASCII) which further complicates the creation process.
- Finally and most importantly, many financial institutions have implemented their own x9 file variant requirements, which further complicate an already difficult situation.
The Write and Translate functions are designed with the purpose of making this process as easy as possible. By using these tools, you can concentrate on the actual x9 data content and not the underlying complexities associated with x9 files.
Write is one of the most powerful x9 file creation tools that you will find anywhere in the marketplace today. Write has been designed to be easily incorporated into your application environment. It creates x9 files from a simple CSV (which defines your items) and a statically defined HeaderXml definition (which defines the x9 file attributes). Although the CSV can be provided in multiple formats, our recommended format has a single row per item, allowing it to be easily created and viewed. The HeaderXml file has 100+ parameters which allows the x9 file to be written specifically to the requirements provided by your financial institution in their companion document. All of the complexity of adapting to the those requirements are satisfied through the HeaderXml definition. Write is simple, straight forward, and very easy to use.
Translate is provided within X9Utilities for completeness, but in reality will be seldom used in most environments. Translate creates a CSV file in a format that can be used as input to write (they share a common CSV format). In this way, Translate can be used to create a sample CSV from an existing x9 file to provide some insight into the process. However, in the real world, our Export function would more typically be used to convert an x9 file to an output CSV, since the entire definition of the x9 file on a record and field basis is fully retained when using Export.
The CSV file begins with an optional header line and is terminated with an “end” line, as follows:
headerXml parameter line (optional since this can also be provided on the command line)
zero or more items
end
CSV Format
Several notes about the CSV file format are as follows:
- Although the first line of the CSV file can point to the HeaderXml file to be used by Write, this is optional since that directive can instead be provided as a command line parameter using the (“xml:” command line option).
- A zero items CSV file is totally valid and will result in the creation of a file with record types 01, 10, 90, and 99.
- Quotes around numeric fields are optional and never required.
- Quotes around alpha fields are only required when the value contains embedded blanks (since a blank will be considered the end of the input line if it is encountered outside of a quoted field). Make sure you include quotes around field values that potentially can contain blanks. This is especially true of file names.
- Our recommended format for Write uses a “t25” line that contains both item and image information. The remaining information is specified in the HeaderXml definition, which allows the x9 file to be constructed as required by your financial institution.
- HeaderXml includes various formatting instructions, indicators, addenda record information when needed, and instructions on how and where an offsetting credit should be inserted.
A sample CSV file is as follows, which would default all type 25 record indicators to the HeaderXml file:
t25,10002,44000001,087770706,”29602722/5526″,,,,,”c:pathToFrontImage”,“c:pathToBackImage”
t25,10004,44000002,097770592,”60333044/5587″,,,,,”c:pathToFrontImage”,“c:pathToBackImage”
t25,10006,44000003,077770392,”29343913/5178″,,,,,”c:pathToFrontImage”,“c:pathToBackImage”
end
HeaderXml
Many financial institutions and third party processors have implemented their own x9.37 requirements and variants that are based (to varying degrees) on the x9.37 file standards. The process of generating x9 files generically in the formats required for these processors becomes a complex task given the numerous options and settings that are required.
X9Ware has addressed this need through our HeaderXml class which is implemented within the SDK and leveraged by our X9Utilities product. HeaderXml define parameter values which control the generation of an x9 file. HeaderXml specifically defines the various values that can be populated in the file header, cash letter header, bundle header, and item records.
HeaderXml values are populated from an external XML file. Our long term goal is to provide the options needed to create x9.37 files for virtually all financial institutions and third party processors that use the x9.37 standard. We are largely met that goal today, since we are not aware of any banks with options that we cannot support. This includes all options needed to populate header and trailer records, various credit formats, various credit locations, and a wide variety of parameters that control the values associated with item and image definitions. In alignment with our support goal, be aware that this definition will change from release to release as we continue to improve upon this process and thus expand the parameters. Although we will always make every attempt to retain compatibility with current implementations, you should also design your application and support processes in a manner where you can adapt to ongoing change.
Write is an advanced tool that can be used to easily create new x9 output files. In order to simplify the overall x9 file creation process, Write controls the creation of bundles and their associated trailer records. It calculates and inserts all required totals within the bundle, cash letter, and file control trailer records. All of this is done automatically behind the scene. Writer input is created by your internal applications in a simple CSV format. Images must be provided in TIFF image exchange (x9.100-181) format as typically created by all industry scanners. A parameter file allows you to specify various options including header and cash letter header values which are provided externally in an XML file. Through the use of these header file parameters, write is designed with the goal of being able to create an x9 file for any financial institution. We have incorporated a large number of options which already make this possible for many endpoints and we continue to enhance this process to work towards that goal. This may not always be possible given the complexities that have been implemented by some processors. Please let us know where we can make enhancements which may involve consulting costs subject to level of difficulty and uniqueness of the required solution.
The following information is provided to write:
- Command line options: identifies inputs, outputs, and optionally the HeaderXml file to be used to control formatting. The HeaderXml file must be either identified on the command line or on the first row of the input CSV file.
- HeaderXml: identifies header, trailer, and overall formatting of the x9 file to be created. There are 100+ parameters within the HeaderXml file which can be used to generate the output x9 file in the format as required by your financial institution. The HeaderXml file is static and typically does not need to be modified once a new implementation is tested and has been moved to production status.
- Items CSV: defines the items to be written including amount, sequence number, MICR routing, MICR OnUs, MICR AuxOnUs, EPC, etc. Several formats are supported for the Items CSV file. The most generic and easy to use is the single line “t25” format which has eleven (11) columns. Using that “t25” format allows the items CSV to be generic in nature, with all formatting information required by your financial institution to be provided via the HeaderXml parameter file.
- Front and Back images: which are referenced at the item level from your Items CSV and thus externally defined in your file system. These images are highly recommended to be encoded in the TIFF image exchange x9.100-181 standard format (which is the format created by all compliant scanners). Images can be provided in other formats (JPG, BMP, GIF, or PNG) but there are potential performance implications when doing so given the processing time associated within image conversion.
Addendum records can be included on your CSV file and then incorporated into the x9 output file. Your input can include type 26 (BOFD) primary endorsement records, or can include type 28 secondary endorsement records. This similarly applies to the endorsement record types for returned item files.
| Command Line Switch | Description |
|---|---|
| -xml: | The headerXml file which defines the parameters to be used for the creation of the output x9 file. The headerXml file can be provided either on the command line or on the first line within the items csv file. |
| -config: | Use a specific x9 configuration for validation which defaults to “x9.37”. For example, the CPA 015 standard can be selected as: “-config:x9.CPA_015”. |
| -t | A summary text file will be created with a suffix of “_summary.txt” in the same folder as the output x9 file. |
| -x | A summary XML file will be created with a suffix of “_summary.xml” in the same folder as the output x9 file. |
| -l | Will list all csv lines to the system log. |
Items
Items can be presented in one of two manners:
- Use of our “t25” format which provides the MICR scan line, amount, and item sequence number of the input item to be created. Additional information is then taken from the HeaderXml definition to complete the type 25 record This approach has the advantage that your CSV file is generic (it contains item information only) with all x9 configurational information then coming from the HeaderXml file.
- Explicitly provide the type 25 (or type 31) record to be created. This method gives you complete control over the data that will be populated into the item detail records, and would be used by advanced applications.
Credits
Credits can become a complex topic, since credit definitions are essentially extensions to many of the x9 standards. X9Utilities supports all common credit formats and can be further enhanced to support additional formats if needed by your organization. An XML field defines which credit format is to be generated, which allows the data to be generic. An XML field is also used to define the relative location of where the credit is to be inserted within the x9 file that is being created.
Credits can be inserted into the generated x9 file using one of several techniques, subject to your design and approach to file creation. Options are as follows:
| Application and Usage | Count | Defined In | Examples |
| Auto Insert: A single credit can be inserted with the amount calculated from the offsetting debits. Various xml fields are used to populate all required fields for the chosen credit format. This approach is almost always used when creating typical x9 files which contain a single credit which offsets your items. | One | XML Only | creditFormat=t25 creditRecordLocation=a20 creditInsertedAutomatically=true creditPayorBankRouting=123456780 creditMicrOnUs>1122334455/005 creditItemSequenceNumber=auto creditDocumentationTypeIndicator=G creditBofdIndicator=U creditImageDrawFront=true creditImageDrawBack=true creditImageDrawMicrLine=true creditAddToItemCount=true creditAddToTotalAmount=true |
| Explicit Definition: Credits can be provided on an explicit basis as individual rows within the items csv file. These credits can be 61 or 62 record types, but can also be type 25s that are masquerading as credits. Tje approach of using type 25s is typically used by banks to construct a deposit file that can be accepted by their capture system. It requires some proprietary technique to identify the credits, which is typically a transaction code that is embedded within the MICR OnUs field. | Multiple | CSV only | 61,2, 44000001,,555555550,”12345678/”, 44000001,”G”,0,, |
| Single Credit: A single credit can be provided within the items csv file using an explicitly provided amount. All other required credit fields will be populated from xml. The csv file should be constructed as a single credit offset by checks. The actual insertion point of the credit is determined from xml. | One | CSV and XML | “credit”,351420 |
| Complex Credits: A single credit or multi-credit file can be created using credit rows which are embedded within the items csv file. The credit row includes amount, routing, OnUs, AuxOnUs, and sequence number. All other required credit fields will be populated from xml. The csv file should be constructed as a series of deposits, where each deposit is a credit offset by checks. The credit insertion point should be defined as “any” to allow it to be written in the order as provided on the items csv file. | Multiple | CSV and XML | “credit”,351420,555555550,12345678/,44000001,3300000001 |
Note that a file with zero items is considered valid and will result in the creation of a file with record types 01, 10, 90, and 99. A sample CSV file is as follows; note that the “image” line includes the file name, image creator payor routing, and image creator date:
t25,10002,44000004,087770706,”29602722/5526″,,,,,”c:pathToFrontImage”,“c:pathToBackImage” t25,10004,44000005,077770392,”29343913/5178″,,,,,”c:pathToFrontImage”,“c:pathToBackImage”
end