AvaTax for Communications EZTax.cfg configuration guide

Bundling

bundling=off (default)

bundling=on

bundlefile=[Path Location]

“bundling=on” must be present for AFC to activate and perform bundling. If it does not exist, bundling will not occur.

The Bundling feature allows the user to define multiple AFC transaction/service type pairs as one unique “bundle” transaction/service pair type. AFC processes all of the transaction/service type pairs in the bundle and stores the results in the file EZTax.bdl, the formatted text bundle definition file. This file may be created and edited by AFC Bundler, an optional utility program.

If Bundling has been activated, AFC uses the default file, EZTax.bdl, in the directory where the database is located. The “bundlefile” option allows for a different file location to be defined. The full path must be specified.

NOTE: This file must be in the same location as the EZTax.dat database file in order for AFC to find and load the bundle information, unless the bundlefile option is used.

Also, this configuration option only applies to AFC Telecom. It does not apply to AFC Sales and Use.

Date Validation

datevalidation=on (default)

datevalidation=off

The Date Validation option is used to perform date validation checking of transaction dates and override dates within the transaction data record. The default setting of “on” allows the validation checking to occur. “off” will disable the Validate Checking feature.

• Transaction dates are checked to be within the range of 19960000 thru 20370000.
• Override dates are checked to be within the range of 19000000 thru 20370000.
• The dates are formatted CCYYMMDD.

Exclusion Option

exclusion=off (default)

exclusion=on

exclusionfile=[Exclusion File Path]

The exclusion=on option must be inserted into the configuration file if an exclusion file is being used in order to set exclusions for specific states. Using the exclusion=off option, will indicate that an exclusion file is not being specified, and by default, AFC will determine that there are no exclusions in any state.

The Exclusion file option must be inserted into the AFC configuration file when the exclusion=on option is used. An exclusion file is a text file containing a list of states that have exclusions. The two-letter abbreviation for each state must be entered in a separate line. Optionally, the country ISO code could be specified prior to the state abbreviation and followed by a comma. Below is an example of an exclusion file:

CA

IL

USA,NY

Upon reading this sample file, AFC will determine that there are exclusions for the state of California, Illinois, and New York.

A 3-character country ISO can also be placed alone on a line. This will cause all taxes in that country to be exempted. Exclusions are intended to exclude taxes for a jurisdiction. For instance, this exclusion file:

USA

CAN,PQ

is interpreted as “we don’t do business in the USA and we also don’t do business in the province of Quebec”. In these jurisdictions, no taxes at all would be applied. If you want to block taxes at some level for a jurisdiction, you would use an override file.

NOTE: Only the three-character ISO country code may be used here. Two-character codes, which may be used elsewhere, are not valid here.

Log Length

loglength=short (default)

loglength=long

This option is used to specify whether AFC will write the standard (short) log or the extended (long) log, the only difference being that the extended log contains an additional nine optional fields. The additional fields provide a twenty character length string field and eight integer fields. These fields are part of the client transaction data and are provided to enhance the sorting and reporting capabilities based on client supplied information. These fields do not affect tax calculations and are placed into the AFC log. The default is the standard log.

Log Message Level

messagelevel=info (default)

messagelevel=warning

messagelevel=error

The message level impacts what messages are sent to the status file.

Log No Tax Transactions

lognotaxtrans=off (default)

lognotaxtrans=on

This option is used to allow writing zero tax amount transactions to the log file.

Log Option

logoption=nocache

logoption=cache (default)

AFC caches returning taxes into log file data and writes the cache to disk when the cache is full. Placing “logoption=nocache” in the EZTax.cfg file will stop caching the log file data in memory and write the log file to disk after processing each transaction.

NOTE: Setting the LOGOPTION to NOCACHE increases the size of the log because consecutive records that are identical except for amounts are not combined, degenerating the speed of the system. It will, however, eliminate the possibility of losing tax data stored in the cache should processing end abnormally. This option is not recommended unless there is a valid reason to use it.

Log Transaction/Service Types

logtransserv=true

logtransserv=false (default)

The Log Transaction Services Types option will decrease the size of the log and increase the processing speed when set to false. This option can be of benefit when the transaction and service type information is not needed in the log output.

NOTE: This value is set to 'true' by default and results in the transaction type and service type being written to the log. When set to 'false,' zeros will be written in place of the transaction and service types.

Nexus Option

nexus=off (default)

nexus=on

nexusfile=[Nexus File Path]

The nexus=on option must be inserted into the configuration file if a nexus file is being used in order to set nexus for specific states. Using the nexus=off option will indicate that a nexus file is not being specified, and by default, AFC will determine that nexus exists in every state.

