ACHConverter Module

Properties   Methods   Events   Config Settings   Errors  

The ACHConverter module is used to convert ACH files into XML, for the purpose of easy viewing and editing. The module can also convert this XML back into the ACH format, so it may later be processed by the ACH network. Validation of these files occurs during the translation process.

Syntax

InPay.Achconverter

Remarks

This class is used for translating ACH files back and forth between the complex data format used by the ACH network and simple XML. By representing an ACH file as an XML structure, the viewing, parsing, and editing of individual ACH records can be easily accomplished. An XML document can be built from scratch and then use the ACHConverter class to convert it to ACH format.

The ConvertACH and ConvertXML methods are used to go back and forth between the ACH format and XML formats. ConvertACH converts from ACH to XML, and ConvertXML converts from XML back into ACH format. The data to be converted is specified by SetInputStream, InputFile or InputString, and the results are written to SetOutputStream, OutputFile or OutputString.

When the parsing is taking place, the source file is checked for validity in several different ways. The format and sequence of the records in the file is checked, as well as the data in each field in a record. Any formatting error or incorrect data (for instance, a character in an numeric-only field) will cause the validity checks to fail. In addition, the totals in each Batch Control Record and in the final File Control Record are checked against values computed as the class parses each record (this last check may be overridden by the VerifyMode property).

For example: ACHConverter1.InputFile = "c:\achtestfile.txt" ACHConverter1.OutputFile = "c:\xmltestfile.xml" ACHConverter1.VerifyMode = vmValidateTotals ACHConverter1.ConvertACH()

After the above code completes successfully, "c:\xmltestfile.xml" will contain the XML representation of the input ACH file. In addition, the following properties will be filled with information about the ACH file that was just parsed:

• FileBatchCount
• FileBlockCount
• FileCreditTotal
• FileDebitTotal
• FileEntryCount
• FileEntryHash

Note: The XML document created (and parsed) by this class is defined in the Schema property.

Property List

The following is the full list of the properties of the module with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the module with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the module with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the module with short descriptions. Click on the links for further details.

FileBatchCount Property (ACHConverter Module)

Total number of batches contained in the file.

Syntax

• Swift
• Objective-C

public var fileBatchCount: Int64 {
  get {...}
}

@property (nonatomic,readonly,assign,getter=fileBatchCount) long long fileBatchCount;

- (long long)fileBatchCount;

Default Value

0

Remarks

A file may contain a minimum of 1 and a maximum of 999999 batches.

This property is read-only.

FileBlockCount Property (ACHConverter Module)

Total number of blocks in a file.

Syntax

• Swift
• Objective-C

public var fileBlockCount: Int64 {
  get {...}
}

@property (nonatomic,readonly,assign,getter=fileBlockCount) long long fileBlockCount;

- (long long)fileBlockCount;

Default Value

0

Remarks

Each block consists of 10 records, or approximately 960 characters.

This property is read-only.

FileCreditTotal Property (ACHConverter Module)

Total amount credited to the merchant's bank account.

Syntax

• Swift
• Objective-C

public var fileCreditTotal: String {
  get {...}
}

@property (nonatomic,readonly,assign,getter=fileCreditTotal) NSString* fileCreditTotal;

- (NSString*)fileCreditTotal;

Default Value

"0"

Remarks

This property contains the total amount of all transactions that credit funds to the merchant's account (this is a gross amount).

This property is read-only.

FileDebitTotal Property (ACHConverter Module)

Total amount debited from the merchant's bank account.

Syntax

• Swift
• Objective-C

public var fileDebitTotal: String {
  get {...}
}

@property (nonatomic,readonly,assign,getter=fileDebitTotal) NSString* fileDebitTotal;

- (NSString*)fileDebitTotal;

Default Value

"0"

Remarks

This property contains the total amount of all transactions that debit funds from the merchant's account (this is a gross amount).

This property is read-only.

FileEntryCount Property (ACHConverter Module)

Total number of entries in a file.

