ACHConverter Component

Properties Methods Events Config Settings Errors

The ACHConverter component is used to convert ACH files into XML, for the purpose of easy viewing and editing. The component 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

DPayments.InPay.Achconverter

Remarks

This component 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 component 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 component 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 component is defined in the Schema property.

Property List

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


FileBatchCount	Total number of batches contained in the file.
FileBlockCount	Total number of blocks in a file.
FileCreditTotal	Total amount credited to the merchant's bank account.
FileDebitTotal	Total amount debited from the merchant's bank account.
FileEntryCount	Total number of entries in a file.
FileEntryHash	Hash of the routing numbers from each detail record in the file.
InputFile	Specifies the file to read data from when calling ConvertXML or ConvertACH .
InputString	Data in memory to read from when calling ConvertXML or ConvertACH .
OutputFile	Specifies the file data is written to when calling ConvertXML or ConvertACH .
OutputString	Contains the results from ConvertXML or ConvertACH .
Schema	Returns the XSD Schema used to create XML from ACH files.
VerifyMode	Determines how the totals in the Batch and File control records are validated.

Method List

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


Config	Sets or retrieves a configuration setting.
ConvertACH	Converts a file from ACH format into XML.
ConvertXML	Converts an XML file into ACH format.
Reset	Reset the internal state of the component and all properties to their default values.
SetInputStream	The input stream to read from when calling ConvertXML or ConvertACH .
SetOutputStream	The output stream to write to when calling ConvertXML or ConvertACH .

Event List

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


Error	Information about errors during data delivery.

Config Settings

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


CloseStreamAfterConversion	If true, the component will close the output stream after conversion.
BuildInfo	Information about the product's build.
GUIAvailable	Tells the component whether or not a message loop is available for processing events.
LicenseInfo	Information about the current license.
MaskSensitive	Whether sensitive data is masked in log messages.
UseInternalSecurityAPI	Tells the component whether or not to use the system security libraries or an internal implementation.

FileBatchCount Property (ACHConverter Component)

Total number of batches contained in the file.

public long FileBatchCount { get; }

Public ReadOnly Property FileBatchCount As Long

Default Value

Remarks

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

This property is read-only.

FileBlockCount Property (ACHConverter Component)

Total number of blocks in a file.

Syntax

C#
VB.NET

public long FileBlockCount { get; }

Public ReadOnly Property FileBlockCount As Long

Default Value

Remarks

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

This property is read-only.

FileCreditTotal Property (ACHConverter Component)

Total amount credited to the merchant's bank account.

Syntax

C#
VB.NET

public string FileCreditTotal { get; }

Public ReadOnly Property FileCreditTotal As String

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 Component)

Total amount debited from the merchant's bank account.

Syntax

C#
VB.NET

public string FileDebitTotal { get; }

Public ReadOnly Property FileDebitTotal As String

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 Component)

Total number of entries in a file.

Syntax

C#
VB.NET

public int FileEntryCount { get; }

Public ReadOnly Property FileEntryCount As Integer

Default Value

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 Component)

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

Syntax

C#
VB.NET

public string FileEntryHash { get; }

Public ReadOnly Property FileEntryHash As String

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 Component)

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

Syntax

C#
VB.NET

public string InputFile { get; set; }

Public Property InputFile As String

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 Component)

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

Syntax

C#
VB.NET

public string InputString { get; set; }

Public Property InputString As String

Default Value

Remarks

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

OutputFile Property (ACHConverter Component)

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

Syntax

C#
VB.NET

public string OutputFile { get; set; }

Public Property OutputFile As String

Default Value

Remarks

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

OutputString Property (ACHConverter Component)

Contains the results from ConvertXML or ConvertACH .

Syntax

C#
VB.NET

public string OutputString { get; }

Public ReadOnly Property OutputString As String

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 Component)

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

Syntax

C#
VB.NET

public string Schema { get; }

Public ReadOnly Property Schema As String

Default Value

Remarks

This property returns the schema (XSD format) that the component 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 and not available at design time.

VerifyMode Property (ACHConverter Component)

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

Syntax

C#
VB.NET

public AchconverterVerifyModes VerifyMode { get; set; }

enum AchconverterVerifyModes {
  vmValidateTotals,
  vmComputeTotals,
  vmNoValidation
}

Public Property VerifyMode As AchconverterVerifyModes

Enum AchconverterVerifyModes
  vmValidateTotals
  vmComputeTotals
  vmNoValidation
End Enum

Default Value

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:


FileBatchCount	Total number of batches contained in this ACH File.
FileBlockCount	Total number of blocks (each block consists of 960 characters).
FileCreditTotal	Gross amount of funds deposited into the merchant's account.
FileDebitTotal	Gross amount of funds removed from the merchant's account
FileEntryCount	Total number of entries in the file (sum of all entries in each batch)
FileEntryHash	Used to validate that there are no transactions missing from the file

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