The ‘nexusfile’ option must be inserted into the AFC configuration file when the nexus=on option is used. A nexus file is a comma-delimited text file that indicates which states have nexus or not. Below is an example of the contents of a nexus file:

CA

NY

IL

TX

The value in each line is the two-letter abbreviation for the state. In the example above, upon reading this nexus file, AFC will determine that nexus exists in the states of California, New York, Illinois, and Texas, and in no other states.

Override Error Handling

overrideerrorhandlingv2=abort

overrideerrorhandlingv2=report (default)

The Override Error Handling ABORT option forces the session to exit if an error is detected when inserting overrides. When this option is set to REPORT, the system will report a warning to the status log, skip the bad override and continue processing the override file.

Override Format

overrideformat=new (default)

overrideformat=old

The Override Format option alerts the system to expect override files in version 8 or version 9 formats. If using a tab delimited override file created using the Override Utility from version 8, it is necessary to change this option to OLD.

Reconciliation Report Option

The reconciliation report option provides a tax inclusive calculation or tax inclusive report which shows the base charges plus any additional taxes calculated. If this configuration option is ON (reconcilerpt=on), the produced report will have the same name as the log, except the extension is “rtr”. If this configuration option is OFF (reconcilerpt=off), the report is not produced. This configuration option will be set to OFF by default. The bybdl option (reconcilerpt=bybdl) is a special flag which adds the bundle package and id to the report within two additional columns.

The report is divided into three sections: Federal Level, Unknowns and State Level.

The Federal Level section contains a summary of all taxes for a given country listed by the ISO for that country. The list is sorted in the following order: USA, CAN, all other nations alphabetically sorted by the ISO identifier for that nation.

NOTE: USA Federal includes federal taxes for all USA territories (American Samoa, Federated States of Micronesia, Guam, Marshall Islands, Northern Mariana Islands, Palau, Puerto Rico, or US Virgin Islands). This includes transactions where the taxing authority is the US Federal jurisdiction.

The Unknowns are transactions in which the jurisdiction for taxation reporting purposes could not be determined.

The State Level section contains taxes at the state level (includes provinces and territories) and is restricted to USA states and territories and Canadian provinces and territories. The list is sorted alphabetically first by all USA states and territories, followed by all Canadian provinces and territories.

There will be one line for each transaction/service type pair used in these jurisdictions, with all the jurisdictions reported together (the only sorting in this section is by t/s pair, not by jurisdiction). Each line appears in the following format:

Standard reports

Jurisdiction, Trans, Svc, Charge, CalcCharge

Bundled reports

Jurisdiction, BundlePkg, BundleId, Trans, Svc, Charge, CalcCharge

For Federal Level reporting, the jurisdiction will be the Federal ISO code. Examples: USA (United States), CAN (Canada), FRA (France), GBR (Great Britain)

Unknown jurisdictions will use the value Unknown for the jurisdiction.

For State Level reporting, the jurisdiction will be the 2-digit official State, Province or Territory code. Examples: NY (New York), MB (Manitoba), AS (American Samoa)

Abbreviations

For the USA, official USPS abbreviations can be found at https://www.usps.com/send/official-abbreviations.htm.

Please refer to the following table for all other abbreviations excluding the USA:

Any transactions where the taxing jurisdiction is the US Federal jurisdiction will not be reflected in this section, so each t/s pair’s total in this section may not equal that pair’s total in the first section.

Report Level

reportlvl=local (city)

reportlvl=default

When set to the [reportlvl=local] configuration option, the difference in the returned tax data values is that the pcode returned is the local pcode for non-federal taxes. This pcode can be used to retrieve the associated jurisdiction information.

Return Non-Billable

returnnonbillable=true

returnnonbillable=false (default)

Non-billable items are compliance only taxes or fees that are used for filing and are not passed on to the user. This option allows you to specify whether non-billable items should be included in the tax table returned by the tax calculation API functions in AFC or not. This option does not affect the AFC log. Non- billable items will always be logged for compliance purposes.

Tax Inclusive (Reverse) Calculations

reversecalcsession=off (default)

reversecalcsession=on

By setting the value to ‘off’, this flag allows customers who do not use tax inclusive calculations to avoid the overhead in time and memory for initialization of the tax inclusive calculation support modules.

To initialize support for tax inclusive calculations at startup, the flag should be set to “on”. If the flag is “off”, the initialization will not occur unless a tax inclusive calculation request is received and will only occur on the first such request received. The primary difference between the “off” and “on” settings for customers that use tax inclusive calculations is when the cost of the tax inclusive calculation initialization is incurred.

Safe Harbor TAM Overrides

safeHarborCellularTAMoverride originalTAM=x, overrideTAM=y