Syntax

• Swift
• Objective-C

public var fileEntryCount: Int32 {
  get {...}
}

@property (nonatomic,readonly,assign,getter=fileEntryCount) int fileEntryCount;

- (int)fileEntryCount;

Default Value

0

Remarks

An entry is defined as a Detail Record or an Addenda Record. Header and Control records are ignored.

This property is read-only.

FileEntryHash Property (ACHConverter Module)

Hash of the routing numbers from each detail record in the file.

Syntax

• Swift
• Objective-C

public var fileEntryHash: String {
  get {...}
}

@property (nonatomic,readonly,assign,getter=fileEntryHash) NSString* fileEntryHash;

- (NSString*)fileEntryHash;

Default Value

"0"

Remarks

This property contains a 10-character long hash of all of the recipient routing numbers in the file. This is used as a check to ensure that no records were lost in the transmission of this ACH file.

This property is read-only.

InputFile Property (ACHConverter Module)

Specifies the file to read data from when calling ConvertXML or ConvertACH .

Syntax

• Swift
• Objective-C

public var inputFile: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=inputFile,setter=setInputFile:) NSString* inputFile;

- (NSString*)inputFile;
- (void)setInputFile :(NSString*)newInputFile;

Default Value

""

Remarks

This property contains the path and filename to the ACH or XML file you wish to parse and convert.

InputString Property (ACHConverter Module)

Data in memory to read from when calling ConvertXML or ConvertACH .

Syntax

• Swift
• Objective-C

public var inputString: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=inputString,setter=setInputString:) NSString* inputString;

- (NSString*)inputString;
- (void)setInputString :(NSString*)newInputString;

Default Value

""

Remarks

This property contains the ACH or XML data, in memory, that you wish to parse and convert.

OutputFile Property (ACHConverter Module)

Specifies the file data is written to when calling ConvertXML or ConvertACH .

Syntax

• Swift
• Objective-C

public var outputFile: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=outputFile,setter=setOutputFile:) NSString* outputFile;

- (NSString*)outputFile;
- (void)setOutputFile :(NSString*)newOutputFile;

Default Value

""

Remarks

This property contains the path and filename where you wish to store your converted results.

OutputString Property (ACHConverter Module)

Contains the results from ConvertXML or ConvertACH .

Syntax

• Swift
• Objective-C

public var outputString: String {
  get {...}
}

@property (nonatomic,readonly,assign,getter=outputString) NSString* outputString;

- (NSString*)outputString;

Default Value

""

Remarks

If SetOutputStream and OutputFile have not been set, the results of the ConvertXML or ConvertACH methods will be stored in memory and returned by the OutputString property.

This property is read-only.

Schema Property (ACHConverter Module)

Returns the XSD Schema used to create XML from ACH files.

Syntax

• Swift
• Objective-C

public var schema: String {
  get {...}
}

@property (nonatomic,readonly,assign,getter=schema) NSString* schema;

- (NSString*)schema;

Default Value

""

Remarks

This property returns the schema (XSD format) that the class uses to generate XML from an ACH file. This same schema is used when parsing XML to re-create an ACH file. During the parsing process, if the input XML does not conform to the schema the translation process will fail with an error.

This property is read-only.

VerifyMode Property (ACHConverter Module)

Determines how the totals in the Batch and File control records are validated.

Syntax

• Swift
• Objective-C

public var verifyMode: AchconverterVerifyModes {
  get {...}
  set {...}
}

public enum AchconverterVerifyModes: Int32 {
  case vmValidateTotals = 0
  case vmComputeTotals = 1
  case vmNoValidation = 2
}

@property (nonatomic,readwrite,assign,getter=verifyMode,setter=setVerifyMode:) int verifyMode;

- (int)verifyMode;
- (void)setVerifyMode :(int)newVerifyMode;

Default Value

0

Remarks