Verify Mode	Description
vmValidateTotals (0)	The totals listed in each control record in the file are compared against the totals that the component computes itself. If there is any mismatch, the component fails with an error.
vmComputeTotals (1)	The totals listed in each control record in the file are ignored. The values computed by the component are substituted. This is useful when adding or removing records from the ACH or XML files.
vmNoValidation (2)	No validation is performed. The values in the file are used, and the computed values are ignored.

Config Method (ACHConverter Component)

Sets or retrieves a configuration setting.

Syntax

C#
VB.NET

public string Config(string configurationString);

Public Function Config(ByVal ConfigurationString As String) As String

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, 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 Component)

Converts a file from ACH format into XML.

Syntax

C#
VB.NET

public void ConvertACH();

Public Sub 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 component 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 component 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 Component)

Converts an XML file into ACH format.

Syntax

C#
VB.NET

public void ConvertXML();

Public Sub 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 component 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 component 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 component 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 component to compute these values for you.

Reset Method (ACHConverter Component)

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

Syntax

C#
VB.NET

public void Reset();

Public Sub Reset()

Remarks

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

SetInputStream Method (ACHConverter Component)

The input stream to read from when calling ConvertXML or ConvertACH .

Syntax

C#
VB.NET

public void SetInputStream(System.IO.Stream inputStream);

Public Sub SetInputStream(ByVal InputStream As System.IO.Stream)

Remarks

This property should contain the stream ConvertXML or ConvertACH will read from. If you do not wish to use a stream, you may specify an InputFile, or simply set the data in memory in the InputString property. If multiple inputs are specified, the source used will be selected in the following priority: SetInputStream, InputFile, and then InputString.

SetOutputStream Method (ACHConverter Component)

The output stream to write to when calling ConvertXML or ConvertACH .

Syntax

C#
VB.NET

public void SetOutputStream(System.IO.Stream outputStream);

Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream)

Remarks

This property should contain the stream you wish the output from ConvertXML or ConvertACH to be written to. If you do not wish to use a stream, you may specify a OutputFile, or simply retrieve the data in memory from the OutputString property. If SetOutputStream and OutputFile are both specified, SetOutputStream takes precedence. OutputString will only be filled if both SetOutputStream and OutputFile are empty.

Error Event (ACHConverter Component)

Information about errors during data delivery.

Syntax

C#
VB.NET

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, AchconverterErrorEventArgs e);

public class AchconverterErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As AchconverterErrorEventArgs)

Public Class AchconverterErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

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 Component)

The component accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

ACHConverter Config Settings

CloseStreamAfterConversion: If true, the component will close the output stream after conversion.

This property is true by default. Therefore, by default, the output stream will be closed after conversion is completed. In order to keep streams open after the conversion completes, you must set this config to false.

Base Config Settings


	BuildInfo: Information about the product's build. When queried, this setting will return a string containing information about the product's build.
	GUIAvailable: Tells the component whether or not a message loop is available for processing events. In a GUI-based application, long-running blocking operations may cause the application to stop responding to input until the operation returns. The component will attempt to discover whether or not the application has a message loop and, if one is discovered, it will process events in that message loop during any such blocking operation. In some non-GUI applications, an invalid message loop may be discovered that will result in errant behavior. In these cases, setting GUIAvailable to false will ensure that the component does not attempt to process external events.
	LicenseInfo: Information about the current license. When queried, this setting will return a string containing information about the license this instance of a component is using. It will return the following information: Product: The product the license is for. Product Key: The key the license was generated from. License Source: Where the license was found (e.g., RuntimeLicense, License File). License Type: The type of license installed (e.g., Royalty Free, Single Server). Last Valid Build: The last valid build number for which the license will work.
	MaskSensitive: Whether sensitive data is masked in log messages. In certain circumstances it may be beneficial to mask sensitive data, like passwords, in log messages. Set this to `true` to mask sensitive data. The default is `true`. This setting only works on these components: `AS3Receiver`, `AS3Sender`, `Atom`, `Client`(3DS), `FTP`, `FTPServer`, `IMAP`, `OFTPClient`, `SSHClient`, `SCP`, `Server`(3DS), `Sexec`, `SFTP`, `SFTPServer`, `SSHServer`, `TCPClient`, `TCPServer`.
	UseInternalSecurityAPI: Tells the component whether or not to use the system security libraries or an internal implementation. When set to `false`, the component will use the system security libraries by default to perform cryptographic functions where applicable. In this case, calls to unmanaged code will be made. In certain environments this is not desirable. To use a completely managed security implementation set this setting to `true`. Setting this setting to `true` tells the component to use the internal implementation instead of using the system security libraries. On Windows, this setting is set to `false` by default. On Linux/macOS, this setting is set to `true` by default. If using the .NET Standard Library, this setting will be `true` on all platforms. The .NET Standard library does not support using the system security libraries. Note: This setting is static. The value set is applicable to all components used in the application. When this value is set the product's system DLL is no longer required as a reference, as all unmanaged code is stored in that file.

Trappable Errors (ACHConverter Component)