safeHarborVoIPTamOverride originalTAM=x, overrideTAM=y

safeHarborPagingTAMoverride originalTAM=x, overrideTAM=y

Safe Harbor TAM Override configuration settings allow traffic study values to be applied for a given session or account.

The results of percentages from a traffic study can be applied by administering traffic study TAM overrides. The TAM values for Cellular, VoIP and Paging are adjusted to reflect the percentages in the traffic study.

Please submit a support case in order to set the override at the account level versus transaction level.

Self-Taxing Rule

selftax=aggregate

selftax=individual (default)

Self-taxing configuration option allows the client to determine whether taxes that are classified as self- taxing should be calculated individually or in aggregate. The aggregate option summarizes the rates for all self-taxing taxes for a transaction, and uses that for determining the tax liability. The individual option determines the tax liability individually for each tax. The main difference in the result is that the taxable measure for the aggregate option will match for all self-taxing taxes, and the total tax liability will be slightly higher.

The following is an example using VoIP-Nomadic/International Usage (59/51) transaction for $100.00 in Honolulu, Hawaii.

Configuration setting selftax=individual

Configuration setting selftax=aggregate

Status Log

statuslog=keep

statuslog=clear (default)

The Status Log option is used to allow for appending new session data to the existing EZTax.sta file. The default setting of “keep” allows for appending the new session data. When set to “clear,” will delete an existing EZTax.sta file and create a new EZTax.sta for the session.

Tax Grouping Options

The following options determine how tax calculation results are returned after calling one of the tax calculation API functions. By changing this option in the configuration file, the taxes returned by the tax calculation API function may be grouped according to this setting.

NOTE: This option will not modify the way that tax calculation results are logged into the AFC log file. Only the tax calculation results returned by either one of the tax calculation API will be group according to the values set for this option.

General Rules

The following rules apply when using any value for this option:

Default Option:

• groupresults=default (default)

  The default option indicates that the taxes returned in the tax table after processing a transaction with AFC will not be grouped. Each tax will be returned in an individual tax record.

Tax Level Options:

• groupsamelevel

  This option will cause rate-based taxes at the same level to be grouped together. For example, if AFC returns a Local Sales Tax and a Local District Tax, these taxes will be grouped together since they have the same tax level (Local).

• groupstate_groupcountyandlocal

  This option will cause all state taxes to be grouped together into a single record, and all county and local taxes to be grouped together into a separate record.

• groupstatecountyandlocal

  This option will cause all state, county, and local taxes to be grouped together into a single record.

Sales Tax Options:

The following options may be used in combination with any of the tax level options specified above. These options may be used to group sales taxes separately from other taxes. This option must be appended to the EZTax.cfg file following the line for the tax level group option.

• groupsales

  This option will group Sales Taxes (tax type 1) and Use Taxes (tax type 49) taxes into a separate record according to the tax level option being specified.

• groupsalescategory

  When using this option, AFC will group any items that are considered Sales Taxes together. In addition to the Sales Tax (tax type 1) and Use Tax (tax type 49), some District and Transit taxes are also in the sales tax category.

Examples

• groupstatecountylocal

  By entering the configuration option shown above into the EZTax.cfg file, all State, County, and Local taxes will be grouped together into a single record.

• groupstatecountylocal
• groupsalescategory

By entering these two options in the configuration file, all State, County, and Local sales category taxes will be grouped together into a single record. Any other State, County and Local taxes (if any) will be grouped into a separate record.

Tax Return Table

When grouping taxes together, the fields in the tax return table will contain the following values:

NOTE: The remaining fields in the tax table will not contain any meaningful value. Grouping tax calculation results may serve as a way to simplify the tax information for display purposes only. If further detail is required for each tax being returned by AFC, this feature should not be used.

Tax on Tax

taxontax=once

taxontax=iterate (default)

taxontax=taxablemeasure

The Tax On Tax option is used to allow for processing taxes when taxes are based on the tax amount of other taxes. AFC will repeatedly calculate the tax on the additional tax amount until either that tax amount (taxontax=iterate) or the taxable measure (taxontax=taxablemeasure) is less than one half of one cent (0.005).

NOTE: Either ‘taxontax=iterate’or ‘taxontax=taxablemeasure’ must be present to perform the tax on tax function. If it is set to ‘taxontax=once’, AFC will perform the calculation one time.

Taxing Authority Report/Trans-Serv Report Option

transservrpt=on (default)

transservrpt=off

transservrpt=bybdl