Batch Control Records contain several fields that provide information about each batch included in the ACH file. These include an Entry Count (number of records in the batch), Credit Total (total funds added to the merchant's account), Debit Total (total of funds removed from the merchant's account), and a hash used to verify that there are no missing transactions. The ending File Control record contains similar information about the entire batch The final record in an ACH file is the File Control Record. This record contains several fields that provide information about all of the batches and all of the transactions in the ACH file. These fields are exposed in the following properties:

There are similar fields for each of the batches contained within the ACH file, but only the final totals are exposed. The class carefully computes these values as the input is parsed, and the table below shows how they are validated:

Config Method (ACHConverter Module)

Sets or retrieves a configuration setting.

Syntax

• Swift
• Objective-C

public func config(configurationString: String) throws -> String

- (NSString*)config:(NSString*)configurationString;

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

ConvertACH Method (ACHConverter Module)

Converts a file from ACH format into XML.

Syntax

• Swift
• Objective-C

public func convertACH() throws -> Void

- (void)convertACH;

Remarks

This method converts an ACH-formatted file into an XML format. This XML can easily be viewed, edited, or otherwise manipulated, and then converted back to ACH format at a later date using the ConvertXML method. The source ACH file can be specified by the SetInputStream method or the InputFile and InputString properties, and the destination XML by the SetOutputStream method or OutputFile, and OutputString properties.

When the ConvertACH method is called, the source ACH file is validated in several ways. The format of each record in the file is checked before it is converted to XML. The validity of data contained within each field in the record is also checked. Any formatting error or incorrect data (for instance, a character in an integer-only field) will cause the class to fail with an error.

In addition, each ACH file contains several Batch Control records and a final File Control Record. These records contain information about the transactions contained within the ACH file. The data contained within these control records is used to make sure the ACH files have not been corrupted, and have not lost records in the transmission process. The class will by default validate the data contained in these control records. However, you can override this functionality by changing the VerifyMode (note that VerifyMode does not affect the format or data validity checks).

ConvertXML Method (ACHConverter Module)

Converts an XML file into ACH format.

Syntax

• Swift
• Objective-C

public func convertXML() throws -> Void

- (void)convertXML;

Remarks

The ConvertACH method takes an industry-standard ACH file and converts it into an XML file. This XML can easily be viewed, edited, or otherwise manipulated. The ConvertXML method takes that modified XML and converts it back into an ACH file so that it can be processed.

The source XML can be specified by the SetInputStream method, or the InputFile and InputString properties, and the destination ACH file by the SetOutputStream method or the OutputFile and OutputString properties.

When the ConvertXML method is called, the source XML is validated in several ways. First, the XML format is validated. Unclosed tags and other editing mistakes will cause the class to be unable to parse the XML. The XML is then validated against the Schema. If any of the tags are missing or out of place, the class will be unable to parse the XML. Finally, each data field contained within an XML tag is then validated for the correct length and formatting (for instance, a character in an integer-only field will cause the class to fail with an error).

In addition, each XML file contains several Batch Control records and a final File Control Record. These records contain information about the transactions contained within the XML-formatted ACH file's Detail Records. The data contained within these control records is used to make sure the ACH files have not been corrupted, and have not lost records in the transmission process.

If you have made changes to the XML and you do not wish to manually compute the new Debit Total, Credit Total, Entry Count, and Entry Hash for each Batch Control record in the XML, you can set VerifyMode to vmComputeTotals, and allow the class to compute these values for you.

Reset Method (ACHConverter Module)

Reset the internal state of the component and all properties to their default values.

Syntax

• Swift
• Objective-C

public func reset() throws -> Void

- (void)reset;

Remarks

The Reset method doesn't have any parameters and doesn't return any value.

Error Event (ACHConverter Module)

Information about errors during data delivery.

Syntax

• Swift
• Objective-C

func onError(errorCode: Int32, description: String)

- (void)onError:(int)errorCode :(NSString*)description;

Remarks

The Error event is fired in case of exceptional conditions during message processing.

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

Config Settings (ACHConverter Module)

Trappable Errors (ACHConverter Module)