The transservrpt option may be inserted into the configuration file if the user wants a transaction-service type report. The report is placed in the same directory as the log file. If this configuration option is ON (transservrpt=on), the produced report will have the same name as the log, except the extension is “tsr”. If this configuration option is OFF (transservrpt=off), the report is not produced. This configuration option will be set to ON by default. The bybdl option (transservrpt=bybdl) is a special flag which adds the bundle package and id to the report within two additional columns.

The report is divided into three sections: Federal Level, Unknowns and State Level.

The Federal Level section contains a summary of all taxes for a given country listed by the ISO for that country. The list is sorted in the following order: USA, CAN, all other nations alphabetically sorted by the ISO identifier for that nation.

NOTE: USA Federal includes federal taxes for all USA territories (American Samoa, Federated States of Micronesia, Guam, Marshall Islands, Northern Mariana Islands, Palau, Puerto Rico, or US Virgin Islands). This includes transactions where the taxing authority is the US Federal jurisdiction.

The Unknowns are transactions in which the jurisdiction for taxation reporting purposes could not be determined.

The State Level section contains taxes at the state level (includes provinces and territories) and is restricted to USA states and territories and Canadian provinces and territories. The list is sorted alphabetically first by all USA states and territories, followed by all Canadian provinces and territories.

There will be one line for each transaction/service type pair used in these jurisdictions, with all the jurisdictions reported together (the only sorting in this section is by t/s pair, not by jurisdiction). Each line appears in the following format:

Standard reports

Jurisdiction, Trans, Svc, Charge

Bundled reports

Jurisdiction, BundlePkg, BundleId, Trans, Svc, Charge

For Federal Level reporting, the jurisdiction will be the Federal ISO code. Examples: USA (United States), CAN (Canada), FRA (France), GBR (Great Britain)

Unknown jurisdictions will use the value Unknown for the jurisdiction.

For State Level reporting, the jurisdiction will be the 2-digit official State, Province or Territory code. Examples: NY (New York), MB (Manitoba), AS (American Samoa)

Abbreviations

For the USA, official USPS abbreviations can be found at https://www.usps.com/send/official-abbreviations.htm.

Please refer to the following table for all other abbreviations excluding the USA:

Any transactions where the taxing jurisdiction is the US Federal jurisdiction will not be reflected in this section, so each t/s pair’s total in this section may not equal that pair’s total in the first section.

NOTE: When using multiple AFC sessions, each session must give a unique name to the log and status files. In order for the trans-serv report files to be named uniquely for each session, the differentiation in log or status file names must be in the file name, not the extension. For example, naming the log files EZTax1.log, EZTax2.log, etc. is acceptable. Naming the log files EZTax.log1, EZTax.log2, etc., will NOT produce usable trans-serv file names.

Transaction/Service Type Pair Validation

transservval=off (default)

transservval=on

The Transaction Service Validation option is used to validate transaction/service type pairs within the transaction data record. To allow the validation checking to occur the setting must be set to “on.” Otherwise the default setting of “off” will disable this feature.

Transaction Count Report

licenserpt=off (default)

licenserpt=detailed

licenserpt=summary

The license report / transaction count report provides a breakdown of all transactions processed. Similar to the tsr report, it will append new entries to the end of the file, and is written out when the session is closed. The file will be named the same as the log file with the extension license.rpt. If logging is disabled, the status file name will be used.

For example, if the log is EZTax.log, the report will be named EZTax.license.rpt.

Detailed Report Columns

Summary Report Columns

Transaction Dump

transactiondump=off (default)

transactiondump=on

With transaction dump turned on, all transactions are logged to a text file named EZTax.log.trn. This can become quite a large file and is normally only used for troubleshooting. For example, with this file AFC, Inc. can reproduce the identical input on our system to what was used on a client’s system, thereby recreating the transaction(s) in question.

Default

Special Exemptions

Use Tax

usetax=transaction (default)

usetax=shipto

The default [usetax=transaction] uses transaction data to determine if consumer use or vendor use is applicable. While [usetax=shipto] compares ‘ship-to’ to ‘ship-from’ to determine if sales tax or use tax applies.

NOTE: This configuration option only applies to AFC Sales and Use. It does not apply to AFC Telecom.

Wholesale/Resale Exempt for Batch

setwholesaleexempted=false (default)

setwholesaleexempted=true

The standard approach for having wholesale or resale exempt taxes preserved in the compliance files is to set the exemption type to 3 (Sales for Resale). However, the CDF format does not support setting the exemption type. Using this configuration option set to true forces batch (eztax_20) to handle wholesale / resale the same way and preserve the exempted taxes in the log for reports.

The tax amount does not change, the only change is that the exempted amount is preserved in the log and available for subsequent reporting.

NOTE: This configuration option only applies to AFC Telecom Users with eztax_20 configuration. It does not apply to AFC Sales and Use.