Skip to main content
Avalara Help Center

TM_00101_AFC User Manual_Telecom

Introduction

Installation

Refer to the AvaTax for Communications (AFC) Installation Manual for complete instructions regarding the installation of AFC on your specific platform.

Getting Started

There are several AFC integration methods available, each allowing for its use based on the client’s needs.

  • AFC SaaS Standard: This method is provided for lower transaction-count customers, allowing for the use of AFC to obtain tax calculations without having to maintain the program on their systems. 
  • On-Site Options: 
    • AFC's API interface: provides the user complete control over access to tax calculations and the data returned, along with the flexibility supported by the report utilities. 
  • AFC SaaS Pro: AFC SaaS Pro is an XML web service used to calculate taxes. Applications send a single transaction to the AFC SaaS web service over the Internet. The taxes are calculated and immediately returned to the client application. Users have the capability of sending and receiving transactions 24 hours a day, 7 days a week. This service is ideal for adding the ability to tax purchases made from online stores and AFC SaaS Pro customers are provided with reports for tax compliance filing. 

The AFC Manual

The AFC Manual has been configured to provide an easy and logical progression for learning AFC and its features, as well as a quick reference (fully linked on the electronic version of the manual). From the initial step of mapping to the final creation of reports based on the processed information, the conceptual simplicity of AFC is fully explained.

Mapping

Prior to performing tax calculations, client transactions and services must be matched, or “mapped,” to the Valid Transaction and Service Pairings defined in AFC. Refer to Section 2 Mapping for the full explanation of how this is accomplished.

Transactions

Once the transactions and services have been mapped, transaction records can be passed to AFC.

Section 3 Transactions explains what AFC expects for each part (or field) contained in a transaction record and provides the definitions and reasons for selecting one of the valid options to use.

VPN Transaction and Service Types

Refer to TM_00115_AFC Transaction and Service Types for a list of combined transaction and service types that are used with VPN transaction types.

Tax Calculations

The AFC Engine accepts the transaction record(s) and performs the tax calculations based upon the information within the record.

Utilities

Once the taxation has been performed, Utilities can be used to provide the tax information in selected formats that meet specific requirements and perform file management functions. The many options available are detailed in the Utilities section of this document

The Advantage of Using Functions

Section 7 provides specific details of the expanded capabilities provided to users that integrate AFC to the billing system using functions. Refer to the figure shown below. The billing system passes information to AFC, as calls are being rated for billing. AFC calculates all required taxes and returns the tax information to the billing system per transaction. In addition, AFC stores all tax data generated in its databases and provides reports that facilitate tax filing and provide insight to the rating, billing and taxing processes.

Figure 1-1 AFC Operation Diagram

image

Adjustment information is returned to the billing system and is utilized to update tax data for report generation and compliance filing. AFC also provides facilities that allow users to insert tax overrides and exempt a transaction from taxes at federal, state, county and local authority levels. AFC also provides the capability to limit exemptions to a specific jurisdiction and to exempt specific taxes.

Using the AFC API is the most efficient method available for interfacing with the AFC system. Due to the superior performance of AFC, there is very little performance difference between a system running without taxation and one running with taxation generation by AFC.

General Product Information

Telecom Types

  • Business Classifications – Allows for specification of business as CLEC or ILEC. 
  • Service Classifications – Allows for specification of business as Primary Long Distance or Local Primary. 
  • Franchise – Allows for the indication that company provides services sold pursuant to a franchise agreement between the carrier and jurisdiction. 
  • Facilities – Allows for specification of the carrier delivering the service as facilities based. 

Customer Attributes 

  • Company Identifier – Allows the AFC user to indicate a specific company that may be included in their customer record and outputted to the tax log to identify company tax log records. 
  • Lifeline – Allows for a customer to be designated as a Lifeline participant. 

Enhanced Flexibility for Users 

User reporting and organizational activities have been enhanced with the addition of user defined fields. This empowers the user to include additional user specific information within transaction records, thereby enhancing reports and data files once processed by the AFC Engine. Note that the Batch Processing utility takes full advantage of the additional transaction fields. 

Enhanced Capabilities for Processing Specialized Taxes 

AFC maintains tax rate histories and applies them according to the transaction date. This allows for tax calculations to process transactions that require dated tax information. 

  • Billable Flag – Allows for the identification of a compliance only tax or fee that is used for filing and not passed on to the user. It is noted as a non-billable item in the tax log. 
  • Compliance Flag – Allows for the identification of a tax or fee that is a tax compliant item and that the tax or fee should be sent to the log. The reporting utilities can identify and generate compliance and billing reports. All existing taxes currently in AFC are compliance taxes or fees. A charge with the compliance set to false in logic is billable but the charge would not be place into the log for compliance or reported in compliance reports. This flag provides EZdata users with the ability to pass non-tax charges to the customer through AFC. 
  • Rate at Final - Allows for a specialized application of tax brackets. Each bracket specifies the tax rate for the “Total Tax” range that it spans. The culmination of all of the brackets results in a tax rate “look-up” table for total transaction amounts. 
  • Tier At Transaction - This logic flag indicates that tax will be calculated using graduated tax brackets on a transaction basis instead of a customer invoice basis. 
  • Tax On Tax Until No Effect - Configuration settings in EZTax.cfg determine one of two methods to calculate Tax on Tax. If the configuration setting is left unchanged, AFC will perform a single iteration of the tax on tax calculation. 

Additional Functions to Support New Capabilities 

An expanded library of functions has been created, the greatest impact of which falls on the Adjustment and Pro-Rated activities. 

  • Adjustment Functions – Additional functions are available to allow for adjustments of debit and pro-rated transactions. 
  • Pro-Rated Allowable Functions – Allow for a pro-rated percentage to be used to calculate the taxable amount on rate tax and calculate the percentage of the line and fixed amounts. AFC identifies taxes that are not allowed to be assessed on a percentage basis internally, and the entire tax amount is calculated. 
  • The Get Rates function has been added to retrieve all possible taxes when given a location by PCode. The structure of the returned tax information is compatible with the new override structure, so that specific changes can be applied to the existing tax data to create override entries. 

New Version Tracking

A version number has been embedded into the AFC database to ensure database compatibility between the AFC software and the AFC database. The AFC Engine compares version numbers on session initialization. If incompatible version numbers are detected, a message is written to the status file and AFC system will not return a valid session handle.

Additional Tax Types

AFC now supports over 450 Tax Types to allow for highly specific tax type designation.

Increased Accuracy

The Tax Amount and Time calculations have been modified to increase accuracy and further reduce rounding errors.

Mapping

The AFC software provides an extensive selection of Transaction and Service Types to meet your taxation requirements with a single taxation package. The correct matching, or “mapping,” of your company products and services to the Valid Transaction and Service Pairings defined in AFC is an essential process that must be completed accurately for taxation to be calculated and applied properly to all transactions. If an incorrect pairing is passed to the AFC engine then no tax is usually returned.

Avalara support is available to assist should any questions arise in determining the correct Transaction and Service pair to use.

Transaction and Service Types

AFC stipulates a unique pair of numbers for each Transaction and Service Type. The first number defines the Transaction Type and the second number defines the Service Type. Transaction Types and Service Types are combined (or “paired”) to uniquely describe a Valid Transaction / Service Pair for a transaction.

Valid Transaction/Service Pairings

TM_00115_AFC Transaction and Service Types provides a complete listing of identifiers used to define valid Transaction / Service Pairings.

Additional Transaction/Service Pairings Supported in Telecom

Telecom and SAU Transaction and Service Types are available for use with Avalara AvaTax for Communications SaaS Pro (REST) v2 and Avalara AvaTax for Communications SaaS Standard. They aren't available to view in the AvaTax for Communications Viewer (Telecom) and are available within the United States only.

Attributes are used to further specify details of a Sales and Use transactions.  Properties are included within some attributes to further define options within the attribute.  For valid Attributes and Properties to use with Telecom and SAU Transaction/Service Types, see Attributes and Properties in the Telecom Mapping Guidelines.

File transervdesc.txt

A file named transervdesc.txt is present in the database directory in each month’s update. This file contains all of the valid transaction type/service type pairs, with the description of those types and of the pairing. It is a fixed format file, though there are spaces and commas between some of the fields for readability. The file is described in the table below.

Note: If using the AFC On-Premise product, use the transervdesc.txt file to identify the valid Transaction/Service Pairs. Do not use this file if using AFC SaaS Pro REST v2 or AFC SaaS Standard because it does not contain the additional Transaction/Service Pairs found in the Telecom and SAU section of TM_00115_AFC Transaction and Service Types.

transervdesc.txt File Format Key

Description

Columns

Alternate Flag

1-1

Market Number

3-4

Market Name

6-35

Transaction Type Number

38-39

Transaction Type Description

41-90

Service Type Number

93-95

Service Type Description

97-146

Long Description

148-end of line

Transaction Mapping Guidelines

Long Distance Transaction and Service Types

The long distance transaction and service types provide the ability to tax 1+, 0+, 800, 900, WATS and private lines for both interstate and intrastate calls. The capability to tax access charges, late charges, services, installations, and International USA Inbound transactions is also provided.

Long Distance Transaction and Service Types can be found in TM_00115_AFC Transaction and Service Types.

  • Transaction Type 1 - Interstate
  • Transaction Type 2 - Intrastate
  • Transaction Type 3 - Other
  • Transaction Type 4 - Non-recurring

Wireless Transaction and Service Types

Wireless Transaction and Service Types can be found in TM_00115_AFC Transaction and Service Types.  Additional information about taxing cellular and PCS long distance transactions is available in TM_00511_AFC Cellular Service Mapping Guidelines.

  • Transaction Type 13 - Cellular

Enhanced Service Transaction and Service Types

These transaction and service types allow the taxing of paging, FAX, and voice mail services. 

Enhanced Service Transaction and Service Types can be found in TM_00115_AFC Transaction and Service Types.

  • Transaction Type 6 - Paging
  • Transaction Type 8 - Fax
  • Transaction Type 9 - Voice mail

Internet Transaction and Service Types

The federal government and most states do not tax Internet usage. AFC determines this based upon the jurisdiction information provided. If taxable, AFC applies the appropriate taxes for the given jurisdiction.

Internet Transaction and Service Types can be found in TM_00115_AFC Transaction and Service Types.

  • Transaction Type 5 - Internet

Local Service Transaction and Service Types

Local Service mapping demands special attention because more than one Transaction/Service Type is required to generate all of the necessary rated and per line taxes. 

Local Service Transaction and Service Types can be found in TM_00115_AFC Transaction and Service Types.  Additional information about taxing local service transactions is available in TM_00518_AFC Local Exchange Mapping Guidelines.

  • Transaction Type 7 - Local

Sales Transaction and Service Types

The transaction type “Sales” and the service type “Product” is provided for the taxing the sale of finished goods. All of the sales tax rates for the various states, counties and localities in the United States are provided.

The transaction type “Sales” and the service type “Use” is provided for taxing the use of products. All of the sales tax rates for the various states, counties and localities in the United States are provided.

Note: At this time, AFC does not handle sales tax exceptions. If a transaction is supplied to AFC using this transaction and service type, sales taxes will be applied based upon the jurisdiction. If sales taxes do not apply to the specified transaction, it is the user’s responsibility to determine this and not pass the transaction to AFC.

Sales Transaction and Service Types can be found in TM_00115_AFC Transaction and Service Types.

  • Transaction Type 10 - Sales
Debit Transactions

Debit transactions involve two transaction types; one at the time of sale as prepayment for the service, the other at the times of use following the purchase.

The time of sale payment should be processed using the Sales/Debit (10/32) transaction. The transactions that follow the sale as the time on the card is expended will be either the Interstate Call (1/1) transaction or the Intrastate Call (2/1) transaction.

When using API’s, the initial Sales/Debit transaction of the prepaid calling card would be processed through the normal API calls such as EZTaxPCodeEx. The Toll call transactions would be processed through the Debit API calls.

Additional information about taxing debit transactions is available in TM_00570_AFC Prepaid and No-Contract Services Mapping Guidelines.

Shipping Transaction and Service Types

Shipping Taxes are provided for the United States, its counties, and localities. 

Shipping Transaction and Service Types can be found in TM_00115_AFC Transaction and Service Types.

  • Transaction Type 11 - Shipping

Telephony Transaction and Service Types

Telephony Transaction and Service Types can be found in TM_00115_AFC Transaction and Service Types.  Additional information about taxing telephony transactions is available in AFC International Mapping Guidelines and AFC Comprehensive Guide to Reports and Data Files.

  • Transaction Type 14 - International
  • Transaction Type 15 - Telephony

Cable Television Transaction and Service Types

Cable Television Transaction and Service Types can be found in TM_00115_AFC Transaction and Service Types.

  • Transaction Type 16 - Cable Television

Satellite Television Transaction and Service Types

Satellite Television Transaction and Service Types can be found in TM_00115_AFC Transaction and Service Types.

  • Transaction Type 18 - Satellite Television

Voice over Internet Protocol (VoIP) Transaction and Service Types

VoIP Transaction and Service Types can be found in TM_00115_AFC Transaction and Service Types.  Additional information about taxing VoIP service transactions is available in TM_00527_AFC VoIP Mapping Guidelines.

  • Transaction Type 19 - VoIP
  • Transaction Type 20 - VoIPA
  • Transaction Type 59 - VoIP-Nomadic
  • Transaction Type 65 - Non-Interconnected VoIP

Nomadic VoIP service (such as soft phone service) should be handled using the Nomadic VoIP transaction type. Fixed location VoIP service (such as a business PBX system) faces different taxation decisions from State, County and Local jurisdictions.

Some jurisdictions have indicated that their taxes apply to VoIP, some have stated that they are not taxing VoIP and don’t plan to in the near future and others are taking a wait and see stance.

Because of these jurisdiction inconsistencies, providers are forced to take different attitudes toward taxation. Some are taxing VoIP as they would normal POTS lines while others are taking the position that VoIP is not taxable as a telecom service. Avalara’s versatile taxation engine is designed to support both of these approaches with the transaction types VoIP and VoIPA.

Refer to Table 2-13 and Figure 2-1. The VoIP transaction type returns telecom taxes in a jurisdiction that has stated that their taxes apply to VoIP and jurisdictions that are undecided. The VoIPA transaction type will only return telecom taxes in jurisdictions that have definitively stated their taxes apply to VoIP. These two approaches will converge as jurisdictions define how they want VoIP taxed.

Table 2-13 VoIP Transaction Returns

 

VoIP

VoIPA

Jurisdictions who tax VoIP

Tax

Tax

Undecided Jurisdictions

Tax

Don’t Tax

Jurisdictions who don’t tax VoIP

Don’t Tax

Don’t Tax

Figure 2-1 VoIP Tax

image

E911 and other Per-Line Taxes

Since VoIP users can connect via a landline or wireless connection and some jurisdictions have different rates for each of these, both rates are incorporated into the AFC system.

Use the “Lines” service type to receive the landline rate and the “Wireless Lines” service type to receive the wireless rate. Application of any per-line taxes, such as State TRS or State USF, is dependent on whether the VoIP or VoIPA is used.

The resulting four choices are:

  1. VoIP / Lines (19/21) – Returns landline E911 and per-line telecom taxes in jurisdictions that tax VoIP, and jurisdictions that are taking a wait and see approach. This combination will return only E911 at the landline rate in jurisdictions that have stated they are not taxing VoIP. 
  2. VoIP / Wireless Lines (19/52) – Will return wireless E911 and per-line telecom taxes in jurisdictions that tax VoIP, and jurisdictions that are taking a wait and see approach. This combination will only return E911 at the wireless rate in jurisdictions that have stated they are not taxing VoIP. 
  3. VoIPA / Lines (20/21) – Will return only landline E911 in jurisdictions that have stated they don’t tax VoIP, and in jurisdictions that are undecided. Will return telecom taxes and landline E911 in jurisdictions that tax VoIP. 
  4. VoIPA / Wireless Lines (20/52) – Will return only wireless E911 in jurisdictions that have stated they don’t tax VoIP, and in jurisdictions that are undecided. Will return telecom taxes and wireless E911 in jurisdictions that tax VoIP. 

Note: The per-line taxes are returned as a “fixed” amount when using the Wireless Lines service type. When passing the Wireless Lines service type you do not need to enter the taxable amount or number of lines. You only need to pass one transaction for each line that needs to be taxed.

Payphone Transaction and Service Types

Payphone Transaction and Service Types can be found in TM_00115_AFC Transaction and Service Types.

  • Transaction Type 21 - Payphone

Software Transaction and Service Types

Software Television Transaction and Service Types can be found in TM_00115_AFC Transaction and Service Types.

  • Transaction Type 24 - Software

Timesharing Transaction and Service Types

Timesharing Television Transaction and Service Types can be found in TM_00115_AFC Transaction and Service Types.

  • Transaction Type 25 - Timesharing

Satellite Phone Transaction and Service Types

Satellite Phone Television Transaction and Service Types can be found in TM_00115_AFC Transaction and Service Types.

  • Transaction Type 60 - Satellite Phone

VPN Transaction and Service Types

VPN Television Transaction and Service Types can be found in TM_00115_AFC Transaction and Service Types.

  • Transaction Type 61 - VPN

Tax Categories

See Category Definitions for a current list of Tax Categories.

Transactions

AFC accepts transaction records from the user and returns calculated taxes. For AFC to return the correct taxation the information in the transaction records must be correct and in the format that AFC requires.

Each Transaction contains the following information:

  1. Customer Transaction Information
    1. Customer Information
    2. Company Information
    3. Transaction Data
  2. Taxing Jurisdiction Information

The Customer Transaction Information has been divided into three sections as suggested above for the purpose of this discussion (see the table below).

Table 3-1 Customer Transaction Information

Customer Information

Company Information

Transaction Data

Business Class

Company Identifier

Charge

County Exempt

Facilities Based

Lines

County Exemption JCode

Franchise

Minutes

Customer Number

(Primary Output Key)

Regulated/Unregulated

Sale/Resale

Customer Type

 

Service Type

Federal Exempt

 

Transaction Bill Date

Federal Exemption JCode

 

Transaction Type

Incorp

 

 

Invoice Number

 

 

Lifeline

 

 

Local Exempt

 

 

Locality Exemption JCode

 

 

Service Class

 

 

Service Level

 

 

Tax Type Exemptions

 

 

State Exempt

 

 

State Exemption JCode

 

 

Tax Exempt

 

 

Options

 

 

Customer Information

Refer to the table below. The following customer information is contained in fields found in the transaction record.

Table 3-2 Customer Information

Description

Valid Entry

Business Class

CLEC = 1, ILEC = 0

Customer Number

(Primary Output Key)

Customer number, user defined

Customer Type

0=residential, 1=business customer

2=Senior Citizen, 3=Industrial

Federal Exempt

If TRUE, transaction exempt from Federal Tax

State Exempt

If TRUE, transaction exempt from State Tax

County Exempt

If TRUE, transaction exempt from County Tax

Locality Exempt

If TRUE, transaction exempt from local tax

Incorp

TRUE indicates within incorporated area

Invoice Number

Invoice number (user defined)

Federal Exemption JCode

Jurisdiction for Federal exemption

State Exemption JCode

Jurisdiction for state exemption

County Exemption JCode

Jurisdiction for County exemption

Locality Exemption JCode

Jurisdiction for local exemption

Lifeline

Lifeline = TRUE, Non-lifeline = FALSE

Service Class

Primary Long Distance = 1, Local Service = 0, (Default Long Distance)

Service Level Number

Service level number (user defined)

Tax Type Exemptions

0 indicates no of special exempts, other value indicates number of special exempts

Tax Exempt

Pointer to tax exempt structure that contains the number of specific tax exemptions specified in tax type exemptions

Exempt Type *s_exempt

Reason for exemption

Optional Fields:

Optional

User defined value for reporting

Optional Alpha

Optional alpha field

Optional 4

Optional Numeric field

Optional 5

Optional Numeric field

Optional 6

Optional Numeric field

Optional 7

Optional Numeric field

Optional 8

Optional Numeric field

Optional 9

Optional Numeric field

Optional 10

Optional Numeric field

Business Class Indicator

The Business Class Indicator field is used to specify if the business making the transaction is an Incumbent Local Exchange Company (ILEC) or a Competitive Local Exchange Company (CLEC). This designation applies to the Customer.

  • An ILEC company is engaged in selling services over company owned lines and equipment,
  • A CLEC company is engaged in selling services competing with an incumbent provider.

This setting can also be considered as, “You are ILEC” or, “You are not ILEC.” If neither class applies, use the default value CLEC.

The business class only impacts Telecom transactions in certain jurisdictions, such as Oregon.

ID

Value

Description

0

ILEC

Customer is an ILEC company.

1

CLEC (Default)

Customer is not an ILEC company.

Customer Number (Primary Output Key)

The Customer Number is a 20-character null terminated string field stored in the tax log and used as the Primary Output Key for all of the AFC billing reports.

Customer Type

This field is used to specify the type of customer involved in the transaction. The customer type is selected from one of the following four Customer Types.

ID

Value

Description

0

Residential

When transactions are made by a customer for home use.

1

Business

When transactions are made at a place of business

2

Senior Citizen

When transactions are made by a customer who meets the jurisdiction requirements to be considered a senior citizen and qualify for senior citizen tax breaks.

3

Industrial

When transactions are made at an industrial business.

Exemption Levels

The exemption level is the jurisdictional level of the taxing authority that defines the tax. It is used to exempt taxes at specific federal, state, county and/or local taxes.

Federal Exempt

The Federal Exempt field is used to specify a Federal level tax exemption.

Note: Most Federal taxes are only exempted when selling to a reseller who is registered, reporting, and remitting to the regulating agency. For this reason, a wholesale exemption or a tax type exemption must be used to exempt taxes at the Federal level.

State Exempt

The State Exempt field is used to specify a State level tax exemption.

County Exempt

The County Exempt field is used to specify a County level tax exemption.

Local Exempt

The Local Exempt field is used to specify a Local level tax exemption.

Incorp

The Incorp field is used to specify whether the customer involved in this transaction is inside or outside of the Local level designated as their location. The tax may or may not be affected by this designator depending upon whether or not the local level has taxes which would apply to the transaction/service type pair.

Invoice Number

The Invoice Number is an optional field used to aid users in uniquely identifying a billing record for a specific customer within their system.

JCode Exemption Levels

The exemption JCode is the JCode associated with the jurisdictional level of the taxing authority that defines the tax. It is used to exempt all federal, state, county and / or local taxes. If the exemption JCode fields are not specified then all taxes are exempt at that level.

To pass an individual tax exemption using the JCode Exemption, use the Tax Exempt structure to specify the tax type, tax level and the JCode for the jurisdiction. Refer to Section 4.1.1.2.

NOTE: JCodes are an internal intermediate Jurisdiction Code that can change monthly. The JCode can be obtained from a PCode or an address using like functions.

Federal Exemption JCode

The Federal Exemption JCode field identifies the JCode of the jurisdiction (i.e. country) for a federal exemption.

State Exemption JCode

The State Exemption JCode field identifies the JCode of the jurisdiction for a state exemption.

County Exemption JCode

The County Exemption JCode field identifies the JCode of the jurisdiction for a county exemption.

Locality Exemption JCode

The Locality Exemption JCode field identifies the JCode of the jurisdiction for a locality exemption.

Lifeline Flag

The Lifeline Flag is used to indicate if a customer is a Lifeline participant.

Service Class Indicator

The Service Class Indicator is provided to delineate the Primary activity of an organization as either Long Distance or Local Service.

  • Primary Long Distance providers are carriers vending their services with over 50% of the gross business activities in Long Distance revenue.
  • Primary Local Service providers are carriers vending their services with over 50% of the gross business activities in Local Service revenue.

NOTE: This has no effect on non-Telecom Transactions

Service Level Number

The Service Level Number is an optional field, commonly populated with the transaction type and service type. This information is stored in the tax log. Some AFC reporting utilities use this field when sorting information and/or creating reports.

Tax Type Exemptions

Two fields are provided for entering the quantity of tax type exemptions and the pointers to the tax exemption structures.

Tax Type Exemptions Field

The Tax Type Exemption indicator specifies the number of tax type exemptions that are included. These are tax type and transaction specific exemptions.

Tax Type Exemption Pointer

Tax type exemption(s) are specified with a pointer to one or more tax exempt structures. The user should supply a pointer to the first Tax Type Exemption and all exemptions must be contained in a contiguous block of memory.

Optional Fields

Optional Fields are provided to allow clients to enhance reporting and billing utilities with information beyond the scope of that which is generated to support AFC activities.

The Primary Output Key (POK) is a 20-character text field that is not manipulated during processing and stored as part of the log file record.

It can be used as part of the sorting key (see Figure 3-1) when using some utilities, allowing for the combining of records based upon this and other fields. It is useful when it is desired to have like taxes from different transactions combined, to have taxes from each transaction detailed individually in a report or to have each transaction detailed at the customer level.

Uniquekey.csf

Image_602.gif

 

Combined taxes

 

If you would want like taxes combined at the customer level, then you specify a like Primary Output Key for the records you want combined.

 

Samekey.csf

Image_603.gif

Company Information

Refer to Table 3-3. The following company information is contained in fields found in the transaction record.

Table 3-3 Company Information

Description

Valid Entry

Company Identifier

Company Identifier, optional

Facilities Based

Facilities Based (default) = TRUE, Non-Facilities Based = FALSE.

Franchise

Franchise (default) = TRUE, Non-Franchise = FALSE.

Regulated/Unregulated

TRUE = Regulated (default) = TRUE, Unregulated = FALSE.

Company Identifier

The Company Identifier field is an optional field made available for alpha information, such as the name of a subsidiary company. This information is passed thru to the tax log so that reporting utilities can sort or summarize by this field.

Facilities Based Flag

The Facilities Based flag specifies whether the transaction is sold over tangible facilities controlled by the seller. If the seller delivering the service owns or controls the facilities used to provide the service, then the seller is facilities based. If the seller does not own or control the facilities, the seller is non-facilities based. In some jurisdictions, tax outcomes will vary depending on whether the service is delivered over infrastructure controlled by the seller.

Franchise Flag

The Franchise flag indicates that the company provides services sold pursuant to a franchise agreement between the carrier and jurisdiction.

Regulated / Unregulated Flag

The Regulated / Unregulated flag is used to specify if the Telecommunications company and its services are regulated by the regulatory commission in the state of the service.

Transaction Data

Refer to Table 3-4. The following transaction information is contained in fields found in the transaction record.

Table 3-4 Transaction Data Information

Description

Valid Entry

Charge

amount charged to customer for transaction

Date

Transaction bill date. This field is provided to allow rating and taxing to occur on a date other than the billing date.

Lines

number of lines (use with transaction type LOCAL and service type LINES)

Minutes

Minutes of call, defaults to zero when not appropriate (NOTE: some taxes are per minute.)

Sale/Resale

TRUE = Sale, FALSE = Resale

Service Type

Refer to TM_00115_AFC Transaction and Service Types for valid Transaction / Service Type entries

Transaction Type

Refer to TM_00115_AFC Transaction and Service Types for valid Transaction / Service Type entries

Charge

The Charge field specifies the amount of the transaction to be taxed. This amount will be passed through AFC to rate the tax based on the specified transaction/service pair.

Date

The Date field is normally populated with the bill date. Generally accepted accounting principles dictate that liabilities should be recorded when revenues are recorded. In most cases, neither of these is recorded (or even known) until billing occurs.

However, companies with a high call volume that record revenue daily as it occurs should record the tax on the same basis (i.e. the call date should be used).

AFC compares this date to the effective date of each tax that applies to the transaction. Historical rates and effective dates are maintained and updated within the AFC Engine and AFC will return the correct tax information based upon the transaction date. The monthly updates assure that the rates and effective dates are current.

WARNING: All transaction data Date fields must be formatted as CCYYMMDD. Failure to do so will cause incorrect results when the transaction is processed.

Lines

When local service is provided, a transaction should be generated with the Lines field populated with the number of lines the customer subscribes to. AFC uses this information for generation of per line taxes usually associated with local E911 charges and local telecommunications relay service taxes and other assorted taxes.

Minutes

The Minutes Field specifies the length of phone call in minutes, with one tenth of a minute precision capability. AFC uses this field for generation of taxes that are specified as per minute flat fees in some taxing jurisdictions and stores the value in the AFC log database.

Sale Type

The Sale Type specifies the whether the transaction is a retail transaction or a wholesale transaction.

  • Resale should be used for wholesale transactions. Telecommunication companies are taxed on transactions made by their clients, which in some cases can be passed on or “resold” to their customers in part or in total. Resale is used to indicate whether the product or service transaction is final or if it is to be resold.
  • The type Sale should be used for retail transactions.

To have exempt taxes available for reporting, exemption type 3 (Sales For Resale) should be used in combination with Resale.

ID

Value

Description

0

Resale

Only Resale/Wholesale taxes apply

1

Sale (Default)

Standard taxes apply

Service Type

Refer to Transaction and Service Types for details of this field.

Transaction Type

Refer to Transaction and Service Types for details of this field.

Taxing Jurisdiction Identification Information

The tax jurisdiction that can claim nexus for the transaction must be obtained in order for the proper taxes to be applied. Assigning the correct jurisdiction to the transaction is crucial in obtaining and returning the correct tax to the billing system.

Jurisdiction information can be supplied to the AFC Engine in several ways. It can be supplied using a Jurisdiction Code (JCode), Permanent (location) Code (PCode), NPANXXs, Zip Code with city, and state information or FIPS Codes.

The JCode Jurisdiction Identification

Avalara has assigned each jurisdiction with a proprietary “JCode” (Jurisdiction Code) that identifies its specific territorial boundaries. A jurisdiction fairly claiming nexus on a transaction within this boundary will apply taxes accordingly. The AFC Engine uses this “jurisdiction bound” JCode to associate the jurisdiction specific taxes to the transaction as it is processed.

However, any alterations in the jurisdictional boundaries, such as an expansion of a city limit, will be reflected in the JCode of locations that are situated within the expanded jurisdiction area.

The Avalara tax research staff monitors jurisdiction taxation activity to maintain current and accurate taxation information. The results of this research is applied to the Monthly updates which are provided to ensure the most accurate taxation is applied to the records processed by the AFC Engine. The JCodes will be changed at this time. It is the user’s responsibility to re-populate their database tables with the new JCodes every time an AFC update is provided. If this task is not performed, the AFC Engine will return incorrect tax calculations for jurisdictions that have been updated.

However, when a transaction is submitted with the stable and location sensitive PCode, the AFC Engine can use internal functions to obtain the correct jurisdiction. Since the AFC Engine is updated with the re- mapped jurisdiction information monthly, tax calculations are always performed with the most current jurisdiction taxation information that applies to the address defined by the PCode.

Figure 3-2 JCode and PCode Changes During Annexation

Image_JcodeAnnexation.png


All that is required to make use of this recommended option is to cross reference or “map” the customer locations with its correct PCode (see Mapping Customer Locations to PCodes) time invested in incorporating PCodes into your database records will be quickly offset by the reduced processing time and the increased accuracy and reliability of your tax reporting will be evident.

Mapping Customer Locations to PCodes

Avalara markets Avalara Geo for Communications to assist in mapping customer locations to PCodes when populating the client customer database. It quickly obtains the current PCode for a specific geographical location.

When performing this task without the aid of AFC Geo, refer to the all_adr.txt file to look up the PCode that should be used to populate the client database with customer information. This comma delimited ASCII file is supplied for use during AFC setup and when adding new customers to the client database. The file is replaced with a current version when monthly updates are performed (refer to Section 8.4).

all_adr.txt is a comma-delimited text file that contains a cross reference of PCodes to taxing jurisdictions. The format is PCode, Primary / Alternate Location, Country, State, County, Locality, Beginning ZIP Code, Ending ZIP Code. These fields are self-explanatory with the exception of the Primary / Alternate Location.

Primary/Alternate Location

The Primary / Alternate location flag is set to '0' to indicate that the location associated with the PCode is a "Primary" location or '1' to indicate that it is an "Alternate" location.

Secondary locations are original city names that remain in use even though the areas within them have since been divided and given different names.

For example, the city of Overland Park, KS is a primary location. The first post office to serve the area was established at the Shawnee Methodist Mission in the early nineteenth century, the extents of which

encompassed the then non-existent city of Overland Park as well as nearly a dozen other cities (primary locations) which appeared over time. The post office still recognizes the Shawnee Methodist Mission area as Shawnee Mission, KS, and continues to deliver to a primary location when the “Alternate Location” address is provided.

Data Entry Modification Procedure

Use the following procedure to acquire the correct information to enter.

  1. Have the customer data entry software first request the NPANXX of the customer from the data entry associate. 
  2. Have the customer data entry software request the zip code of the customer from the data entry associate. 
  3. Query the NPANXX7 file and the "all_adr" file/database to obtain the associated PCodes. 
  4. If matching PCodes are found, populate the customer data record with the associated address from the "all_adr" file and request verification from the customer data entry associate. 
  5. If the PCodes do not match or if the customer data entry associate rejects the automated selection, display all addresses associated with both PCodes and the zip code entered. 
  6. Allow the customer data entry associate to select the appropriate address from the list. 
  7. In the unlikely event that the customer address is not displayed, allow the customer data entry person to enter the address supplied by the customer. Store the address with a "special key" as instructed by Avalara Return the address and key to Avalara via E-mail. Avalara will research the missing address and include it in the next monthly update. Avalara will also provide you with a cross reference of the "special key" and the correct "PCode" to allow the customer record to be properly installed. 

NOTE: Avalara subscribes to the United States Postal Database which should preclude this event. Nonetheless, it does occur on occasion and this process has been established for that reason.

Use the PCode from the customer record for the service address when interfacing with AFC.

Resources such as the USPS or the U.S. Census Department web sites can also be helpful in pinpointing a customer location.

AFC functions can also be used to obtain PCodes (see Section 7.8 API Listings). For detailed information about determining the tax jurisdiction which can claim nexus on a transaction, refer to Section 3.5.

NPANXX

NPANXX input is nearly as accurate as the JCode method and performance differences are virtually undetectable. Using this method, the jurisdiction is determined by the three elements of a transaction; the origination, termination and bill-to.

However, there are potential problems associated with using the NPANXX.

  1. The first six digits of a toll free 800 or 888 number do not constitute an NPANXX. Rather, these numbers are associated with a “ring to” number which is the number that is actually reached when the 800/888 number is dialed. The NPANXX of the “ring to” number should be used as the NPANXX for the 800 number. This replacement must be made before the information is passed to the AFC system. 
  2. Switches are capable of producing CDRs with account codes in place of a “Bill To” number, which is not related to an actual NPANXX. The user is required to convert this number to the actual NPANXX using data from the billing system before interfacing with AFC. 

NPANXXs exist for the U.S., Barbados, Canada, Guam, Mexico, Northern Mariana Islands, Puerto Rico, Trinidad & Tobago and the US Virgin Islands. These countries are on the North American dialing plan.

Use of NPANXX for determination of a taxing jurisdiction is not sufficient for local service. There are too many foreign exchanges that will incorrectly map customers to the wrong local tax jurisdiction resulting in the wrong local taxes to be applied and unwanted calls to your customer service department.

Zip Codes

This method of providing jurisdiction information is the least efficient method provided. When using the ZIP Code and address information, AFC cannot determine the jurisdiction for a telecommunication transaction since information regarding the origination and termination numbers is not provided. A record submitted using this method will compromise the accuracy of correct jurisdiction identification, the degree of which would depend upon the amount of data provided for the address and the user’s ability to select the correct taxing jurisdiction zip code and address. AFC databases necessarily contain numerous duplicate zip codes that cross taxing jurisdiction and locality boundaries. Providing a complete address with zip code will provide the best possible match. If the address information is not provided, AFC will return taxes based upon the first match of the input record information.

If the jurisdiction is positively identified by the billing system it would be appropriate to use the zip code for transactions. For instance, this would apply if the transaction is the sale of a product at a business that has just one location or in the case of internet usage from a residence.

AFC currently has Zip Code information for U.S. and Canadian jurisdictions. Use the Zip Code Plus 4 Interface to use the 6 character Canadian postal codes.

Zip Plus 4

Just as with the Zip Code method (see Section 3.5.3), AFC cannot determine the jurisdiction for a telecommunication transaction since information regarding the origination and termination numbers is not provided. However, it is useful (and more accurate than the 5-digit zip code) because this 9-digit zip code uniquely identifies a location, which can then be used to determine the tax jurisdiction. There is no need to supply the additional city and county information and information in these fields are ignored.

NOTE: Supplying ZIP Code Plus 4 information where the plus 4 is all zeros will function like the ZIP Code Interface since the United States Postal Service has no valid plus 4 code assigned with all zeros. The default will retrieve the first jurisdiction with the supplied 5-digit zip code.

Canadian Postal Codes

Canadian postal codes need to be specified using the ZIP Plus 4 to retrieve a tax jurisdiction code. Place the first three characters go in the zip code field and the last three characters go in the plus 4 field. In addition, the country ISO field must be set to the Canadian ISO Code.

FIPS Codes

AFC has functions allowing the use of FIPS codes to retrieve tax jurisdiction codes. The US Census Bureau provides the following description of the FIPS Codes and associated reference tables.

“The Federal Information Processing Standards codes (FIPS codes) are a standardized set of numeric or alphabetic codes issued by the National Institute of Standards and Technology (NIST) to ensure uniform identification of geographic entities through all federal government agencies. The entities covered include: states and statistically equivalent entities, counties and statistically equivalent entities, named populated and related location entities (such as, places and county subdivisions), and American Indian and Alaska Native areas”.

A FIPS Code is a 10-digit numeric code with the following format:

Table 3-5 FIPS CODE FORMAT

SSCCCPPPPP

SS

FIPS State Code

CCC

FIPS County Code

PPPPP

FIPS Place Code

Figure 3-3 FIPS State Codes for the States and the District of Columbia

Name

FIPS State Numeric Code

FIPS State Alpha Code

Name

FIPS State Numeric Code

FIPS State Alpha Code

Alabama

1

AL

Montana

30

MT

Alaska

2

AK

Nebraska

31

NE

Arizona

4

AZ

Nevada

32

NV

Arkansas

5

AR

New Hampshire

33

NH

California

6

CA

New Jersey

34

NJ

Colorado

8

CO

New Mexico

35

NM

Connecticut

9

CT

New York

36

NY

Delaware

10

DE

North Carolina

37

NC

District of Columbia

11

DC

North Dakota

38

ND

Florida

12

FL

Ohio

39

OH

Georgia

13

GA

Oklahoma

40

OK

Hawaii

15

HI

Oregon

41

OR

Idaho

16

ID

Pennsylvania

42

PA

Illinois

17

IL

Rhode Island

44

RI

Indiana

18

IN

South Carolina

45

SC

Iowa

19

IA

South Dakota

46

SD

Kansas

20

KS

Tennessee

47

TN

Kentucky

21

KY

Texas

48

TX

Louisiana

22

LA

Utah

49

UT

Maine

23

ME

Vermont

50

VT

Maryland

24

MD

Virginia

51

VA

Massachusetts

25

MA

Washington

53

WA

Michigan

26

MI

West Virginia

54

WV

Minnesota

27

MN

Wisconsin

55

WI

Mississippi

28

MS

Wyoming

56

WY

Missouri

29

MO

 

 

 

Figure 3-4 FIPS State Codes for the Outlying Areas of the United States, the Freely Associated States and Trust Territory

Area Name

FIPS State Numeric Code

FIPS State Alpha Code

Status

American Samoa

60

AS

1

Federated States of Micronesia

64

FM

3

Guam

66

GU

1

Marshall Islands

68

MH

3

Northern Mariana Islands

69

MP

1

Palau

70

PW

4

Puerto Rico

72

PR

1

Virgin Islands of the U.S.

78

VI

1

Support for India

Processing tax calculations in the the country of India includes support for all the states. Please reference the table below for the appropriate IDs, abbreviations and PCodes for each state.

States in India

Ctry Code

ISO

State Id

Abbv

State

PCODE

356

IND

1

AP

Andhra Pradesh

5148401

356

IND

2

AR

Arunachal Pradesh

5148402

356

IND

3

AS

Assam

5148403

356

IND

4

BR

Bihar

5148404

356

IND

5

CT

Chhattisgarh

5148405

356

IND

6

GA

Goa

5148406

356

IND

7

GJ

Gujarat

5148407

356

IND

8

HR

Haryana

5148408

356

IND

9

HP

Himachal Pradesh

5148409

356

IND

10

JK

Jammu and Kashmir

5148410

356

IND

11

JH

Jharkhand

5148411

356

IND

12

KA

Karnataka

5148412

356

IND

13

KL

Kerala

5148413

356

IND

14

MP

Madhya Pradesh

5148414

356

IND

15

MH

Maharashtra

5148415

356

IND

16

MN

Manipur

5148416

356

IND

17

ML

Meghalaya

5148417

356

IND

18

MZ

Mizoram

5148418

356

IND

19

NL

Nagaland

5148419

356

IND

20

OR

Odisha

5148420

356

IND

21

PB

Punjab

5148421

356

IND

22

RJ

Rajasthan

5148422

356

IND

23

SK

Sikkim

5148423

356

IND

24

TN

Tamil Nadu

5148424

356

IND

25

TG

Telangana

5148425

356

IND

26

TR

Tripura

5148426

356

IND

27

UP

Uttar Pradesh

5148427

356

IND

28

UT

Uttarakhand

5148428

356

IND

29

WB

West Bengal

5148429

356

IND

30

AN

Andaman and Nicobar

5148430

356

IND

31

CH

Chandigarh

5148431

356

IND

32

DN

Dadra Nagar Haveli

5148432

356

IND

33

DD

Daman and Diu

5148433

356

IND

34

DL

Delhi

5148434

356

IND

35

LD

Lakshadweep

5148435

356

IND

36

PY

Puducherry

5148436

Jurisdiction Identification Details

Obtaining the correct user’s location is critical in calculating the local taxation.

Determining the Taxing Jurisdiction for Wireline

AFC applies taxes to transactions based on the statutes that dictate specific taxes per jurisdiction. The AFC engine contains current taxing information for jurisdictions, but for AFC to calculate taxes for long distance telecommunication calls correctly it must determine the taxing jurisdiction for the transaction based on the following:

  • Origination Jurisdiction – The Origination location of the transaction to be taxed. For telecom activity, this is usually specified by the number called from, also known as the “From Number” or “Origination number.
  • Termination – The Termination location of the transaction to be taxed. For telecom activity, this is usually specified by the number called, also known as the "To Number" or the "Termination number."
  • Service Address – The Service Address of the transaction to be taxed. For telecom activity, this is usually specified by the service location; also known as the Bill To Number or BTN.

Each jurisdiction from the state level down to the local level establishes jurisdiction rules to determine if their tax will apply to a specific call transaction. These jurisdiction rules (also known as sourcing rules) for determining the correct jurisdiction arose from a United States Supreme Court ruling that established the minimum requirements necessary for a taxing jurisdiction to claim “nexus” and validly tax a particular wireline long distance telecommunication transaction.

Known as the Goldberg Rule, or the “2 out of 3 Rule,” the ruling requires that two out of the three sourcing elements (origination, termination, and service address) must take place in a particular jurisdiction in order for that jurisdiction to tax the transaction. Figure 3-6 provides two examples to illustrate this principle.

Figure 3-5 Correct Jurisdiction Transaction Taxation applying Goldberg Rule

2 out of 3

The first example is a call that originates in Oregon, terminates in California and has a service address (BTN) in Oregon. Since “2 out of 3” sourcing elements take place in Oregon, Oregon may tax this transaction.

The second example is a call that originates in New Mexico, terminates in Texas and has a service address (BTN) in Kansas. Since no state has more than 1 out of the 3 sourcing elements, the transaction is not taxable by any state.

The “Goldberg Rule” or “2 out of 3” is the minimum standard. Many jurisdictions apply rules that apply stricter nexus requirements. For example, a jurisdiction might require that a transaction both originate and be billed in that jurisdiction in order to be taxed. This is a stricter requirement since the jurisdiction has eliminated one of the elements as a possibility. Fewer transactions will be taxable by this rule than by the straight “Goldberg Rule”. No jurisdiction may impose a rule that will result in more transactions being taxable than the “Goldberg Rule”.

Incorrect Jurisdiction Assignment

A customer may be assigned an incorrect jurisdiction if the geographical information is not thoroughly researched. In the example shown in Figure 3-7, the customer (marked by an X) resides in a rural area located in Pawnee County, Nebraska, just outside the city limits of Summerfield, Kansas.

Figure 3-6 Geographical Anomaly

Summerfield Map

However, in all likelihood this customer’s phone line is served by a switch in Summerfield, Kansas and will therefore have a Summerfield, Kansas NPANXX. It is also likely that the customer’s mail service is provided by the Summerfield, Kansas Post Office and therefore has a Summerfield, Kansas mailing address.

This geographical anomaly will cause an incorrect assessment of taxation if not researched properly. If the AFC user enters the customers NPANXX and Service Address information into the transaction records, the customer will be incorrectly assessed taxes according to those of the Summerfield, Kansas jurisdiction instead of those for the unincorporated area of Pawnee County, Nebraska jurisdiction.

Tax Situsing

Although the jurisdiction is determined by the “2 out of 3 rule” for the majority of long distance telecommunications taxes, it is only one of 10 rules specified for jurisdiction determination by taxing jurisdictions in the United States.

  1. Tax based on 2 out of 3 Rule – Apply tax where 2 out 3 jurisdictions are equal. This is usually the default option.
  2. Tax based upon Billing – Apply tax based on the billing location.
  3. Tax based upon Origination – Apply tax based on the Origination of the call location.
  4. Tax based upon Termination – Apply tax based on the Termination of the call location.
  5. Tax if (Bill=Orig) – Apply tax only if billing jurisdiction and origination jurisdiction is equal.
  6. Tax if (Bill=Orig=Term) – Apply tax only if all three jurisdictions are equal.
  7. Tax if (Bill=Tax Jurisdiction) – Apply tax if billing jurisdiction equals origination or termination jurisdictions.
  8. Tax if (Bill=Term) – Apply tax only if billing jurisdiction and termination jurisdiction is equal.
  9. Tax if (Orig=Tax Jurisdiction) – Apply tax if origination jurisdiction equals billing or termination jurisdictions.
  10. Tax if (Term=Tax Jurisdiction) – Apply tax if termination jurisdiction equals billing or origination jurisdictions.

Determining the Taxing Jurisdiction for Cellular

For cellular transactions, the service address (BTN) is used to determine the jurisdiction. Cellular services by their inherent nature are nomadic, making the origination point of a phone call transient and prone to difficulty in tracking. In an effort to resolve this uncertainty, Congress passed the Mobile Telecommunications Sourcing Act (MTSA). The MTSA is a federal law which requires all state and local taxes to adopt language sourcing cellular services to the customer’s “place of primary use” (PPU) or the location where the customer predominately uses their cell phone. The federal statute allows the seller to presume that the place of primary use is the customer’s billing address until the customer notifies them that this is not the case.

Determining the Taxing Jurisdiction for VoIP

VoIP services may be utilized on a nomadic basis with difficulties in determining the originating location at the time of the call. Unfortunately, Congress has not passed a Primary Place of Use (PPU) statute for VoIP; however, the same guidelines outlined in the Mobile Telecommunications Sourcing Act (MTSA) are the generally followed industry practice. The seller is allowed to presume the PPU based on the customer’s billing address until the customer notifies them that this is not the case.

Determining the Taxing Jurisdiction within Canada

Sourcing telecommunication taxes in Canada differs in that determining the “place of supply” must be clearly identified through application of the following rules:

  1. A supply of a telecommunication service, which produces the availability of telecommunications facilities, (other than a service of granting sole access to a telecommunications channel) is made in a province if:
    • all of the facilities are ordinarily located in that province; or
    • where not all of the facilities are ordinarily located in the province, the invoice for the supply is sent to an address in that province.
  2. For other types of supplies of telecommunication services (other than a service of granting sole access to a telecommunications channel), the supply is made in a province if the telecommunication:
    • is both emitted (originating) and received (terminating) in that province;
    • is either emitted (originating) or received (terminating) in that province and the billing location for the service is located in that province; or
    • is emitted (originating) in the province and received (terminating) outside the province and the billing location for the service is not in a province where the telecommunication is emitted or received.

AFC Calculations

The AFC Engine accepts the transaction record, processes the information provided and creates a table containing the generated tax information. Additional methods to process specialized taxes are available through the use of AFC functions.

Meeting the Requirements of Specific Tax Issues

Many tax issues are resolved within the AFC Engine, thereby relieving the user from making changes to account for them. Additional functions are provided to meet other special taxation issues.

Table 4-1 Specific Tax Issues

Category

Description

Specific Tax Exemptions

Specifies tax type at specific tax level for exemption

Tax Adjustments

Allow for adjustment activities such as refunds, changing a customer’s bill or when terminating un-collectable accounts.

Tax Overrides

Allows for a change of a tax rate.

Tax Rate Brackets

Tax rate that changes as the taxable amount of the transaction increases.

Rate at Final

A specialized case of tax brackets.

Discount Adjustment

Allows for entry of different discount adjustment types.

Tier on Transaction

Allows for tax to be determined using graduated tax brackets.

Tax on Tax Until no Effect

Option to control calculation of tax on tax

Taxed Taxes

Allows for processing when one tax includes in its base the tax calculated from another tax.

Get Rates

Retrieves current tax information in a form suitable for overrides.

Tax Type Exemptions

Tax Type Exemptions are used to specify a specific Tax Type at a specific Tax Level to be exempted for the current transaction. The exemption jurisdiction code specifies the jurisdiction for the tax exemption. If the jurisdiction code is not specified (i.e. set to zero), then all taxes of the Tax Type and Tax Level specified are considered exempt regardless of the jurisdiction they are calculated for. Typically the JCode should be specified as specific tax exemptions are normally only effective for specific jurisdictions.

Another option allows the tax type to be set to zero, to indicate that all taxes of a specific tax level are exempt in the specific jurisdiction.

Declaring Tax Type Exemptions within a Transaction Record

When setting up the AFC transaction record, there are fields that specify either exempt at a tax level or a specific tax. For more information, reference Sections 3.1.4 for exemption levels, 3.2.2 for Jcode exemption levels and 3.2.6 for tax type exemption levels.

Declaring Tax Type Exemptions Using Functions

Alternatively, Tax Type Exemptions can be applied using functions (such as APIs). The following fields are required for this.

Table 4-2 Tax Exempt Record

Tax Type

Tax Type identifier

Tax Level

Tax Level identifier

JCode for Exemption

Jurisdiction for exemption

In addition, the transaction contains a pointer set to the tax exempt to exempt a specific tax.

Table 4-3 Tax Exemption Fields

tax_exempt

Identifies the number of exemption records

*s_exempt

Pointer to the Tax Exempt record (see Table 2-4) or Array of Tax Exempt records.

If no records are setup, this value should be null.

General Tips When Declaring Tax Exemptions
  1. The JCode is used to specify tax exemptions because exemptions are normally only effective for specific jurisdictions.
  2. Federal taxes cannot be exempted using a level exemption, but can be exempted using specific exemptions. Some taxes, such as the Federal USF tax, are non-exemptible using level exemptions. These non-exemptible federal taxes may also be overridden to exempt them.  Refer to Section 4.1.3 for more information on Tax Overrides.
  3. It is easy to evaluate the exemptions passed through AFC because they are tracked separately and stored in the tax log by type of exemption.

Tax Adjustments

Tax adjustment functions provide for adjustment activities such as refunds, changing a customer’s bill or writing off un-collectable accounts. The AFC engine allows adjustments to be passed by the user. Note that these adjustments must be accounted for to provide an audit trail.

Tax adjustments are made using the Adjustment functions. The tax amount entered should be a positive number for credit adjustments as the adjustment functions will appropriately sign the charges, lines or locations for computation purposes. The adjustments are logged in the EZTax.log along with the rest of the tax and transaction data associated with the tax run. The information is returned to the billing system and is utilized to update tax data for report generation and compliance filing.

Adjustments may be declared as ‘default’ in which case they are processed exactly like a similar charge transaction with negative tax results. They may be declared as least or most favorable. This declaration is only useful for taxes which have multiple tiers or brackets and should be used with caution. The rate will be determined separately for each tax returned within the tax table. AFC software will search the tiers or brackets and select the tier which has either the highest rate (for most favorable) or lowest rate (for least favorable) and apply that rate to the number of lines or charge amount as appropriate.

General Tips When Making Tax Adjustments
  1. To calculate adjustments accurately, AFC requires the following activity:
    1. Call AFC using an adjustment API. (Please refer to the APIs provided in Section 7.8 API Listings).
    2. Send positive values for change and lines.
    3. Set the adjustment method (see the Adjustment Method Table below).
    4. Set the discount type (see the Discount Type Table in Section 4.1.7).
  2. If logging is turned on, adjustments are stored in the eztax.log file with the other transactions.

Adjustment Method Table

Name

Description

Default

Tax brackets applied normally.

LeastFavorableRate

Tax brackets applied to produce smallest tax refund.

MostFavorableRate

Tax brackets applied to produce largest tax refund.

Line Based Adjustments

Normal adjustments are managed with the processes outlined thoughout this section; however, there are exceptions to this process when managing line based adjustments in Invoice Mode. When adjustments are made in Invoice Mode with line based transactions, AFC will use the rate for the total number of lines within the adjustment(s). The system will not make any assumptions regarding the purchase rate of the original lines. Therefore, the rate charged will reflect the total number of lines received. (Please see the example provided in the scenario below).

Adjustment Scenario

Number of Lines

Rate

Total Tax Amount

Customer Orders 1 line

Rate @ 0.67

Tax = 0.67

Customer Orders 5 lines

Rate adjusted to 6 lines @ 0.34

Tax+=1.37

Customer Orders 40 lines

Rate adjusted to 46 lines @ 0.22

Tax+=8.08

Customer Orders 5 lines

Rate adjusted to 51 lines @ 0.17

Tax-=1.45

Customer adjustment 7 lines: rate @ 0.34 tax = 2.38

 

Rate Table

Lines

Tax

Lines

Tax

1-10

5.92

81-90

53.28

11-20

11.84

91-100

59.20

21-30

17.76

101-110

65.12

31-40

23.68

111-120

71.04

41-50

29.60

121-130

76.96

51-60

35.52

131-140

88.80

61-70

41.44

141-150

59.20

71-80

47.36

151-160

94.72

Tax Overrides

Overrides allow the client to change the rate of a tax in the AFC Engine. Avalara markets the AFC Manager – Rate and Logic Modifier (a Graphic User Interface based Windows program that is sold separately) to support this activity. It steps the user through the process of creating an EZTax.ovr file. Alternatively, overrides can be achieved using the Override functions (such as APIs).

WARNING: An override to exempt taxes OVERRIDES the tax information in Avalara’s tax research database. This is not recommended for those that do not possess a full understanding of the tax ramifications and liabilities when doing so.

Although all clients can use Tax Overrides, the method to make use of them depends upon the client type.

  1. AFC SaaS Standard clients must use the AFC Manager – Rate and Logic Modifier to create an EZTax.ovr file that contains the overrides to insert. The file is then uploaded to the service bureau inside the FTP.zip file that carries the CDS file for processing. The overrides are then used during that processing and for subsequent processing until a new or empty override file is uploaded.
  2. Avalara clients that submit records in Batch fashion must use the AFC Manager - Rate and Logic Modifier to create an EZTax.ovr file that contains the overrides to insert. Filelocs.txt is then modified to point to this file. When the data file is processed, the overrides are inserted automatically.
  3. Avalara clients that integrate with the AFC Engine using functions (such as APIs) can use the Override utility as an easy way to create overrides in the same manner that batch mode and online clients do, modify filelocs.txt to point to the EZTax.ovr file or use the file path to point to the EZTax.ovr file.

The following functions use a session and a tax override record to override the tax rates used by AFC to calculate taxes.

Table 4-4 Tax Override Names and Descriptions

Function Name

Override Description

EZTaxOvrJCodeEx**

 

**This is the override JCode function for the most current version of AFC.

 

Performs tax override using a JCode to designate the Jurisdiction.

EZTaxOvrJCodeWithAdd

Specified an override for a specific tax.

EZTaxOvrPCodeEx

Performs tax override using a PCode to designate the

Jurisdiction.

EZTaxOvrZipEx

Performs tax override using zip code and address information

to designate the Jurisdiction.

Tax Override Fields

AFC functions can be used to override a specific tax rate used by AFC.

Table 4-5 Tax Override Fields

Field

Description

Scope

Scope of override

Type

Tax type identifier

Level

Tax level identifier

Exempt Level

Level of Exemption

Limit

Maximum lines or charge to apply tax to

Date

Effective date of Tax Rate

Tax Rate

Tax Rate

Previous Tax Rate

Previous tax rate

Maximum Base

Maximum amount to apply tax

Excess Tax

Rate for amount above the Maximum Base

State Override

Override state rate if present

County Override

Override county tax if present

Replace State Tax

Tax replaces state tax

Replace County Tax

Tax replaces county tax

Scope

Refer to Table 4-6. The term Scope is used to indicate the magnitude of the override.

Table 4-6 Tax Level Effect of Exemption

Tax Level

Scope

Effect of Exemption

Federal

Federal

Exempt all defined Federal taxes

Federal

State

Exempt entire State for the specific Federal taxes

Federal

County

Exempt the Federal taxes within a specified County

Federal

Locality

Exempt the Federal taxes within a specified Locality

State

State

Exempt all Defined State taxes within a State

State

County

Exempt the State taxes within a specified County

State

Locality

Exempt the State taxes within a specified Locality

County

State

Exempt all County taxes within a specified State

County

County

Exempt all County taxes within a specified County

County

Locality

Exempt the County taxes within a specified Locality

Locality

State

Exempt all Locality taxes within a specified State

Locality

County

Exempt all Locality taxes within a specified County

Locality

Locality

Exempt all Locality taxes within a specified Locality

As an example, specifying a gross receipts tax at the Local level with a scope of State level will cause all jurisdictions in the state identified by the jurisdiction to be passed to the AFC Engine with the specified tax overridden. The County level affects all taxes in the County and Local level affects only the jurisdiction specified. The specification of Federal level is only valid with federal taxes which will always be overridden at the Federal level.

Type

The Tax type identifier is used to define the type of tax for which the override will apply.  Refer to AFC Tax Types for a complete list of supported Tax Types.

Level

The Tax level identifier is used to define the level for which the override will apply.

Exempt Level

Refer to Table 4-6. The Exempt Level indicator is used to define whether a tax can be exempted by an exemption for all taxes at the same level as this tax. TRUE indicates that the tax can be exempted while FALSE indicates that it cannot be exempted. Note that the tax can still be exempted by a specific tax exemption.

For instance, a state level universal service fund will be exempt if this field is set TRUE and a state level tax exemption flag is passed to AFC. If the flag is set TRUE an exemption at the level of the tax will exempt the tax. If the flag is set FALSE an exemption at the level of the tax will have no effect on that specific tax.

Limit

The limit indicator is only used for taxes applied per line. When this field is set to zero it indicates no limits are in effect for the specified tax. When the limit is not zero, AFC will apply the tax based upon the number of lines up to, but never exceeding, the limit amount. This has no effect on sales taxes

Date

The Date field is used to define the effective date that the tax rate is active. The transaction date is compared to the effective date to determine if the current tax rate or the previous tax rate is to be applied.

Tax Rate

If the taxes are computed as a percentage of the charge then the Tax Rate field is used to indicate the tax rate. For example, if a 5% sales tax were applied then the tax rate would be entered as .05. For all other taxes such as per line, fixed, and per minute, the dollar amount should be entered for the tax.

Previous Tax Rate

The Previous Tax Rate field is supplied for use when a previous tax is to be used for the tax rate.

Maximum Base

The Maximum Base defines the maximum charge that the tax is applied to. Any charge above the maximum base is charged at the excess tax rate.

Excess Tax

If the tax only caps the charge that the tax is applied to then set the excess tax to zero.

State Override

The Locality or County sales tax record can override the state sales tax rate. This is useful where localities or counties have a special agreement with the state to collect the state tax at a different rate. If the tax is zero then no override will be in effect.

County Override

The Locality sales tax record can override a County sales tax rate. This is useful where localities have a special agreement with the County to collect the County tax at a different rate. If the tax is zero then no override will be in effect.

Replace State Tax

This option is made available for the rare occasion when a Locality or County sales tax replaces the state sales tax completely.

Replace County Tax

This option is made available for the rare occasion when a Locality sales tax replaces a county sales tax completely.

Tax Override Options

The Enhanced Override is used to override taxes.

Table 4-7 Tax Override Options

Name

Description

Enhanced Override

Required fields for the Enhanced Override.

Enhanced Date Override

Required fields for Date Override.

Enhanced Rate Override

Required fields for Rate Override.

Enhanced Override

The Enhanced Override requires the following fields.

Table 4-8 Enhanced Override Fields

Name Description

Scope

Scope of override

Type

Tax Type identifier

Level

Tax Level identifier

Date Count

Number of date records (normally 2)

Date Table

Address of array of date records

Enhanced Date Override

The Enhanced Date override requires the following fields.

Table 4-9 Enhanced Date Override Fields

Name Description

Override Date

Starting (effective) date for this set of tax rates

Rate Count

Number of rate records for this date (normally 1)

Level Exempt

Indicates if tax can be exempted by an exemption for all taxes at the same level as this tax.

Tax can still be exempted by specific tax exemption.

Rate Table

address of array of rate records

Enhanced Rate Override

The Enhanced Rate Override requires the following fields and rate entries in rate table for taxes.

Table 4-10 Sales Rate Override Fields

Name Description

Tax

Tax Amount (rate)

Maximum Base

Max amount subject to this tax(end of bracket)

Replace State

Tax replaces the state tax

State Override

Overrides the state rate if present

Replacement County

Tax replaces the county tax

County Override

Overrides the county tax if present

Get Rates

The AFC Get Rates function can be used to build the current tax information into the override structure. Specific changes can be made to returned tax entries to create custom overrides.

Table 4-11 Get Rates Override Fields

Name Description

PCode

Jurisdiction PCode

Tax Count

Count of all taxes for this jurisdiction

*Taxes Table

Table of all taxes for this jurisdiction in override format

NOTE: The scope value will be set to the tax level.

General Tips When Using Overrides
  1. Overrides are not permanent. When an AFC session is exited the created overrides are removed and no longer available. They can also be removed without exiting a session using the EZTaxRestore function.
  2. AFC cannot override a tax that does not exist. If an existing tax is a rate, it is necessary to override the tax as a rate, not a per line or fixed amount. Failure to do so will result in incorrect and high tax amounts.
  3. Non-exemptible taxes may be overridden to exempt taxes that are normally not exemptible.
  4. The AFC Override functions can be used to override the rates, but they will not affect the rules that
  5. Determine what taxes are applied to different transaction/service pairs.
General Rules for Configuring Override File
  1. The override file path must be listed in filelocs.txt.
  2. The override file must be the last item in filelocs.txt.
  3. There cannot be any blank lines in filelocs.txt.

Also, in order to verify that an override file is in the process of being loaded, the user must go to the AFC Directory and locate the .sta or status file which indicates that an override file has been successfully loaded.

Tax Rate Brackets

Some jurisdictions will dictate a tax rate that changes as the taxable amount of the transaction increases. These break points at which the changes occur define the brackets (or steps) and are most commonly based on dollar amount ranges although other units of measure exist. The rate may increase or decrease according to usage levels.

AFC supports these transactions with an unlimited number of tax brackets. The Avalara Tax Research department continually researches jurisdictions for specific tax practices, such as tax rate brackets, updating the AFC Engine monthly. These updates occur automatically and the user is not required to make changes to account for this.

An example of this is illustrated in Figure 4-1. If a jurisdiction has a general sales tax set at 2% for the first $500 of a single transaction and set at 1% for that which is over $500, the tax for a $1200 sale would be calculated as shown in the figure.

Figure 4-1 Example of Sale with Tax Brackets

First $500 of Sale

$500

@

2%

=

$10.00

 

Remaining Amount of Sale (Over $500)

$700

@

1%

=

7.00

 

 

 

 

 

 

$17.00

Total Tax

Rate at Final

Rate at Final is a variation of the typical tax bracket. Basically a lookup table, each bracket is defined by the break points at which a rate change occurs and contains the rate to be charged for the total transaction amount falling within the range.

For example, suppose a state establishes an E911 tax with a tax rate dependent on the total number of lines as shown in Figure 4-2.

Figure 4-2 Example of Tax Brackets

Lines

Rate

1

$0.19

2

$0.14

3

$0.13

4 to 5

$0.11

6 to 10

$0.10

11 to 25

$0.08

26 to 50

$0.06

51 to 99

$0.05

100+

$0.04

 

If a customer has 7 lines, the tax rate of $0.10 per line will apply for a total tax of $0.70.

If a customer has 2 lines, the tax rate of $0.14 per line will apply for a total tax of $0.28.

Limits

Some jurisdictions have established tax rates that either take effect or cease to take effect at a specific threshold, defined as a currency value. The point at which this occurs is referred to as a cap or limit. AFC supports these transactions and the user is not required to make changes to account for it.

As an example, if a jurisdiction charges a 10% UTT on only the first $10 of an invoice, the tax for a $20 invoice would “cap” at the $10 threshold, resulting in a ($10 x 10% =) $1 UTT fee.

As an example of the converse, if a jurisdiction does NOT tax the first $25 of Internet Access usage, a $35 charge would be reduced by the $25 threshold “limit,” resulting in a ($35-$25 = ) $10 taxed amount.

Surcharges

When a government entity levies a surcharge, AFC automatically includes this surcharge in the base of the FET. The most common occurrence of this is found in E911 surcharges. The returned tax table shows which tax entries are considered surcharges.

Prorated Taxes

The AFC Prorating functions send in a percentage that is used to calculate taxable amount on the rated tax and calculates a percentage of the line and fixed amounts. These functions check the prorated logic of each tax in the appropriate jurisdiction to determine if prorating is allowed. If prorating is not allowed, the full amount is taxed.

Discount Adjustment

AFC has an additional table that stores discount types by state with an “allow ability” indicator. The adjustment functions have arguments for the discount type which look up the discount type from the table to determine whether to apply taxes or not.

Discounts may or may not be taxed within each state. When a discount is taxed, the customer receives a tax benefit commensurate with the amount of the discount (i.e., if the customer gets $5 off on a transaction subject to a 5% tax, the customer pays $0.25 less in tax than they would have). When a discount is not taxed, the customer receives no tax benefit from the discount. Whether a discount is taxed or not depends on the type of discount and the rules in a particular tax jurisdiction.

AFC provides five discount types to use in defining the particular discount to be applied and are fully described with supporting example in the following sub-sections.

Discount Type

ID

Value

Description

0

None (Default)

Discount Type not applicable.

1

Retail Product

An amount subtracted from the original price to arrive at a lower price.

2

Manufacturer Product

A credit applied to the total amount reimbursed to either the retailer or the customer by the manufacturer.

3

Account Level

A stand-alone discount that is not applied against any service but instead as a stand-alone product.

4

Subsidized

A credit for telephone service where the telephone provider provides a service to a lifeline eligible customer. The credit will be applied to the subscriber line charge.

5

Goodwill

A credit applied to customer invoices for the purpose of engendering customer goodwill. For example, compensation for a service outage.

Account Level

Especially prevalent in large accounts, this discount is a stand-alone discount that is not applied against any service but instead as a stand-alone product.

Example Description of Account Level

A Kansas customer spends significant amounts on a wide range of services including local exchange, intrastate toll, and interstate toll. The customer’s purchasing activity occurs in several states and across multiple accounts. The customer’s spending levels earn it a $1,000.00 discount that is not applied to any particular product or service, but will be applied at an account level.

XYZ Phone Company’s Tax Department has determined that account level discounts in Kansas will receive full tax credit, so the discount is mapped to a tax category created to represent generic account level discounts and the customer gets a $53.00 credit of Kansas state sales tax along with the $1,000.00 discount. The application of Kansas sales tax to the discount, rather than other state's sales taxes (i.e., states in which there was purchasing activity that helped to earn the discount), is a consequence of the discount being applied to a Kansas account and The Tax Department has determined that the related tax risk is acceptable.

Goodwill

A credit applied to customer invoices for the purpose of engendering customer goodwill. For example, compensation for a service outage.

Example Description of Goodwill

A Kansas customer buys a second line and gets voice mail free for a month ($6.00 value). The free voice mail is a Goodwill Discount because, although it is offered by the retailer and applied to a particular product or service, the terms of the promotion provide that the discount will not be taxed.

To accomplish this, the billing system will make separate calls to the taxing engine of $6.00 for the monthly recurring voice mail charge and -$6.00 for the Goodwill Discount. Both transactions will be represented by the same tax category, but the billing system will send an additional value on the discount transaction indicating that it is a Goodwill Discount. The $6.00 charge for voice mail generates $0.32 in Kansas state sales tax. When the -$6.00 discount is processed for tax applications, the taxing engine determines that a Goodwill Discount is not taxed and generates -$0.00 in Kansas state sales tax. The offsetting tax amounts are presumably netted together in the tax summary on the customer’s bill.  Whether the charge and discount amounts are netted on the customer’s bill is up to the billing system, and does not affect the tax calculation or the presentation of tax on the bill.

Manufacturer Product

A credit applied to the total amount reimbursed to either the retailer or the customer by the manufacturer.

Example Description of Manufacturer Product

A Kansas customer buys a satellite dish for $300.00 and receives a $50.00 rebate (discount) from the satellite company. The billing system will make separate calls to the taxing engine for the dish charge of

$300.00 and the discount of -$50.00. Both transactions will be represented by the same tax category, but the billing system will send an additional value on the discount transaction indicating that it is a Manufacturer Discount. The $300.00 charge for the satellite dish generates $15.90 in Kansas state sales tax. For the -$50.00 discount, the tax engine determines that Kansas does not allow any tax credit on Manufacturer Discounts and generates $0.00 in Kansas state sales tax. The offsetting tax amounts are presumably netted together in the tax summary on the customer’s bill. Whether the charge and discount amounts are netted on the customer’s bill is up to the billing system, and does not affect the tax calculation or the presentation of tax on the bill.

Retail Product

A retail product discount is an amount subtracted from the original price to arrive at a lower price.

Example Description of Retail Product

A Kansas customer has voice mail and is charged a monthly recurring charge of $6.00/month. The customer buys a second line and gets voice mail free for a month. The billing system will make separate calls to the taxing engine for the monthly recurring charge of $6.00 and the discount of -$6.00. Both transactions will be represented by the same tax category, but the billing system will send an additional value on the discount transaction indicating that it is a Retailer Discount.

The $6.00 charge for voice mail generates $0.32 in Kansas state sales tax. For the -$6.00 discount, the tax engine determines that Kansas allows a full tax credit on Retailer Discounts and generates -$0.32 in Kansas state sales tax. The offsetting tax amounts are presumably netted together in the tax summary on the customer’s bill. Whether the charge and discount amounts are netted on the customer’s bill is up to the billing system, and does not affect the tax calculation or the presentation of tax on the bill.

Subsidized

A credit for telephone service where the telephone provider provides a service to a lifeline eligible customer. The credit will be applied to the subscriber line charge.

Example Description of Subsidized

A Kansas Lifeline customer purchases local exchange service. Local exchange service is normally $24.00, but Lifeline customers are charged $20.50 and the balance of $3.50 is drawn from a federal government fund for the subsidization of local exchange service to Lifeline customers. The company still has $24.00 in revenue and will owe Kansas state sales tax on the entire $24.00 in revenue. The company is prohibited from drawing on the federal government fund to pay for the tax on the $3.50, so the customer must pay all of the applicable tax.

Tier at Transactions

In some states, the sales tax on a product has tier taxing logic. When tax is calculated using Tier at Transactions the tax is determined using graduated tax brackets on each transaction separately rather than the amount of the customer invoice. The tax applies tax brackets based on the single product transaction. Tier at Transaction is not the default setting in AFC.

Tax on Tax Until no Effect

The default application of tax on tax is to make one pass through the calculation of each tax, adding the appropriate taxes to the base amount to be taxed. If the tax on tax until no effect option is selected, AFC will continue to recalculate tax on tax until the amount added is less than 0.005 (one half of a cent).

Historical Tax Rates

AFC maintains an unlimited number of past tax rates. The tax rate history tables contain the tax rates and effective dates and are referenced when tax calculations are performed on date other than the current date.

Taxed Taxes

Taxed taxes are instances in which one tax includes in its base the tax calculated from another tax. This can happen when the taxed tax was passed on from the carrier to the end user, thus being revenue to the carrier. This commonly happens with the Federal USF, but it can happen with other taxes as well. As the scope of this document prohibits a discussion of the many examples of taxed taxes, the most common occurrence is discussed here with an example to serve as an introduction to the topic.

AFC applies Federal excise tax to surcharges, the federal universal service funds and the Federal telecommunications relay service fund. The taxation of the federal universal service funds is performed because they are not taxes by definition. In addition, both the federal universal service funds and the federal telecommunications relay service fund are levied against telecommunications companies, not end users.

Telecommunications companies are allowed, but not required, to pass these fees on to their customer base. As these fees are revenue, not taxes, collecting revenue based upon a provided service is taxable as payment for that service.

When the federal excise tax is multiplied by the amount passed to AFC for a transaction and the tax generated by AFC doesn't agree with the calculation it is due to this situation. This phenomenon is not limited to the federal excise tax. It is, however, where it is most noticed due to the volume of federal excise taxes and the common knowledge of its rate.

Refer to Figure 4-3. In the case where the Federal USF and the FET are returned for a transaction, the Federal USF is automatically included in the base of the FET. If both taxes are returned for a $100 charge, the taxes would be calculated as follows:

Figure 4-3 Taxed Taxes Example (tax rate of 3% is used in this example)

Tax A

 

FET

Charge

 

$100.00

 

Charge

 

$100.00

Rate

x

3 %

 

 

 

 

Tax Amount

=

$3.00

-->

Tax A

+

$3.00

 

 

 

 

Tax B base

=

$103.00

 

 

 

 

Rate

x

3%

 

 

 

 

Tax Amount

=

$3.09

Tax Logging

Once the tax calculations are complete, the EZTax.log is created. The log is a binary database containing all of the taxes generated during the tax run. Information in the log includes the jurisdictional data, tax types, tax levels, sale amounts, tax rates, tax amounts, exemptions, adjustments, customer number, etc.

Once AFC performs a graceful exit, the EZTax.log is available for use. This file is commonly used to create tax returns, provide audit trails and internal tracking, and used when making projections.

The options available for reporting the tax information vary based on the integration method that the client has chosen to use.

  1. Batch mode clients – The EZTax.log is automatically produced when processing the .CDS file. Several utilities are available for use to produce files to be imported into the billing system. Refer to Section 5.1 for utility selection assistance.
  2. AFC SaaS Standard clients - The EZTax.log is automatically produced and the sorting and reporting activities are performed automatically.
  3. On-site clients - The EZTax.log is automatically produced. Many sorting and reporting utilities are available for use to produce the desired output file. Refer to Section 5.1 for utility selection assistance.
  4. APIs - Clients who use the functions (such as APIs) must turn logging on to gain the benefit of sorting utilities. All of the information used for billing is returned real time during taxation.

Returned Taxes

Once the tax calculations are completed, the tax information is placed in the Tax Table, available to be returned to the user from the AFC engine. An additional Tax Table will be returned if using Invoice Mode.

Taxes Table

The AFC Table is dynamically allocated during AFC session initialization. This table is used to store tax information as AFC processes transaction records. The size of this table is dependent upon the maximum taxes that can be generated for a single transaction. As such, the size of this table can change from month to month as new taxes are generated or removed from taxing jurisdictions. It is always safe to access from 0 (zero) to [tax_count_returned -1] locations of the table. The user is cautioned to treat this as a read only area. Attempting to access locations that do not exist will result in access violations on most operating systems.

Each function that performs tax calculations or tax exceptions returns a count of taxes generated for the specified transaction. The transaction tax data can be retrieved for use in a billing system by accessing the Tax Table pointer which indicates the location of the tax amount in the AFC Table array.

Returned Tax Information

Tax information can be returned using the P Code, J Code, Zip or FIPS functions. A value is returned to indicate the number of taxes returned and included in the Tax Table. Each tax calculated is returned as a record in the tax table. Taxes are retrieved by looping through the table by the number of taxes, which is then returned by the taxation API call.

Each row in the Tax Table will contain the information shown in Table 4-12.

Table 4-12 Enhanced Taxes Table Fields

Name Description

PCode

PCode for tax jurisdiction

Tax Type

Tax Type

Tax Level

Tax Level**

Calculation Type

Calculation Type (i.e. Rate, Fixed, Per Minute, Per Line)

Rate

Tax Rate or amount applied

Tax Amount

Calculated tax amount

Taxable Measure

Amount of charge plus any taxed taxes

Exempt Sale Amount

Amount of the charge exempt from taxes

*Desc

Tax description string

Billable

Billable flag from tax logic

Compliance

Compliance flag from tax logic

Surcharge Flag

FET taxable flag from tax record

**Country taxes within any US territory will be returned at a state level versus a federal level.

Returned Tax Information Using Invoice Mode

AFC applies Steps, Brackets and/or Limits on a per transaction basis unless operating in Invoice Mode. Invoice Mode is used to group transactions that apply to the same customer. AFC maintains a history of the transactions and applies the Steps, Brackets and/or Limits to entire group of transactions.

For example, suppose a jurisdiction charges a 10% sales on just the first $10 of an invoice. If two separate $6 transactions on the invoice are passed while not in Invoice Mode, two $0.60 tax charges would be erroneously totaled and a $1.20 tax would be generated. However, if these same transactions are passed while in Invoice Mode, the total tax charge would be correctly totaled and a $1.00 tax would be generated.

Table 4-13 Invoice Mode Tax Table Fields

Name Description

PCode

PCode for tax

Tax Type

Tax Type

Tax Level

Tax Level**

Calculation Type

Calculation Type (i.e. Rate, Fixed, Per Minute, Per Line)

Rate

Tax Rate or amount applied.

Tax Amount

Calculated tax amount.

Exempt Sale Amount

Amount of the charge exempt from taxes.

*Desc

Tax description string

Lines

For tax calculations based on line counts, it is the number of lines used in the calculation to produce the tax. For Federal taxes, the line count always matches the lines input. For all other taxes, it is 0.

Minutes

For tax calculations based on minutes, it is the number of minutes used in the calculation to produce the tax. For all other taxes, it is 0.

Max Base

Maximum amount to which tax is applied amounts above this will be taxed at a higher bracketed rate (if applicable).

Min Base

Minimum amount to which tax is applied amounts below this will be taxed at a lower bracketed rate (if applicable).

Excess Tax

Rate for amount above Max Base returned as part of county tax.

Total Charge

Sum of charges calculated on a per customer basis.

**Country taxes within any US territory will be returned at a state level versus a federal level.

Invoice Mode Tax Amount Adjustments

Since AFC processes each transaction as it is received with no knowledge of future transactions it must make adjustments to the tax amount when additional transactions are received that cause the rate of previous transactions to change.

Example

(Please reference and see the Rate Table for an overview of rates.)

Standard tax mode:

3 lines were received at the rate of 0.45 per line for E911 => tax amount $1.35.

2 lines were received at the rate of 0.50 per line for E911 => tax amount $1.00.

Total tax for E911 => $2.35

Invoice Mode:

3 lines were received at the rate of 0.45 per line for E911 => tax amount $1.35.

2 more lines were received for a total of 5 lines which changes the rate to 0.40 per line.

The total tax should be $2.00 but since the customer had already been taxed $1.35 for this same tax then the additional tax amount returned is $0.65.

Total tax for E911 => $2.00

In some cases the adjustment required for a rate change may cause a negative tax amount to be returned. The summarized tax amounts returned when the list of customer transactions are complete will match what the customer would have been charged had the series of transactions processed been entered as a single transaction.

Tax Grouping

AFC allows a client application to group the tax calculation results returned in the tax table based on tax level and tax type criteria. This may be accomplished by setting the appropriate group mode option in the configuration file (see TM_00548_AFC Configuration Guide). The option specified in the configuration file will automatically be applied to every AFC session as it is initialized. However, this option may be overridden by calling the EZTaxGroupResults API function.

NOTE: This option will not modify the way that tax calculation results are logged into the EZtax 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:

  1. Federal taxes may not be grouped. Each Federal tax will be returned individually.
  2. Non-billable taxes may not be grouped.
  3. Only rate-based taxes may be grouped. Taxes with a different calculation type (for example, fixed, per line, etc) will be returned individually.
  4. Use taxes may be grouped with other use taxes only (for example, state and local use tax). Use taxes will not be grouped with other tax types.
  5. When grouping taxes for different tax levels (for example, state and local taxes) the jurisdiction code for the lowest level jurisdiction will be returned.
  6. Unincorporated taxes will be considered as County taxes when grouping taxes by tax level, and will be grouped accordingly.
  7. The tax rates for all taxes being grouped into a single record will be added together.

Options:

AFC provides the following options in order to group the taxes in the tax table by tax level:

  1. Group taxes at the same level. When using this option, taxes at the same level will be grouped together.
  2. Group state, group county and local. By using this option, all state level taxes will be grouped into a single record, and all county and local taxes will be grouped together into a separate record.
  3. Group state, county, and local. If this option is specified, all state, county, and local taxes will be grouped together.

In addition to grouping taxes by tax level, AFC allows you to separate sales taxes from other tax types. The following options may be used in conjunction to the tax level options specified above.

  • Group sales taxes. This option indicates that Sales Taxes (tax type 1) and Use Taxes should be grouped separately from other taxes.
  • Group taxes in the sales category. All taxes that are in the sales category (such as some District and Transit taxes, in addition to Sales Taxes) will be grouped together separately from other taxes.

If the group mode is being specified within the EZTax.cfg file, the sales tax option may be combined with the tax level option by inserting the option in the line following the tax level option. For example:

groupstatecountyandlocal

groupsalescategory

When calling the API function, a sales tax option may be combined with a tax level option by using the bitwise OR operator in the group mode parameter. For example:

EZTaxGroupResults(session, GROUP_ST_CO_LOCAL | GROUP_SALES_CATEGORY);

By using the default option in the configuration file or the API function, this feature will be disabled, and all taxes will be returned in an individual record.

Tax Return Table

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

  1. Jurisdiction Code. Jurisdiction Code (PCode or JCode depending on the API call and interface being used) for the lowest level jurisdiction. For example, if Kansas state taxes and Overland Park local taxes were grouped together, the tax record will contain the jurisdiction code for Overland Park.
  2. Tax level. When grouping State, County and Local taxes together, the tax record will contain a value of 6 in the tax level. When grouping only County and Local taxes together, the tax record will contain a value of 7 in the tax record. Constants are provided for these values in the appropriate file.
  3. Tax type. When grouping different taxes together, the tax type in the tax record will contain a value of 0. If only Sales Taxes (tax type 1) or Use Taxes (tax type 49) are being grouped together, the tax record will contain the corresponding tax type.
  4. Tax amount. This field will contain the sum of the tax amount for all taxes being grouped together.
  5. Tax rate. This field will contain the sum of the tax rates for all taxes being grouped together.

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 Types

When a transaction is processed through the AFC Engine, a Tax Type is assigned based on the results. The Tax Type is determined by the transaction location and transaction/service pairs provided in the transaction record and is used to accurately describe the exact nature of the tax applied.

With so many Tax Types available, highly detailed and specific tax descriptions are provided for use in taxation disclosure. This is useful in billing and customer service, and simplifies tax compliance filing.

AFC allows for a change, referred to as an override (see section 4.1.3), of the rate for a specific tax type and tax level in a specific jurisdiction. When overriding a tax type, the tax type must exist in the jurisdiction where for the override is to be made.

See AFC Tax Types for a complete list of supported tax types or refer to the EZTaxTaxType.h file located on the most recent Distribution/Update. For .NET users, the tax types are also available in EZTaxConstants.cs. For Java users, the tax types are also available in TaxType.java.

Nexus

AFC allows a client application to set the nexus information in multiple methods.

  • Set the appropriate nexus option in the configuration file (see TM_00548_AFC Configuration Guide). The option specified in the configuration file will automatically be applied to every AFC session as it is initialized. However, this option may be overridden by calling the EZTaxSetNexus API function.
  • By EZTaxSetNexus API function.
  • By using a nexus_table at the transaction level.
  • By EZTaxSetStateNexus API function.

General Usage

When the engine determines there is no nexus for the taxing jurisdiction of the transaction, no taxes will be returned.

If the nexus information has been set by either configuration file or by API call, the transaction level nexus will take precedence.

EZTaxSetNexus allows one call to set all nexus information whereas EZTaxSetStateNexus allows the client application to set each state individually.

By using EZTaxSetNexus with a null pointer and a nexus count of zero, it will reset the AFC engine to default value of nexus in every state.

Nexus is only used within the United States.

Exclusions

AFC allows a client application to exclude states or countries (and all lower level jurisdictions) from taxation. By using the exclusion option, the client is informing AFC that the specified state or country and all lower jurisdictions are to return no taxes. An excluded state will exempt all state and lower level jurisdiction taxes; however, it will continue to return federal level taxes. An excluded country will exempt all federal and lower level jurisdiction taxes. Exclusions may be accomplished using several methods, such as those listed below:

  • Set the appropriate exclusion option in the configuration file (see TM_00548_AFC Configuration Guide). The option specified in the configuration file will automatically be applied to every AFC session as it is initialized. However, this option may be overridden with other API functions.
  • Use the EZTaxSetStateExclusion API function.
  • Use the EZTaxClearExclusion API function.

General Usage

When the engine determines that taxes are excluded at the state level for a transaction, only federal level taxes are returned. When the engine determines that taxes are excluded at the federal level, no taxes are returned.

EZTaxClearExclusion will clear all exclusion information and return taxes at every level.

US Territories

US Territory exclusions function like state exclusions and are set and cleared when the federal level USA country code is used without a state or territory. When specified as a state jurisdiction using the two letter state code, ex. ‘USA,VI’, the exclusion behaves like any other state jurisdiction.

Country codes for US Territories are deprecated.

Utilities

Refer to Figure 5-1. While tax results are typically returned to the billing system using functions, the primary output mechanism of the AFC Engine employs the EZtax Log. The EZTax.log is the link to the outside world. There are twenty-four utilities to choose from, one of which will almost certainly suit your need.

When an AFC session is started with the AFC Initialization Function, the Tax Log is opened if the Tax Log parameter is set to true. This allows the AFC Log to capture the binary formatted transaction and tax data generated by the AFC Engine.

After exiting the AFC session, the AFC Log becomes available for use. This file should be archived by the user for reruns, recovery and auditing purposes. This is accomplished by simply copying the EZTax.log file to a local storage location (refer to Figure 5-1). In most cases this binary file will be used in the future and nearly all of the utilities will delete the contents of the AFC Log upon job completion.

Figure 5-1 AFC Log Data Path

EZTaxEngine

If the Billing System is configured to use the AFC Functions and does not require the logging of data, set the first parameter of the AFC Initialization Function to FALSE to disable transaction logging. For instance, if your program is saving or using the tax data returned to it by the tax calculation functions, you would have no need to use the data in the log file for later processing.

NOTE: When running AFC in batch fashion the EZTax.log file is always generated.

It is imperative that rigid backup practices are established and followed to avoid losing the transaction and data information created during a session. Most utilities will delete the inputted log file when the utility is finished and backups would be required should reruns be needed.

Utility Selection

AFC provides utilities for reporting and file management. The latest utilities, along with their file formats, are located on the most current update. AFC has conversion utilities available for converting the tax log file to formats used by compliance services. Contact Avalara for information on converting to specific services.

Reporting Utilities

The reporting utilities are used for customer billing and compliance reporting. They extract specific data from the content rich binary EZtax Log file, commonly sorting the data into a logical and orderly format. The resulting output is a flat file containing just the information required for the specific report, compatible with common software such as spreadsheets and databases.

The most common use of this information is to file tax returns. However, other uses may include audit trails, internal tracking and projections.

Reporting File Extensions

Refer to Table 5-1. The reporting utility output file extensions are customized to indicate the type of information provided within the file. Note that some utilities may produce more than one type of output file.

Table 5-1 File Extension Definitions

Log File Extension

Log File Type

File Format

Note

.csf

Customer Billable amounts

.csf

 

.ssf

Tax Compliance amounts

.ssf

This file is not generated when the [–cl] command line option is used.

Note: Non-compliance taxes (nca) aren't included in the the .ssf Compliance file.

.nba

Non-billable amounts for compliance

.ssf

This file is not generated when the [–cl] command line option is used. If there are no non-billable amounts, this file is not created.

.nca

Non-compliance amounts that were billed

.ssf

This file is generated only if there are transactions in the AFC log that do not require compliance with a jurisdiction.

.scl

Billable amounts combined with non-billable amounts

.ssf

This file is generated when the [-cl] command line option is used. The .scl file is created instead of the .ssf and .nba files.

Note: Non-compliance taxes (nca) aren’t included in the .scl Compliance file.

The report file generated by the utility will be formatted as a comma delimited file or fixed field length file depending on the utility used. Refer to the specific utility documentation to determine which formatting will be provided.

Some report utilities provide specialized reports with the file name log.rpt. These comma delimited files are modifications of .csf and .ssf report formats.

Refer to Figure 5-2. For example, the EZLog_NS.exe utility produces a comma-delimited flat file report with an .ssf extension. When this file is copied into a preformatted (headings and column widths preset) MS Excel spreadsheet the following output is displayed. If the spreadsheet had not been preformatted the titles would not be present and the field widths might vary.

Figure 5-2 Sample EZLog_NS spreadsheet

Image_Fig5-2.png

File Management Utilities

File management utilities are provided for maintenance purposes, such as combining one or more archived AFC log files or appending one log file to another.

Note that AFC provides the asciilog.exe utility for maintenance of AFC log files. It allows the user to view the unsorted log file as readable ASCII text without deleting the file.

Specifying a Log File at Run Time

The AFC Log file to be submitted to a utility is specified by the log file name in the Filelocs.txt file (EZTax.log by default). However, this file name will be ignored if a different file name is provided in the AFC Initialization Function at session startup.

The Filelocs.txt contains the file locations for text file contains all of paths to the AFC Data Base files. Each file in the AFC Data base is represented by one line. The lines in the text file must be in the defined order and all files must be represented.

NOTE: Batch utility clients can only use the filelocs.txt file as they will not be using the function programming method.

Log.sum File

The Log.sum file accumulates tax compliance totals over multiple runs to generate a compilation of the tax totals. It contains a summary of the EZTax.log(s) with the data organized by taxing jurisdictions. Only the EZ* prefix report utilities can be used to generate the log.sum file, which can then be passed as the input to most of the report utilities.

This is a turnaround file used for maintaining one smaller log file rather than multiple log files in cases where the customer billing cycle occurs more frequently than the tax compliance cycle. It carries tax compliance information forward until the report is produced. The srt* utilities use this file for input only.

WARNING: The customer information is lost in the summation of the log.sum. Remember to delete or move this file before running a utility that uses it, if a combined report is not desired.

General Tips When Using Utilities

AFC is designed to provide optimum flexibility in creating reports. The following tips have been accumulated to assist in making the best use of available options.

  1. Combining Log Files
  2. If an AFC log file exists when AFC is run, new tax data will be appended to the end of an existing log file (i.e. not placed into a new log file). Also, log files can be combined prior to passing to a utility, although they cannot be split apart after they are merged.
  3. The criteria for deciding to combine files is based on how often AFC is run, how big the created log files are and the date cycles of your billing and tax compliance system. Note that most transactions will generate many tax records and that each tax record is either 100 or 168 bytes long, depending on the configuration.
  4. Many clients use a new log file for each run of AFC to reduce the complexity introduced when a rerun or restart is required.
  5. Most clients will do all of their customer billing processing within their Function programs and use the log file to process only tax compliance data at a later date.
  6. Utilities are provided to merge two or more log files into a single log file. This is useful when running reports that reflect the combined data of the individual log files.
  7. Primarily the srt* utilities will produce files sorted by the jurisdictional level.
  8. AFC provides the asciilog.exe utility for maintenance of AFC log files, allowing the user to create an ASCII version of the log file.
  9. Many utilities produce a log.sum file that accumulates tax compliance totals over multiple runs to generate a compilation of the tax totals.
  10. The pkzip executable option listed with some utilities is only available with the windows platform.

AFC Utilities

Table 5-2 Utility Summary

Utility Name

Function

Short Description

asciilog.exe

File Management

Dumps the contents of the logfilename.log to an ASCII version of the log file

batchsplit.exe

Processing

Allows for two output log files. logfilename1.log is the voice data log and logfilename2.log is the data log.

commerge.exe

File Management

Combines the log file with the log.sum (if present) then sorts and combines the data.

comrp.exe

Reporting

Data formatted to produce a customer information file called ComRPT.ssf.

comptnum.exe

Reporting

Reads the log file specified in filelocs.txt and produces comma delimited text files outputfilename.ssf, outputfilename.nca, and outputfilename.nba (or a unified file outputfilename.scl) for tax compliance filing.

csf20.exe

Processing

Reads the log file specified in filelocs.txt. Uses a CDF filename from the command line to name the output files.

customsort.exe

Reporting

Produces a comma-delimited file for compliance filing. User selects sort criteria and preferences. Refer to the AFC Custom Sort Utility User Manual for more information on this utility.

ezcomprep.exe

Reporting

Produces a comma-delimited file for compliance filing. Sorting and combining is performed at the jurisdictional level.

ezlog_ns.exe

Reporting

Produces a comma-delimited file for compliance filing.

ezlogcust.exe

Reporting

Produces a comma-delimited file for customer billing. Sorting and reporting is done at the customer level.

ezlogcustios.exe

Reporting

Produces a comma-delimited file for customer billing. Sorting and reporting is done at the customer level.

ezlogcustpts.exe

Reporting

Produces a comma-delimited file for customer billing. Sorting and reporting is done at the customer level. The sort key also contains PCode, optional, and Service Level Number fields.

ezlogcustptslnl.exe

Reporting

Produces a comma-delimited file for customer billing. Sorting and reporting is done at the customer level. In addition to the PCode, optional, and Service Level Number fields and the number of lines are also included.

EZTax_20.exe

Processing

Refer to batchfile processing for details on the Batch processing method.

EZTaxappend.exe

File Management

Combines two log files.

EZTaxappendf.exe

File Management

Combines multiple log files.

log no tax transactions

 

This is an option in the EZTax.cfg file, placed here as it may effect the output.

srtcdf20.exe

Reporting

Produces a fixed length text file logfilename.ssf for tax compliance filing and a fixed length text file filename.csf for customer billing.

srtcdf20p.exe

Reporting

Produces a fixed length text file EZTaxlogfilename.ssf for tax compliance filing and a fixed length text file logfilename.csf for customer billing.

srtcomcust20.exe

Reporting

Produces a comma delimited text file logfilename.ssf for tax compliance filing and a fixed length text file logfilename.csf for customer billing.

srtcomma20.exe

Reporting

Produces a comma delimited text file logfilename.ssf for tax compliance filing and a fixed length text file logfilename.csf for customer billing.

srtcomma20l.exe

Reporting

Produces a comma delimited text file logfilename.ssf for tax compliance filing and a fixed length text file logfilename.csf for customer billing, separating adjustments. The .csf file is used for import into the billing system to populate customer bills. The comma-delimited .ssf file is sorted at the jurisdictional level. The .ssf file also contains the number of lines.

srtcomma20ld.exe

Reporting

Produces a comma delimited text file logfilename.ssf for tax compliance filing and a fixed length text file logfilename.csf for customer billing.

srtrev20l.exe

Reporting

Produces a comma delimited text file logfilename.ssf for tax compliance filing and a fixed length text file logfilename.csf for customer billing, separating adjustments. The .csf file is used for import into the billing system to populate customer bills. The comma-delimited .ssf file is sorted at the jurisdictional level. The .ssf file also contains the number of lines and the base sale amount. The base sale amount can be included in the csf by command-line option.

strg.exe

Reporting

Produces a fixed length text file logfilename.ssf for tax compliance filing. If the extra logfilename is specified, it is used for appending instead of the log.sum.

upsize_log.exe

File Management

Converts the short format logfilename1 to a long format log logfilename1.

asciilog.exe

COMMAND LINE

asciilog logfilename.log <+p> <+tc> <+a> <+h> <-csv> <-?>

DESCRIPTION

The asciilog.exe command dumps the contents of the logfilename.log to an ASCII version of the log file. It does not sort or combine records. It produces a file named logfilename.txt which is a legible version of the logfilename.log data.

INPUT

Log file: logfilename.log file as defined in the command line and is NOT deleted at end of job.

OUTPUT

Comma delimited logfilename.txt or logfilename.csv file.

FILE FORMAT KEY

The contents of the file are highly dependent upon the command line arguments. Use the +h argument to prepend the output with a header row that defines each column.

ARGUMENTS (in any order)

+p option adds the P-Code to the output, located before the Country for each record

+tc option adds the tax category description to the end of each record

+a option outputs all available fields

+h option prepends the output with a header record

-csv option uses .csv as the extension for easier import to other applications

-? option displays usage screen and exits

NOTES:

  • AFC log is NOT deleted.
  • Also, to have valid values for transaction type and service type, the AFC session that generated the log must have logtransserv=true (ref 7.2.3.8 Log Transaction / Service Types).

batchsplit.exe

COMMAND LINE

batchsplit inputfilename.cdf logfilename1.log logfilename2.log [-dD]

DESCRIPTION

The batchsplit command is a processing utility designed to accept records submitted in batch fashion. Records are supplied as an ASCII formatted file inputfilename.cdf. Two output log files are produced. logfilename1.log is the voice data log and logfilename2.log is the data log.

INPUT

Reads the inputfilename.cdf ASCII text file

OUTPUT

logfilename1 - as defined in the command line. logfilename2 - as defined in the command line.

read_err.st - any errors found while editing input file are reported here. billing.log - date/time stamp log (appended to).

bureau_log - run totals (appended to).

EZTax.sta - status

inputfilename.rpt - break down by totals (not for compliance filing).

FILE FORMAT KEY

Refer to Figure 6-2.

ARGUMENTS

logfilename1.log - Voice Data Log file name

logfilename2.log - Data Log file name

d or D - enables the default transaction/service type processing

NOTES:

  • If the cust_no field in the cdf file has an "I:" in it, the transaction will go to the data log. If not, the transaction will go to the voice log.
  • The transactionservice.exp file must be in the EZtax working directory. EZTax.log is neither deleted nor created.
  • Filelocs.txt MUST be in the working directory.

SAMPLE DATA

678367N 704752N 678367NB20070109+00000005067 0 0000001000001SI I: 6444U00000000013CDXXXC 

678367N 408276N 678367NB20070109-14485457933 0 0000001000001SI 6444U00000003645DLFFFI 

678367N 650786N 678367NB20070109+00000000600 0 0000001000001SI 6444U00000000002CDLXFC 

commerge.exe

COMMAND LINE

commerge

DESCRIPTION

The commerge.exe command reads the log file specified in filelocs.txt, combines the log file with the log.sum (if present) then sorts and combines the data.

INPUT

Reads the log file as defined by filelocs.txt or AFC Initialization Function. log.sum – optional input from previous run

OUTPUT

No output file is produced as this is a log manipulation utility.

FILE FORMAT KEY

The output file produced is a log file with no format key as this is a log manipulation utility.

ARGUMENTS

None.

NOTES:

  • The log.sum file is created
  • WARNING - EZTax.log is DELETED. Make backups in case reruns are needed.

SAMPLE DATA

No output file is produced as this is a log manipulation utility.

comptnum.exe

COMMAND LINE

comptnum [-z <pkzip executable>] outputfilename <extralogfilename> [-cl]

DESCRIPTION

The comptnum.exe command reads the log file specified in filelocs.txt and produces comma delimited text files outputfilename.ssf, outputfilename.nca, and outputfilename.nba (or a unified file outputfilename.scl) for tax compliance filing.

INPUT

Reads the logfilename.log file as defined by filelocs.txt or EZtax Initialization Function.

log.sum – optional input from previous run.

OUTPUT

Comma Delimited outputfilename.ssf (nca, nba, scl) file for tax compliance filing. Sorted and condensed by PCode, Tax Type, Tax Level, Tax Rate

FILE FORMAT KEY

Country, State, County, Locality, PCode, Tax type, Tax Type Description, Tax level, Tax Level Description, Tax rate, Tax amount, Gross Sale, Exempt, Adjustments, Taxable measure, Minutes

Figure 5-3 comptnum SSF File Format Key

Description

Type

Country

Alpha

State

Alpha

County

Alpha

Locality

Alpha

PCode

Numeric

Tax Type

Numeric

Tax Type Description

Alpha

Tax Level

Numeric

Tax Level Description

Alpha

Tax Rate

Numeric

Tax Amount

Numeric

Gross Sale

Numeric

Exempt

Numeric

Adjustments

Numeric

Taxable Measure

Numeric

Minutes

Numeric

Customer number

Alpha

ARGUMENTS

-z <pkzip executable> - path to zip executable file*

<output filename>

extra log file name – use instead of log.sum

–cl creates a combined compliance log file with a .scl extension, containing both the billable and non-billable amounts instead of a separate log file for each.

*The pkzip executable option is only available with the windows platform.

NOTES:

  • The Tax Rate field is sensitive to positive and negative values
  • The log.sum file is NOT created
  • WARNING - EZTax.log is DELETED. Make backups in case reruns are needed.

SAMPLE DATA

USA, , , , 0, 6, Federal Excise Tax, 0, Federal, 0.030000, 63.946941, 2131.564739, 0.000000, 0.000000, 2131.564739, 2376516.0, 1 

USA, CA, , , 253500, 9, P.U.C. Fee, 1, State, 0.001100, 0.072776, 66.159998, 0.000000, 0.000000, 66.159998, 155916.0, 0000000000000002 

USA, CA, , , 253500, 10, E911 Tax, 1, State, 0.006500, 0.450252, 69.269518, 0.000000, 0.000000, 69.269518, 155916.0, 0000000000004302 

USA, CA, , , 253500, 19, State High Cost Fund, 1, State, 0.024300, 1.607688, 66.159998, 0.000000, 0.000000, 66.159998, 155916.0, 0000000000999999 

U, 1SA, CA, , , 253500, 21, CA Teleconnect Fund, 1, State, 0.001600, 0.105856, 66.159998, 0.000000, 0.000000, 66.159998, 155916.0, Customer Number 2 

USA, CA, , , 253500, , 160, CA High Cost Fund A, 1, State, 0.001500, 0.099240, 66.159998, 0.000000, 0.000000, 66.159998, 155916.0, User value here 

USA, CO, , , 427200, 13, State Universal Service Fund, 1, State, 0.029000, 0.026172, 0.902500, 0.000000, 0.000000, 0.902500, 1920.0, xxxxxxxxxxxxxxxx2 

USA, CO, DENVER, , 442100, 4, District Tax, 2, County, 0.001000, 0.000211, 0.210945, 0.000000, 0.000000, 0.210945, 246.0, 00000000000000000000 

See Transactions and Tax Types for descriptions of the data in the generated file.

comrpt.exe

COMMAND LINE

comrpt [-cl]

DESCRIPTION

The comrpt.exe command reads the log.sum. The data is then formatted to produce a customer information file called compliance.ssf.

INPUT

Reads the log.sum file.

log.sum – optional input from previous run

OUTPUT

Fixed Length compliance.ssf file.

FILE FORMAT KEY

Figure 5-4 comrpt File Format Key

Description

Type

Length

Positions

PCode

Numeric

9

1-9

Tax Type

Numeric

6

10-15

Tax Level

Numeric

1

16

Tax Rate

Numeric

8

17-24

Tax Amount

Numeric

12

25-36

File Record Length

 

36

 

ARGUMENTS

–cl creates a combined compliance log file with a .scl extension, containing both the billable and non-billable amounts instead of a separate log file for each.

NOTES:

None.

See Transactions and Tax Types for descriptions of the data in the generated file.

csf20.exe

COMMAND LINE

csf20 [-z <pkzip executable>] outputfilename [-cl]

DESCRIPTION

The csf20.exe command is a processing utility that reads the log file specified in filelocs.txt. It produces a fixed length file with a .CSF extension. The command line argument determines the output file name.

INPUT

Reads the log file as defined by filelocs.txt.

OUTPUT

Fixed Length outputfilename.csf file.

FILE FORMAT KEY

Table 5-3 csf20.exe File Format Key

Description

Type

Length

Positions

Customer Number

A/N

20

1-20

Tax type

A/N

6

21-26

Authority level

A/N

1

27

Tax amount sign

A

1

28

Tax amount

N

11.5

29-39

File record length

 

39

 

ARGUMENTS

outputfilename

-z <pkzip executable> - path to zip executable file*

–cl creates a combined compliance log file with a .scl extension, containing both the billable and non-billable amounts instead of a separate log file for each.

*The pkzip executable option is only available with the windows platform.

NOTES:

  • EZTax.log is not deleted.
  • filelocs.txt MUST be in the working directory.

See Transactions and Tax Types for descriptions of the data in the generated file.

customsort.exe

COMMAND LINE

customsort -cfg customsort.cfg [-log logfile] [-data datapath] [-work workpath] [-ext extension] [-?]

DESCRIPTION

The custom sort utility is designed to allow clients to produce taxation reports which are sorted and summarized using client-specified fields and/or options. The utility is restricted to fields available in the AFC transaction log, which can be affected by configuration settings in the EZTax.cfg.

INPUT

Reads the log file as defined by filelocs.txt.

OUTPUT

User defined.

ARGUMENTS (in any order)

-cfg customsort.cfg : Required. Custom sort configuration to be used.

-log logfile : EZTax log file to be processed (DEF: EZTax.log).

-data <path> : Data directory; overrides config file value.

-work <path> : Working directory; overrides config file value.

-ext <ext> : Result file extension without ‘.’; overrides reserved config file extension.

-summarize <sumfile> : Log file is summarized into sumfile. On large log files, this option can substantially speed up the sorting process.

-out <fname> : Output base filename; overrides config file. This option can be used when there is a need to set the output files from a script so that different sorts can share the same configuration file.

-? : Display usage and exit

Refer to the AFC Custom Sort Utility User Manual for more information on this utility.

ezcomprep.exe

COMMAND LINE

ezcomprep [-cl]

DESCRIPTION

The ezcomprep.exe command reads the log file specified in filelocs.txt and produces a comma- delimited file for compliance filing. It does not include adjustments as part of Gross Sale. Sorting and combining is performed at the jurisdictional level. It combines the contents of log.sum if it exists.

INPUT

Reads the log file as defined by filelocs.txt or AFC Initialization Function.

log.sum – optional input from previous run

OUTPUT

log.sum – sorted and condensed log file as optional input for next run

Comma delimited outputfilename.rpt file.

Sorted and condensed by PCode, Tax Type, Tax Level, Tax Rate

FILE FORMAT KEY

Country, State, County, Locality, Tax type, Tax level, Tax rate, Tax amount, Gross Sale, Exempt, Adjustments, Taxable measure, Minutes

Figure 5-5 ezcomprep File Format Key

Description

Type

Country

Alpha

State

Alpha

County

Alpha

Locality

Alpha

Tax Type

Numeric

Tax Level

Numeric

Tax Rate

Numeric

Tax Amount

Numeric

Gross Sale

Numeric

Exempt

Numeric

Adjustments

Numeric

Taxable Measure

Numeric

Minutes

Numeric

ARGUMENTS

–cl creates a combined compliance log file with a .scl extension, containing both the billable and non-billable amounts instead of a separate log file for each.

NOTES:

  • WARNING - EZTax.log is DELETED. Make backups in case reruns are needed.

SAMPLE DATA

USA,,,, 6, 0, 0.030000, 29881.866905, 996062.252444, 0.000000, 0.000000, 996062.252444, 14859213.000000

See Transactions and Tax Types for descriptions of the data in the generated file.

ezlog_ns.exe

COMMAND LINE

ezlog_ns outputfilename [-cl]

DESCRIPTION

The ezlog_ns.exe command reads the log file specified in filelocs.txt and produces a comma- delimited file for compliance filing.

INPUT

Reads the log file name from filelocs.txt.

log.sum – optional input from previous run

OUTPUT

log.sum – sorted and condensed log file as optional input for next run

Comma delimited outputfilename.ssf file.

Sorted and condensed by PCode, Tax Type, Tax Level, Tax Rate

FILE FORMAT KEY

Country, State, County, Locality, Tax type, Tax level, Tax rate, Tax amount, Gross Sale, Exempt, Adjustments, Taxable measure, Minutes

Figure 5-6 ezlog_ns File Format Key

Description

Type

Country

Alpha

State

Alpha

County

Alpha

Locality

Alpha

Tax Type

Numeric

Tax Level

Numeric

Tax Rate

Numeric

Tax Amount

Numeric

Gross Sale

Numeric

Exempt

Numeric

Adjustments

Numeric

Taxable Measure

Numeric

Minutes

Numeric

ARGUMENTS

outputfilename

–cl creates a combined compliance log file with a .scl extension, containing both the billable and non-billable amounts instead of a separate log file for each.

NOTES:

  • WARNING - EZTax.log is DELETED. Make backups in case reruns are needed.

SAMPLE DATA

USA,,,, 6, 0, 0.030000, 29881.866905, 996062.252444, 0.000000, 0.000000, 996062.252444, 14859213.000000

See Transactions and Tax Types for descriptions of the data in the generated file.

ezlogcust.exe

COMMAND LINE

ezlogcust [-cl]

DESCRIPTION

The ezlogcust.exe command reads the log file specified in filelocs.txt and produces a comma- delimited file for customer billing. Sorting and reporting is done at the customer level.

INPUT

Reads the log file as defined by filelocs.txt or AFC Initialization Function. log.sum – optional input from previous run

OUTPUT

log.sum – sorted and condensed log file as optional input for next run

Comma delimited log.rpt file.

Sorted and condensed by Customer Number, PCode, Tax Type, Tax Level, Tax Rate, Calculation Type.

FILE FORMAT KEY

Country, State, County, Locality, Tax type, Tax level, Tax rate, Calculation Type, Tax amount, Gross Sale, Exempt, Adjustments, Taxable measure, Minutes, Lines, Customer Number

Figure 5-7 ezlogcust File Format Key

Description

Type

Country

Alpha

State

Alpha

County

Alpha

Locality

Alpha

Tax Type

Numeric

Tax Level

Numeric

Tax Rate

Numeric

Calculation Type

Numeric

Tax Amount

Numeric

Gross Sale

Numeric

Exempt

Numeric

Adjustments

Numeric

Taxable Measure

Numeric

Minutes

Numeric

Lines

Numeric

Customer Number

Alpha Numeric

ARGUMENTS

–cl creates a combined compliance log file with a .scl extension, containing both the billable and non-billable amounts instead of a separate log file for each.

NOTES:

  • WARNING - EZTax.log is DELETED. Make backups in case reruns are needed.

SAMPLE DATA

USA, , , , 6, 0, 0.030000, RATE, 0.892576, 29.752527, 0.000000, 0.000000, 29.752527, 0.000000, 1, 1, 2143278889

USA, TX, , , 9, 1, 0.001670, RATE, 0.049687, 29.752527, 0.000000, 0.000000, 29.752527, 0.000000, 1, 0, 2143278889

USA, TX, , , 13, 1, 0.036000, RATE, 1.035438, 28.762179, 0.000000, 0.000000, 28.762179, 0.000000, 1, 0, 2143278889

USA, TX, , , 26, 1, 0.012500, RATE, 0.367089, 29.367090, 0.000000, 0.000000, 29.367090, 0.000000, 1, 0, 2143278889

USA, TX, DALLAS, DALLAS, 1, 1, 0.062500, RATE, 1.863693, 29.819089, 0.000000, 0.000000, 29.819089, 0.000000, 1, 0, 2143278889

USA, TX, DALLAS, DALLAS, 1, 3, 0.010000, RATE, 0.298022, 29.802214, 0.000000, 0.000000, 29.802214, 0.000000, 1, 0, 2143278889

USA, TX, DALLAS, DALLAS, 4, 3, 0.010000, RATE, 0.283838, 28.383766, 0.000000, 0.000000, 28.383766, 0.000000, 0, 0, 2143278889

USA, TX, DALLAS, DALLAS, 10, 3, 0.620000, PER_LINE, 0.620000, 0.000000, 0.000000, 0.000000, 0.000000, 0.000000, 1, 0, 2143278889

USA, TX, DALLAS, DALLAS, 51, 3, 1.350000, PER_LINE, 1.350000, 0.000000, 0.000000, 0.000000, 0.000000, 0.000000, 1, 0, 2143278889

USA, , , , 6, 0, 0.030000, RATE, 0.210216, 7.007192, 0.000000, 0.000000, 7.007192, 5.100000, 0, 0, 2143278889B

USA, , , , 18, 0, 0.072805, RATE, 0.009967, 0.136896, 0.000000, 0.000000, 0.136896, 0.100000, 0, 0, 2143278889B

USA, , , , 31, 0, 0.000730, RATE, 0.000099, 0.135089, 0.000000, 0.000000, 0.135089, 0.100000, 0, 0, 2143278889B

USA, TX, , , 9, 1, 0.001670, RATE, 0.011392, 6.821736, 0.000000, 0.000000, 6.821736, 5.000000, 0, 0, 2143278889B

USA, TX, , , 10, 1, 0.006000, RATE, 0.039000, 6.500000, 0.000000, 0.000000, 6.500000, 5.000000, 0, 0, 2143278889B

USA, TX, , , 13, 1, 0.036000, RATE, 0.242515, 6.736532, 0.000000, 0.000000, 6.736532, 5.100000, 0, 0, 2143278889B

USA, TX, , , 26, 1, 0.012500, RATE, 0.086118, 6.889438, 0.000000, 0.000000, 6.889438, 5.100000, 0, 0, 2143278889B

USA, TX, DALLAS, DALLAS, 1, 1, 0.062500, RATE, 0.436224, 6.979585, 0.000000, 0.000000, 6.979585, 5.100000, 0, 0, 2143278889B

USA, TX, DALLAS, DALLAS, 1, 3, 0.010000, RATE, 0.068331, 6.833129, 0.000000, 0.000000, 6.833129, 5.000000, 0, 0, 2143278889B

USA, TX, DALLAS, DALLAS, 4, 3, 0.010000, RATE, 0.068331, 6.833129, 0.000000, 0.000000, 6.833129, 5.000000, 0, 0, 2143278889B

See Transactions and Tax Types for descriptions of the data in the generated file.

ezlogcustios.exe

COMMAND LINE

ezlogcustios [-cl]

DESCRIPTION

The ezlogcustios.exe command reads the log file specified in filelocs.txt and produces a comma- delimited file for customer billing. Sorting and reporting is done at the customer level.

INPUT

Reads the reads the log file specified in filelocs.txt or AFC Initialization Function.

log.sum – optional input from previous run

OUTPUT

log.sum – sorted and condensed log file as optional input for next run

Comma delimited log.rpt file.

Sorted and condensed by Customer Number, PCode, Invoice Number, Optional, Service Level Number, Tax Type, Tax Level, Tax Rate

FILE FORMAT KEY

Invoice Number, Optional, Service Level Number, Country, State, County, Locality, Tax type, Tax level, Tax rate, Tax amount, Gross Sale, Exempt, Adjustments, Taxable measure, Minutes, Customer Number

Figure 5-8 ezlogcustios File Format Key

Description

Type

Invoice Number

Numeric

Optional

Numeric

Service Level Number

Numeric

Country

Alpha

Description

Type

State

Alpha

County

Alpha

Locality

Alpha

Tax Type

Numeric

Tax Level

Numeric

Tax Rate

Numeric

Tax Amount

Numeric

Gross Sale

Numeric

Exempt

Numeric

Adjustments

Numeric

Taxable Measure

Numeric

Minutes

Numeric

Customer Number

Alpha Numeric

ARGUMENTS

–cl creates a combined compliance log file with a .scl extension, containing both the billable and non-billable amounts instead of a separate log file for each.

NOTES:

  • WARNING - EZTax.log is DELETED. Make backups in case reruns are needed.

SAMPLE DATA

6, 8, 7, USA, AL, AUTAUGA, AUTAUGAVILLE, 1, 1, 0.040000, RATE, 0.720000, 18.000000, 0.000000, 0.000000, 18.000000, 275.940002, 54, 18, BillSoft Inc. 

6, 8, 7, USA, AL, AUTAUGA, JONES, 1, 2, 0.020000, RATE, 0.320000, 16.000000, 0.000000, 0.000000, 16.000000, 245.280014, 48, 16, BillSoft Inc. 

6, 8, 7, USA, AL, AUTAUGA, PRATTVILLE, 1, 3, 0.025000, RATE, 0.050000, 2.000000, 0.000000, 0.000000, 2.000000, 30.660000, 6, 2, BillSoft Inc. 

6, 8, 7, USA, AL, AUTAUGA, AUTAUGAVILLE, 1, 3, 0.030000, RATE, 0.060000, 2.000000, 0.000000, 0.000000, 2.000000, 30.660000, 6, 2, BillSoft Inc. 

6, 8, 7, USA, , , , 6, 0, 0.030000, RATE, 14.312928, 477.097605, 0.000000, 0.000000, 477.097605, 5825.416504, 1140, 380, BillSoft Inc. 

6, 8, 7, USA, AL, , , 8, 1, 0.060000, RATE, 2.200486, 36.674766, 0.000000, 0.000000, 36.674766, 551.879822, 108, 36, BillSoft Inc. 

6, 8, 7, USA, AL, BALDWIN, , 10, 2, 0.690000, PER_LINE, 4.140000, 2.000000, 0.000000, 0.000000, 2.000000, 30.660000, 6, 2, BillSoft Inc. 

6, 8, 7, USA, AL, AUTAUGA, , 10, 2, 0.850000, PER_LINE, 35.700001, 14.000000, 0.000000, 0.000000, 14.000000, 214.620010, 42, 14, BillSoft Inc. 

6, 8, 7, USA, AL, , , 16, 1, 0.060000, RATE, 7.759929, 129.332160, 0.000000, 0.000000, 129.332160, 1931.577759, 378, 126, BillSoft Inc. 

6, 8, 7, USA, , , , 18, 0, 0.089000, RATE, 5.340000, 60.000000, 0.000000, 0.000000, 60.000000, 919.800232, 180, 60, BillSoft Inc. 

6, 8, 7, USA, AL, , , 23, 1, 0.150000, PER_LINE, 16.200001, 36.000000, 0.000000, 0.000000, 36.000000, 551.879822, 108, 36, BillSoft Inc. 

6, 8, 7, USA, , , , 31, 0, 0.003560, RATE, 0.213600, 60.000000, 0.000000, 0.000000, 60.000000, 919.800232, 180, 60, BillSoft Inc. 

6, 8, 7, USA, AL, BALDWIN, , 35, 2, 1.950000, PER_LINE, 11.700000, 2.000000, 0.000000, 0.000000, 2.000000, 30.660000, 6, 2, BillSoft Inc. 

6, 8, 7, USA, AL, AUTAUGA, , 35, 2, 2.400000, PER_LINE, 100.800004, 14.000000, 0.000000, 0.000000, 14.000000, 214.620010, 42, 14, BillSoft Inc. 

6, 8, 7, USA, AL, , , 44, 1, 0.700000, FIXED, 12.600000, 18.474840, 0.000000, 0.000000, 18.474840, 275.940002, 54, 18, BillSoft Inc. 

6, 8, 7, USA, , , , 55, 0, 0.025365, RATE, 1.014600, 40.000000, 0.000000, 0.000000, 40.000000, 613.199890, 120, 40, BillSoft Inc. 

6, 8, 7, USA, , , , 56, 0, 0.010680, RATE, 0.213600, 20.000000, 0.000000, 0.000000, 20.000000, 306.599976, 60, 20, BillSoft Inc. 

6, 8, 7, USA, , , , 62, 0, 0.001015, RATE, 0.040600, 40.000000, 0.000000, 0.000000, 40.000000, 613.199890, 120, 40, BillSoft Inc. 

6, 8, 7, USA, , , , 63, 0, 0.000427, RATE, 0.008540, 20.000000, 0.000000, 0.000000, 20.000000, 306.599976, 60, 20, BillSoft Inc. 

See Transactions and Tax Types for descriptions of the data in the generated file.

ezlogcustpts.exe

COMMAND LINE

ezlogcustpts [-cl]

DESCRIPTION

The ezlogcustpts.exe command reads the log file specified in filelocs.txt and produces a comma- delimited file for customer billing. Sorting and reporting is done at the customer level. The sort key also contains PCode, optional, and Service Level Number fields.

INPUT

Reads the log file as defined by filelocs.txt or AFC Initialization Function.

log.sum – optional input from previous run

OUTPUT

log.sum – sorted and condensed log file as optional input for next run

Comma delimited log.rpt file.

Sorted and condensed by Customer Number, PCode, Optional, Service Level Number, Tax Type, Tax Level, Tax Rate

FILE FORMAT KEY

PCode, Transaction type, Service Type, Country, State, County, Locality, Tax type, Tax level, Tax rate, Tax amount, Gross Sale, Exempt, Adjustments, Taxable measure, Minutes, Customer Number.

Figure 5-9 ezlogcustpts File Format Key

Description

Type

PCode

Numeric

Optional

Numeric

Service Level Number

Numeric

Country

Alpha

State

Alpha

County

Alpha

Locality

Alpha

Tax Type

Numeric

Tax Level

Numeric

Tax Rate

Numeric

Tax Amount

Numeric

Gross Sale

Numeric

Exempt

Numeric

Adjustments

Numeric

Taxable Measure

Numeric

Minutes

Numeric

Customer Number

Alpha Numeric

ARGUMENTS

–cl creates a combined compliance log file with a .scl extension, containing both the billable and non-billable amounts instead of a separate log file for each.

NOTES:

  • WARNING - EZTax.log is DELETED. Make backups in case reruns are needed.

SAMPLE DATA

0, 1, 1, USA,,,, 6, 0, 0.030000, 0.128824, 4.294140, 0.000000, 0.000000, 4.294140, 61.320000, BillSoft, Inc.

0, 1, 1, USA,,,, 18, 0, 0.072805, 0.291220, 4.000000, 0.000000, 0.000000, 4.000000, 61.320000, BillSoft, Inc.

0, 1, 1, USA,,,, 31, 0, 0.000730, 0.002920, 4.000000, 0.000000, 0.000000, 4.000000, 61.320000, BillSoft, Inc.

0, 1, 2, USA,,,, 6, 0, 0.030000, 0.128824, 4.294140, 0.000000, 0.000000, 4.294140, 61.320000, BillSoft, Inc.

0, 1, 2, USA,,,, 18, 0, 0.072805, 0.291220, 4.000000, 0.000000, 0.000000, 4.000000, 61.320000, BillSoft, Inc.

0, 1, 2, USA,,,, 31, 0, 0.000730, 0.002920, 4.000000, 0.000000, 0.000000, 4.000000, 61.320000, BillSoft, Inc.

0, 1, 3, USA,,,, 6, 0, 0.030000, 0.128824, 4.294140, 0.000000, 0.000000, 4.294140, 61.320000, BillSoft, Inc.

0, 1, 3, USA,,,, 18, 0, 0.072805, 0.291220, 4.000000, 0.000000, 0.000000, 4.000000, 61.320000, BillSoft, Inc.

0, 1, 3, USA,,,, 31, 0, 0.000730, 0.002920, 4.000000, 0.000000, 0.000000, 4.000000, 61.320000, BillSoft, Inc.

0, 1, 4, USA,,,, 18, 0, 0.072805, 0.291220, 4.000000, 0.000000, 0.000000, 4.000000, 61.320000, BillSoft, Inc.

0, 1, 4, USA,,,, 31, 0, 0.000730, 0.002920, 4.000000, 0.000000, 0.000000, 4.000000, 61.320000, BillSoft, Inc.

0, 2, 1, USA,,,, 6, 0, 0.030000, 0.120000, 4.000000, 0.000000, 0.000000, 4.000000, 61.320000, BillSoft, Inc.

0, 2, 2, USA,,,, 6, 0, 0.030000, 0.120000, 4.000000, 0.000000, 0.000000, 4.000000, 61.320000, BillSoft, Inc.

0, 2, 3, USA,,,, 6, 0, 0.030000, 0.120000, 4.000000, 0.000000, 0.000000, 4.000000, 61.320000, BillSoft, Inc.

0, 2, 5, USA,,,, 6, 0, 0.030000, 0.120000, 4.000000, 0.000000, 0.000000, 4.000000, 61.320000, BillSoft, Inc.

0, 3, 6, USA,,,, 6, 0, 0.030000, 0.360000, 12.000000, 0.000000, 0.000000, 12.000000, 183.960007, BillSoft, Inc.

0, 3, 9, USA,,,, 6, 0, 0.030000, 0.120000, 4.000000, 0.000000, 0.000000, 4.000000, 61.320000, BillSoft, Inc.

100, 1, 1, USA, AL, , , 16, 1, 0.060000, 0.257648, 4.294140, 0.000000, 0.000000, 4.294140, 61.320000, BillSoft, Inc.

100, 1, 2, USA, AL, , , 16, 1, 0.060000, 0.257648, 4.294140, 0.000000, 0.000000, 4.294140, 61.320000, BillSoft, Inc.

100, 1, 3, USA, AL, , , 16, 1, 0.060000, 0.257648, 4.294140, 0.000000, 0.000000, 4.294140, 61.320000, BillSoft, Inc.

100, 1, 4, USA, AL, , , 16, 1, 0.060000, 0.257648, 4.294140, 0.000000, 0.000000, 4.294140, 61.320000, BillSoft, Inc.

100, 2, 1, USA, AL, , , 16, 1, 0.060000, 0.240000, 4.000000, 0.000000, 0.000000, 4.000000, 61.320000, BillSoft, Inc.

100, 2, 2, USA, AL, , , 16, 1, 0.060000, 0.240000, 4.000000, 0.000000, 0.000000, 4.000000, 61.320000, BillSoft, Inc.

100, 2, 3, USA, AL, , , 16, 1, 0.060000, 0.240000, 4.000000, 0.000000, 0.000000, 4.000000, 61.320000, BillSoft, Inc.

100, 2, 4, USA, AL, , , 16, 1, 0.060000, 0.240000, 4.000000, 0.000000, 0.000000, 4.000000, 61.320000, BillSoft, Inc.

100, 2, 5, USA, AL, , , 16, 1, 0.060000, 0.240000, 4.000000, 0.000000, 0.000000, 4.000000, 61.320000, BillSoft, Inc.

100, 3, 6, USA, AL, , , 16, 1, 0.060000, 0.720000, 12.000000, 0.000000, 0.000000, 12.000000, 183.960007, BillSoft, Inc.

200, 2, 5, USA, AL, AUTAUGA, , 10, 2, 0.050000, 0.100000, 2.000000, 0.000000, 0.000000, 2.000000, 30.660000, BillSoft, Inc.

See Transactions and Tax Types for descriptions of the data in the generated file.

ezlogcustptslnl.exe

COMMAND LINE

ezlogcustptslnl [-cl]

DESCRIPTION

The ezlogcustptslnl.exe command reads the log file specified in filelocs.txt and produces a comma-delimited file for customer billing. Sorting and reporting is done at the customer level. In addition to the PCode, optional, and Service Level Number fields and the number of lines and are also included.

INPUT

Reads the log file as defined by filelocs.txt or AFC Initialization Function.

log.sum – optional input from previous run

OUTPUT

log.sum – sorted and condensed log file as optional input for next run

Comma delimited log.rpt file.

Sorted and condensed by Customer Number, PCode, Optional, Service Level Number, Tax Type, Tax Level, Tax Rate

FILE FORMAT KEY

PCode, Transaction type, Service Type, Country, State, County, Locality, Tax type, Tax level, Tax rate, Tax amount, Gross Sale, Exempt, Adjustments, Taxable measure, Minutes, Customer Number, Lines

Figure 5-10 ezlogcustptslnl File Format Key

Description

Type

PCode

Numeric

Optional

Numeric

Service Level Number

Numeric

Country

Alpha

State

Alpha

County

Alpha

Locality

Alpha

Tax Type

Numeric

Tax Level

Numeric

Tax Rate

Numeric

Tax Amount

Numeric

Gross Sale

Numeric

Exempt

Numeric

Adjustments

Numeric

Taxable Measure

Numeric

Minutes

Numeric

Customer Number

Alpha Numeric

Lines

Numeric

ARGUMENTS

–cl creates a combined compliance log file with a .scl extension, containing both the billable and non-billable amounts instead of a separate log file for each.

NOTES:

  • WARNING - EZTax.log is DELETED. Make backups in case reruns are needed.

SAMPLE DATA

0, 0, 0, USA, , , , 6, 0, 0.030000, 2.462930, 82.097663, 0.000000, 0.000000, 82.097663, 0.000000, BillSoft, Inc. , 6, 2

0, 0, 0, USA, , , , 18, 0, 0.089000, 1.157000, 13.000000, 0.000000, 0.000000, 13.000000, 0.000000, BillSoft, Inc. , 0, 0

0, 0, 0, USA, , , , 31, 0, 0.000000, 0.000000, 13.000000, 13.000000, 0.000000, 0.000000, 0.000000, BillSoft, Inc. , 0, 0

1210800, 0, 0, USA, KS, , , 13, 1, 0.048700, 1.458565, 29.949999, 0.000000, 0.000000, 29.949999, 0.000000, BillSoft, Inc. , 0, 0

1284800, 0, 0, USA, KS, SALINE, , 10, 2, 0.750000, 2.250000, 0.000000, 0.000000, 0.000000, 0.000000, 0.000000, BillSoft, Inc. , 3, 0

1284900, 0, 0, USA, KS, SALINE, SALINA, 1, 1, 0.053000, 2.039814, 38.487064, 0.000000, 0.000000, 38.487064, 0.000000, BillSoft, Inc. , 0, 0

1284900, 0, 0, USA, KS, SALINE, SALINA, 1, 2, 0.010000, 0.384871, 38.487064, 0.000000, 0.000000, 38.487064, 0.000000, BillSoft, Inc. , 0, 0

1284900, 0, 0, USA, KS, SALINE, SALINA, 1, 3, 0.007500, 0.288653, 38.487064, 0.000000, 0.000000, 38.487064, 0.000000, BillSoft, Inc. , 0, 0

2502500, 0, 0, USA, NY, , , 5, 1, 0.025000, 0.925712, 37.028499, 0.000000, 0.000000, 37.028499, 0.000000, BillSoft, Inc. , 0, 0

2502500, 0, 0, USA, NY, , , 45, 1, 0.003750, 0.138857, 37.028499, 0.000000, 0.000000, 37.028499, 0.000000, BillSoft, Inc. , 0, 0

2604000, 0, 0, USA, NY, NEW YORK, , 10, 2, 1.000000, 3.000000, 0.000000, 0.000000, 0.000000, 0.000000, 0.000000, BillSoft, Inc. , 3, 0

2604000, 0, 0, USA, NY, NEW YORK, , 27, 2, 0.005950, 0.220320, 37.028499, 0.000000, 0.000000, 37.028499, 0.000000, BillSoft, Inc. , 0, 0

2604000, 0, 0, USA, NY, NEW YORK, , 28, 2, 0.001275, 0.047211, 37.028499, 0.000000, 0.000000, 37.028499, 0.000000, BillSoft, Inc. , 0, 0

2604100, 0, 0, USA, NY, NEW YORK, NEW YORK, 1, 1, 0.042500, 1.630325, 38.360599, 0.000000, 0.000000, 38.360599, 0.000000, BillSoft, Inc., 0, 0

2604100, 0, 0, USA, NY, NEW YORK, NEW YORK, 1, 3, 0.043750, 1.678276, 38.360599, 0.000000, 0.000000, 38.360599, 0.000000, BillSoft, Inc., 0, 0

2604100, 0, 0, USA, NY, NEW YORK, NEW YORK, 29, 3, 0.023500, 0.870170, 37.028499, 0.000000, 0.000000, 37.028499, 0.000000, BillSoft, Inc., 0, 0

See Transactions and Tax Types for descriptions of the data in the generated file.

EZTax_20.exe

EZTax_20 is a Processing Utility used to pass transaction records through the AFC Engine in Batch fashion.  Refer to batch file processing for details on the Batch processing method.

EZTaxappend.exe

COMMAND LINE

EZTaxappend logfilename1.log logfilename2.log

DESCRIPTION

The EZTaxappend.exe command is used to combine two logfilename.log files. It appends logfilename1.log to logfilename2.log, leaving logfilename1.log intact.

INPUT

logfilename1.log

OUTPUT

logfilename2.log

FILE FORMAT KEY

The output file produced is a log file with no format key as this is a log manipulation utility.

ARGUMENTS

logfilename1.log – the name of the EZTaxlog file to be appended

logfilename2.log – the name of the EZTaxlog file to be appended to.

NOTES:

  • log.sum is NOT created.
  • EZTax.log is NOT deleted.
  • logfilename1.log and logfilename2.log must be actual filenames.
  • Filelocs.txt is not used.

EZTaxappendf.exe

COMMAND LINE

EZTaxappendf filelist.txt extaxlogfilename.log

DESCRIPTION

The EZTaxappendf.exe command is used to combine the logfilename.log files listed in the filelist.txt text file containing the paths and logfilename.log names to combine.

INPUT

Filelist.txt

OUTPUT

logfilename.log

FILE FORMAT KEY

The output file produced is a log file with no format key as this is a log manipulation utility.

ARGUMENTS

Filelist.txt – the text file supplied by the user with the names of the logfilename.log files.

logfilename.log – the name of the new logfilename.log to be created.

NOTES:

  • logfilename.log will be created if it does not exist. Otherwise it will append to the existing
  • logfilename.log file.
  • All log files defined in Filelist.txt are concatenated to logfilename.log
  • log.sum is NOT created.
  • EZTax.log is NOT deleted.
  • Filelocs.txt is not used.
  • Filelist.txt entries can be space or line delimited.

log no tax transactions

DESCRIPTION

LOGNOTAXTRANS=OFF

LOGNOTAXTRANS=ON

The Log No Tax Transaction option is used to allow writing zero tax amount transactions to the EZTax.ntl log file. The default setting of “OFF” disables this logging function. When set to “ON,” AFC will write zero tax amount transactions to the EZTax.ntl log file.

The no tax transaction log is used to track transactions that do not return any tax types and therefore do not perform tax calculations. This allows for the distinction from a transaction that logs zero tax when a calculation has occurred and resulted in a value of zero which is then placed in EZTax.log.

The no tax transaction log will be named [logname].ntl in which logname refers to the name of the AFC transaction log file, minus the extension, and will be output to the same directory as the log file.

Example of Naming Convention:

(Based on the assumption that the billing system has two sessions with log files named SessionA.log and SessionB.log.)

The output from a normal run with no tax transaction logging enabled would be: SessionA.log

SessionA.sta

SessionA.tsr

SessionA.ntl

SessionB.log

SessionB.sta

SessionB.tsr

SessionB.ntl

 

NOTE: The lognotaxtrans switch is over-ridden by the overall logging switch. If logging is turned off when the EZTaxInitEx function initializes the AFC session, the no-tax-trans log will not be created.

 

FILE FORMAT KEY

Short Format:

Company Identifier, Customer Number, Transaction Type, Service Type, P Code, Charge

Figure 5-11 Short EZTax.ntl Log File Format Key

Description

Type

Length

Positions

Company Identifier

Alpha Numeric

20

1-20

Customer Number

Alpha Numeric

20

21-40

Transaction Type

Numeric

4

41-44

Service Type

Numeric

4

45-48

P Code

Numeric

10

49-58

Charge

Numeric

15.5

59-73

Record Length

 

73

 

Long Format:

Company Identifier, Customer Number, Optional Alpha Text, Transaction Type, Service Type, P Code, Charge

Figure 5-12 EZTax.ntl Long Log File Format Key

Description

Type

Length

Positions

Company Identifier

Alpha Numeric

20

1-20

Customer Number

Alpha Numeric

20

21-40

Optional Alpha

Alpha

20

41-60

Transaction Type

Numeric

4

61-64

Service Type

Numeric

4

65-68

P Code

Numeric

10

69-78

Charge

Numeric

15.5

79-93

Record Length

 

93

 

NOTES:

None

SAMPLE DATA

Short Format:

company_identifier, customer_number, transaction_type, service_type, P_Code, charge

--- Sample output begins on the next line ----------

EZtax version 9.0.0.0.5 No-tax Transaction Log

6215687423a, TU98602746, 0001, 0027, 2102300, 1395.00000 

6215687423a, OP97602744, 0001, 0027, 2102300, 630.00000 

6215687423a, 104602742, 0004, 0008, 2102300, 950.00000 

6215687423a, 555602718, 0001, 0027, 2102300, 100.00000 

6215687423a, 16055602716, 0001, 0027, 2102300, 100.00000 

6215687423a, 22602711, 0001, 0027, 2102300, 100.00000 

6215687423a, 19602709, 0003, 0006, 2102300, 266.44000 

6215687423a, 33602707, 0001, 0027, 2102300, 300.00000 

6215687423a, 55602705, 0001, 0027, 2102300, 500.00000 

6215687423a, LD55602703, 0001, 0027, 2102300, 100.00000 

6215687423a, 56602701, 0003, 0006, 2102300, 266.44000 

6215687423a, 57602699, 0001, 0027, 2102300, 300.00000 

6215687423a, 58602697, 0001, 0027, 2102300, 500.00000 

6215687423a, 58587819, 0001, 0027, 2350600, 500.00000 

Long Format:

company_identifier, customer_number, optional alpha text, transaction_type, service_type, P_Code, charge

--- Sample output begins on the next line ----------

EZtax version 9.0.0.0.5 No-tax Transaction Log

6215687423a, TU98602746, Optional Text, 0001, 0027, 2102300, 1395.00000 

6215687423a, OP97602744, Optional Text, 0001, 0027, 2102300, 630.00000 

6215687423a, 104602742, Optional Text, 0004, 0008, 2102300, 950.00000 

6215687423a, 555602718, Optional Text, 0001, 0027, 2102300, 100.00000 

6215687423a, 16055602716, Optional Text, 0001, 0027, 2102300, 100.00000 

6215687423a, 22602711, Optional Text, 0001, 0027, 2102300, 100.00000 

6215687423a, 19602709, Optional Text, 0003, 0006, 2102300, 266.44000 

6215687423a, 33602707, Optional Text, 0001, 0027, 2102300, 300.00000 

6215687423a, 55602705, Optional Text, 0001, 0027, 2102300, 500.00000 

6215687423a, LD55602703, Optional Text, 0001, 0027, 2102300, 100.00000 

6215687423a, 56602701, Optional Text, 0003, 0006, 2102300, 266.44000 

6215687423a, 57602699, Optional Text, 0001, 0027, 2102300, 300.00000 

6215687423a, 58602697, Optional Text, 0001, 0027, 2102300, 500.00000 

6215687423a, 58587819, Optional Text, 0001, 0027, 2350600, 500.00000 

srtcdf20.exe

COMMAND LINE

srtcdf20 [-z <pkzip executable>] outputfilename [-nN] [extralogfilename] [-cl]

DESCRIPTION

The srtcdf20.exe command reads the log file specified in filelocs.txt and produces a fixed length text file outputfilename.ssf for tax compliance filing and a fixed length text file outputfilename.csf for customer billing.

INPUT

Reads the log file as defined by filelocs.txt or AFC Initialization Function.

log.sum – optional input from previous run, or uses the extralogfilename from the command line.

OUTPUT

Fixed Length outputfilename.ssf file for tax compliance filing.  Sorted and condensed by PCode, Tax Type, Tax Level, Tax Rate

Fixed Length outputfilename.csf file for customer billing.  Sorted and condensed by Customer Number, Tax Type, Tax Level, Tax Rate FILE

FORMAT KEYS

Figure 5-13 srtcdf20 SSF File Format Key

Description

Type

Length

Positions

PCode

Numeric

9

1-9

Tax Type

Numeric

6

10-15

Tax Level

Numeric

1

16

Tax Rate

Numeric

8.5

17-24

Tax Amount Sign

Alpha

1

25

Tax Amount

Numeric

11.5

26-36

File Record Length

 

36

 

 

Figure 5-14 srtcdf20 CSF File Format Key

Description

Type

Length

Positions

Customer Number

Numeric

20

1-20

Tax Type

Numeric

6

21-26

Tax Level

Numeric

1

27

Tax Amount

Numeric

12

28-39

File Record Length

 

39

 

ARGUMENTS:

-z <pkzip executable> - path to zip executable file* N or n – CSF file is not sorted

extra log file name – use instead of log.sum

–cl creates a combined compliance log file with a .scl extension, containing both the billable and non-billable amounts instead of a separate log file for each.

*The pkzip executable option is only available with the windows platform.

NOTES:

  • The Tax Rate field is sensitive to positive and negative values
  • The log.sum file is NOT created
  • WARNING - EZTax.log is DELETED. Make backups in case reruns are needed.

SAMPLE DATA

0                1                  2                  3 

123456789012345678901234567890123456 

------------------------------------------------------------ 

000000000000006000003000+00098418707 

000000000000007000000580+00018387113 

000000000000018000003180+00081599822 

000000000000031000000039+00001000752 

See Transactions and Tax Types for descriptions of the data in the generated file.

srtcdf20p.exe

COMMAND LINE

srtcdf20p [-z <pkzippath>] outputfilename [-nN] [-cl]

DESCRIPTION

The srtcdf20p.exe command reads the log file specified in filelocs.txt and produces a fixed length text file outputfilename.ssf for tax compliance filing and a fixed length text file outputfilename.csf for customer billing.

The .csf file is used for import into the billing system to populate customer bills. Various compliance vendors use the .ssf file. The csf file also contains the PCode.

INPUT

Reads the logfile as defined by filelocs.txt or AFC Initialization Function. log.sum – optional input from previous run

OUTPUT

Fixed Length outputfilename.ssf file for tax compliance filing.  Sorted and condensed by PCode, Tax Type, Tax Level, Tax Rate

Fixed Length outputfilename.csf file for customer billing.  Sorted and condensed by Customer Number, Tax Type, Tax Level, Tax Rate FILE

FORMAT KEYS

Figure 5-15 srtcdf20p SSF File Format Key

Description

Type

Length

Positions

PCode

Numeric

9

1-9

Tax Type

Numeric

6

10-15

Tax Level

Numeric

1

16

Tax Rate

Numeric

8.5

17-24

Tax Amount Sign

Alpha

1

25

Description

Type

Length

Positions

Tax Amount

Numeric

11.5

26-36

File Record Length

 

36

 

 

Figure 5-16 srtcdf20p CSF File Format Key

Description

Type

Length

Positions

Customer Number

Numeric

20

1-20

Tax Type

Numeric

6

21-26

Tax Level

Numeric

1

27

Tax Amount

Numeric

12

28-39

PCode

Numeric

9

40-48

File Record Length

 

48

 

ARGUMENTS:

-z <pkzip executable> - path to zip executable file*

N or n – CSF file is not sorted

–cl creates a combined compliance log file with a .scl extension, containing both the billable and non-billable amounts instead of a separate log file for each.

*The pkzip executable option is only available with the windows platform.

NOTES:

  • The Tax Rate field is sensitive to positive and negative values
  • The log.sum file is NOT created
  • WARNING - EZTax.log is DELETED. Make backups in case reruns are needed.

See Transactions and Tax Types for descriptions of the data in the generated file.

srtcomcust20.exe

COMMAND LINE

srtcomcust20 [-z <pkzip executable>] outputfilename [nN] [extra log file name] [-cl]

DESCRIPTION

The srtcomcust20.exe command reads the log file specified in filelocs.txt and produces a comma delimited text file outputfilename.ssf for tax compliance filing and a fixed length text file outputfilename.csf for customer billing.

The .csf file is used for import into the billing system to populate customer bills. The comma- delimited .ssf file is sorted at the customer level.

INPUT

Reads the log file as defined by filelocs.txt or EZtax Initialization Function.

log.sum – optional input from previous run or uses the extra log file name from the command line.

OUTPUT

Comma Delimited outputfilename.ssf file for tax compliance filing.  Sorted and condensed by Customer Number, PCode, Tax Type, Tax Level, Tax Rate, Calculation Type.

Fixed Length outputfilename.csf file for customer billing.  Sorted and condensed by Customer Number, Tax Type, Tax Level, Tax Rate

FILE FORMAT KEY

Figure 5-17 srtcomcust20 SSF File Format Key

Description

Type

Country

Alpha

State

Alpha

County

Alpha

Locality

Alpha

PCode

Numeric

Tax Type

Numeric

Tax Level

Numeric

Tax Rate

Numeric

Calculation Type

Alpha

Tax Amount

Numeric

Gross Sale

Numeric

Exempt

Numeric

Adjustments

Numeric

Taxable Measure

Numeric

Minutes

Numeric

Lines

Numeric

Customer Number

Alpha Numeric

 

Figure 5-18 srtcomcust20 CSF File Format Key

Description

Type

Length

Positions

Customer Number

Numeric

20

1-20

Tax Type

Numeric

6

21-26

Tax Level

Numeric

1

27

Tax Amount

Numeric

12

28-39

File Record Length

 

39

 

ARGUMENTS:

-z <pkzip executable> - path to zip executable file* N or n – CSF file is not sorted

extra log file name – use instead of log.sum

–cl creates a combined compliance log file with a .scl extension, containing both the billable and non-billable amounts instead of a separate log file for each.

*The pkzip executable option is only available with the windows platform.

NOTES:

  • The Tax Rate field is sensitive to positive and negative values
  • The log.sum file is NOT created
  • WARNING - EZTax.log is DELETED. Make backups in case reruns are needed.

See Transactions and Tax Types for descriptions of the data in the generated file.

srtcomma20.exe

COMMAND LINE

Srtcomma20 [-z <pkzip executable>] outputfilename [nN] [extra log file name][-cl]

DESCRIPTION

The srtcomma20.exe command reads the log file specified in filelocs.txt and produces a comma delimited text file outputfilename.ssf for tax compliance filing and a fixed length text file outputfilename.csf for customer billing.

The .csf file is used for import into the billing system to populate customer bills. The comma- delimited .ssf file is sorted at the jurisdictional level.

INPUT

Reads the logfilename.log file as defined by filelocs.txt or AFC Initialization Function.

log.sum – optional input from previous run or uses the extra log file name from the command line.

OUTPUT

log.sum – sorted and condensed log file as optional input for next run

Comma Delimited outputfilename.ssf file for tax compliance filing. Sorted and condensed by PCode, Tax Type, Tax Level, Tax Rate

Fixed Length outputfilename.csf file for customer billing.  Sorted and condensed by Customer Number, Tax Type, Tax Level, Tax Rate

FILE FORMAT KEY

Country, State, County, Locality, Tax type, Tax level, Tax rate, Tax amount, Gross Sale, Exempt, Adjustments, Taxable measure, Minutes

File 5-19 srtcomma20 SSF File Format Key

Description

Type

Country

Alpha

State

Alpha

County

Alpha

Locality

Alpha

Tax Type

Numeric

Tax Level

Numeric

Tax Rate

Numeric

Description

Type

Tax Amount

Numeric

Gross Sale

Numeric

Exempt

Numeric

Adjustments

Numeric

Taxable Measure

Numeric

Minutes

Numeric

 

Figure 5-20 srtcomma20 CSF File Format Key

Description

Type

Length

Positions

Customer Number

Alpha

20

1-20

Tax Type

Numeric

6

21-26

Tax Level

Numeric

1

27

Tax Amount Sign

Alpha

1

28

Tax Amount

Numeric

11.5

29-39

File Record Length

 

39

 

ARGUMENTS:

-z <pkzip executable> - path to zip executable file*

N or n – CSF file is not sorted

extra log file name – use instead of log.sum

–cl creates a combined compliance log file with a .scl extension, containing both the billable and non-billable amounts instead of a separate log file for each.

*The pkzip executable option is only available with the windows platform.

NOTES:

  • The Tax Rate field is sensitive to positive and negative values
  • The log.sum file is NOT created
  • WARNING - EZTax.log is DELETED. Make backups in case reruns are needed.

SAMPLE DATA

USA,,,, 6, 0, 0.030000, 29881.866905, 996062.252444, 0.000000, 0.000000, 996062.252444, 14859213.000000

USA,,,, 7, 0, 0.007600, 10116.132171, 1331070.000000, 0.000000, 0.000000, 1331070.000000, 20410578.000000

USA,,,, 18, 0, 0.031400, 11145.492379, 354952.000000, 0.000000, 0.000000, 354952.000000, 5446827.000000

USA, AL, , , 16, 1, 0.067000, 969.972210, 14477.196802, 0.000000, 0.000000, 14477.196802, 220238.671875

USA, AZ, , , 1, 1, 0.050000, 0.806080, 16.121600, 0.000000, 0.000000, 16.121600, 245.280014

USA, AZ, , , 10, 1, 0.012500, 9.068400, 725.472000, 0.000000, 0.000000, 725.472000, 11037.642578

USA, AZ, , , 12, 1, 0.011000, 7.980192, 725.472000, 0.000000, 0.000000, 725.472000, 11037.642578

USA, AZ, APACHE, , 1, 1, 0.050000, 0.806080, 16.121600, 0.000000, 0.000000, 16.121600, 245.280014

USA, AZ, APACHE, , 1, 2, 0.027000, 0.435283, 16.121600, 0.000000, 0.000000, 16.121600, 245.280014

USA, AZ, APACHE, SPRINGERVILLE, 1, 1, 0.050000, 0.705320, 14.106400, 0.000000, 0.000000, 14.106400, 214.620010

See Transactions and Tax Types for descriptions of the data in the generated file.

srtcomma20l.exe

COMMAND LINE

srtcomma20l [-z <pkzip executable>] outputfilename <nN> <-p> <-s> <pcsf> <extralogfilename> [- cl]

DESCRIPTION

The srtcomma20l.exe command reads the log file specified in filelocs.txt and produces a comma delimited text file outputfilename.ssf for tax compliance filing and a fixed length text file outputfilename.csf for customer billing, separating adjustments.

The .csf file is used for import into the billing system to populate customer bills. The comma- delimited .ssf file is sorted at the jurisdictional level.  The .ssf file also contains the number of lines.

INPUT

Reads the logfilename.log file as defined by filelocs.txt or AFC Initialization Function.

log.sum – optional input from previous run or uses the extra log file name from the command line.

OUTPUT

Fixed Length outputfilename.ssf file for tax compliance filing.  Sorted and condensed by PCode, Tax Type, Tax Level, Tax Rate.

Fixed Length outputfilename.csf file for customer billing.  Sorted and condensed by Customer Number, Tax Type, Tax Level, Tax Rate, Tax Amount.

FILE FORMAT KEY

Country, State, County, Locality, Tax type, Tax level, Tax rate, Tax amount, Gross Sale, Exempt, Adjustments, Taxable measure, Minutes, Lines

WITH -p OPTION SPECIFIED

PCode, Tax type, Tax level, Tax rate, Tax amount, Gross Sale, Exempt, Adjustments, Taxable measure, Minutes, Lines

Figure 5-21 srtcomma20l SSF File Format Key without –p option

Description

Type

Country

Alpha

State

Alpha

County

Alpha

Locality

Alpha

Tax Type

Numeric

Tax Level

Numeric

Tax Rate

Numeric

Tax Amount

Numeric

Gross Sale

Numeric

Exempt

Numeric

Description

Type

Adjustments

Numeric

Taxable Measure

Numeric

Minutes

Numeric

Lines

Numeric

 

Figure 5-22 srtcomma20l SSF File Format Key with –p option

Description

Type

PCode

Numeric

Tax Type

Numeric

Tax Level

Numeric

Tax Rate

Numeric

Tax Amount

Numeric

Gross Sale

Numeric

Exempt

Numeric

Adjustments

Numeric

Taxable Measure

Numeric

Minutes

Numeric

Lines

Numeric

 

Figure 5-23 srtcomma20l CSF File Format Key

Description

Type

Length

Positions

Customer Number

Alpha

20

1-20

Tax Type

Numeric

6

21-26

Tax Level

Numeric

1

27

Tax Amount Sign

Alpha

1

28

Tax Amount

Numeric

11.5

29-39

File Record Length

 

39

 

ARGUMENTS

-z <pkzip executable> - path to zip executable file* N or n – .csf file is unsorted

-p – add PCode to ssf file. Does not add PCode to csf file

-s – produce only the ssf. The .csf file is not created.

-pcsf – add PCode to csf file.

extra log file name – use instead of log.sum

–cl creates a combined compliance log file with a .scl extension, containing both the billable and non-billable amounts instead of a separate log file for each.

*The pkzip executable option is only available with the windows platform.

NOTES:

  • The Tax Rate field is sensitive to positive and negative values
  • The log.sum file is NOT created
  • WARNING - EZTax.log is DELETED. Make backups in case reruns are needed.

SAMPLE DATA

USA,,,, 6, 0, 0.030000, 29881.866905, 996062.252444, 0.000000, 0.000000, 996062.252444, 14859213.000000, 0

USA,,,, 7, 0, 0.007600, 10116.132171, 1331070.000000, 0.000000, 0.000000, 1331070.000000, 20410578.000000, 0

USA,,,, 18, 0, 0.031400, 11145.492379, 354952.000000, 0.000000, 0.000000, 354952.000000, 5446827.000000, 0

USA, AL, , , 16, 1, 0.067000, 969.972210, 14477.196802, 0.000000, 0.000000, 14477.196802, 220238.671875, 0

USA, AZ, , , 1, 1, 0.050000, 0.806080, 16.121600, 0.000000, 0.000000, 16.121600, 245.280014, 0

USA, AZ, , , 10, 1, 0.012500, 9.068400, 725.472000, 0.000000, 0.000000, 725.472000, 11037.642578, 0

USA, AZ, , , 12, 1, 0.011000, 7.980192, 725.472000, 0.000000, 0.000000, 725.472000, 11037.642578, 0

USA, AZ, APACHE, , 1, 1, 0.050000, 0.806080, 16.121600, 0.000000, 0.000000, 16.121600, 245.280014, 0

USA, AZ, APACHE, , 1, 2, 0.027000, 0.435283, 16.121600, 0.000000, 0.000000, 16.121600, 245.280014, 0

USA, AZ, APACHE, SPRINGERVILLE, 1, 1, 0.050000, 0.705320, 14.106400, 0.000000, 0.000000, 14.106400, 214.620010, 0

SAMPLE DATA WITH -p OPTION

0, 6, 0, 0.030000, 29881.866905, 996062.252444, 0.000000, 0.000000, 996062.252444, 14859213.000000, 0

0, 7, 0, 0.007600, 10116.132171, 1331070.000000, 0.000000, 0.000000, 1331070.000000, 20410578.000000, 0

0, 18, 0, 0.031400, 11145.492379, 354952.000000, 0.000000, 0.000000, 354952.000000, 5446827.000000, 0

100, 16, 1, 0.067000, 969.972210, 14477.196802, 0.000000, 0.000000, 14477.196802, 220238.671875, 0

125300, 1, 1, 0.050000, 0.806080, 16.121600, 0.000000, 0.000000, 16.121600, 245.280014, 0

125300, 10, 1, 0.012500, 9.068400, 725.472000, 0.000000, 0.000000, 725.472000, 11037.642578, 0

125300, 12, 1, 0.011000, 7.980192, 725.472000, 0.000000, 0.000000, 725.472000, 11037.642578, 0

125400, 1, 1, 0.050000, 0.806080, 16.121600, 0.000000, 0.000000, 16.121600, 245.280014, 0

125400, 1, 2, 0.027000, 0.435283, 16.121600, 0.000000, 0.000000, 16.121600, 245.280014, 0

125500, 1, 1, 0.050000, 0.705320, 14.106400, 0.000000, 0.000000, 14.106400, 214.620010, 0

See Transactions and Tax Types for descriptions of the data in the generated file.

srtcomma20ld.exe

COMMAND LINE

srtcomma20ld [-z <pkzip executable>] outputfilename <nN> <-p> <-s> <pcsf> <extralogfilename> [-cl] [-tc]

DESCRIPTION

The srtcomma20ld.exe command reads the log file specified in filelocs.txt and produces a comma delimited text file outputfilename.ssf for tax compliance filing and a fixed length text file outputfilename.csf for customer billing, separating adjustments.

The .csf file is used for import into the billing system to populate customer bills. The comma- delimited .ssf file is sorted at the jurisdictional level. The .ssf file also contains the number of lines.

Note: srtcomma20ld handles adjustments differently than srtcomma20l does by subtracting the adjustment from the Gross Sales before the Net Taxable Amount is calculated.

INPUT

Reads the logfilename.log file as defined by filelocs.txt or AFC Initialization Function.

log.sum – optional input from previous run or uses the extra log file name from the command line.

OUTPUT

Fixed Length outputfilename.ssf file for tax compliance filing. Sorted and condensed by PCode, Tax Type, Tax Level, Tax Rate.

Fixed Length outputfilename.csf file for customer billing.  Sorted and condensed by Customer Number, Tax Type, Tax Level, Tax Rate, Tax Amount.

FILE FORMAT KEY

Country, State, County, Locality, Tax type, Tax level, Discount type, Calculation type, Tax rate, Tax amount, Gross Sale, Exempt, Adjustments, Taxable measure, Minutes, Lines

WITH -p OPTION SPECIFIED

PCode, Tax type, Tax level, Discount type, Calculation type, Tax rate, Tax amount, Gross Sale, Exempt, Adjustments, Taxable measure, Minutes, Lines

Figure 5-24 srtcomma20ld SSF File Format Key without –p option

Description

Type

Country

Alpha

State

Alpha

County

Alpha

Locality

Alpha

Tax Type

Numeric

Tax Level

Numeric

Discount Type

Numeric

Calculation Type

Numeric

Tax Rate

Numeric

Tax Amount

Numeric

Gross Sale

Numeric

Exempt

Numeric

Adjustments

Numeric

Taxable Measure

Numeric

Minutes

Numeric

Lines

Numeric

 

Figure 5-25 srtcomma20ld SSF File Format Key with –p option

Description

Type

PCode

Numeric

Tax Type

Numeric

Tax Level

Numeric

Discount Type

Numeric

Calculation Type

Numeric

Tax Rate

Numeric

Tax Amount

Numeric

Gross Sale

Numeric

Exempt

Numeric

Adjustments

Numeric

Description

Type

Taxable Measure

Numeric

Minutes

Numeric

Lines

Numeric

 

Figure 5-26 srtcomma20l CSF File Format Key

Description

Type

Length

Positions

Customer Number

Alpha

20

1-20

Tax Type

Numeric

6

21-26

Tax Level

Numeric

1

27

Tax Amount Sign

Alpha

1

28

Tax Amount

Numeric

11.5

29-39

Tax Category (optional)

Alpha

50

40-69

File Record Length

 

39 or 89

 

ARGUMENTS

-z <pkzip executable> - path to zip executable file* N or n – .csf file is unsorted

-p – add PCode to ssf file. Does not add PCode to csf file

-s – produce only the ssf. The .csf file is not created.

-pcsf – add PCode to csf file.

extra log file name – use instead of log.sum

–cl creates a combined compliance log file with a .scl extension, containing both the billable and non-billable amounts instead of a separate log file for each.

-tc adds the tax category description to the end of each line

*The pkzip executable option is only available with the windows platform.

NOTES:

  • The Tax Rate field is sensitive to positive and negative values
  • The log.sum file is NOT created
  • WARNING - EZTax.log is DELETED. Make backups in case reruns are needed.

SAMPLE DATA

USA, NY, NEW YORK, NEW YORK, 1, 1, 0, 1, 0.042500, 50.950600, 1198.837637, 0.000000, 0.000000, 1198.837637, 480.0, 0

USA, NY, NEW YORK, NEW YORK, 1, 3, 0, 1, 0.041250, 49.452053, 1198.837637, 0.000000, 0.000000, 1198.837637, 480.0, 0

USA, PA, BERKS, KEMPTON, 1, 1, 0, 1, 0.060000, 58.370907, 972.848456, 0.000000, 0.000000, 972.848456, 240.0, 0

USA, PA, SCHUYLKILL, NEW PHILADELPHIA, 1, 1, 0, 1, 0.060000, 58.370907, 972.848456, 0.000000, 0.000000, 972.848456, 240.0, 0

SAMPLE DATA WITH -p OPTION

1040600, 1, 1, 0, 1, 0.060000, 34.397387, 573.289778, 0.000000, 0.000000, 573.289778, 240.0, 0

1054600, 1, 1, 0, 1, 0.060000, 34.397387, 573.289778, 0.000000, 0.000000, 573.289778, 240.0, 0

1615500, 1, 1, 0, 1, 0.050000, 25.328978, 506.579556, 0.000000, 0.000000, 506.579556, 480.0, 0

2395900, 1, 1, 0, 1, 0.060000, 111.182681, 1853.044679, 0.000000, 0.000000, 1853.044679, 480.0, 0

2604100, 1, 1, 0, 1, 0.042500, 50.950600, 1198.837637, 0.000000, 0.000000, 1198.837637, 480.0, 0

2604100, 1, 3, 0, 1, 0.041250, 49.452053, 1198.837637, 0.000000, 0.000000, 1198.837637, 480.0, 0

3232600, 1, 1, 0, 1, 0.060000, 58.370907, 972.848456, 0.000000, 0.000000, 972.848456, 240.0, 0

3415300, 1, 1, 0, 1, 0.060000, 58.370907, 972.848456, 0.000000, 0.000000, 972.848456, 240.0, 0

See Transactions and Tax Types for descriptions of the data in the generated file.

srtcommadetail.exe

COMMAND LINE

srtcommadetail [-z <pkzip executable>] outputfilename [nN] <-nocsf> <extralogfilename> [-cl]

DESCRIPTION

The srtcommadetail.exe command reads the log file specified in filelocs.txt and produces a comma delimited text file outputfilename.ssf for tax compliance filing and a fixed length text file outputfilename.csf for customer billing.

INPUT

Reads the logfilename.log file as defined by filelocs.txt or AFC Initialization Function.

log.sum – optional input from previous run.

OUTPUT

Comma Delimited outputfilename.ssf file for tax compliance filing. Sorted and condensed by PCode, Tax Type, Tax Level, Tax Rate

Fixed Length outputfilename.csf file for customer billing.  Sorted and condensed by Customer Number, Tax Type, Tax Level, Tax Rate

FILE FORMAT KEY

Country, State, County, Locality, PCode, Tax type, Tax Type Description, Tax level, Tax Level Description, Tax rate, Tax amount, Gross Sale, Exempt, Adjustments, Taxable measure, Minutes

Figure 5-27 srtcommadetail SSF File Format Key

Description

Type

Country

Alpha

State

Alpha

County

Alpha

Locality

Alpha

PCode

Numeric

Tax Type

Numeric

Tax Type Description

Alpha

Tax Level

Numeric

Tax Level Description

Alpha

Tax Rate

Numeric

Tax Amount

Numeric

Gross Sale

Numeric

Exempt

Numeric

Adjustments

Numeric

Taxable Measure

Numeric

Description

Type

Minutes

Numeric

 

Figure 5-28 srtcommadetail CSF File Format Key

Description

Type

Length

Positions

Customer Number

Alpha

20

1-20

Tax Type

Numeric

6

21-26

Tax Level

Numeric

1

27

Tax Amount Sign

Alpha

1

28

Tax Amount

Numeric

11.5

29-39

File Record Length

 

39

 

ARGUMENTS

-z <pkzip executable> - path to zip executable file*

<output filename>

n or N – csf file is not sorted

-nocsf – csf file is not created

extra log file name – use instead of log.sum

–cl creates a combined compliance log file with a .scl extension, containing both the billable and non-billable amounts instead of a separate log file for each.

*The pkzip executable option is only available with the windows platform.

NOTES:

  • The Tax Rate field is sensitive to positive and negative values
  • The log.sum file is NOT created
  • WARNING - EZTax.log is DELETED. Make backups in case reruns are needed.

SAMPLE DATA

USA, , , , 0, 6, Federal Excise Tax, 0, Federal, 0.030000, 63.946941, 2131.564739, 0.000000, 0.000000, 2131.564739, 2376516.0

USA, CA, , , 253500, 9, P.U.C. Fee, 1, State, 0.001100, 0.072776, 66.159998, 0.000000, 0.000000, 66.159998, 155916.0

USA, CA, , , 253500, 10, E911 Tax, 1, State, 0.006500, 0.450252, 69.269518, 0.000000, 0.000000, 69.269518, 155916.0

USA, CA, , , 253500, 19, State High Cost Fund, 1, State, 0.024300, 1.607688, 66.159998, 0.000000, 0.000000, 66.159998, 155916.0

USA, CA, , , 253500, 21, CA Teleconnect Fund, 1, State, 0.001600, 0.105856, 66.159998, 0.000000, 0.000000, 66.159998, 155916.0

USA, CA, , , 253500, 60, CA High Cost Fund A, 1, State, 0.001500, 0.099240, 66.159998, 0.000000, 0.000000, 66.159998, 155916.0

USA, CO, , , 427200, 13, State Universal Service Fund, 1, State, 0.029000, 0.026172, 0.902500, 0.000000, 0.000000, 0.902500, 1920.0

USA, CO, DENVER, , 442100, 4, District Tax, 2, County, 0.001000, 0.000211, 0.210945, 0.000000, 0.000000, 0.210945, 246.0

See Transactions and Tax Types for descriptions of the data in the generated file.

srtrev20l.exe

COMMAND LINE

srtrev20l [-z <pkzip executable>] outputfilename <nN> <-p> <-s> <pcsf> <extralogfilename> [-cl] [- tc]

DESCRIPTION

The srtrev20l.exe command reads the log file specified in filelocs.txt and produces a comma delimited text file outputfilename.ssf for tax compliance filing and a fixed length text file outputfilename.csf for customer billing, separating adjustments. It is intended for use with log files created using tax inclusive calculation functionality in AFC.

The .csf file is used for import into the billing system to populate customer bills. The comma- delimited .ssf file is sorted at the jurisdictional level. The .ssf file also contains the number of lines.

INPUT

Reads the logfilename.log file as defined by filelocs.txt or AFC Initialization Function.

log.sum – optional input from previous run or uses the extra log file name from the command line.

OUTPUT

Fixed Length outputfilename.ssf file for tax compliance filing. Sorted and condensed by PCode, Tax Type, Tax Level, Tax Rate.

Fixed Length outputfilename.csf file for customer billing.  Sorted and condensed by Customer Number, Tax Type, Tax Level, Tax Rate, Tax Amount.

FILE FORMAT KEY

Country, State, County, Locality, Tax type, Tax level, Tax rate, Tax amount, Gross Sale, Exempt, Adjustments, Taxable measure, Minutes, Lines, Sale amount

WITH -p OPTION SPECIFIED

PCode, Tax type, Tax level, Tax rate, Tax amount, Gross Sale, Exempt, Adjustments, Taxable measure, Minutes, Lines

Figure 5-29 srtrev20l SSF File Format Key without –p option

Description

Type

Country

Alpha

State

Alpha

County

Alpha

Locality

Alpha

Tax Type

Numeric

Tax Level

Numeric

Tax Rate

Numeric

Tax Amount

Numeric

Gross Sale

Numeric

Exempt

Numeric

Adjustments

Numeric

Taxable Measure

Numeric

Minutes

Numeric

Lines

Numeric

Sale Amount

Numeric

 

Figure 5-30 srtrev20l SSF File Format Key with –p option

Description

Type

PCode

Numeric

Tax Type

Numeric

Tax Level

Numeric

Tax Rate

Numeric

Tax Amount

Numeric

Gross Sale

Numeric

Exempt

Numeric

Adjustments

Numeric

Taxable Measure

Numeric

Minutes

Numeric

Lines

Numeric

Sale Amount

Numeric

 

Figure 5-31 srtrev20l CSF File Format Key

Description

Type

Length

Positions

Customer Number

Alpha

20

1-20

Tax Type

Numeric

6

21-26

Tax Level

Numeric

1

27

Tax Amount Sign

Alpha

1

28

Tax Amount

Numeric

11.5

29-39

Tax Category (optional)

Alpha

50

40-69

Base Sale Amount (optional)

Numeric

8

40-47 or 70-77

File Record Length

 

39, 47, 69, or 77

 

ARGUMENTS

-z <pkzip executable> - path to zip executable file* N or n – .csf file is unsorted

-p – add PCode to ssf file. Does not add PCode to csf file

-s – produce only the ssf. The .csf file is not created.

-pcsf – add PCode to csf file.

extra log file name – use instead of log.sum

–cl creates a combined compliance log file with a .scl extension, containing both the billable and non-billable amounts instead of a separate log file for each.

-tc adds the tax category description to the end of each line in the csf

-b adds the base sale amount to the end of each linein the csf

*The pkzip executable option is only available with the windows platform.

NOTES:

  • The Tax Rate field is sensitive to positive and negative values
  • The log.sum file is NOT created
  • WARNING - EZTax.log is DELETED. Make backups in case reruns are needed.

SAMPLE DATA

USA, , , , 55, 0, 0.136000, 2.086860, 41.360000, 26.015440, 0.000000, 15.344560, 3.5, 0, 41.36

USA, , , , 170, 0, 0.015000, 0.015000, 41.360000, 26.015440, 0.000000, 15.344560, 3.5, 0, 41.36

USA, PA, , , 44, 1, 1.000000, 1.000000, 0.000000, 0.000000, 0.000000, 0.000000, 3.5, 0, 41.36

USA, PA, ALLEGHENY, PITTSBURGH, 1, 1, 0.060000, 2.738097, 45.634953, 0.000000, 0.000000, 45.634953, 3.5, 0, 41.36

USA, PA, ALLEGHENY, PITTSBURGH, 1, 2, 0.010000, 0.456350, 45.634953, 0.000000, 0.000000, 45.634953, 3.5, 0, 41.36

USA, PA, ALLEGHENY, PITTSBURGH, 14, 1, 0.050000, 2.173093, 43.461860, 0.000000, 0.000000, 43.461860, 3.5, 0, 41.36

SAMPLE DATA WITH -p OPTION

0, 55, 0, 0.136000, 0.000000, 82.720000, 52.030880, 15.344560, 15.344560, 7.0, 0, 82.72

0, 170, 0, 0.015000, 0.000000, 82.720000, 52.030880, 15.344560, 15.344560, 7.0, 0, 82.72

3198500, 44, 1, 1.000000, 0.000000, 0.000000, 0.000000, 0.000000, 0.000000, 7.0, 0, 82.72

3206100, 1, 1, 0.060000, 0.000000, 91.269906, 0.000000, 45.634953, 45.634953, 7.0, 0, 82.72

3206100, 1, 2, 0.010000, 0.000000, 91.269906, 0.000000, 45.634953, 45.634953, 7.0, 0, 82.72

3206100, 14, 1, 0.050000, 0.000000, 86.923720, 0.000000, 43.461860, 43.461860, 7.0, 0, 82.72

See Transactions and Tax Types for descriptions of the data in the generated file.

strg.exe

COMMAND LINE

strg outputfilename <extralogfilename> [-cl]

DESCRIPTION

The srtg.exe command reads the log file specified in filelocs.txt and produces a fixed length text file outputfilename.ssf for tax compliance filing. If the extralogfilename is specified, it is used for appending instead of the log.sum.

INPUT

Reads the logfilename file as defined by filelocs.txt or EZtax Initialization Function.

log.sum – optional input from previous run

<n> - optional input superseding log.sum

OUTPUT

Fixed Length outputfilename.ssf file for tax compliance filing. Sorted and condensed by PCode, Tax Type, Tax Level, Tax Rate

FILE FORMAT KEY

Figure 5-32 strg SSF File Format Key

Description

Type

Length

Positions

PCode

Numeric

9

1-9

Tax Type

Numeric

6

10-15

Tax Level

Numeric

1

16

Tax Rate

Numeric

8

17-24

Tax Amount Sign

Alpha

1

25

Tax Amount

Numeric

11.5

26-36

File Record Length

 

36

 

ARGUMENTS

<outputfilename>

extralogfilename - optional input superseding log.sum

–cl creates a combined compliance log file with a .scl extension, containing both the billable and non-billable amounts instead of a separate log file for each.

NOTES:

  • WARNING - EZTax.log is DELETED. Make backups in case reruns are needed. Removes log.sum (or extra log)

SAMPLE DATA

0                1                  2                  3 

123456789012345678901234567890123456 

------------------------------------------------------------ 

000000000000006000003000+00098418707 

000000000000007000000580+00018387113 

000000000000018000003180+00081599822 

000000000000031000000039+00001000752 

See Transactions and Tax Types for descriptions of the data in the generated file.

upsize_log.exe

COMMAND LINE

upsize_log logfilename1.log logfilename2.log

DESCRIPTION

The upsize_log.exe command converts the short format logfilename1.log to a long format log logfilename2.log.

INPUT

First log file logfileame1.

OUTPUT

The output file produced is a log file with no format key as this is a log manipulation utility.

ARGUMENTS

None.

NOTES:

  • log.sum is NOT created.
  • EZTax.log is NOT deleted.

See Transactions and Tax Types for descriptions of the data in the generated file.

Batch File Processing

AFC allows company transactions to be taxed without directly interfacing AFC with the billing system using the batch_sau command line feature. Although system performance is excellent using the batch file processing method, it is less efficient than a direct interface in the following ways:

  1. The billing system must provide an additional function that creates the AFC batch file.
  2. AFC must read the batch-input file. With a direct interface, this is not necessary as the billing system itself will read all required data from databases or files in order to perform rating functions.
  3. The billing system must read results of the AFC process for inclusion on end customer bills and journal entries in the users accounting system.

However, this method can be the most cost effective, and provide the quickest solution to tax compliance, depending upon the billing system in use and the level of technical expertise available. This is available to both AFC SaaS Standard and AFC on-site licensed product clients.

Batch Processing Description

Refer to Figure 6-1. The Batch processing method allows for transaction information in a pre-defined fixed length ASCII formatted file to be exported to and read by the AFC engine, without directly integrating to a billing system. The formatted file is submitted to the AFC Engine using the precisely defined format shown in Section 6.2. AFC processes the file and returns the taxes in a separate fixed length ASCII file generated by one of available utilities. This file can be imported by the billing system and viewed as a spreadsheet or other compatible software. The file contains key references, keyed per transaction or per account.

AFC automatically summarizes tax data generated based upon the key passed, thereby returning unique taxes per record or summarized results per customer. This simple method of interfacing is performed with relative ease and with little programming experience.

Avalara clients that perform billing on mainframe computers have also found this method beneficial because most mainframe users utilize a batch or batch-like billing process, which allows for easy insertion of a new taxation method. The taxation step is simply replaced with an export and an import process.

When taxation is to be performed, all transactions are exported to a PC for taxation and the results are imported back into the mainframe.

Figure 6-1 AFC Batch Mode Model

image

When using the batch utility, the location of the AFC Data Base must be specified by using the filelocs.txt file. The batch utility has built in edit functions to stop any erroneous data from being submitted to the tax engine or to warn you about possible problems and still allow the transaction to be processed. An output file is generated containing warning and error messages found during the run along with the line number of the transaction.

Clients submitting CDS files in Batch fashion automatically produce an EZTax.log file. The user may select from several utilities to create a .csf file to be imported back into the billing system. Refer to Section 5.1 for aid in output utility selection.

AFC CDS Input File Specifications

The CDS fixed length input file contains one or more data records comprised of the fields detailed in the figure below. Note that a file containing this specification is provided with the monthly update.

Figure 6-2 CDF20 Client Input Data Specification

Opt/Req

Sec

Data Description

Type

Len

Positions

Defaults

Note

R

J

Origination

N

10

1-10

 

Originating NPANXX if flag=N

Originating PCode if flag=P

Originating State code if flag=S (numeric value)

R

J

Origination Flag

A

1

11

 

Set to N if using NPANXX, P if using PCode, or S if using State code

R

J

Termination

N

10

12-21

 

Terminating NPANXX if flag=N

Terminating PCode if flag=P

Terminating State code if flag=S (numeric value)

R

J

Termination Flag

A

1

22

 

Set to N if using NPANXX, P if using PCode, or S if using State code

R

J

Service Address

N

10

23-32

 

Service (BTN) NPANXX if flag=N

Service PCode if flag=P

Service State code if flag=S (numeric value)

R

J

Service Address Flag

A

1

33

 

Set to N if using NPANXX, P if using PCode, or S if using State code

R

C

Customer Type

A

1

34

B

Business, Residential Customer, Industrial, or Senior Citizen

R

T

Invoice Date

N

8

35-42

 

Format "CCYYMMDD"

R

T

Taxable Amount Sign

A

1

43

 

Format "+" , "-", “p” or ‘m”

R

T

Taxable Amount

N

11.5

44-54

 

Format "99999999999" Zero-Filled, 5 decimal places, no decimal point

R

T

Lines

N

6

55-60

0

6-character integer

R

T/S

Transaction Type

A/N

6

67-72

 

See TM_00115_AFC Transaction and Service Types

R

T/S

Service Type

A/N

6

73-78

 

See TM_00115_AFC Transaction and Service Types

R

T

Client Resale Flag

A

1

79

S

Call subject to Sale or Resale

R

C

Inc-Code

A

1

80

I

Customer is Inside or Outside an incorporated city area

R

C

Fed. Exempt

A

1

81

Blank

Call is eXempt from Federal taxes (X or blank)

R

C

State Exempt

A

1

82

Blank

Call is eXempt from State taxes (X or blank)

R

C

County Exempt

A

1

83

Blank

Call is eXempt from County taxes (X or blank)

R

C

Local Exempt

A

1

84

Blank

Call is eXempt from Local taxes (X or blank)

O

C

Customer Number (Primary Output Key)

A/N

20

85-104

 

Defines primary Key for Client Summary Data

R

CO

Regulated / Unregulated Flag

A

1

105

R

Reseller is Regulated or Unregulated in the state of sale

R

T

Call Duration (in minutes)

N

11.1

106-116

 

Format "99999999999" Zero-Filled, 1 decimal place, no decimal point

R

T

Telecom Type

A

1

117

C

C - Calls, D-Debit Card Calls, P-Point of sale

R

C

Service Class Indicator

A

1

118

D

D = Primarily Long Distance, L = Primarily Local

O

C

Lifeline Flag

A

1

119

Blank

L = Lifeline customer, N = Non-Lifeline

R

CO

Facilities Based Flag

A

1

120

N

F = Facilities based, N = Non-Facilities based

R

CO

Franchise Flag

A

1

121

N

F = Franchise based, N = Non-Franchise based

R

C

Business Class Indicator

A

1

122

C

C = CLEC, I = ILEC

J=Taxing Jurisdiction Info.; C=Customer Info.; CO=Company Info.; T=Transaction Info.; T/S=Transaction/Service type; M= Misc.; R=Required, O=Optional

 

Each field within a record contains information specific to one of four categories; Taxing Jurisdiction Identification, Company, Customer and Transaction (see the table below). These four categories are addressed in detail in the following subsections.

Table 6-1 CDF Categories

  Customer Transaction Information

Taxing Jurisdiction Identification Information

Customer Information

Company Information

Transaction Information

Origination

Customer Type

Facilities Based Flag

Invoice Date

Origination Flag

Inc-Code

Franchise Flag

Taxable Amount Sign

Termination

Fed Exempt

Regulated / Unregulated Flag

Taxable Amount

Termination Flag

State Exempt

 

Lines

Service Address

County Exempt

 

Client Resale Flag

Service Address Flag

Local Exempt

 

Call Duration

 

Customer Number (Primary Output Key)

 

Telecom Type

 

Service Class Indicator

 

Transaction Type

 

Lifeline Flag

 

Service Type

 

Business Class Indicator

 

 

Taxing Jurisdiction Identification Information

The Origination, Origination Flag, Termination, Termination Flag, Service Address (also referred to as the “bill-to” address) and Service Address Flag fields of the record are discussed in this section.

The batch interface method is designed to allow for the transaction jurisdiction service address, origination point and termination point to be entered as NPANXXs, PCodes or State Code in the first fields of the transaction record. (Note that there are advantages to using the PCode as described in Section 3.5.1.1).

NPANXXs are the first six-digits of a phone number in North America (area code and prefix). They are administered under the North American Numbering Plan and associated with locations thereby making them useful for jurisdiction identification. However, it is important to be aware that many NPANXXs serve jurisdictions foreign to the jurisdiction they are associated with.

PCodes are proprietary permanent jurisdiction codes created by Avalara that allow AFC software users to populate their databases with proper jurisdiction assignments. When jurisdiction codes change, they are re-mapped by Avalara and the PCode is updated, providing clients with up to date information without making any changes themselves. The PCode is the preferred method of assigning and maintaining jurisdiction identification, and the time invested in including PCodes into your database records will pay off with increased accuracy and reliability.

The State Code (see the cross reference table below) should be used when restricting the tax calculations to the Federal and State level. The following table provides the valid numeric State Codes for this field.  Using State Codes is discouraged as the county and locality jurisdictional information is lost and will not be applied.

Table 6-2 State Code Cross Reference Table

State

State Code

State

State Code

State

State Code

NO STATE

0

Kansas

17

North_Dakota

35

Alabama

1

Kentucky

18

Ohio

36

Alaska

2

Louisiana

19

Oklahoma

37

Arizona

3

Maine

20

Oregon

38

Arkansas

4

Maryland

21

Pennsylvania

39

California

5

Massachusetts

22

Rhode_Island

40

Colorado

6

Michigan

23

South_Carolina

41

Connecticut

7

Minnesota

24

South_Dakota

42

Delaware

8

Mississippi

25

Tennessee

43

Washington_DC

9

Missouri

26

Texas

44

District_of_Columbia

9

Montana

27

Utah

45

Florida

10

Nebraska

28

Vermont

46

Georgia

11

Nevada

29

Virginia

47

Hawaii

12

New_Hampshire

30

Washington

48

Idaho

13

New_Jersey

31

West_Virginia

49

Illinois

14

New_Mexico

32

Wisconsin

50

Indiana

15

New_York

33

Wyoming

51

Iowa

16

North_Carolina

34

 

 

Origination

The Origination location of the transaction to be taxed. For telecom activity, this is usually specified by the number called from, also known as the “From Number” or “Origination number). It can be filled with the NPANXX, PCode or State Code.

Origination Flag

The Origination Flag specifies the configuration of the information in the Origination field. This field should contain N if the Origination is in NPANXX format, P if the Origination is in PCode format and S if the Origination is in State format.

Termination

The Termination location of the transaction to be taxed. For telecom activity, this is usually specified by the number called, also known as the "To Number" or the "Termination number." It can be filled with the NPANXX, PCode or State Code.

Termination Flag

The Termination Flag specifies the configuration of the information in the Termination field. This field should contain N if the Termination is in NPANXX format, P if the Termination is in PCode format and S if the Termination is in State format.

Service Address

The Service Address of the transaction to be taxed. For telecom activity, this is usually specified by the number that the call was billed to (also know as the Bill To Number or BTN) or the location of service. It can be filled with the NPANXX, PCode or State Code.

Service Address Flag

The Service Address Flag specifies the configuration of the information in the Service Address field. This field should contain N if the Service Address is in NPANXX format, P if the Service Address is in PCode format and S if the Service Address is in State format.

Customer Information

The transaction customer information is supplied using the following fields; Customer Type, Inc-Code, Fed Exempt, State Exempt, County Exempt, Local Exempt, Service Class Indicator, Lifeline Flag, Federal Exemption JCode, State Exemption JCode, County Exemption JCode, Locality Exemption JCode, Invoice Number, Service Level Number and Business Class Indicator.

Customer Type

This field is used to specify the type of customer involved in the transaction. The Customer Type is selected from one of the following four options.

  1. Business - When transactions are made at a place of business.
  2. Residential - When transactions are made by a customer for home use.
  3. Industrial - When transactions are made at an industrial business.
  4. Senior Citizen - When transactions made by a customer meeting the jurisdiction requirements to be considered a senior citizen and qualify for senior citizen tax breaks.
Inc-Code

The Inc-Code field is used to specify whether the customer involved in this transaction is inside (specified with an “I” in the one character length field) or outside (specified with an “O” in the one character length field) of the incorporated area designated as their location. The tax may or may not be affected by this designator depending upon whether or not the unincorporated areas are taxed in the same manner as the incorporated areas.

Exemption Levels

The exemption level is the jurisdictional level of the taxing authority that defines the tax. It is used to exempt taxes at specific federal, state, county and/or local taxes.

Fed Exempt

The Federal Exempt field is used to specify a Federal level tax exemption.

State Exempt

The State Exempt field is used to specify a State level tax exemption.

County Exempt

The County Exempt field is used to specify a County level tax exemption.

Local Exempt

The Local Exempt field is used to specify a Local level tax exemption.

Customer Number (Primary Output Key)

The Primary Output Key (POK) is a 20-character text field that is not manipulated during processing and stored as part of the log file record.

It can be used as part of the sorting key (see Figure 6-3) when using some utilities, allowing for the combining of records based upon this and other fields. It is useful when it is desired to have like taxes from different transactions combined, to have taxes from each transaction detailed individually in a report or to have each transaction detailed at the customer level.

Figure 6-3 Primary Output Key

Image_Uniquekey_cds.png

uniquekeyCSF

Combined taxes 

If you would want like taxes combined at the customer level, then you specify a like POK for the records you want combined. 

Image_Samekey_cdf.png

SamekeyCSF

Service Class Indicator

The Service Class Indicator is provided to delineate the Primary activity of an organization as either Long Distance or Local Service.

The service class only impacts Telecom transactions in certain jurisdictions, such as New York.

NOTE: This has no effect on non-Telecom Transactions.

Service Class

ID

Value

Description

0

Local (Default)

Primary Local Service providers are carriers vending their services with over 50% of the gross business activities in Local Service revenue.

1

Long Distance

Primary Long Distance providers are carriers vending their services with over 50% of the gross business activities in Long Distance revenue.

Lifeline Flag

The Lifeline Flag is used to indicate if a customer is a Lifeline participant.

Lifeline Flag

Value

Description

True

Has the effect of turning off the calculation of taxes that are not collected from Lifeline recipients.

False (Default)

Collects all taxes.

Business Class Indicator

The Business Class Indicator field is used to specify if the business making the transaction is an Incumbent Local Exchange Company (ILEC) or a Competitive Local Exchange Company (CLEC).

  • An ILEC company is engaged in selling services over company owned lines and equipment,
  • A CLEC company is engaged in selling services competing with an incumbent provider.

Company Information

The transaction information is contained in fields found in the transaction record. The Company Identifier, Facilities-Based Flag, Franchise Flag and Regulated/Unregulated Flag are discussed in this section.

Facilities Based Flag

The Facilities Based flag specifies whether the transaction is sold over tangible facilities controlled by the seller. If the seller delivering the service owns or controls the facilities used to provide the service, then the seller is facilities based. If the seller does not own or control the facilities, the seller is non-facilities based. In some jurisdictions, tax outcomes will vary depending on whether the service is delivered over infrastructure controlled by the seller.

Franchise Flag

The Franchise flag indicates that the company provides services sold pursuant to a franchise agreement between the carrier and jurisdiction. This designation applies to the Seller.

Note: Marking the transaction as Franchise = False will often result in no franchise fees or taxes being returned.

Franchise Flag

Value

Description

True (Default)

Seller has a franchise agreement with jurisdiction.

False

Franchise fees and taxes do not apply to seller.

Regulated / Unregulated Flag

The Regulated / Unregulated flag is used to specify if the Telecommunication company and its services are regulated by the Public Utility Commission, the Federal Communication Commission and/or other government authorities.

Unless the seller is registered with the state regulatory commission as a rate-regulated, incumbent provider, all transactions should be Regulated = False.

Field

Value

Description

Regulated Flag

True

Company is rate-regulated

False (Default)

Company is not rate-regulated

Transaction Information

The transaction information is contained in fields found in the transaction record. The Invoice Date, Taxable Amount Sign, Taxable Amount, Lines, Client Resale Flag, Call Duration and Telecom Type fields of the record are discussed in this section.

Invoice Date

The Invoice Date is normally populated with the bill date. Generally accepted accounting principles dictate that liabilities should be recorded when revenues are recorded. In most cases, neither of these is recorded (or even known) until billing occurs.

However, companies with a high call volume that record revenue daily as it occurs should record the tax on the same basis (i.e. the call date should be used).

AFC compares this date to the effective date of each tax that applies to the transaction.

  • If the date passed to AFC is "equal to" or "greater than" the effective tax date, the current tax rate is used.
  • If the date passed to AFC is prior to the effective date, the tax rate in effect for the tax is used to generate the tax amount applicable to the transaction.
  • If a transaction is passed to AFC without a date (that is, the date is set to zero), AFC will set the date to the current date.

Note: The invoice date passed to the server in the transaction by default is preserved as is. It is recommended that clients not use time zone modifiers on the invoice date.

Taxable Amount Sign

The Taxable Amount Sign field is filled with either a “+” (plus) sign to indicate a charge or a “-“ (minus) sign to indicate a refund or credit. In addition, the letters “p” (plus) and “m” (minus) are respectively used to indicate the appropriate refund or credit on tax inclusive calculations.

Taxable Amount

The Taxable Amount field specifies the amount of the transaction to be taxed. This amount will be passed through AFC to rate the tax based on the specified transaction/service pair. In addition, when peforming a tax inclusive calculation, the taxable or charge amount entered by the user must reflect the desired total charge plus the total tax returned (i.e. revenue plus total tax).

Lines

When local service is provided, a transaction should be generated with the Lines field populated with the number of lines the customer subscribes to. AFC uses this information for generation of per line taxes usually associated with local E911 charges and local telecommunications relay service taxes and other assorted taxes.

Transaction Type

Refer to Section 2 Mapping for details of this field.

Service Type

Refer to Section 2 Mapping for details of this field.

Client Resale Flag

Telecommunication companies are taxed on transactions made by their clients, which in some cases can be passed on or “resold” to their customers in part or in total. The Client Resale (wholesale) flag is used to indicate whether the product or service transaction is final or if it is to be resold.

To have exempt taxes available for reporting, exemption type 3 (Sales For Resale) should be used in combination with Resale.

Call Duration

The Call Duration Field specifies the length of phone call in minutes, with one tenth of a minute precision capability. AFC uses this field for generation of taxes that are specified as per minute flat fees in some taxing jurisdictions and stores the value in the AFC log database.

Telecom Type

The Telecom Type field specifies the type of telecom transaction. Enter D for Debit calls, P for Point of Sale or C for a normal call.

It is possible to see both the sale transaction and service usage with one entry in the batch system by using the “P” Telecom Type flag. In this case, the system will put the same dollar figure through the AFC engine using the transaction/service pair 10/32 followed by the 01/01 T/S pair. Since it is unlikely that the customer will use the entire prepaid service on a single long-distance call, this is best used for an approximation on what the telecom taxes will be.

Federal or State Exclusion

The Federal or State Exclusion option allows the EZTax_20 user to prevent federal and/or state (or province) and all lower jurisdictions including county, and local taxes from being created for Call Detail Records (CDRs) from specified countries or states. If excluding a state, the Federal taxes will be calculated from CDR records that have been designated for state exclusion. If excluding a country, no taxes, including federal taxes, will be calculated.

When running AFC in batch fashion it checks for the exclude.txt file. If the file exists, the state and country jurisdictions listed in the file will be excluded. For state exclusions, state, county and local taxes are excluded. For country (federal) exclusions, country, state, county and local taxes are excluded.

If the file does not exist, the plain ASCII text file “exclude.txt” federal/state exclusions file can be created. Please reference Section 1.5 Exclusion Configuration File in the AFC Manager User Manual for additional details and instructions on creating exclusion files.

Accumulating the Log

For AFC users that run using the batch processing to do billing daily, the EZTax.Log needs to be accumulating to run the sorting utility at the end of the month to create a tax compliance file.

Daily:

  1. Run the taxation on *.CDF file. 
  2. Archive the EZTax.Log file to another location on the system. 
  3. Run the sorting utility executable. *.CSF is used for current client billing. The optional *.SSF file is intended for end of the month tax compliance filing and can be ignored if generated. 
  4. The next taxation run of the *.CDF file will produce a new EZTax.Log file when using some utilities since it has been emptied by the previous sorting utility. 

Monthly:

Avalara supplies the EZTaxappend and extaxappendf executable utilities that can be used to combine logs into a single monthly log file. At the end of the month, select the utility that best fits your requirements and combine the appropriate achieved log files. This will produce the tax compliance file .ssf file. The optional .csf file is intended for use by billing clients and can be ignored if generated.

EZTax_20 Utility Specification

COMMAND LINE

EZTax_20 inputfilename.cdf [-d] [-vrpt [reportname.csv]] [-?]

DESCRIPTION

The EZTax_20 command is a processing utility designed to accept records submitted in batch fashion. Records are supplied as an ASCII formatted file inputfilename.cdf.

INPUT

Reads the inputfilename.cdf ASCII text file

OUTPUT

EZTax.Log - as defined by filelocs.txt.

read_err.st - any errors found while editing input file are reported here. billing.log - date/time stamp log (appended to).

bureau_log - run totals (appended to).

EZTax.sta – status from AFC engine

inputfilename.rpt - break down by totals (not for compliance filing).

reportname.csv – validation report, by default named inputfilename.csv

FILE FORMAT KEY

Refer to Figure 6-2.

ARGUMENTS (in any order)

input filename : The cdf file with input records

-d : Indicates to use default transaction/service types

-vrpt [reportfile] : Create a comma delimited validation report. This report will show each cdf line input with what API call was made along with any remarks or errors. A sample is included in Figure 6-x.

-? : Print help screen and exit

NOTES:

  • The transactionservice.exp file must be in the AFC working directory.
  • EZTax.log is not deleted.
  • Filelocs.txt MUST be in the working directory.

Deprecated CDF20 File Structure

Figure 6-4 CDF20 File Structure for Deprecated Input File of Version 8

image

Figure 6-5 Data Specification for Deprecated Input File of Version 8

Data Description

Type

Len

In Client CDRFile

Positions

Defaults

Note

Origin

N

10

Yes

1-10

NPANXX if flag=N

P code if flag=P

State code if flag=S

NPANXX (Area Code+ Exchange)

Origin Flag

A

1

 

11

 

N-origin is NPANXX

P-origin is npermkey

S-origin state abbreviation

Termination

N

10

Yes

12-21

NPANXX if flag=N

P code if flag=P

State code if flag=S

Area Code+ Exchange (N) or npermkey (P) or state abNumber

Termination Flag

A

1

 

22

 

N-termination is NPANXX

P-termination is npermkey

S-origin state abbreviation

Service Address

N

10

Yes

23-32

NPANXX if flag=N

P code if flag=P

State code if flag=S

Customer NPANXX

Service Address Flag

A

1

 

33

 

N-origin is NPANXX

P-origin is npermkey

S-origin state abbreviation

Customer Type

A

1

Yes

34

B

Business or Residential Customer

Invoice Date

N

8

Yes

35-42

 

Format "CCYYMMDD"

Taxable Amount Sign

A

1

Yes

43

 

Format "+", "-", “p” or “m”

Taxable Amount

N

11.5

Yes

44-54

 

Format "99999999999" Zero-Filled, 5 decimal places, no decimal point

Lines

N

6

Yes

55-60

0

6-character integer

Transaction Type

A/N

6

Yes

67-72

 

See TM_00115_AFC Transaction and Service Types

Service Type

A/N

6

Yes

73-78

 

See TM_00115_AFC Transaction and Service Types

Client Resale Flag

A

1

Yes

79

S

Call subject to sale or resale

Inc-Code

A

1

Yes

80

I

Customer is Inside or Outside and Incorporated Locality Area

Fed. Exempt

A

1

Yes

81

Blank

Call is eXempt from Federal taxes

State Exempt

A

1

Yes

82

Blank

Call is eXempt from State taxes

County Exempt

A

1

Yes

83

Blank

Call is eXempt from County taxes

Local Exempt

A

1

Yes

84

Blank

Call is eXempt from Local taxes

Primary Output Key

A/N

20

Yes

85-104

 

Defines primary Key for Client Summary Data

Regulated / Unregulated Flag

A

1

 

105

R

Reseller is Regulated or Unregulated in the state of sale

Call Duration

N

11

 

106-116

 

Format "99999999999" Zero-Filled,

1decimal places, no decimal point

Telecom Type

A

1

 

117

C

C - Calls, D-Debit Calls, P - Point of Sale

 

 

 

 

 

 

 

File Record Length*

 

 

 

117

 

 

 

 

 

 

 

 

 

* Each record Must terminate with a CR (ASCII 13) and LF (ASCII 10) located at positions 118 and 119 respectively.

 

 

Do not append an end-of-file character (ASCII 26) to the end of the Client Input Data File.    

The C/C++ API

The software for AFC is written in C/C++ and is delivered as an executable, creating a flexible programming environment. The AFC engine operates independently from the client’s billing system allowing it to be easily integrated using APIs. Making use of the AFC API functions is the most efficient interface to the AFC Engine and there is very little performance difference when running the AFC taxation generation.

To integrate with AFC, programmers simply link with it and interface through a standard and well documented set of API calls. Programmers can typically perform the integration of AFC with a billing system by utilizing the documentation. If questions should arise, Avalara provides unlimited phone support for the integration of AFC and provides consulting services if desired.

Many AFC clients have accomplished integration in a matter of days and indicated that the effort with their previous system took from three months to a year. Many companies spend multiples of the yearly license cost to integrate with competing products, enduring long periods of inoperability during the integration process. The product is delivered as a DLL, shared library or shared executable allowing upgrades and enhancements of AFC to be accomplished by simply replacing a file.

Furthermore, the AFC API provides a rich and complete set of interfaces for taxation. In addition to taxation APIs, it provides the ability to do adjustments, refunds, debits, prepaids, overrides, jurisdiction information conversions and database interfaces. The APIs allow taxation using jurisdictional information provided by jurisdiction codes, NPANXX, address and zip codes.

AFC API calls are descriptively named for easy identification and selection. For instance, functions that end with “JCode” or “J” are Jurisdiction Code functions. Similar naming standards are maintained for the “PCode,” “NPAN” and “Zip” functions.

Language Interfaces for AFC

AFC is written in C/C++ code. Interfaces to other software languages are provided that add another DLL for the translation from C/C++ to that other language.

AFC supports interfaces to Java, the Microsoft .NET family, RPG, COBOL and Microsoft VB6.

Configuration

Avalara offers all programs and file updates through a client login site, allowing for the download of a zip file containing the installation or update files. After an order is processed, the download zip file will be placed in the company’s user folder. Check this folder regularly for new downloads, updates and announcements about Avalara’s products and services.

The install wizard suggests a default file folder organization (refer to the AFC Installation Manual). Avalara encourages the use of the default settings to simplify the monthly update procedure. Changing the default settings will require a modification of each monthly update in order for it to it to adhere to the modified file folder organization, increasing the possibility of errors and poor performance.

The include files (header files) directory and the lib file must be incorporated into the C/C++ compiler and linker and the appropriate include files must be added to your source code to access the Avalara constants and structures. These files are in the same folder as the DLL.

Filelocs.txt File

AFC installs the Filelocs.upd file. This file must be moved to your working directory and renamed to filelocs.txt. Windows Explorer should be set to show file extensions so that there is no confusion between the two files. The Filelocs (File Locations) file (see Table 7-1) contains the paths to the files used by AFC.

Table 7-1 Filelocs.txt Example

PATH

DESCRIPTION

C:\BillSoft\EZTax\Data\EZTax.dat;

INPUT:  EZtax Data file

C:\BillSoft\EZTax\Data\EZTax.idx;

INPUT:  EZtax IDX file

C:\BillSoft\EZTax\Data\EZTax.dll;

INPUT:  EZtax DLL file

EZTax.log;

I/O:  EZtax log file

C:\BillSoft\EZTax\Data\EZTax.npa;

INPUT:  EZtax NPANXX cross reference file

EZTax.sta;

OUTPUT:  EZtax status file

tmp77777.dat;

I/O:  EZtax temporary file

C:\BillSoft\EZTax\Data\EZDesc.dat;

INPUT:  EZtax location description file

C:\BillSoft\EZTax\Data\EZZIP.dat;

INPUT:  EZtax ZIP Code file

C:\BillSoft\EZTax\cust_key;

I/O:  EZtax customer key file

C:\BillSoft\EZTax\Data\EZTax.pcd;

 

C:\BillSoft\EZTax\Data\EZTax.jtp;

 

Filelocs.sta File

The Filelocs.sta file will be created by EZTaxInitEx when the file paths are not provided or incomplete, and if EZTaxInitEx cannot find Filelocs.txt in the current working directory. The directory where Filelocs.sta is created is the working directory that AFC is using, and this is where Filelocs.txt should be placed. Copy the Filelocs.upd file that is distributed with the AFC monthly update, rename it to Filelocs.txt, edit the locations to match your configuration, and rerun your application.

AFC produces two .sta files:

  • filelocs.sta
  • EZTax.sta

In addition, the utilities can produce:

  • log_file.sta
  • read_err.sta

All the files except EZTax.sta are normally zero length. Any other size indicates a problem. Refer to Table 7-2 for an example of the output in EZTax.sta.

Table 7-2 EZTax.sta Example

4/17/07 14:21:38.806 <Info>: EZtax Version Number: 9.0.0.5, platform = Windows! 

04/17/07 14:21:38.806 <Warning>: Configuration line >notranslog=off< not recognized. 

04/17/07 14:21:39.572 <Info>: Tax override shown below inserted successfully 

04/17/07 14:21:39.572 <Info>: 0, 87, 0, 0 

04/17/07 14:21:39.572 <Info>: 20060801, 1, 1 

04/17/07 14:21:39.572 <Info>: 5.500000, 2147483647.000000 

04/17/07 14:21:39.572 <Info>: 19000101, 1, 1 

04/17/07 14:21:39.572 <Info>: 4.500000, 2147483647.000000 

04/17/07 14:22:09.307 <Info>: PCODE file closed, 0 PCODE records not found 

04/17/07 14:22:09.307 <Info>: JCODE file closed, 0 JCODE records not found 

04/17/07 14:22:09.307 <Info>: Closing AFC Session 334260 

General Overview of AFC API Integration

When integrated using the C/C++ APIs, the AFC Engine operates independent of the client’s billing system giving the client more options. The engine is designed to allow passing of data through the program rather than integration with the client’s billing system.

Refer the figure below. With the Application Programmer Interface (API), the billing system passes transaction information to the AFC Engine as it is being rated for billing. AFC accepts the transaction information, calculates all of the required taxes and returns the generated tax information to the billing system.

Figure 7-1 AFC API Model

image

Refer the figure below. In addition to calculating and generating tax information, the AFC Engine can store all of the generated tax data in AFC database log files. Utilities are provided for performing data manipulation and generating reports that facilitate tax filing and provide insight to the rating, billing and taxing processes.

Figure 7-2 AFC Engine

EZTaxEngine

Detailed Discussion of AFC API Integration

Avalara provides a multi-threaded dynamic link library that is utilized to interface with AFC. Integration of an API interface opens the full capabilities of AFC.

Refer to Figure 7-3. The AFC Engine primarily accepts transaction information from the customer billing system and returns the taxes associated with the transaction. However, it can also be used to perform the following functions:

  1. Perform tax adjustments. 
  2. Supply Jurisdiction information and JCodes based on address, Zip Code or NPANXX information. 
  3. Supply Jurisdiction information, address information, and convert JCodes to PCodes and PCodes to JCodes. 
  4. Return Tax information based on Transactions. 

Tax Adjustments

Adjustment information is returned to the billing system and is utilized to update tax data for report generation and compliance filing. AFC also provides facilities that allow users to insert tax overrides and exempt a transaction from taxes at federal, state, county and local authority levels. In addition, AFC also provides the capability to limit exemptions to a specific jurisdiction and to exempt specific taxes.

Obtaining Jurisdiction and Address Information From JCodes and PCodes

Another option allows AFC to determine the taxing jurisdiction. After adding PCodes to the customer record, use the NPANXX to PCode conversion function to obtain PCodes for the NPANXXs associated with the TO and FROM numbers. AFC can use these PCodes, along with the PCode representing the “Bill To Number,” to perform tax calculations by passing the PCodes to AFC using the EZTaxPCodeEx function. In most cases it is acceptable and proper to use the PCode for a customer’s address as the “Bill To Number”. This can be helpful in cases where the BTN (Bill To Number) is not available in the CDR (Call Detail Record) source.

Obtaining Jurisdiction and Address Information From JCodes and PCodes

The AFC Address Database is available to obtain the address of a specific JCode or PCode. This is normally not used during the AFC session as the billing system normally has address information required for billing. AFC uses this database when generating reports for tax filing. The Address Database interface is provided as a valuable tool to Avalara customers.

Obtaining Tax Information From Transactions

AFC accepts transaction information and returns taxes to the Customer Billing System. Refer to Section 3 Transactions for a detailed description of this process.

Figure 7-3 AFC API Operation Diagram

image

Preparing the AFC Application Programmer Interface (API) Interface

This section defines the steps required to interface AFC directly with a billing system. With this interface, the billing system passes transactions to AFC as they are being rated or billed. AFC calculates all required taxes and returns the tax information to the billing system per transaction. In addition, AFC stores all tax data generated in its databases and provides reports that facilitate tax filing and provide insight to the telecommunications rating, billing and taxing processes.

AFC functions are included in the dynamic link library EZTax2.lib. To access AFC functions, this library must be accessible when building the executable for the billing system at either link or executable build time. When using the DLL, EZTax2.dll must be in a location that will allow the system to load the DLL.

To use the Avalara’s AFC Engine in a C or C++ code environment, the include file directory and the lib file must be incorporated into the client C/C++ compiler and linker.

  1. The include file directory is in the same folder as the dll found at C:\BillSoft\EZTax\dll if you installed using the default directory. Add this folder to the include folders for your C++ compiler.
  2. Add the following include files located in the dll folder to your source code in order to access the Avalara constants and structures.
    1. EZTaxStruct.h - Provides data structures required to interface with AFC. Refer to Public Header and Modules for the detailed structure.
    2. EZTaxDefine.h, EZTaxTransType, EZTaxServType, EZTaxTaxType.h, EZTaxServType.h, EZTaxCountryType.h, EZTaxStateType.h - Provides data constants required to interface with EZtax. Refer to Public Header and Modules for the detailed structure.
    3. EZTaxProto.h - Contains function prototypes. Refer to Public Header and Modules for the detailed structure.
  3. Add the selected include files and the lib file to your project file list if you wish to use editing tools such as Microsoft Visual Studio to perform code completion based on the structure members.

NOTE: If you include the EZTaxProto.h file in your source code it will include the EZTaxStruct.h and the EZTaxDefine.h.

AFC API Function Calls

An AFC session is started with a call to one of the initialization routines (EZTaxInitEx or EZTaxInitExMT, usually) to initialize the task. APIs are called to perform specified AFC functions that achieve the desired results of the session.

Once all transactions are completed, EZTaxExitSessionEx must be called for each session started to flush database buffers, de-allocate memory and perform other clean-up duties which free up resources utilized by AFC. Sessions must be completed by a call to EZTaxExitSessionEx at least once per tax filing period to insure that the tax log is properly configured and complete before utilities that generate filing information are started.

Retrieving Taxes

The AFC Tax Table

The AFC table is allocated during AFC session initialization. The size of this table is dependent upon the maximum taxes that can be generated for a single transaction. As such, the size of this table can change from month to month as new taxes are generated or removed from taxing jurisdictions. It is always safe to access from 0 (zero) to [tax_count_returned -1] locations of the table. The user is cautioned to treat this as a read only area. Attempting to access locations that do not exist will result in access violations on most operating systems.

Each function that performs tax calculations or adjustments returns a count of the taxes generated for the transaction and stores the taxes in the Tax Table. The taxes can be retrieved for storage in a billing system by using the taxes_tbl struct pointer, which is activated when EZTaxInitEx is called. The pointer to the AFC table can be used to select a tax from the array of taxes_tbl objects using the following code.

{ 
    int index; double tax; 
    tax = EZTax_table[index].tax_amount; 
}
Sample Code to Retrieve Taxes

To retrieve taxes generated, the following code segment (shown without proper status checking) can be used with the DLL:

#include <BillSoft/EZTaxDefine.h> 
#include <BillSoft/EZTaxProto.h> 
#include <BillSoft/EZTaxStruct.h> 
main() 
{ 
    short int i; 
    short int tax_count; 
    int err_code; 
    double tax; 
    struct enhanced_taxes_tbl *EZTax_table; 
    struct sau_J_Code transaction; 
    EZTaxSession session; 

    EZTax_table = EZTaxInitEx(FALSE, NULL, &session); 

// initialize the transaction here 

    tax_count = EZTaxSAUJCode(session, &transaction, NULL, 0, &err_code); 
    if (tax_count > 0) 
    { 
        for(i=0; i<tax_count; i++) 
        { 
            tax = EZTax_table[i].tax_amount; 

// Perform billing system task or store tax data 
        
        } 
    } 
    EZTaxExitSessionEx(session); 
} 

Multi-Threading

A user can process multiple sessions in separate threads (referred to as multi-threading) with AFC. This technique increases the processing speed and efficiency of the client billing system because each thread can start an independent AFC session and call the specified AFC functions.

For example, if there is a requirement to compute a customer’s taxes on calls and services, and also to offer tax quotes, then one session can be setup with tax logging turned on to calculate the customer’s bills while another session is established with tax logging turned off to offer tax quotes without the results being logged.

Another example would be to allow the client’s billing system to process more than one customer base on the same run, with each customer base using a separate session. In addition, the capability exits to specify that each session will have a unique tax log in order to produce separate logs at session start up.

The latest in version 9

The latest version of AFC 9 features enhanced support for applications that use AFC in a multi-threaded environment. Applications that want to take advantage of this new support should adhere to the following guidelines:

  • AFC supports concurrent processing on separate threads by assigning each thread its own EZTaxSession object. Usage of the same EZTaxSession by multiple threads is not supported and will result in unpredictable and erroneous tax calculations.
  • Each separate EZTaxSession object should have a unique AFC log file if tax logging is enabled for that session.
  • Each separate EZTaxSession object should have a unique status file.
  • When opening AFC, use the new “EZTaxInitExMT” method. Users who previously initialized AFC using EZTaxInitEx will have one additional parameter to provide - a string that contains the directory name to be used as the AFC Default directory. If this string is NULL, AFC will continue to look in the Working Directory of the application for EZTax.cfg and filelocs.txt. Otherwise, AFC will search the supplied directory name for EZTax.cfg and filelocs.txt.
  • When an AFC Session is no longer needed, be sure to call EZTaxExitSessionEx with the AFC Session object obtained from EZTaxInitExMT. Sessions that are opened with EZTaxInitExMT will not be closed when EZTaxExit is called, and failure to call EZTaxExitSessionEx will result in a memory leak.
  • Certain functions will not work if a session is created with EZTaxInitExMT. These include EZTaxGetHandle, which translates an EZTaxSession object to an integer handle. Since the corresponding handle is not created by AFC when using the new EZTaxInitExMT method, functions that take an integer handle argument cannot be used against a multi-threaded session.
  • Other functions that take no handle or session object are also not supported, including:
    1. EZTaxPtoFips (use EZTaxPtoFipsEx)
    2. EZTaxNtoJCode (use EZTaxNtoJCodeEx)
    3. EZTaxJtoPCode (use EZTaxJtoPCodeEx).

    When sessions have been initialized by EZTaxInitExMT, an attempt to use these functions will return an error code and will not work.

  • A new function has been added to AFC so that sessions created by EZTaxInitExMT will have the functionality of AFC without resorting to an integer session handle. EZTaxOldOvrJCode allows users to use the old override structure with an EZTaxSession object.

Users that start all their sessions before any separate threads are started and before any tax calculations are performed can continue to use EZTaxInitEx, or the new function EZTaxInitDirEx. EZTaxInitDirEx provides the name for the Default AFC directory, exactly like EZTaxInitExMT. Neither of these functions is thread-safe, but the subsequent processing against the EZTaxSession objects created by these functions is thread-safe.

If one or both of these non-thread-safe functions are used to initialize all EZTaxSession objects, EZTaxExit will continue to close any open EZTaxSession objects without the need for a specific call to EZTaxExitSession for each EZTaxSession object.

Multiple Sessions

When using the APIs, a session is started with a call to EZTaxInitExMT. Successive calls to EZTaxInitExMT will initialize additional sessions, thereby accomplishing multi-threaded operation.

AFC writes compliance information to the EZTax.log file. The compliance logging function can be enabled or disabled with each session and each session controls its own log file. The Log records are kept in the memory to improve the efficiency and are written to the disk periodically. Several techniques can be used to control when the log is written to disk, although many applications do not need any special handling of the compliance log.

Overrides may be used with multiple sessions as each session will maintain its own overrides. The override can be specified by JCode, PCode, NPANXX and Zip Code. Since each session has its own override, the user can remove the override from a session by using the call EZTaxRestoreEx.

Each Session must have a separate Log File

Each Session should have a separate temporary File - and this is required if that session applies overrides to the tax table

Session Management

Several functions call EZTaxGetHandle to create session handles into memory pointers. Utilizing the session handle from the memory improves operating efficiently. The session handle references AFC sessions. It is a long integer that is pulled from a stack of unused session handles setup during the EZTaxInitEx call.

EZTaxInitEx returns a void pointer type to the session memory and is defined as EZTaxSession. Each time a session is initialized through EZTaxInitEx the session pointer is placed on a dynamically allocated stack.

The File Path structure (see Public Header and Modules) provides the ability to override any file path specified in the filelocs.txt configuration file programmatically. A subset of the paths can be overridden by specifying “NULL” for paths where the default is to be maintained. An address to this structure can be specified when initializing a session with EZTaxInitEx.

General Tips to Maintain Session Efficiency

When using sessions to make calls to the database, it is important to maintain the performance level between the billing system and the AFC engine.

The following tips have been accumulated to assist users in maintaining session efficiency.

  1. Some calculations, such as requests for quotes from the Sales department, might not be appropriate to log to the compliance files. Open a separate session for quotes with no logging to achieve this.
  2. If calculations have special tax rates that require an override of the AFC database, open a separate session (with a separate log file and temporary file) for the override calculations.
  3. If the application terminates all sessions at the end of a billing cycle, the normal session completion will save all of the compliance data to the disk.
  4. The EZTaxFlushToLogEx API can be used if more control of the log file is needed. Some specialized applications call EZTaxFlushToLogEx after every call to one of the tax calculations, to ensure that the disk copy of the log is always completely up-to-date.
  5. Using the EZTaxExitSessionEx to control the log will close the session and save the compliance data to the log. If all sessions are complete then EZTaxExit will perform the same function for each session open.
  6. Higher efficiency levels are obtained if you have sufficient memory (approximately 10 MB per session) to "CACHE_ALL." Using the memory CACHE improves the processing speed many times over.
  7. The maximum number of sessions is 500.
  8. If multiple users want to perform tax calculations simultaneously (such as a Web application) then use Session Pooling (Refer to 7.6.5).

Session Pooling

Session pooling is a resource managing tool that allows for multiple sessions to be held in a “pool” where each can be checked out, processed and returned one at a time.

It is modeled after the office "steno pool" where instead of assigning a stenographer to a department, a department would request one from the pool. The stenographer would leave, take the dictation and return to the pool waiting for the next call. The concept was that a company might have only 5 stenographers, but 20 departments that needed stenography service. If 20 stenographers were hired, they would probably be sitting around with no work for 75% of the work day. The drawback is that sometimes all 5 will be checked out of the pool, and a department will have to wait for a stenographer to return.

Session pools work in exactly the same manner. A transaction comes in that needs to be processed, a session is grabbed from the pool, the session processes the transaction, and the session is returned to the pool. If a second transaction comes in before the first transaction has completed, it gets the second session from the pool. The AFC Web service has multiple sessions in the session pool to handle about 20 customers of AFC SaaS Pro.

The application should be structured in the following manner:

  1. Create the number of sessions required.
  2. Store the session handles in a memory table with a “use flag.”
  3. When a tax calculation is required, search the table to find a handle that is not in use.
  4. Set the use flag to on indicating the session is “in use”.
  5. Perform the tax calculation.
  6. Set the use flag to off, indicating the session is “not in use”.
General Tips When Using Session Pooling

The following tips have been accumulated to assist users when using Session Pooling.

  1. Periodically call EZTaxFlushToLogEx on each session to update the EZTax.log for each open session.
  2. If there are more than 10 concurrent users the pool of sessions can be permitted to grow dynamically for greater flexibility.
  3. The use of Invoice Mode and overrides is prohibited since the session obtained for the next transaction is unknown. Invoice Mode could be used if the session was held for all of the customer's transactions.

Sample Coding

The following sample code listings have been accumulated to assist users in performing specific tasks.

Using EZTaxGetRates to Build an Override

The Get Rates function can be used to accomplish an override using the following steps.

  1. Call EZTaxGetRates with the desired PCode for the jurisdiction
    Call objEZTax.EZTaxGetRates(glHandle, OLATHE_PCODE, taxes)
  2. Search the taxes Table returned in the Jurisdiction Data to find the desired Enhanced Override for your tax type and tax level. This example searches for the state sales tax.
    overrides = taxes.taxesTable 
    For i = 0 To taxes.taxesCount - 1 
        If (overrides(i).Type = SALES_TAX) And (overrides(i).level = STATE_LEVEL) Then 
            Call printMessage("Found State Sales Tax") 
        Set stateSalesTax = overrides(i) 
        foundSalesTax = True 
        End If 
    Next I 
    
  3. Using the Enhanced Override object found, make the appropriate changes
    If foundSalesTax Then 
        effectiveDates = stateSalesTax.dateTable 
        Set currentEffectiveDate = effectiveDates(0) 
        rates = currentEffectiveDate.rateTable 
        Set currentRate = rates(0) 
        currentRate.tax = 0.04 
    
  4. Apply the override to AFC
        Call objEZTax.EZTaxOvrJCodeEx(glHandle, OLATHE_JCODE, stateSalesTax) 
        Call printMessage("Rate changed to 4%") 
    End If 
    

API Listings

APIs Listed By Function

Sorted by Function

Description

Session Management Functions

The following functions support session activity.

EZTaxInitEx

Initializes an AFC Session.

EZTaxInitExMT

Initializes an AFC Multi-session. Multiple calls may be made to set up completely different sessions.

EZTaxInitDirEx

Reads AFC files and initializes the AFC system. Multiple calls may be made to set up completely independent sessions.

EZTaxInitV914

Reads AFC files and initializes the AFC system. Multiple calls may be made to set up completely independent sessions.

 

The input structure allows all optional input files to be specified through the initialization method. This method does not use filelocs.txt and will ignore exclusion, nexus and bundle file settings in EZTax.cfg.

EZTaxInitV98

EZTaxInitV98 reads AFC files and initializes the AFC system. It differs from EZTaxInitExMT in that the tax table returned includes tax category information.

EZTaxClearExclusion

Removes all exclusions that have been set

EZTaxClearTSR

Allows API functionality to delete the data created by EZTaxGetTSR.

EZTaxConvertExemption

Convert tax exempt struct to form usable by engine.

EZTaxExitSessionEx

Exits an AFC Session.

EZTaxExit

EZTaxExit insures that all internal buffer contents are stored on disk, memory allocated by the system is deallocated and that databases are properly closed.

EZTaxSetWorkingDir

Used to define a directory as the working directory.

EZTaxStart

Declares and initializes the session.

EZTaxStartEx

Declares and initializes the session.

EZTaxSetLogName

Allows applications API functionality to set just the log instead of all the data files.

EZTaxSetNexus

Sets nexus on or off for the specified states.

EZTaxSetStateExclusion

Uses the country code and a state code to set an exclusion.

EZTaxSetStateNexus

Uses a state code to set the nexus.

Jurisdiction Conversion Functions

The following functions are provided to convert between jurisdictional interfaces. This is useful when the service address is available for a call record transaction to be taxed but only NPANXX information is available for origination and termination points.

EZTaxCountryToPCode

EZTaxCountryToPCode takes a 3 byte country ISO code and converts it to the correct PCode for that country.

EZTaxGetAddressEx

Used to obtain the address of a specific JCode. This is normally not used during the AFC Session as the billing system normally has address information required for billing. AFC uses this database when generating reports for tax filing. The Address Database interface is provided as a valuable tool to Avalara customers.

EZTaxGetJurisdiction

Retrieves the jurisdiction where the transaction is determined to be taxed.

EZTaxGetTaxCatV98

EZTaxGetTaxCatV98 retrieves the tax category description for a specified tax code.

EZTaxJtoPCodeEx

Returns PCode that is cross-referenced to a JCode.

EZTaxLogicOvrJCodeEx

Specified a logic override for a specific tax using a JCode.

EZTaxLogicOvrJCodeExP

Specified a logic override for a specific tax using a JCode.

EZTaxNextAddressEx

Returns the next sequential address for a specified jurisdiction when the jurisdiction or parts of it are known by more than one address. This is true for the many jurisdictions contained within the AFC system, especially large cities. The Address Database interface is provided as a valuable tool to Avalara customers.

EZTaxPtoJCodeEx

Converts a PCode into a JCode.

EZTaxZtoJCodeEx

Used to populate customer databases records with JCodes. Avalara recommends the use of PCodes over JCodes, in which case the ZtoPCodeEx function would be used. This provides users that interface with AFC a large performance boost by providing addresses. The Zip Code Database interface is provided as a valuable tool to Avalara customers.

EZTaxZtoPCodeEx

Converts a zip code and address to a PCode.

EZTaxPtoFipsEx

Converts a PCode to a Fips Code.

EZTaxNtoJCodeEx

Obtain JCodes associated with an NPANXX.

EZTaxFtoPCodeEx

Converts a Fips Code into a PCode.

EZTaxGetCountryID

Get country ID for a PCode

EZTaxGetStateID

Get state ID for a PCode

Debit Transaction Functions

EZTaxDebitJEx

Accepts transaction data and performs tax debit calculations. BTN, origination and termination information is passed using JCodes.

EZTaxDebitNEx

Accepts transaction data and performs tax debit calculations. BTN, origination, and termination information is passed using NPANXXs.

EZTaxDebitPEx

Accepts transaction data and performs tax debit calculations. BTN, origination and termination information is passed using PCodes.

Override Functions

The following functions are provided to override an AFC value for the remainder of a session.

EZTaxRestoreEx

Removes all overrides that have been inserted by the user into the AFC databases. This action occurs automatically on EZTaxExit.

 

EZTaxOldOvrJCodeEx

EZTaxOvrJCodeEx specifies an override for a specific tax. Tax Jurisdiction information is passed via jurisdiction code. It takes a J_Code and an override structure as input and inserts a tax override into the AFC db system.

EZTaxOvrJCodeEx

Specifies an override for a specific tax. Tax Jurisdiction information is passed with a jurisdiction code. It takes a JCode and an override structure as input and inserts a tax override into the AFC db system for that session.

EZTaxOvrJCodeWithAdd

Specifies and override for a specific tax.

EZTaxOvrNPANEx

Specifies an override for a specific tax. Tax jurisdiction information is passed with an NPANXX. It takes an NPANXX and an override structure as input and inserts a tax override into the AFC db system for that session.

EZTaxOvrPCodeEx

Specifies an override for a specific tax. Tax jurisdiction information is passed with a PCode. It takes a PCode and an override structure as input and inserts a tax override into the AFC db system for that session.

EZTaxOvrZipEx

Specifies an override for a specific tax. Tax jurisdiction information is passed via zip code and address. It takes zip code plus 4 and address information, as well as an override structure as input and inserts a tax override into the AFC db system for that session.

Invoice Mode Functions

The following functions are provided to support Invoice Mode Operation.

EZTaxSetInvoiceModeEx

Turns Invoice Mode on and off.

EZTaxSetInvoiceModeV98

EZTaxSetInvoiceModeV98 sets Invoice Mode on or off - allocating or freeing memory for tables. It differs from EZTaxSetInvoiceModeEx in that the tax table returned contains tax category information.

EZTaxNextCustomerEx

Indicates that all of the transactions associated with this customer are complete. The system then clears out the transaction history table in preparation of the next set of transactions.

EZTaxJCodeEx

Accepts transaction data and performs appropriate tax calculations. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. BTN, origination and termination information is passed using JCodes.

EZTaxTaxInclusiveJCode

Accepts transaction data and performs a tax inclusive calculation. If the AFC Session was started with the tax log open, a transaction with the newly-calculated charge will be logged and will be reflected in tax reports. BTN, origination and termination information is passed using JCodes.

EZTaxDebitTaxInclusiveJCode

Accepts transaction data and performs a tax inclusive calculation for prepaid debit transactions. If the AFC Session was started with the tax log open, a transaction with the newly-calculated charge will be logged and will be reflected in tax reports. BTN, origination and termination information is passed using JCodes.

EZTaxThisJCodeEx

Accepts transaction data and performs appropriate tax calculations. The tax jurisdiction to use for tax calculations is specified to AFC with this method. If the AFC Session was started with the tax log open, appropriate taxes are logged and will be reflected in tax reports. Jurisdiction information is passed using a JCode.

EZTaxThisPCodeEx

Can be used to specify taxing based upon address information only by passing the encoded PCode.

EZTaxPCodeEx

Accepts transaction data and performs appropriate tax calculations. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. BTN, origination and termination information is passed using PCodes.

EZTaxTaxInclusivePCode

Accepts transaction data and performs a tax inclusive calculation. If the AFC Session was started with the tax log open, a transaction with the newly-calculated charge will be logged and will be reflected in tax reports. BTN, origination and termination information is passed using PCodes.

EZTaxDebitTaxInclusivePCode

Accepts transaction data and performs a tax inclusive calculation for prepaid debit transactions. If the AFC Session was started with the tax log open, a transaction with the newly-calculated charge will be logged and will be reflected in tax reports. BTN, origination and termination information is passed using PCodes.

EZTaxNPANEx

Accepts an NPANXX as input and calculates taxes for the transaction. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. BTN, origination and termination information is passed using NPANXXs.

EZTaxTaxInclusiveNPAN

Accepts transaction data and performs a tax inclusive calculation. If the AFC Session was started with the tax log open, a transaction with the newly-calculated charge will be logged and will be reflected in tax reports. BTN, origination and termination information is passed using NPANXXs.

EZTaxDebitTaxInclusiveNPAN

Accepts transaction data and performs a tax inclusive calculation for prepaid debit transactions. If the AFC Session was started with the tax log open, a transaction with the newly-calculated charge will be logged and will be reflected in tax reports. BTN, origination and termination information is passed using NPANXXs.

EZTaxZipEx

Accepts transaction data and performs appropriate tax calculations. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports.

EZTaxTaxInclusiveZip

Accepts transaction data and performs a tax inclusive calculation. If the AFC Session was started with the tax log open, a transaction with the newly-calculated charge will be logged and will be reflected in tax reports. Jurisdiction information is passed using address information.

EZTaxDebitTaxInclusiveZip

Accepts transaction data and performs a tax inclusive calculation for prepaid debit transactions. If the AFC Session was started with the tax log open, a transaction with the newly-calculated charge will be logged and will be reflected in tax reports. Jurisdiction information is passed using address information.

Credit Adjustment Functions

The following functions are provided for implementing adjustments such as refunds, changing a customer’s bill or when terminating un-collectable accounts.

These functions accept transaction data and perform appropriate tax calculations required to refund or credit taxes for U.S. jurisdictions (Debits use EZTaxAdjDebitEx APIs). If the AFC Session was started with the tax log open, appropriate taxes reductions are logged and will be reflected in tax reports.

EZTaxAdjDebitJEx

BTN, origination and termination information is passed using JCodes.

EZTaxAdjDebitNEx

BTN, origination and termination information is passed using NPANXXs.

EZTaxAdjDebitPEx

BTN, origination and termination information is passed using PCodes.

EZTaxAdjDebitZEx

The tax jurisdiction is specified using address information.

EZTaxAdjJCodeEx

BTN, origination and termination information is passed using JCodes.

EZTaxAdjTaxInclusiveJCode

Performs a tax inclusive calculation. Any logging will be done with the newly-calculated charge. BTN, origination and termination information is passed using JCodes.

EZTaxAdjDebitTaxInclusiveJCode

Performs a tax inclusive calculation for a prepaid debit transaction. Any logging will be done with the newly-calculated charge. BTN, origination and termination information is passed using JCodes.

EZTaxAdjNPANEx

BTN, origination and termination information is passed using NPANXXs.

EZTaxAdjTaxInclusiveNPAN

Performs a tax inclusive calculation. Any logging will be done with the newly-calculated charge. BTN, origination and termination information is passed using NPANXXs.

EZTaxAdjDebitTaxInclusiveNPAN

Performs a tax inclusive calculation for a prepaid debit transaction. Any logging will be done with the newly-calculated charge. BTN, origination and termination information is passed using NPANXXs.

EZTaxAdjPCodeEx

BTN, origination and termination information is passed using PCodes.

EZTaxAdjTaxInclusivePCode

Performs a tax inclusive calculation. Any logging will be done with the newly-calculated charge. BTN, origination and termination information is passed using PCodes.

EZTaxAdjDebitTaxInclusivePCode

Performs a tax inclusive calculation for a prepaid debit transaction. Any logging will be done with the newly-calculated charge. BTN, origination and termination information is passed using PCodes.

EZTaxAdjProRateJCode

Accepts a J_Code struct as input and calculates tax adjustments for the transaction, then pro-rates the taxes calculated by the given percentage for partial-month rates.

EZTaxAdjProRateNPAN

Accepts an NPAN_struct as input and calculates tax adjustments for the transaction, then pro-rates the taxes calculated by the given percentage for partial-month rates.

EZTaxAdjProRatePCode

Accepts a PCode struct as input and calculates tax adjustments for the transaction, then pro-rates the taxes calculated by the given percentage for partial-month rates.

EZTaxAdjProRateThisJCode

Accepts transaction data and performs appropriate tax calculations. The tax jurisdiction to use for tax calculations is specified to AFC with this method. If the AFC Session was started with the tax log open, appropriate taxes are logged and will be reflected in tax reports. Jurisdiction information is passed using a JCode. It pro-rates the taxes calculated by the given percentage for partial-month rates.

EZTaxAdjProRateThisPCode

Accepts transaction data and performs appropriate tax calculations. The tax jurisdiction to use for tax calculations is specified to AFC with this method. If the AFC Session was started with the tax log open, appropriate taxes are logged and will be reflected in tax reports. Jurisdiction information is passed using a PCode. It pro-rates the taxes calculated by the given percentage for partial-month rates.

EZTaxAdjProRateZip

EZTaxAdjProRateZip takes a Zip Code struct as input and calculates tax adjustments for the transaction. It pro-rates the taxes calculated by the given percentage for partial-month rates.

EZTaxAdjTaxInclusiveZip

Performs a tax inclusive calculation. Any logging will be done with the newly-calculated charge. BTN, origination and termination information is passed using address information.

EZTaxAdjDebitTaxInclusiveZip

Performs a tax inclusive calculation for a prepaid debit transaction. Any logging will be done with the newly-calculated charge. BTN, origination and termination information is passed using address information.

EZTaxAdjTPPEx

EZTaxAdjTPPEx accepts Tangible Personal Property (TPP) transaction data and performs appropriate tax calculations required to refund or credit taxes. The user provides up to three addresses: Ship From, Ship To and Point of Acceptance. Rules will be applied against the input addresses to determine in what jurisdiction any SALES or USE taxation would be applicable. A Nexus Table may optionally be provided. If so it will be checked to determine if nexus exists in the state found to have taxing jurisdiction. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports.

EZTaxAdjZipEx

The tax jurisdiction is specified using address information.

Interstate-Intrastate Determination Functions

The Interstate-Intrastate functions are used to determine if a call is interstate or intrastate.

EZTaxJTTypeEx

Returns transaction type for a given pair of JCodes indicating whether the call is interstate or intrastate. The first JCode is the originating and the second the terminating JCode. Will set error code to INTERSTATE_NOT_VALID_FOR_INTERNATIONAL_CALLS If the originating country and terminating country are not the same.

EZTaxNTTypeEx

Returns transaction type for a given pair of NPANXX’s indicating whether the call is interstate or intrastate. The first NPANXX is the originating and the second is the terminating NPANXX.

EZTaxPTTypeEx

Returns transaction type for a given pair of PCodes indicating whether the call is interstate or intrastate. The first PCode is the originating and the second the terminating PCode. Will set error code to INTERSTATE_NOT_VALID_FOR_INTERNATIONAL_CALLS If the originating country and terminating country are not the same.

EZTaxTPPEx

Accepts up to three addresses; Ship From, Ship To, and Point-Of- Acceptance. It requires Ship From. If others have NOT NULL values, then they must be valid. Uses rules to determine interstate or intrastate to determine which taxing jurisdiction should be used. It accepts the optional Nexus Table, which if given will be checked against the jurisdiction determined above. No taxes will be calculated unless the flag is set (by the caller) for the given state. It returns tax_count, having populated the tax log structure with any taxes found.

Get Functions

These functions are supplied to support activities requiring the retrieval of information and data.

EZTaxGetCustomLog

Returns the JCode that has jurisdiction at the most detailed taxing level.

EZTaxGetCustomLogCount

Returns the number of records in the current custom log table.

EZTaxGetHandle

Returns the handle object given the session.

EZTaxGetLogName

Retrieves the log filename when it is specified using the filelocs.txt. Current use is in the batch executables that open the log file and must know the filename.

EZTaxGetLogV914

Returns a pointer to a log structure, which is used for customized logging. Returns a pointer to the v9114 tax log table.

EZTaxGetLogV914Count

Returns the number of records in the current custom log table.

EZTaxGetNoTaxTrans

Returns a pointer to a no-tax transaction structure.

EZTaxGetRates

Utilizes a PCode as input to produce the table of all taxes for that jurisdiction.

EZTaxGetTaxDescription

Retrieves the tax description for a specified tax code. Current use is in utilities reporting from the log, but users can also use this new feature.

EZTaxGetTSR

Allows applications API functionality to get the transaction service report

EZTaxMaxTaxCount

Returns the maximum number of taxes that one transaction can generate.

ProRate Functions

EZTaxProRate functions accept transaction data and perform appropriate tax calculations. If the taxing jurisdiction allows a pro-rated reduction of taxes, the tax returned will be appropriately reduced. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports.

EZTaxProRateJCodeEx

BTN, origination and termination information is passed using JCodes. This program takes a J_Code struct as input and calculates taxes for the transaction. This is the same as EZTaxJCodeEx but with percent as input.

EZprivate lineTaxProRateNPANEx

BTN, origination and termination information is passed using NPANXX. This program takes an NPANXX code struct as input and calculates taxes for the transaction. This is the same as EZTaxNPANEx but with input percent

EZTaxProRatePCodeEx

BTN, origination and termination information is passed using PCode. This program takes a PCode struct as input and calculates taxes for the transaction. This is the same as EZTaxPCodeEx but with percent as input.

EZTaxProRateThisJCodeEx

Jurisdiction information is passed using a JCode. This program takes a specific jurisdiction code as input and calculates taxes for the transaction. It is the same as EZTaxThisJCodeEx but with percent as input.

EZTaxProRateThisPCodeEx

Jurisdiction information is passed using a PCode. This program takes a specific jurisdiction code as input and calculates taxes for the transaction. It is the same as EZTaxThisPCodeEx but with percent as input.

EZTaxProRateZipEx

Jurisdiction information is passed using a Zip Code. This program takes a Zip Code plus 4 structure as input and calculates taxes for the transaction. This is the same as EZTaxZipEx but with percent as input.

Private Line or Point-to-Point Functions

Private line, or Point-to-Point (PTP) as it is often referred to, allows a transaction to be split between the A point and Z point. The percentage specified applies to the A point. The Z point percentage will be automatically calculated as 1-(A pt %).

EZTaxPrivateLine

Jurisdiction information is passed using a PCode. The program applies the % split to the A point tax calculation, then the remaining % split to the Z point calculation.

EZTaxPrivateLineAdj

Jurisdiction information is passed using a PCode. The program applies the % split to the A point tax adjustment, then the remaining % split to the Z point adjustment.

Miscellaneous Functions

The following functions perform miscellaneous operations.

EZTaxCalcJurisdiction

Returns the JCode that has jurisdiction at the most detailed taxing level.

EZTaxDbVersion

Reads the database version from EZTax.dll and returns it to the caller.

EZTaxDllVersion

Returns the version number of the AFC API.

EZTaxFlushToLogEx

Writes the current internal tax log buffers to the tax log disk file. The internal tax log buffers are normally written to when they are filled to capacity or when EZTaxExitEx is called. This function can be called to force a write to tax log disk file.

EZTaxFreeRates

Frees up the memory from the table of all taxes for a jurisdiction returned from EZTaxGetRates.

EZTaxGroupResults

Sets the mode that AFC uses to group the returned taxes by.

EZTaxSessionDbVersion

Reads the database version being used by the specified AFC Session and returns it to the caller.

EZTaxWriteToLogEx

Allows customers to create the correctly formatted binary AFC log from scratch by passing in data they have stored from a different database or saved from AFC transactions using EZTaxInitExp.

EZTaxWriteToLogV914

Allows customers to create the correctly formatted binary AFC log from scratch by passing in data they have stored from a different database or saved from AFC transactions.

EZTaxBridgeConference

Used for calculating tax specifically for a bridge conference.

EZTaxAdjDebitJEx

Description

EZTaxAdjDebitJEx accepts transaction data and performs appropriate tax calculations required to refund or credit taxes for Debit transactions. If the AFC Session was started with the tax log open, appropriate tax reductions are logged and will be reflected in tax reports. BTN, origination and termination information is passed using J-codes.

Format

short int EZTaxAdjDebitJEx(EZTaxSession session, struct J_CodeEx *trans, int discount_type, int adj_method, int *err_code);

Header(s) Required

EZTaxDefine.h

EZTaxProto.h

EZTaxStruct.h

Return Value List

[0] : Indicates no tax data available for transaction (not taxable) or an error has occurred

[n] : Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session : session handle returned when initialized with call to EZTaxInitEx

*trans : Pointer to data structure which contains transaction data.

J-code transaction information

discount_type : discount type code

adj_method : adjustment method (DLM)

*err_code : error status returned

Remarks

Returns tax adjustments identical to method used for returning tax calculations. Interface data structures are also described in detail in the AFC Data Structures section of the Manual. The AFC calculations section contains a detailed explanation of how taxes are returned to the user.

EZTaxAdjDebitNEx

Description

EZTaxAdjDebitNEx accepts transaction data and performs appropriate tax calculations required to refund or credit taxes for Debit transactionss. If the AFC Session was started with the tax log open, appropriate taxes reductions are logged and will be reflected in tax reports. BTN, origination and termination information is passed using NPANXXs

Format

short int EZTaxAdjDebitNEx(EZTaxSession session, struct NPANXX_codeEx *trans, int discount_type, int adj_method, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[0]: Indicates no tax data available for transaction (not taxable) or an error has occurred.

[n]: Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session: session handle returned when initialized with call to EZTaxInitEx

*trans: NPANXX transaction information

discount_type: discount type code

adj_method: adjustment method (DLM)

*err_code: error status returned

Remarks

Returns tax adjustments identical to method used for returning tax calculations. Interface data structures are also described in detail in the AFC Data Structures section. The section AFC Calculations explains how taxes are returned to the user in detail.

EZTaxAdjDebitPEx

Description

Function EZTaxAdjDebitPEx accepts transaction data and performs appropriate tax calculations required to refund or credit taxes for Debit transactionss. If the AFC Session was started with the tax log open, appropriate taxes reductions are logged and will be reflected in tax reports. BTN, origination and termination information is passed using PCodes.

Format

short int EZTaxAdjDebitPEx(EZTaxSession session, struct P_CodeEx *trans, int discount_type, int adj_method, int *err_code)

Header(s) Required

EZTaxProto.h

Libraries

EZTax2.lib

Return Value List

0 : Indicates no tax data available for transaction (not taxable) or an error has occurred.

n : Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session : session handle returned when initialized with call to EZTaxInitEx

*trans : P-code transaction information

discount_type : discount type code

adj_method : adjustment method (DLM)

*err_code : error status returned

Remarks

Returns tax adjustments identical to method used for returning tax calculations. Interface data structures are also described in detail in the AFC Data Structures section. The section AFC Calculations explains how taxes are returned to the user in detail.

EZTaxAdjDebitTaxInclusiveJCode (EZTaxAdjDebitRevJCode deprecated)

Description

EZTaxAdjDebitTaxInclusiveJCode accepts transaction data and performs a tax inclusive adjustment calculation for a prepaid debit transaction to arrive at the base sale amount. The desired total (charge plus all taxes) is placed in the ‘charge’ field in the transaction, and base charge necessary to generate the total is returned in the ‘base_sale’ parameter. Taxes for the desired transaction are returned in the same manner as EZTaxAdjJCodeEx. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. BTN, origination and termination information is passed using JCodes. The base sale amount will also be stored in the ‘optional’ field in the log output, converted to an integer.

Format

short int EZTaxAdjDebitTaxInclusiveJCode (EZTaxSession session, struct J_CodeEx *trans, int discount_type, int adj_method, double *base_sale, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[-1]: A critical error occurred while preparing the tax inclusive calculation session

[0]: No taxes calculated or an error was found

[n]: Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session: session handle returned when initialized with call to EZTaxInitEx

*trans: transaction information

discount_type: discount type code

adj_method: adjustment method (DLM)

*base_sale: calculated charge returned

*err_code: error status returned

Remarks

When both return and err_code are 0, no taxes were found, but there is no error. The base_sale returned will equal the charge sent in. If the charge sent in is insufficient to cover the taxes generated, then no taxes will be calculated and the err_code will be set to -37. An error will be logged to the status file indicating an insufficient charge error occurred.

**Note**: Non-billable taxes are not included in the calculation of the basesale amount. Adding the base sale amount and all taxes that appear in thelog for a transaction may result in a value greater than the target amount;any non-billable taxes returned by the transaction *will* be included in the total.

EZTaxAdjDebitTaxInclusiveNPAN (EZTaxAdjDebitRevNPAN deprecated)

Description

EZTaxAdjDebitTaxInclusiveNPAN accepts transaction data and performs a tax inclusive adjustment calculation for a prepaid debit transaction to arrive at the base sale amount. The desired total (charge plus all taxes) is placed in the ‘charge’ field in the transaction, and base charge necessary to generate that total is returned in the ‘base_sale’ parameter. Taxes for the desired transaction are returned in the same manner as EZTaxAdjNPANEx. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. BTN, origination and termination information is passed using NPANXXs. The base sale amount will also be stored in the ‘optional’ field in the log output, converted to an integer.

Format

short int EZTaxAdjDebitTaxInclusiveNPAN(EZTaxSession session, struct NPANXX_CodeEx *trans, int discount_type, int adj_method, double *base_sale, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[-1] : A critical error occurred while preparing the tax inclusive calculation session

[0] : No taxes calculated or an error was found

[n] : Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session: session handle returned when initialized with call to EZTaxInitEx

*trans: transaction information

discount_type: discount type code

adj_method: adjustment method (DLM)

*base_sale: calculated charge returned

*err_code: error status returned

Remarks

When both return and err_code are 0, no taxes were found, but there is no error. The base_sale returned will equal the charge sent in. If the charge sent in is insufficient to cover the taxes generated, then no taxes will be calculated and the err_code will be set to -37. An error will be logged to the status file indicating an insufficient charge error occurred.

**Note**: Non-billable taxes are not included in the calculation of the base sale amount. Adding the base sale amount and all taxes that appear in the log for a transaction may result in a value greater than the target amount, any non-billable taxes returned by the transaction *will* be included in the total.

EZTaxAdjDebitTaxInclusivePCode (EZTaxAdjDebitRevPCode deprecated)

Description

EZTaxAdjDebitTaxInclusivePCode accepts transaction data and performs a tax inclusive adjustment calculation for a prepaid debit transaction to arrive at the base sale amount. The desired total (charge plus all taxes) is placed in the ‘charge’ field in the transaction, and base charge necessary to generate that total is returned in the ‘base_sale’ parameter. Taxes for the desired transaction are returned in the same manner as EZTaxAdjPCodeEx. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. BTN, origination and termination information is passed using PCodes. The base sale amount will also be stored in the ‘optional’ field in the log output, converted to an integer.

Format

short int EZTaxAdjDebitTaxInclusivePCode(EZTaxSession session, struct P_CodeEx *trans, int discount_type, int adj_method, double *base_sale, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[-1] : A critical error occurred while preparing the tax inclusive calculation session

[0] : No taxes calculated or an error was found

[n] : Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session: session handle returned when initialized with call to EZTaxInitEx

*trans: transaction information

discount_type: discount type code

adj_method: adjustment method (DLM)

*base_sale: calculated charge returned

*err_code: error status returned

Remarks

When both return and err_code are 0, no taxes were found, but there is no error. The base_sale returned will equal the charge sent in. If the charge sent in is insufficient to cover the taxes generated, then no taxes will be calculated and the err_code will be set to -37. An error will be logged to the status file indicating an insufficient charge error occurred.

**Note**: Non-billable taxes are not included in the calculation of the base sale amount. Adding the base sale amount and all taxes that appear in the log for a transaction may result in a value greater than the target amount;any non-billable taxes returned by the transaction *will* be included in the total.

EZTaxAdjDebitTaxInclusiveZip (EZTaxAdjDebitRevZip deprecated)

Description

EZTaxAdjDebitTaxInclusiveZip accepts transaction data and performs a tax inclusive adjustment calculation to arrive at the base sale amount. The desired total (charge plus all taxes) is placed in the ‘charge’ field in the transaction, and base charge necessary to generate that total is returned in the ‘base_sale’ parameter. Taxes for the desired transaction are returned as EZTaxJCodeEx. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. The base sale amount will also be stored in the ‘optional’ field in the log output, converted to an integer.

This function passes tax jurisdiction information to AFC by specifying the appropriate zip code, state identifier, county, and locality. AFC uses this information to determine the JCode used for tax calculations. It is important to supply complete address information; there are many duplicate zip codes and localities contained within the AFC database tables. AFC always returns the first match of the data supplied.

Supplying incomplete information can result in tax calculations for an unexpected jurisdiction. When information regarding the locality is not supplied, AFC may be limited to data based upon the county or parish involved. Likewise, when information about the county is not supplied, the AFC engine may be limited to calculations based upon the state and zip code identifiers.

Format

short int EZTaxAdjDebitTaxInclusiveZip(EZTaxSession session, struct zip_codeEx *trans, int discount_type, int adj_method, double *base_sale, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[-1]: A critical error occurred while preparing the tax inclusive calculation session

[0]: No taxes calculated or an error was found

[n]: Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session: session handle returned when initialized with call to EZTaxInitEx

*trans: transaction information

discount_type: discount type code

adj_method: adjustment method (DLM)

*base_sale: calculated charge returned

*err_code: error status returned

Remarks

When both return and err_code are 0, no taxes were found, but there is no error. The base_sale returned will equal the charge sent in. If the charge sent in is insufficient to cover the taxes generated, then no taxes will be calculated and the err_code will be set to -37. An error will be logged to the status file indicating an insufficient charge error occurred.

**Note**: Non-billable taxes are not included in the calculation of the base sale amount. Adding the base sale amount and all taxes that appear in the log for a transaction may result in a value greater than the target amount; any non-billable taxes returned by the transaction *will* be included in the total.

EZTaxAdjDebitZEx

Description

EZTaxAdjDebitZEx accepts transaction data and performs appropriate tax calculations required to refund or credit taxes for Debit transactionss. If the AFC Session was started with the tax log open, appropriate taxes reductions are logged and will be reflected in tax reports. The tax jurisdiction is specified using address information, identical to EZTaxDebitZEx.

Format

short int EZTaxAdjDebitZEx(EZTaxSession session, struct zip_codeEx *trans, int discount_type, int adj_method, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[0] : Indicates no tax data available for transaction (not taxable) or an error has occurred.

[n] : Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session : session handle returned when initialized with call to EZTaxInitEx

*trans : zip code transaction information

discount_type : discount type code

adj_method : adjustment method (DLM)

* err_code : error status returned

Remarks

Returns tax adjustments identical to method used for returning tax calculations. Interface data structures are also described in detail in the AFC Data Structures section. The section AFC Calculations explains how taxes are returned to the user in detail. AFC currently has Zip Code information for U.S. and Canadian jurisdictions.

EZTaxAdjJCodeEx

Description

EZTaxAdjJCodeEx accepts transaction data and performs appropriate tax calculations required to refund or credit taxes (Debit transactionss use EZTaxAdjDebitEx API’s). If the AFC Session was started with the tax log open, appropriate taxes reductions are logged and will be reflected in tax reports.  BTN, origination and termination information is passed using JCodes.

Format

short int EZTaxAdjJCodeEx(EZTaxSession session, struct J_CodeEx *trans, int discount_type, int adj_method, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxStruct.h

EZTaxDefine.h

Libraries

EZTax2.lib

Return Value List

[0] : Indicates no tax data available for transaction (not taxable) or an error has occurred.

[n] : Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session : session handle returned when initialized with call to EZTaxInitEx

*trans : J-code transaction information

discount_type : discount type code

adj_method : adjustment method (DLM)

*err_code : error status returned

Remarks

Returns tax adjustments identical to method used for returning tax calculations. Interface data structures are also described in detail in the AFC Data Structures section. The section AFC Calculations explains how taxes are returned to the user in detail.

EZTaxAdjNPANEx

Description

EZTaxAdjNPANEx accepts transaction data and performs appropriate tax calculations required to refund or credit taxes (Debit transactionss use EZTaxAdjDebitEx API’s). If the AFC Session was started with the tax log open, appropriate taxes reductions are logged and will be reflected in tax reports.  BTN, origination and termination information is passed using NPANXXs.

Format

short int EZTaxAdjNPANEx(EZTaxSession session, struct NPANXX_codeEx *trans, int discount_type, int adj_method, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[0] : Indicates no tax data available for transaction (not taxable) or an error has occurred.

[n] : Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session : session handle returned when initialized with call to EZTaxInitEx

*trans : NPANXX transaction information

discount_type : discount type code

*err_code : error status returned

adj_method : adjustment method (DLM)

Remarks

Returns tax adjustments identical to method used for returning tax calculations. Interface data structures are also described in detail in the AFC Data Structures section. The section AFC Calculations explains how taxes are returned to the user in detail.

EZTaxAdjPCodeEx

Description

EZTaxAdjPCodeEX accepts transaction data and performs appropriate tax calculations required to refund or credit taxes (Debit transactionss use EZTaxAdjDebitEx API’s). If the AFC Session was started with the tax log open, appropriate taxes reductions are logged and will be reflected in tax reports.  BTN, origination and termination information is passed using PCodes.

Format

short int EZTaxAdjPCodeEx(EZTaxSession session, struct P_CodeEx *trans, int discount_type, int adj_method, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[0] : Indicates no tax data available for transaction (not taxable) or an error has occurred.

[n] : Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session : session handle returned when initialized with call to EZTaxInitEx

*trans : P-code transaction information

discount_type : discount type code

adj_method : adjustment method (DLM)

*err_code : error status returned

Remarks

Returns tax adjustments identical to method used for returning tax calculations. Interface data structures are also described in detail in the AFC Data Structures section. The section AFC Calculations explains how taxes are returned to the user in detail.

EZTaxAdjProRateJCode (EZTaxAdjProRateJCodeEx deprecated)

Description

EZTaxAdjProRateJCode takes a J_Code struct as input and calculates tax adjustments for the transaction. It pro-rates the taxes calculated by the given percentage, for partial-month rates.

The user can select the type of Pro-Rate adjustment handling by using one of the following parameters:

prorate_credit_or_cancel = STANDARD_PRORATED_ADJUSTMENT (1)

Standard or default processing will not return fixed taxes that are not flagged as pro-ratable. This approach should be used when the desire is to only return taxes that are pro-ratable. An example would be when a client has canceled a service and is due back taxes that are refundable.

prorate_credit_or_cancel = CANCEL_PRORATED_CALCULATION (2)

Cancel option will return fixed taxes that are not flagged as pro-ratable. This approach should be used when the desire is to cancel out a previous pro-rated calculation. An example would be when a pro-rated tax calculation has been made in error and needs to be canceled out so that the net taxes are 0.

Format

short int EZTaxAdjProRateJCode(EZTaxSession session, struct J_CodeEx *trans, int discount_type, double percent, int adj_method, int prorate_credit_or_cancel, int *err_code);

Return Value List

[0] : Indicates no tax data available for transaction (not taxable) or an error has occurred.

[n] : Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session : session handle returned when initialized with call to EZTaxInitEx

*trans : J-code transaction information

discount_type : discount type code

percent : portion of the billing period to pro-rate the tax by

adj_method : adjustment method (DLM)

int prorate_credit_or_cancel : method for how pro-rated adjustment should handle non-prorated taxes

*err_code : error status returned

Remarks

None

EZTaxAdjProRateNPAN (EZTaxAdjProRateNPANEx deprecated)

Description

EZTaxAdjProRateNPAN takes an NPANXX struct as input and calculates tax adjustments for the transaction. It pro-rates the taxes calculated by the given percentage, for partial-month rates.

The user can select the type of Pro-Rate adjustment handling by using one of the following parameters:

prorate_credit_or_cancel = STANDARD_PRORATED_ADJUSTMENT (1)

Standard or default processing will not return fixed taxes that are not flagged as pro-ratable. This approach should be used when the desire is to only return taxes that are pro-ratable. An example would be when a client has canceled a service and is due back taxes that are refundable.

prorate_credit_or_cancel = CANCEL_PRORATED_CALCULATION (2)

Cancel option will return fixed taxes that are not flagged as pro-ratable. This approach should be used when the desire is to cancel out a previous pro-rated calculation. An example would be when a pro-rated tax calculation has been made in error and needs to be canceled out so that the net taxes are 0.

Format

short int EZTaxAdjProRateNPAN (EZTaxSession session, struct NPANXX_codeEx *trans, int discount_type, double percent, int adj_method, int prorate_credit_or_cancel, int *err_code);

Return Value List

[0] : Indicates no tax data available for transaction (not taxable) or an error has occurred.

[n] : Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session : session handle returned when initialized with call to EZTaxInitEx

*trans : NPANXX transaction information

discount_type : discount type code

percent : portion of the billing period to pro-rate the tax by

adj_method : adjustment method (DLM)

int prorate_credit_or_cancel : method for how pro-rated adjustment should handle non-prorated taxes

*err_code : error status returned

Remarks

None

EZTaxAdjProRatePCode (EZTaxAdjProRatePCodeEx deprecated)

Description:

EZTaxAdjProRatePCode takes a p-code struct as input and calculates tax adjustments for the transaction. It pro-rates the taxes calculated by the given percentage, for partial-month rates.

The user can select the type of Pro-Rate adjustment handling by using one of the following parameters:

prorate_credit_or_cancel = STANDARD_PRORATED_ADJUSTMENT (1)

Standard or default processing will not return fixed taxes that are not flagged as pro-ratable. This approach should be used when the desire is to only return taxes that are pro-ratable. An example would be when a client has canceled a service and is due back taxes that are refundable.

prorate_credit_or_cancel = CANCEL_PRORATED_CALCULATION (2)

Cancel option will return fixed taxes that are not flagged as pro-ratable. This approach should be used when the desire is to cancel out a previous pro-rated calculation. An example would be when a pro-rated tax calculation has been made in error and needs to be canceled out so that the net taxes are 0.

Format

short int EZTaxAdjProRatePCode (EZTaxSession session, struct P_CodeEx *trans, int discount_type, double percent, int adj_method, int prorate_credit_or_cancel, int *err_code);

Return Value List

[0] : Indicates no tax data available for transaction (not taxable) or an error has occurred.

[n] : Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session : session handle returned when initialized with call to EZTaxInitEx

*trans : p-code transaction information

discount_type : discount type code

percent : portion of the billing period to pro-rate the tax by

adj_method : adjustment method (DLM)

* int prorate_credit_or_cancel : method for how pro-rated adjustment should handle non-prorated taxes

*err_code : error status returned

Remarks

None

EZTaxAdjProRateThisJCode (EZTaxAdjProRateThisJCodeEx deprecated)

Description

EZTaxAdjProRateThisJCode accepts transaction data and performs appropriate tax calculations. The tax jurisdiction to use for tax calculations is specified to AFC with this method. If the AFC Session was started with the tax log open, appropriate taxes are logged and will be reflected in tax reports.  Jurisdiction information is passed using a PCode. It pro-rates the taxes calculated by the given percentage, for partial-month rates.

The user can select the type of Pro-Rate adjustment handling by using one of the following parameters:

prorate_credit_or_cancel = STANDARD_PRORATED_ADJUSTMENT (1)

Standard or default processing will not return fixed taxes that are not flagged as pro-ratable. This approach should be used when the desire is to only return taxes that are pro-ratable. An example would be when a client has canceled a service and is due back taxes that are refundable.

prorate_credit_or_cancel = CANCEL_PRORATED_CALCULATION (2)

Cancel option will return fixed taxes that are not flagged as pro-ratable. This approach should be used when the desire is to cancel out a previous pro-rated calculation. An example would be when a pro-rated tax calculation has been made in error and needs to be canceled out so that the net taxes are 0.

Format

short int EZTaxAdjProRateThisJCode (EZTaxSession session, struct this_J_Code *trans, int discount_type, double percent, int adj_method, int prorate_credit_or_cancel, int *err_code);

Return Value List

[0] : Indicates no tax data available for transaction (not taxable) or an error has occurred.

[n] : Indicates number of taxes stored in the struct taxes_tbl array for this transaction

Parameters

session : Session object returned for session when initialized with call to EZTaxInitEx.

*trans : Pointer to data structure that contains transaction data.

See the this_J_Code struct in EZTaxStruct.h

discount_type : discount type code

percent : portion of the billing period to pro-rate the tax by

adj_method : adjustment method (DLM)

int prorate_credit_or_cancel : method for how pro-rated adjustment should handle non-prorated taxes

*err_code : error status returned

Remarks

This API call is particularly suited for processing local transactions, since there is only one jurisdiction involved.

EZTaxAdjProRateThisPCode (EZTaxAdjProRateThisPCodeEx deprecated)

Description

EZTaxAdjProRateThisPCode accepts transaction data and performs appropriate tax calculations. The tax jurisdiction to use for tax calculations is specified to AFC with this method. If the AFC Session was started with the tax log open, appropriate taxes are logged and will be reflected in tax reports.  Jurisdiction information is passed using a PCode. It pro-rates the taxes calculated by the given percentage, for partial-month rates.

The user can select the type of Pro-Rate adjustment handling by using one of the following parameters:

prorate_credit_or_cancel = STANDARD_PRORATED_ADJUSTMENT (1)

Standard or default processing will not return fixed taxes that are not flagged as pro-ratable. This approach should be used when the desire is to only return taxes that are pro-ratable. An example would be when a client has canceled a service and is due back taxes that are refundable.

prorate_credit_or_cancel = CANCEL_PRORATED_CALCULATION (2)

Cancel option will return fixed taxes that are not flagged as pro-ratable. This approach should be used when the desire is to cancel out a previous pro-rated calculation. An example would be when a pro-rated tax calculation has been made in error and needs to be canceled out so that the net taxes are 0.

Format

short int EZTaxAdjProRateThisPCode (EZTaxSession session, struct this_P_Code *trans, int discount_type, double percent, int adj_method, int prorate_credit_or_cancel, int *err_code);

Return Value List

[0] : Indicates no tax data available for transaction (not taxable) or an error has occurred.

[n] : Indicates number of taxes stored in the struct taxes_tbl array for this transaction

Parameters

session : Session object returned for session when initialized with call to EZTaxInitEx.

*trans : Pointer to data structure that contains transaction data.

See the this_P_Code struct in EZTaxStruct.h

discount_type : discount type code

percent : portion of the billing period to pro-rate the tax by

adj_method : adjustment method (DLM)

int prorate_credit_or_cancel : method for how pro-rated adjustment should handle non-prorated taxes

*err_code : error status returned

Remarks

This API call is particularly suited for processing local transactions, since there is only one jurisdiction involved.

EZTaxAdjProRateZip (EZTaxAdjProRateZipEx deprecated)

Description

EZTaxAdjProRateZip takes a p-code struct as input and calculates tax adjustments for the transaction. It pro-rates the taxes calculated by the given percentage, for partial-month rates.

You can select the type of Pro-Rate adjustment handling by using one of the following parameters:

prorate_credit_or_cancel = STANDARD_PRORATED_ADJUSTMENT (1)

Standard or default processing will not return fixed taxes that are not flagged as pro-ratable. This approach should be used when the desire is to only return taxes that are pro-ratable. An example would be when a client has canceled a service and is due back taxes that are refundable.

prorate_credit_or_cancel = CANCEL_PRORATED_CALCULATION (2)

Cancel option will return fixed taxes that are not flagged as pro-ratable. This approach should be used when the desire is to cancel out a previous pro-rated calculation. An example would be when a pro-rated tax calculation has been made in error and needs to be canceled out so that the net taxes are 0.

Format

short int EZTaxAdjProRateZip (EZTaxSession session, struct zip_codeEx *trans, int discount_type, double percent, int adj_method, int adj_method, int prorate_credit_or_cancel, int *err_code);

Return Value List

[0] : Indicates no tax data available for transaction (not taxable) or an error has occurred.

[n] : Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session : session handle returned when initialized with call to EZTaxInitEx

*trans : zip code transaction information

discount_type : discount type code

percent : portion of the billing period to pro-rate the tax by

adj_method : adjustment method (DLM)

int prorate_credit_or_cancel : method for how pro-rated adjustment should handle non-prorated taxes

*err_code : error status returned

Remarks

None

EZTaxAdjTaxInclusiveJCode (EZTaxAdjRevJCode deprecated)

Description

EZTaxAdjTaxInclusiveJCode accepts transaction data and performs a tax inclusive adjustment calculation to arrive at the base sale amount. The desired total (charge plus all taxes) is placed in the ‘charge’ field in the transaction, and base charge necessary to generate that total is returned in the ‘base_sale’ parameter. Taxes for the desired transaction are returned in the same manner as EZTaxAdjJCodeEx does. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. BTN, origination and termination information is passed using JCodes. The base sale amount will also be stored in the ‘optional’ field in the log output, converted to an integer.

Format

short int EZTaxAdjTaxInclusiveJCode(EZTaxSession session, struct J_CodeEx *trans, int discount_type, int adj_method, double *base_sale, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[-1]: A critical error occurred while preparing the tax inclusive calculation session

[0]: No taxes calculated or an error was found

[n]: Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session: session handle returned when initialized with call to EZTaxInitEx

*trans: transaction information

discount_type: discount type code

adj_method: adjustment method (DLM)

*base_sale: calculated charge returned

*err_code: error status returned

Remarks

When both return and err_code are 0, no taxes were found, but there is no error. The base_sale returned will equal the charge sent in. If the charge sent in is insufficient to cover the taxes generated, then no taxes will be calculated and the err_code will be set to -37. An error will be logged to the status file indicating an insufficient charge error occurred.

**Note**: Non-billable taxes are not included in the calculation of the base sale amount. Adding the base sale amount and all taxes that appear in the log for a transaction may result in a value greater than the target amount, as any non-billable taxes returned by the transaction *will* be included in that total.

EZTaxAdjTaxInclusiveNPAN (EZTaxAdjRevNPAN deprecated)

Description

EZTaxAdjTaxInclusiveNPAN accepts transaction data and performs a tax inclusive adjustment calculation to arrive at the base sale amount. The desired total (charge plus all taxes) is placed in the ‘charge’ field in the transaction, and base charge necessary to generate that total is returned in the ‘base_sale’ parameter. Taxes for the desired transaction are returned in the same manner as EZTaxAdjNPANEx does. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. BTN, origination and termination information is passed using NPANXXs. The base sale amount will also be stored in the ‘optional’ field in the log output, converted to an integer.

Format

short int EZTaxAdjTaxInclusiveNPAN (EZTaxSession session, struct NPANXX_CodeEx *trans, int discount_type, int adj_method, double *base_sale, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[-1]: A critical error occurred while preparing the tax inclusive calculation session

[0]: No taxes calculated or an error was found

[n]: Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session: session handle returned when initialized with call to EZTaxInitEx

*trans: transaction information

discount_type: discount type code

adj_method: adjustment method (DLM)

*base_sale: calculated charge returned

*err_code: error status returned

Remarks

When both return and err_code are 0, no taxes were found, but there is no error. The base_sale returned will equal the charge sent in. If the charge sent in is insufficient to cover the taxes generated, then no taxes will be calculated and the err_code will be set to -37. An error will be logged to the status file indicating an insufficient charge error occurred.

**Note**: Non-billable taxes are not included in the calculation of the base sale amount. Adding the base sale amount and all taxes that appear in the log for a transaction may result in a value greater than the target amount, as any non-billable taxes returned by the transaction *will* be included in that total.

EZTaxAdjTaxInclusivePCode (EZTaxAdjRevPCode deprecated)

Description

EZTaxAdjTaxInclusivePCode accepts transaction data and performs a tax inclusive adjustment calculation to arrive at the base sale amount. The desired total (charge plus all taxes) is placed in the ‘charge’ field in the transaction, and base charge necessary to generate that total is returned in the ‘base_sale’ parameter. Taxes for the desired transaction are returned in the same manner as EZTaxAdjPCodeEx does. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. BTN, origination and termination information is passed using PCodes. The base sale amount will also be stored in the ‘optional’ field in the log output, converted to an integer.

Format

short int EZTaxAdjTaxInclusivePCode(EZTaxSession session, struct P_CodeEx *trans, int discount_type, int adj_method, double *base_sale, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[-1]: A critical error occurred while preparing the tax inclusive calculation session

[0]: No taxes calculated or an error was found

[n]: Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session: session handle returned when initialized with call to EZTaxInitEx

*trans: transaction information

discount_type: discount type code

adj_method: adjustment method (DLM)

*base_sale: calculated charge returned

*err_code: error status returned

Remarks

When both return and err_code are 0, no taxes were found, but there is no error. The base_sale returned will equal the charge sent in. If the charge sent in is insufficient to cover the taxes generated, then no taxes will be calculated and the err_code will be set to -37. An error will be logged to the status file indicating an insufficient charge error occurred.

**Note**: Non-billable taxes are not included in the calculation of the base sale amount. Adding the base sale amount and all taxes that appear in the log for a transaction may result in a value greater than the target amount, as any non-billable taxes returned by the transaction *will* be included in that total.

EZTaxAdjTaxInclusiveZip (EZTaxAdjRevZip deprecated)

Description

EZTaxAdjTaxInclusiveZip accepts transaction data and performs a tax inclusive adjustment calculation to arrive at the base sale amount. The desired total (charge plus all taxes) is placed in the ‘charge’ field in the transaction, and base charge necessary to generate that total is returned in the ‘base_sale’ parameter. Taxes for the desired transaction are returned as EZTaxJCodeEx does. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. The base sale amount will also be stored in the ‘optional’ field in the log output, converted to an integer.

When the user knows the tax jurisdiction, address information can be supplied to specify it. This function passes tax jurisdiction information to AFC by specifying the appropriate zip code, state identifier, county, and locality. AFC uses this information to determine the JCode used for tax calculations. It is important to supply complete address information as there are many duplicate zip codes and localities contained within the AFC database tables. AFC always returns the first match of the data supplied.

Supplying incomplete information can result in tax calculations for an unexpected jurisdiction. When information regarding the locality is not supplied, AFC may be limited to data based upon the county or parish involved. Likewise, when information about the county is not supplied, the AFC engine may be limited to performance of calculations based upon the state and zip code identifiers.

Format

short int EZTaxAdjTaxInclusiveZip(EZTaxSession session, struct zip_codeEx *trans, int discount_type, int adj_method, double *base_sale, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[-1]: A critical error occurred while preparing the tax inclusive calculation session

[0]: No taxes calculated or an error was found

[n]: Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session: session handle returned when initialized with call to EZTaxInitEx

*trans: transaction information

discount_type: discount type code

adj_method: adjustment method (DLM)

*base_sale: calculated charge returned

*err_code: error status returned

Remarks

When both return and err_code are 0, no taxes were found, but there is no error. The base_sale returned will equal the charge sent in. If the charge sent in is insufficient to cover the taxes generated, then no taxes will be calculated and the err_code will be set to -37. An error will be logged to the status file indicating an insufficient charge error occurred.

**Note**: Non-billable taxes are not included in the calculation of the base sale amount. Adding the base sale amount and all taxes that appear in the log for a transaction may result in a value greater than the target amount, as any non-billable taxes returned by the transaction *will* be included in that total.

EZTaxAdjTPPEx

Description

EZTaxAdjTPPEx accepts Tangible Personal Property (TPP) transaction data and performs appropriate tax calculations required to refund or credit taxes. The user provides up to three addresses: Ship From, Ship To and Point of Acceptance. Rules will be applied against the input addresses to determine in what jurisdiction any SALES or USE taxation would be applicable. A Nexus Table may optionally be provided; if so it will be checked to determine if nexus exists in the state found to have taxing jurisdiction. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports.

Format

short int EZTaxAdjTPPEx(EZTaxSession session, struct TPP_addrEx *tpp_trans, int discount_type, struct nexus_table *nex_tab, short int nexus_count, int adj_method, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[0]: Indicates no tax data available for transaction (not taxable) or an error has occurred.

[n]: Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session : session handle returned when initialized with call to EZTaxInitEx

*tpp_trans : transaction information

discount_type : discount type code

*nex_tab : the nexus table

nexus_count : count of the entries in the nexus table

adj_method : adjustment method (DLM)

*err_code : error status returned

Remarks

Nexus Table

The Nexus Table (see structure definition below) provides a list of USPS state abbreviations, each with a flag indicating whether the user has nexus in that state. This table is optional. If the table is not provided, nexus is assumed in all states. The user is responsible for establishing this table and passing it to EZtax.

Interface data structures are also described in detail in the AFC Data Structures section. The section AFC Calculations explains how taxes are returned to the user in detail.

Minimum Requirements

Ship From address must be provided. Address structure must include COUNTRY ISO, STATE, LOCALITY, and ZIP CODE. All fields in any unused address must be NULL.

If only the Ship From address is provided, the transaction will always be INTRASTATE, and Ship From will be the taxing jurisdiction. If only Ship From and Point-of-Acceptance addresses are given, Point-of- Acceptance is used as the Ship To address.

The Transaction Type and Service Type fields of the tax_data structure are set within this function. Any value previously set will be ignored.

In addition to other error codes that may be set for AFC API function calls, the following in particular apply to EZTaxAdjTPPEx-

-27 Missing or Invalid Ship From Address

-28 Invalid Ship To Address

-29 Invalid Point-of-Acceptance

-30 Invalid State Input

EZTaxAdjZipEx

Description

EZTaxAdjZipEx accepts transaction data and performs appropriate tax calculations required to refund or credit taxes for U.S. jurisdictions (Debit transactionss use EZTaxAdjDebitEx API’s). If the AFC Session was started with the tax log open, appropriate taxes reductions are logged and will be reflected in tax reports. The tax jurisdiction is specified using address information, identical to EZTaxZipEx.

Format

short int EZTaxAdjZipEx(EZTaxSession session, struct zip_codeEx *trans, int discount_type, int adj_method, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[0] : Indicates no tax data available for transaction (not taxable) or an error has occurred.

[n] : Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session : session handle returned when initialized with call to EZTaxInitEx

*trans : zip code transaction information

discount_type : discount type code

adj_method : adjustment method (DLM)

*err_code : error status returned

Remarks

This API is used for tax adjustments for U.S. jurisdictions.

Returns tax adjustments identical to method used for returning tax calculations. Interface data structures are also described in detail in the AFC Data Structures section. The section AFC Calculations explains how taxes are returned to the user in detail.

EZTaxBridgeConference

Description

EZTaxBridgeConference was designed and intended for calculating tax specifically for a bridge conference with a Billing, Host, Bridge and list of participants.

Exported Function Format

EZTaxBridgeConference(EZTaxSession session, BridgeConferenceTransaction* bconft, int *err_code);

Return Value List

0: No taxes calculated or an error was found

n: Indicates number of taxes stored in the applicable tax array for this transaction

Parameters

session : session handle returned when initialized with call to EZTaxInitEx

*bconft : bridge conference transaction information

*err_code : error status returned

Remarks

When both return and err_code are 0, no taxes were found, but there is no error.

EZTaxCalcJurisdiction

Description

EZTaxCalcJurisdiction returns the JCode that has jurisdiction at the most detailed taxing level.

Format

unsigned long int EZTaxCalcJurisdiction (EZTaxSession session, struct J_CodeEx *trans, int *err_code)

Header(s) Required

EZTaxStruct.h

EZTaxDefine.h

EZTaxProto.h

Libraries

EZTax2.lib

Return Value List

The most detailed jurisdiction determined to be applicable based on the transaction information; however, if there is an error, both JCODE_NOT_FOUND (-11) and err_code zero are returned.

Parameters

session : session handle returned when initialized with call to EZTaxInitEx

*trans : J-code transaction information

Remarks

This API call does not log the taxes or calculate and return a tax table. It does apply the jurisdiction rules to determine what taxing authority has jurisdiction for that transaction.

EZTaxClearExclusion

Description

EZTaxClearExclusion is used to remove all exclusions that have been set.

Format

short int EZTaxClearExclusion(EZTaxSession session);

Header(s) Required

EZTaxProto.h

Libraries

EZTax2.lib

Return Value List

TRUE : was successful.

FALSE : failed.

Parameters

Session : session handle returned when initialized with call to EZTaxInitEx

Remarks

None

EZTaxClearTSR

Description

EZTaxClearTSR allows API functionality to delete the data created by EZTaxGetTSR. This is used to prevent memory leaks during operation.

Format

void EZTaxClearTSR(EZTaxSession session, struct rtr_data* rpt)

Return Value List

Void

Parameters

session: session handle returned for session when initialized with call to EZTaxInitEx

rpt: pointer to the T/S Report created by EZTaxGetTSR. This will be cleared from memory by EZTaxClearTSR.

Remarks

None

EZTaxConvertExemption

Description

Convert tax_exempt struct to form usable by the engine.

Exported Function Format

short int EZTaxConvertExemption(struct tax_exempt *exemption, unsigned geocode_in, short int ispcode_in, short int taxtype_in, short int taxlevel_in, short int category_in, short int scope_in, short int domain_in, short int incNbaFlag_in, short int ignLvlExFlag_in, int *err_code)

Return Value List

0: Error was found

1: Exemption successfully converted

Parameters

*exemption : exemption to convert

*err_code : error status returned

Remarks

None

EZTaxCountryToPCode

Description

EZTaxCountryToPCode takes a 3 byte country ISO code and converts it to the correct PCode for that country.

Format

unsigned long int EZTaxCountryToPCode(EZTaxSession session, const char* iso_code, int *err_code)

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

Libraries

EZTax2.lib

Return Value List

PCode : converted from the input fips code

0 : if conversion is unsuccessful

Parameters

session : session handle returned when initialized with call to EZTaxInitEx

*iso_code: 3 byte country ISO code to convert

*err_code : error status returned

Remarks

The value “UNS” will return the PCode for unsupported country. If the initial call fails due to the county code not being supported, this can be a fallback value to use.

EZTaxDbVersion

Description

Function EZTaxDbVersion reads the database version from EZTax.dll and returns it to the caller.

Format

short int EZTaxDbVersion(char *psz_EZTax_dat, char *psz_db_version);

Header(s) Required

EZTaxDefine.h

EZTaxProto.h

Libraries

EZTax2.lib

Return Value List

TRUE if database version is returned in psz_db_version

FALSE if database version couldn't be obtained

Parameters

*psz_EZTax_dat : path to EZTax.dat file

*psz_db_version : address of character array that will receive the database version.

Remarks

The database version will be returned in the form ww.xx.yy.zz, where each piece of the database version number can be 1 or 2 digits.

EZTaxDebitJEx

Description

EZTaxDebitJEx accepts transaction data and performs appropriate tax calculations. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. BTN, origination and termination information is passed using JCodes.

Format

short int EZTaxDebitJEx(EZTaxSession session, struct J_CodeEx *trans, int *err_code)

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[0] : Indicates no tax data available for transaction (not taxable) or an error has occurred.

[n] : Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session : session handle returned when initialized with call to EZTaxInitEx

*trans : J-code transaction information

*err_code : error status returned

Remarks

Interface data structures are also described in detail in the AFC Data Structures section. The section AFC Calculations explains how taxes are returned to the user in detail.

Returns tax adjustments identical to method used for returning tax calculations.

EZTaxDebitNEx

Description

EZTaxDebitNEx accepts transaction data and performs appropriate tax calculations. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. BTN, origination and termination information is passed using NPANXXs.

Format

short int EZTaxDebitNEx(EZTaxSession session, struct NPANXX_codeEx *trans, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[0] : Indicates no tax data available for transaction (not taxable) or an error has occurred.

[n] : Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session : session handle returned when initialized with call to EZTaxInitEx

*trans : NPANXX transaction information

*err_code : error status returned

Remarks

Interface data structures are also described in detail in the AFC Data Structures section. The section AFC Calculations explains how taxes are returned to the user in detail.

EZTaxDebitPEx

Description

EZTaxDebitPEx accepts transaction data and performs appropriate tax calculations. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. BTN, origination and termination information is passed using PCodes.

Format

short int EZTaxDebitPEx(EZTaxSession session, struct P_CodeEx *trans, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[0] : Indicates no tax data available for transaction (not taxable) or an error has occurred.

[n] : Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session : session handle returned when initialized with call to EZTaxInitEx

*trans : P-code transaction information

*err_code : error status returned

Remarks

Interface data structures are also described in detail in the AFC Data Structures section. The section AFC Calculations explains how taxes are returned to the user in detail.

EZTaxDebitTaxInclusiveJCode (EZTaxDebitRevJCode deprecated)

Description

EZTaxDebitTaxInclusiveJCode accepts transaction data and performs a tax inclusive calculation for prepaid debit transactions to arrive at the base sale amount. The desired total (charge plus all taxes) is placed in the ‘charge’ field in the transaction, and base charge necessary to generate that total is returned in the ‘base_sale’ parameter. Taxes for the desired transaction are returned in the same manner as EZTaxJCodeEx. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. BTN, origination and termination information is passed using JCodes. The base sale amount will also be stored in the ‘optional’ field in the log output, converted to an integer.

Format

short int EZTaxDebitTaxInclusiveJCode(EZTaxSession session, struct J_CodeEx *trans, double *base_sale, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[-1]: A critical error occurred while preparing the tax inclusive calculation session

[0] : No taxes calculated or an error was found

[n]: Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session: session handle returned when initialized with call to EZTaxInitEx

*trans: transaction information

*base_sale: calculated charge returned

*err_code: error status returned

Remarks

When both return and err_code are 0, no taxes were found, but there is no error. The base_sale returned will equal the charge sent in. If the charge sent in is insufficient to cover the taxes generated, then no taxes will be calculated and the err_code will be set to -37. An error will be logged to the status file indicating an insufficient charge error occurred.

**Note**: Non-billable taxes are not included in the calculation of the base sale amount. Adding the base sale amount and all taxes that appear in the log for a transaction may result in a value greater than the target amount; any non-billable taxes returned by the transaction *will* be included in the total.

EZTaxDebitTaxInclusiveNPAN (EZTaxDebitRevNPAN deprecated)

Description

EZTaxDebitTaxInclusiveNPAN accepts transaction data and performs a tax inclusive calculation for prepaid debit transactions to arrive at the base sale amount. The desired total (charge plus all taxes) is placed in the ‘charge’ field in the transaction, and base charge necessary to generate that total is returned in the ‘base_sale’parameter. Taxes for the desired transaction are returned in the same manner as EZTaxNPANEx. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. BTN, origination and termination information is passed using NPANXXs. The base sale amount will also be stored in the ‘optional’ field in the log output, converted to an integer.

Format

short int EZTaxDebitTaxInclusiveNPAN(EZTaxSession session, struct NPANXX_CodeEx *trans, double *base_sale, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[-1]: A critical error occurred while preparing the tax inclusive calculation session

[0]: No taxes calculated or an error was found

[n]: Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session: session handle returned when initialized with call to EZTaxInitEx

*trans: transaction information

*base_sale: calculated charge returned

*err_code: error status returned

Remarks

When both return and err_code are 0, no taxes were found, but there is no error. The base_sale returned will equal the charge sent in. If the charge sent in is insufficient to cover the taxes generated, then no taxes will be calculated and the err_code will be set to -37. An error will be logged to the status file indicating an insufficient charge error occurred.

**Note**: Non-billable taxes are not included in the calculation of the base sale amount. Adding the base sale amount and all taxes that appear in the log for a transaction may result in a value greater than the target amount; any non-billable taxes returned by the transaction *will* be included in the total.

EZTaxDebitTaxInclusiveZip (EZTaxDebitRevZip deprecated)

Description

EZTaxDebitTaxInclusiveZip accepts transaction data and performs a tax inclusive calculation for prepaid debit transactions to arrive at the base sale amount. The desired total (charge plus all taxes) is placed in the ‘charge’ field in the transaction, and base charge necessary to generate that total is returned in the ‘base_sale’ parameter. Taxes for the desired transaction are returned in the same manner as EZTaxJCodeEx. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. The base sale amount will also be stored in the ‘optional’ field in the log output, converted to an integer.

This function passes tax jurisdiction information to AFC by specifying the appropriate zip code, state identifier, county, and locality. AFC uses this information to determine the JCode used for tax calculations. It is important to supply complete address information; there are many duplicate zip codes and localities contained within the AFC database tables. AFC always returns the first match of the data supplied.

Supplying incomplete information can result in tax calculations for an unexpected jurisdiction. When information regarding the locality is not supplied, AFC may be limited to data based upon the county or parish involved. Likewise, when information about the county is not supplied, the EZtax engine may be limited to performance of calculations based upon the state and zip code identifiers.

Format

short int EZTaxDebitTaxInclusiveZip(EZTaxSession session, struct zip_codeEx *trans, double *base_sale, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[-1]: A critical error occurred while preparing the tax inclusive calculation session

[0]: No taxes calculated or an error was found

[n]: Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session: session handle returned when initialized with call to EZTaxInitEx

*trans: transaction information

*base_sale: calculated charge returned

*err_code: error status returned

Remarks

When both return and err_code are 0, no taxes were found, but there is no error. The base_sale returned will equal the charge sent in. If the charge sent in is insufficient to cover the taxes generated, then no taxes will be calculated and the err_code will be set to -37. An error will be logged to the status file indicating an insufficient charge error occurred.

**Note**: Non-billable taxes are not included in the calculation of the base sale amount. Adding the base sale amount and all taxes that appear in the log for a transaction may result in a value greater than the target amount; any non-billable taxes returned by the transaction *will* be included in the total.

EZTaxDllVersion

Description

Function EZTaxDllVersion returns the version number of the AFC API.

Format

short int EZTaxDllVersion(char *psz_library_version);

Header(s) Required

EZTaxDefine.h

EZTaxProto.h

Libraries

EZTax2.lib

Return Value List

TRUE : if the database version is returned in psz_library_version

FALSE : if database version couldn't be obtained

Parameters

psz_library_version : version string returned

Remarks

The version string is the same value that is displayed in the EZTax.sta status file.

EZTaxExit

Description

EZTaxExit writes the contents of database buffers to disk, de-allocates memory, closes databases and performs other clean-up duties which free up resources utilized by EZtax. This function will then exit the AFC system.

EZTaxExit terminates all sessions that were created with calls to EZTaxInit in addition to processes mentioned above.

Format

short int EZTaxExit(EZTaxSession session)

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

Libraries

EZTax2.lib

Return Value List

always returns TRUE

Parameters:

Void

Remarks

EZTaxExit must be called to terminate all existing AFC Session(s). EZTaxExit will close any sessions still running.

EZTaxExitSessionEx

Description

EZTaxExitSessionEx will terminate a session specified by valid session handle. EZTaxExitSessionEx writes the current internal tax log buffers to the tax log disk file, de-allocates cached database memory, closes all AFC database files, and performs other clean-up duties which free up resources utilized for the specified session.

Format

short int EZTaxExitSessionEx(EZTaxSession session);

Header(s) Required

EZTaxProto.h

Libraries

EZTax2.lib

Return Value List

TRUE : if session exited successfully

FALSE : if an error occurred

Parameters

session : session handle returned when initialized with call to EZTaxInitEx

Remarks

The session handle and the struct taxes_tbl * returned by EZTaxInitEx during the initialization of the given session handle are invalidated by a call to this function. Attempting to use either after a call to EZTaxExitSessionEx will cause errors.

EZTaxFlushToLogEx

Description

EZtax FlushToLogEx writes the current internal tax log buffers to the tax log disk file. The internal tax log buffers are normally written to when they are filled to capacity or EZTaxExit is called. This function can be called to force a write to tax log disk file.

Format

short int EZTaxFlushToLogEx(EZTaxSession session);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

always returns TRUE

Parameters

session : session handle returned when initialized with call to EZTaxInitEx

Remarks

EZTaxFlushToLogEx writes the content of internal tax log buffers to disk.

EZTaxFreeRates

Description

EZTaxFreeRates frees up the memory from the table of all taxes for a jurisdiction returned from EZTaxGetRates

Format

short int EZTaxFreeRates(struct jurisdictionTaxes *taxes);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

Libraries

EZTax2.lib

Return Value List

always returns 0

Parameters

*taxes : tax information to be freed

Remarks

None

EZTaxFtoPCodeEx

Description

EZTaxFtoPCodeEx converts a Fips Code into a PCode. Zero is returned if not found.

Format

unsigned long int EZTaxFtoPCodeEx(EZTaxSession session, char *Fips, int *err_code)

Header(s) Required

EZTaxDefine.h

EZTaxProto.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

PCode : converted from the input fips code 0 : if conversion is unsuccessful

Parameters

session : session handle returned when initialized with call to EZTaxInitEx

*Fips: Fips code to convert

*err_code : error status returned

Remarks

None

EZTaxGetAddressEx

Description

EZTaxGetAddressEx utilizes a J-Code as input to produce the location/address data for the jurisdiction identified by the J-Code.

Format

short int EZTaxGetAddressEx(EZTaxSession session, unsigned long int j_code, struct address_data_p4 *address, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

Libraries

EZTax2.lib

Return Value List

NOT_FOUND : EZTaxGetAddressEx failed due to invalid JCode or an error has occurred.

FOUND : EZTaxGetAddressEx successfully retrieved address

MORE : EZTaxGetAddressEx successfully retrieved address and other valid addresses exist for this jurisdiction. Other address can be obtained by calling EZTaxNextAddressEx.

Parameters

Session : session handle returned when initialized with call to EZTaxInitEx

j_code : j-code to find an address for

*address : the address information returned

*err_code : error status code

Remarks

None

EZTaxGetCustomLog

Description

EZTaxGetCustomLog is a routine that returns a pointer to a log structure, which is used for customized logging.

Format

struct EZTax_logEx *EZTaxGetCustomLog(EZTaxSession session)

Return Value List

NULL : Indicates an error has occurred

pointer : The logging structure pointer

Parameters

session: session handle returned with call to initialize the AFC Session.

Remarks

This function is used after a call to initialize the AFC Session and before any taxes are calculated. The log structure returned can be used to call EZTaxWriteToLogEx to output the information to the AFC log. EZTaxGetCustomLogCount can be used to get the record count in the log table as needed.

When a transaction has been processed, the custom log structure will contain the tax information generated by that transaction.

The value in eztax_logEx.p_code is the jcode representation of the jurisdiction.

EZTaxGetCountryID

Description

EZTaxGetCountryID returns the country ID associated with the PCode passed in.

For a list of country IDs, refer to the Country Id column listed under “Appendix A – Supported Country Codes” in document TM_00561_AFC Comprehensive Guide to Reports and Data Files.

Format

unsigned int EZTaxGetCountryID(EZTaxSession session, unsigned long int PCode, int *err_code);

Return Value List

unsigned int representing the country id associated with the PCode passed in.

Parameters

session : Session object returned for session when initialized with call to EZTaxInitEx.

PCode : AFC proprietary code representing a taxing jurisdiciton

*err_code: Error codes returned. See the header EZTaxDefine.h for definitions.

Remarks

None

EZTaxGetCustomLogCount

Description

Function returns the number of records in the current custom log table. This function can be used in conjunction with EZTaxGetCustomLog() which returns a pointer to the custom log table.

Format

short int EZTaxGetCustomLogCount(EZTaxSession session)

Return Value List

Count of records : 0 if no records exist, else the number of records in the custom log table.

Parameters

session: session handle returned with call to initialize the AFC Session.

Remarks

GetCustomLogCount returns the number of taxes contained in the EZTaxGetCustomLog structure. The log count includes no summarization. The log count always includes the non- billable tax count.

EZTaxGetHandle

Description

EZTaxGetHandle returns the handle object given the session.

Format

long int EZTaxGetHandle(EZTaxSession session);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

Libraries

EZTax2.lib

Return Value List

Handle : value if found

[-1] : otherwise

Parameters

session: session handle returned when initialized with call to EZTaxInitEx

Remarks

None

EZTaxGetJurisdiction

Description

EZTaxGetJurisdiction retrieves the jurisdiction where the transaction is determined to be taxed at. Current use is in the batch executables that report tax revenue group by state.

Format

unsigned long int EZTaxGetJurisdiction(EZTaxSession session, struct J_CodeEx trans, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

Libraries

EZTax2.lib

Return Value List

[0]: if jurisdiction is not found

JCcode : otherwise

Parameters

session : session handle returned when initialized with call to EZTaxInitEx

trans : transaction information

*err_code : error status returned

Remarks

None

EZTaxGetLogName

Description

EZTaxGetLogName retrieves the log filename when it is specified using the filelocs.txt. Current use is in the batch executables that open the log file and must know the filename.

Format

short int EZTaxGetLogName(EZTaxSession session, char *filename);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

Libraries

EZTax2.lib

Return Value List

SESSION_NOT_INIT : if session handle is invalid

TRUE : otherwise

Parameters

session: session handle returned when initialized with call to EZTaxInitEx

*filename: filename from filelocs.txt configuration file or paths variable EZTaxInitEx was called with

Remarks

None

EZTaxGetLogV914

Description

EZTaxGetLogV914 is a routine that returns a pointer to a log structure, which is used for customized logging.

Format

struct eztax_log_v914 *EZTaxGetLogV914(EZTaxSession session)

Return Value List

NULL : Indicates an error has occurred

pointer : The v914 logging structure pointer

Parameters

session: session handle returned with call to initialize the AFC Session.

Remarks

This function is used after a call to initialize the AFC Session and before any taxes are calculated. The log structure returned can be used to call EZTaxWriteToLogV914 to output the information to the AFC log. EZTaxGetLogV914Count can be used to get the record count in the log table.

When a transaction has been processed, the V914 tax log structure will contain the tax information generated by that transaction. In addition it will contain the charge and t/s pair used in the tax calculation. This can be valuable when processing bundled transactions, as the t/s pair will be the bundled product and the charge the % allocated to this t/s pair.

The value in eztax_log_v914.p_code is the jcode representation of the jurisdiction.

EZTaxGetLogV914Count

Description

Function returns the number of records in the current custom log table. This function can be used in conjunction with EZTaxGetLogV914 () which returns a pointer to the v9114 tax log table.

Format

short int EZTaxGetLogV914Count (EZTaxSession session)

Return Value List

Count of records : 0 if no records exist, else the number of records in the v914 tax log table.

Parameters

session: session handle returned with call to initialize the AFC Session.

Remarks

GetLogV914Count returns the number of taxes contained in the EZTaxGetLogV914 structure. The log count includes no summarization. The log count always includes the non-billable tax count.

EZTaxGetNoTaxTrans

Description

Function returns a pointer to a no-tax transaction structure, which is used for for tracking transactions that produce no taxes.

Format

struct no_tax_tbl *EZTaxGetNoTaxTrans(EZTaxSession session);

Return Value List

NULL : Indicates an error has occurred

pointer : The no tax transaction structure pointer

Parameters

session: session handle returned when initialized with call to EZTaxInitEx

Remarks

This function is used after a call to EZTaxInitEx.

EZTaxGetRates

Description

EZTaxGetRates utilizes a PCode as input to produce the table of all taxes for that jurisdiction.

Format

short int EZTaxGetRates(EZTaxSession session, unsigned long int p_code, struct jurisdictionTaxes *taxes, int *err_code)

Header (s) Required

EZTaxProto.h

EZTaxDefine.h

Libraries

EZTax2.lib

 

Return Value List

Success: 0

Failure: 1

Parameters

pCode : jurisdiction to get rate information for

*taxes : tax rates

*err_code : error codes

Remarks

None

EZTaxGetStateID

Description

EZTaxGetStateID returns the state id associated with the PCode passed in.

For a list of US state codes, refer to the Id column listed under “Appendix B – Supported States, Territories and Provinces” in document TM_00561_AFC Comprehensive Guide to Reports and Data Files.

Format

unsigned int EZTaxGetStateID (EZTaxSession session, unsigned long int PCode, int *err_code);

Return Value List

unsigned int representing the state id associated with the PCode passed in.

Parameters

session : Session object returned for session when initialized with call to EZTaxInitEx.

PCode : AFC proprietary code representing a taxing jurisdiciton

*err_code: Error codes returned. See the header EZTaxDefine.h for definitions.

Remarks

None

EZTaxGetTaxCatV98

Description

EZTaxGetTaxCatV98 retrieves the tax category description for a specified tax code. Current use is in utilities reporting from the log, but users can also use this new feature.

Format

char *EZTaxGetTaxCatV98(EZTaxSession session, int taxCode);

Header (s) Required

EZTaxProto.h

EZTaxDefine.h

Libraries

EZTax2.lib

Return Value List

the tax category description

Parameters

session : session handle returned when initialized with call to EZTaxInitEx

taxCode : the tax type to get the description for

Remarks

None

EZTaxGetTaxDescription

Description

EZTaxGetTaxDescription retrieves the tax description for a specified tax code. Current use is in utilities reporting from the log, but users can also use this new feature.

Format

char *EZTaxGetTaxDescription(EZTaxSession session, int taxCode);

Header (s) Required

EZTaxProto.h

EZTaxDefine.h

Libraries

EZTax2.lib

Return Value List

the tax description

Parameters

session : session handle returned when initialized with call to EZTaxInitEx

taxCode : the tax type to get the description for

Remarks

None

EZTaxGetTSR

Description

EZTaxGetTSR allows applications API functionality to get the transaction service report. A flag is used to specify whether the report data should be returned or written to file.

Format

struct rtr_data* EZTaxGetTSR(EZTaxSession session, int *size, short int returnData)

Return Value List

Pointer to rtr_data : if method succeeded AND returnData is true

NULL : otherwise

Parameters

session: session handle returned with call to initialize the AFC Session.

size : an integer passed by reference that will be set to the size of the returned array

returnData : flag that determines if the TSR data should be returned or written to file.

Remarks

EZTaxGetTSR returns a pointer to an array of data. This data is cleared from memory using EZTaxClearTSR. Using EZTaxGetTSR without calling EZTaxClearTSR can lead to memory leaks.

If returnData is false, the function flushes the TSR data to file and clears the data from memory.

If returnData is true, the function returns the TSR data as an array and does not clear the data. Once the returned data is processed and no longer needed, the calling application should call EZTaxClearTSR() to clear the data from memory.

EZTaxGroupResults

Description

This function sets the mode that AFC uses to group the returned taxes by. After calling this function, the results in the tax return table will be grouped as specified by the groupMode parameter.

Format

short int EZTaxGroupResults(EZTaxSession session, unsigned long int groupMode);

Header (s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

short int : TRUE or FALSE indicating if the function succeeded or not.

Parameters:

int groupMode: Constant indicating how tax calculation results should be returned. The options to group taxes by tax level are following:

  • GROUP_SAME_LEVEL: Indicates that taxes at the same level should be grouped together.
  • GROUP_CO_LOCAL: When using this option, AFC will group all state taxes into a single record, and county and local taxes will be grouped together into a separate record.
  • GROUP_ST_CO_LOCAL. State, county and local taxes will be grouped together.

The options to group sales taxes separately may be appended to a tax level option by using the bitwise OR operator (|). These options are:

  • GROUP_SALES: Sales taxes (tax type 1) and Use Taxes (tax type 49) will be grouped separately from other taxes.
  • GROUP_SALES_CATEGORY: All taxes in the sales tax category will be grouped into a single record.

The DEFAULT option may be used to disable tax grouping. These options are included in the EZTaxDefine.h header file.

EZTaxInitDirEx

Description

EZTaxInitDirEx reads AFC files and initializes the AFC system. Multiple calls may be made to set up completely independent sessions.

Format

struct enhanced_taxes_tbl *EZTaxInitDirEx(short int tax_log, struct file_path *paths, EZTaxSession *session, char *directory);

Header(s) Required

EZTaxProto.h

EZTaxStruct.h

EZTaxDefine.h

Libraries

EZTax2.lib

Return Value List

pointer : to structure where taxes are returned later

NULL : if an error occurred

Parameters

tax_log : flag to log taxes or not

*paths : data structure with file-paths, if null or incomplete, paths are read from file_locs.txt

*session : session handle returned

*directory : name of directory that AFC will search for EZTax.cfg and filelocs.txt

Remarks

This function initializes and starts an AFC Session.

Multiple sessions can be initialized by successive calls to EZTaxInitDirEx.

EZTaxInitEx

Description

EZTaxInitEx reads AFC files and initializes the AFC system. Multiple calls may be made to set up completely independent sessions.

Format

struct enhanced_taxes_tbl *EZTaxInitEx(short int tax_log, struct file_path *paths, EZTaxSession *session);

Header(s) Required

EZTaxProto.h

EZTaxStruct.h

EZTaxDefine.h

Libraries

EZTax2.lib

Return Value List

pointer : to structure where taxes are returned later

NULL : if an error occurred

Parameters

tax_log : flag to log taxes or not

*paths : data structure with file-paths, if null or incomplete, paths are read from file_locs.txt

*session : session handle returned

Remarks

This function initializes and starts an AFC Session.

Multiple sessions can be initialized by successive calls to EZTaxInitEx.

EZTaxInitExMT

Description

EZTaxInitExMT reads AFC files and initializes the AFC system. Multiple calls may be made to set up completely independent sessions.

Format

struct enhanced_taxes_tbl *EZTaxInitEx(short int tax_log, struct file_path *paths, EZTaxSession *session, char *directory);

Header(s) Required

EZTaxProto.h

EZTaxStruct.h

EZTaxDefine.h

Libraries

EZTax2.lib

Return Value List

pointer : to structure where taxes are returned later

NULL : if an error occurred

Parameters

tax_log : flag to log taxes or not

*paths : data structure with file-paths, if null or incomplete, paths are read from file_locs.txt

*session : session object returned

*directory : name of directory that AFC will search for EZTax.cfg and filelocs.txt

Remarks

This function initializes and starts an AFC Session.

This function is designed to be thread-safe - other sessions on other threads can be running AFC calculations when this function is called.

Be sure to call EZTaxExitSessionEx for each EZTaxSession object created by EZTaxInitExMT. EZTaxExit will not close sessions created by EZTaxInitExMT. Failure to call EZTaxExitSessionEx will result in memory leaks.

EZTaxInitV914

Description

EZTaxInitV914 reads AFC files and initializes the AFC system. Multiple calls may be made to set up completely independent sessions.

The input structure allows all optional input files to be specified through the initialization method. This method does not use filelocs.txt and will ignore exclusion, nexus and bundle file settings in EZTax.cfg.

Format

struct enhanced_taxes_tbl * EZTaxInitV914(short int tax_log_enabled, struct file_path_v914 *paths, EZTaxSession *session);

Return Value List

pointer : to structure where taxes are returned later

NULL : if an error occurred

Parameters

tax_log_enabled : flag to enable the log taxes process

*paths : data structure with file-paths.

*session : session object returned

*directory : name of directory that AFC will search for EZTax.cfg and filelocs.txt

Remarks

This function initializes and starts an AFC Session and is designed to be thread-safe - other sessions on other threads can be running AFC calculations when this function is called.

Be sure to call EZTaxExitSessionEx for each EZTaxSession object created by EZTaxInitV914. EZTaxExit will not close sessions created by EZTaxInitV914. Failure to call EZTaxExitSessionEx will result in memory leaks.

EZTaxInitV98

Description

EZTaxInitV98 reads AFC files and initializes the AFC system. It differs from EZTaxInitExMT in that the tax table returned includes tax category information. Multiple calls may be made to set up completely independent sessions.

Format

struct taxes_tbl_v98 *EZTaxInitV98(short int tax_log, struct file_path *paths, EZTaxSession *session, char *directory);

Header(s) Required

EZTaxProto.h

EZTaxStruct.h

EZTaxDefine.h

Libraries

EZTax2.lib

Return Value List

pointer : to structure where taxes are returned later

NULL : if an error occurred

Parameters

tax_log : flag to log taxes or not

*paths : data structure with file-paths, if null or incomplete, paths are read from file_locs.txt

*session : session object returned

*directory : name of directory that AFC will search for EZTax.cfg and filelocs.txt

Remarks

This function initializes and starts an AFC Session.

This function is designed to be thread-safe - other sessions on other threads can be running AFC calculations when this function is called.

**Note**: Be sure to call EZTaxExitSessionEx for each EZTaxSession object created by EZTaxInitV98. EZTaxExit will not close sessions created by EZTaxInitV98. Failure to call EZTaxExitSessionEx will result in memory leaks.

EZTaxJCodeEx

Description

EZTaxJCodeEx accepts transaction data and performs appropriate tax calculations. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. BTN, origination and termination information is passed using JCodes.

Format

short int EZTaxJCodeEx(EZTaxSession session, struct J_CodeEx *trans, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[0] : No taxes calculated or an error was found

[n] : Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session : session handle returned when initialized with call to EZTaxInitEx

*trans : transaction information

*err_code : error status returned

Remarks

When both return and err_code are 0, no taxes were found, but there is no error.

EZTaxJtoPCodeEx

Description

EZTaxJtoPCodeEx Returns PCode that is cross-referenced to a JCode.

Format

unsigned long int EZTaxJtoPCodeEx(EZTaxSession session, unsigned long int JCode, int *err_code);

Header(s) Required

EZTaxDefine.h

EZTaxProto.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

PCode : for the input jcode if found, 0 otherwise

Parameters

session: Session handle returned when initialized with call to EZTaxInitEx

JCode: j-code to convert

*err_code: Error status returned

Remarks

None

EZTaxJTTypeEx

Description

Returns transaction type for a given pair of JCodes indicating whether the call is interstate or intrastate. The first JCode is the originating and the second the terminating JCode. Will set error code to INTERSTATE_NOT_VALID_FOR_INTERNATIONAL_CALLS if the originating country and terminating country are not the same.

(EZTaxJTType deprecated)

The returned value can also be used to determine service types. For example, for transaction types, 19, 20, 21, and 59, the interstate service type is 49 and the intrastate service is 50. For transaction type 61, the interstate service is 585, and the intrastate service is 586. The caller is responsible to map INTERSTATE or INTRASTATE to the right service type.

Format

short int EZTaxJTTypeEx(EZTaxSession session, unsigned long int orig_J_Code, unsigned long int term_J_Code, int* err_code)

Return Value List

INTERSTATE or INTRASTATE : depending on the origination and termination States.

Parameters

session: Session handle returned when session was initialized

orig_J_Code: origination j-code

term_J_Code: termination j-code

*err_code : error status returned

Remarks

This call will eventually be deprecated. Recommend usage of EZTaxPTTypeEx(…) which works with PCodes in place of this call.

EZTaxLogicOvrJCodeEx

Description

EZTaxLogicOvrJCodeEx specifies a logic override for a specific tax. TaxJurisdiction information is passed via jurisdiction code. It takes a J_Code and a logicOverride structure as input and inserts a logic override into the EZTax db system.

Exported Function Format

short int EZTaxLogicOvrJCodeEx(EZTaxSession session, unsigned long int j_code, struct logicOverride *over)

Parameters

session : Session object returned for session when initialized with a call to EZTaxInitEx

j_code : Specifies jurisdiction to override via JCode

*over : pointer to override information in the logic override form

See struct logicOverride in EZTaxStruct.h for detailed information. Note that this structure points to other structures with detailed information on effective date for each logic change. Interface data structures are also described in detail in the EZTax Data Structuressection.

Return Value List

FALSE : Override failed

TRUE : Override established

Remarks

Taxes which are overridden are in effect from the time the override is established until the EZTax session is terminated. All overrides can be removed from the system using the method EZTaxRestore.

Overrides must be approached with caution. The system allows overrides of all logic and allows you to specify the scope of the override. Overriding logic on a state or county level can impact taxes in excess of a thousand jurisdictions in some cases. Further detail is contained in the EZTax Data Structure section.

EZTaxLogicOvrJCodeExP

Description

EZTaxLogicOvrJCodeEx specifies a logic override for a specific tax. Tax Jurisdiction information is passed via jurisdiction code. It takes a J_Code and a logicOverride structure as input and inserts a logic override into the EZTax db system.

Format

short int EZTaxLogicOvrJCodeExP(EZTaxSession session, unsigned long int j_code, struct logicOverride *over)

Header(s) Required

EZTaxDefine.h

EZTaxProto.h

EZTaxStruct.h

Libraries

EZTax2.lib

Parameters

session : Session object returned for session when initialized with call to EZTaxInitEx

j_code : Specifies jurisdiction to override via JCode

*over : pointer to override information in the logic override form

See struct logicOverride in EZTaxStruct.h for detailed information. Note that this structure points to other structures with detailed information on effective date for each logic change. Interface data structures are also described in detail in the EZTax Data Structures section.

Return Value List

FALSE : Override failed

TRUE : Override established

Remarks

Taxes which are overridden are in effect from the time the override is established until the EZTax session is terminated. All overrides can be removed from the system using the method EZTaxRestore.

Overrides must be approached with caution. The system allows overrides of all logic and allows the user to specify the scope of the override. Overriding logic on a state or county level can impact taxes in excess of a thousand jurisdictions in some cases. Further detail is contained in the EZTax Data Structure section.

EZTaxLogicOvrJCodeExUseTax

Description

EZTaxLogicOvrJCodeExUseTax specifies a logic override for a specific tax. Tax Jurisdiction information is passed via jurisdiction code. It takes a J_Code and a logicOverride structure as input and inserts a logic override into the EZTax db system.

Format

short int EZTaxLogicOvrJCodeExUseTax(EZTaxSession session, unsigned long int j_code, struct logicOverride *over)

Header(s) Required

EZTaxDefine.h

EZTaxProto.h

EZTaxStruct.h

Libraries

EZTax2.lib

Parameters

session : Session object returned for session when initialized with call to EZTaxInitEx

j_code : Specifies jurisdiction to override via JCode

*over : pointer to override information in the logic override form. See struct logicOverride in EZTaxStruct.h for detailed information.

Note that this structure points to other structures with detailed information on effective date for each logic change. Interface data structures are also described in detail in the EZTax Data Structures section.

Return Value List

FALSE : Override failed

TRUE : Override established

Remarks

Taxes which are overridden are in effect from the time the override is established until the EZTax session is terminated. All overrides can be removed from the system using the method EZTaxRestore.

Overrides must be approached with caution. The system allows overrides of all logic and allows the user to specify the scope of the override. Overriding logic on a state or county level can impact taxes in excess of a thousand jurisdictions in some cases. Further detail is contained in the EZTax Data Structure section.

EZTaxMaxTaxCount

Description

EZTaxMaxTaxCount returns the maximum number of taxes that one transaction can generate.

Format

Short int EZTaxMaxTaxCount();

Header(s) Required

EZTaxProto.h

Libraries

EZTax2.lib

Return Value List

Count : Maximum tax count generated by one transaction

Parameters

None

Remarks

None

EZTaxNextAddressEx

Description

EZTaxNextAddressEx returns the next sequential record containing alternative address information for a specific JCode. This function can be used to obtain additional address for a specified jurisdiction when EZTaxGetAddressEx returns MORE, indicating additional information is available. The majority of jurisdictions have more than one set of address/zip code data associated with them.

Format

short int EZTaxNextAddressEx(EZTaxSession session, struct address_data_p4 *address, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

FOUND : is returned if last address found

MORE : is returned if an address is found and more addresses are available

NOT_FOUND : is returned if not found

Parameters

session : session handle returned when initialized with call to EZTaxInitEx

*address : address information

*err_code : error status returned

Remarks

None

EZTaxNextCustomerEx

Description

EZTaxNextCustomerEx puts the taxes calculated in the customer table into a customer tax table that the client can reference and reinitializes the customer table to prepare for the next set of customer records.

Format

int EZTaxNextCustomerEx(EZTaxSession session);

Libraries

EZTax2.lib

Header(s) Required

EZTaxProto.h,

EZTaxDefine.h,

EZTaxStruct.h

Return Value List

Tax count : positive if all taxes waiting have been returned

[-1] : if there was an error

[-1*tax count] : if more taxes are waiting to be retrieved

Parameters

session : Session handle returned for session when initialized with call to EZTaxInit.

References:

EZTaxSetInvoiceModeEx

EZTaxSetInvoiceModeV98

Remarks

To be used if the system is in Invoice Mode. Reinitializes the customer table to prepare for the next set of customer records when all waiting taxes have been retrieved. If the return value is negative (and not -1), EZTaxNextCustomerEx must be called again to retrieve more taxes. Interface data structures are also described in detail in the AFC Data Structures section.

**Note**: The summarized taxes returned when calling EZTaxNextCustomerEx are identical to the total of the individual taxes returned from the taxing APIs. Typically one or the other is used but not both. Combining the individual taxes and the summarized taxes will result in twice as much taxes as should be normal.

EZTaxNPANEx

Description

Function EZTaxNPANEx takes an NPANXX_codeEx struct as input and calculates taxes for the transaction. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. BTN, origination and termination information is passed using NPANXXs.

Format

short int EZTaxNPANEx(EZTaxSession session, struct NPANXX_codeEx *trans, int *err_code);

Header(s) Required

EZTaxProto.h,

EZTaxDefine.h,

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[n] : number of taxes returned

Parameters

session : Session handle returned when initialized with call to EZTaxInitEx

*trans : npanxx transaction information

*err_code : Error status returned

Remarks

Interface data structures are also described in detail in the AFC Data Structures section. The section AFC Calculations explains how taxes are returned to the user in detail.

EZTaxNtoJCodeEx

Description

EZTaxNtoJCodeEx returns JCode that is cross-referenced to an NPANXX

Format

unsigned long int EZTaxNtoJCodeEx (EZTaxSession session, unsigned long int npanxx, int *err_code);

Header(s) Required

EZTaxDefine.h

EZTaxProto.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

FALSE (0) : Indicates that the PCode specified was not found or an error has occurred.

JCode : Jurisdiction code

Parameters

session : Session handle returned when initialized with call to EZTaxInitEx

npanxx : 6 digit NPANXX (area code and exchange)

*err_code : Error codes returned. See the header EZTaxDefine.h for definitions.

Remarks

This function converts an NPANXX into a J-Code. If the supplied NPANXX was not found or an error has occurred 0 is returned, which is valid U.S. Federal level code. Please check the error code before using the JCode that is returned.

EZTaxNTTypeEx

Description

EZTaxNTTypeEx returns transaction type for a given pair of NPANXX’s indicating whether the call is interstate or intrastate. The first NPANXX is the originating and the second is the terminating NPANXX.

Format

short int EZTaxNTTypeEx(EZTaxSession session, unsigned long int orig_NPANXX, unsigned long int term_NPANXX);

Header(s) Required

EZTaxDefine.h

EZTaxProto.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[n] : 1 if the call was Interstate, 2 if the call was Intrastate

Parameters

session: Session handle returned when initialized with call to EZTaxInitEx

orig_NPANXX : A NPANXX for the originating part of the call.

term_NPANXX : A NPANXX for the terminating part of the call.

Remarks

This program takes the origination and termination NPANXXs as input and determines if the call if INTERSTATE or INTRASTATE and returns the corresponding response to the caller

EZTaxOldOvrJCodeEx

Description

EZTaxOldOvrJCodeEx specifies an override for a specific tax. Tax jurisdiction information is passed via jurisdiction code. It takes a J_Code and an override structure as input and inserts a tax override into the AFC db system.

Format

short int EZTaxOvrJCodeEx(EZTaxSession session, unsigned long int j_code, struct tax_ovrd *over);

Header(s) Required

EZTaxDefine.h

EZTaxProto.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

FALSE : Override failed

TRUE : Override established

Parameters

session : Session object returned for session when initialized with call to EZTaxInitEx or EZTaxInitExMT.

j_code : Specifies jurisdiction to override via JCode.

over : Pointer to structure that specifies specific tax to override. See struct tax_ovrd in EZTaxStruct.h for detailed information. Interface data structures are also described in detail in the AFC Data Structures section.

Remarks

Taxes which are overridden are in effect from the time the override is established until the AFC Session is terminated. All overrides can be removed from the system using the method EZTaxRestore.

Overrides must be approached with caution. The system allows overrides of all taxes and allows the user to specify the scope of the override. Overriding a tax on a state or county level can impact taxes in excess of a thousand jurisdictions in some cases. Further detail is containedin the AFC Data Structure section.

EZTaxOvrJCodeEx

Description

EZTaxOvrJCodeEx specifies an override for a specific tax. Tax Jurisdiction information is passed via jurisdiction code. It takes a J_Code and an override structure as input and inserts a tax override into the AFC db system.

Format

short int EZTaxOvrJCodeEx(EZTaxSession session, unsigned long int j_code, struct enhancedOverride *over)

Header(s) Required

EZTaxDefine.h

EZTaxProto.h

EZTaxStruct.h

Libraries

EZTax2.lib

Parameters

session : Session object returned for session when initialized with call to EZTaxInitEx

j_code : Specifies jurisdiction to override via JCode

*over : pointer to override information in the same form as returned by EZTaxGetRates. See struct enhancedOverride in EZTaxStruct.h for detailed information.

Note: This structure points to other structures with detailed information on effective date for each tax rate and tax bracket. Interface data structures are also described in detail in the AFC Data Structures section.

Return Value List

FALSE : Override failed

TRUE : Override established

Remarks

Taxes which are overridden are in effect from the time the override is established until the AFC Session is terminated. All overrides can be removed from the system using the method EZTaxRestore.

Overrides must be approached with caution. The system allows overrides of all taxes and allows the user to specify the scope of the override. Overriding a tax on a state or county level can impact taxes in excess of a thousand jurisdictions in some cases. Further detail is contained in the AFC Data Structure section.

EZTaxOvrJCodeWithAdd

Description

EZTaxOvrJCodeWithAdd specifies an override for a specific tax. Tax Jurisdiction information is passed via jurisdiction code. It takes a J_Code and an override structure as input and inserts a tax override into the EZTax db system.

Format

short int EZTaxOvrJCodeWithAdd(EZTaxSession session, unsigned long int j_code, struct enhancedOverride *over)

Headers Required

EZTaxDefine.h

EZTaxProto.h

EZTaxStruct.h

Libraries

EZTax2.lib

Parameters

session : Session object returned for session when initialized with call to EZTaxInitEx

j_code : Specifies jurisdiction to override via JCode

*over : pointer to override information in the same form as returned by EZTaxGetRates. See struct enhancedOverride in EZTaxStruct.h for detailed information. Note that this structure points to other structures with detailed information on effective date for each tax rate and tax bracket. Interface data structures are also described in detail in the EZTax Data Structures section.

Return Value List

FALSE : Override failed

TRUE : Override established

Remarks

Taxes which are overridden are in effect from the time the override is established until the EZTax session is terminated. All overrides can be removed from the system using the method EZTaxRestore.

Overrides must be approached with caution. The system allows overrides of all taxes and allows the user to specify the scope of the override. Overriding a tax on a state or county level can impact taxes in excess of a thousand jurisdictions in some cases. Further detail is contained in the EZTax Data Structure section.

EZTaxOvrNPANEx

Description

EZTaxOvrNPANEx specifies an override for a specific tax. Tax jurisdiction information is passed via NPANXX. It takes an NPANXX and an override structure as input and inserts a tax override into the AFC db system.

Format

short int EZTaxOvrNPANEx(EZTaxSession session, unsigned long int npanxx, struct enhancedOverride *over)

Header(s) Required

EZTaxDefine.h

EZTaxProto.h

EZTaxStruct.h

Libraries

EZTax2.lib

Parameters

session : Session object returned for session when initialized with call to EZTaxInitEx

npanxx : Specifies jurisdiction to override via NPANXX

*over : pointer to override information in the same form as returned by EZTaxGetRates. See struct enhancedOverride in EZTaxStruct.h for detailed information.

Note: This structure points to other structures with detailed information on effective date for each tax rate and tax bracket. Interface data structures are also described in detail in the AFC Data Structures section.

Return Value List

FALSE : Override failed

TRUE : Override established

Remarks

Taxes which are overridden are in effect from the time the override is established until the AFC Session is terminated. All overrides can be removed from the system using the method EZTaxRestore.

Overrides must be approached with caution. The system allows overrides of all taxes and allows the user to specify the scope of the override. Overriding a tax on a state or county level can impact taxes in excess of a thousand jurisdictions in some cases. Further detail is contained in the AFC Data Structure section.

EZTaxOvrPCodeEx

Description

EZTaxOvrPCodeEx specifies an override for a specific tax. Tax jurisdiction information is passed via permanent jurisdiction code. It takes a P_Code and an override structure as input and inserts a tax override into the AFC db system.

Format

short int EZTaxOvrPCodeEx(EZTaxSession session, unsigned long int p_code, struct enhancedOverride *over)

Header(s) Required

EZTaxDefine.h

EZTaxProto.h

EZTaxStruct.h

Libraries

EZTax2.lib

Parameters

session : Session object returned for session when initialized with call to EZTaxInitEx

p_code : Specifies jurisdiction to override via PCode

*over : pointer to override information in the same form as returned by EZTaxGetRates. See struct enhancedOverride in EZTaxStruct.h for detailed information.

Note: This structure points to other structures with detailed information on effective date for each tax rate and tax bracket. Interface data structures are also described in detail in the AFC Data Structures section.

Return Value List

FALSE : Override failed

TRUE : Override established

Remarks

Taxes which are overridden are in effect from the time the override is established until the AFC Session is terminated. All overrides can be removed from the system using the method EZTaxRestore.

Overrides must be approached with caution. The system allows overrides of all taxes and allows the user to specify the scope of the override. Overriding a tax on a state or county level can impact taxes in excess of a thousand jurisdictions in some cases. Further detail is contained in the AFC Data Structure section.

EZTaxOvrZipEx

Description

EZTaxOvrZipEx specifies an override for a specific tax. Tax jurisdiction information is passed via zip code and address. It takes zip code plus 4 and address information, as well as an override structure as input and inserts a tax override into the AFC db system.

Format

short int EZTaxOvrZipEx(EZTaxSession session, struct zip_address_p4 int zip_addr, struct enhancedOverride *over, int *err_code)

Header(s) Required

EZTaxDefine.h

EZTaxProto.h

Libraries

EZTax2.lib

Parameters

session : Session object returned for session when initialized with call to EZTaxInitEx.

zip_addr : Specifies jurisdiction to override via Zip code and address.

*over : pointer to override information in the same form as returned by EZTaxGetRates. See struct enhancedOverride and struct zip_address_p4 in EZTaxStruct.h for detailed information.

err_code : error status returned

Note: The enhancedOverride structure points to other structures with detailed information on effective date for each tax rate and tax bracket. Interface data structures are also described in detail in the AFC Data Structures section.

Return Value List

FALSE : Override failed

TRUE : Override established

Remarks

Taxes which are overridden are in effect from the time the override is established until the AFC Session is terminated. All overrides can be removed from the system using the method EZTaxRestore.

Overrides must be approached with caution. The system allows overrides of all taxes and allows the user to specify the scope of the override. Overriding a tax on a state or county level can impact taxes in excess of a thousand jurisdictions in some cases. Further detail is contained in the AFC Data Structure section.

EZTaxPCodeEx

Description

EZTaxPCodeEx accepts transaction data and performs appropriate tax calculations. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. BTN, origination and termination information is passed using PCodes. This program takes a PCode struct as input and calculates taxes for the transaction.

Format

short int EZTaxPCodeEx(EZTaxSession session, struct P_CodeEx *trans, int* err_code);

Header(s) Required

EZTaxDefine.h

EZTaxProto.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

FALSE : Indicates no tax data available for transaction (not taxable) or an error has occurred.

[n] : Indicates number of taxes stored in the struct taxes_tbl array for this transaction.

Parameters

session : Session object returned for session when initialized with call to EZTaxInitEx.

*trans : Pointer to data structure that contains transaction data. See the P_CodeEx struct in the header file EZTaxStruct.h.

*err_code : Error status returned

Remarks

Interface data structures are also described in detail in the AFC Data Structures section. The section AFC Calculations explains how taxes are returned to the user in detail.

EZTaxPrivateLine

Description

EZTaxPrivateLine accepts transaction data and performs tax calculations for a private line transaction. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. This program takes a private_line_P _Code struct as input and calculates taxes for the transaction. The private_line_P_Code struct has fields named point_A (origination point), point_Z(termination point), both in PCode, and split which is a number between 0 and 1 to indicate the percentage which applies to the origination point. Any remaining charges are then applied to the termination point.

Format

short int EZTaxPrivateLine (EZTaxSession session, struct private_line_P_Code *trans, int *err_code);

Return Value List

[0] : No taxes calculated or an error was found

[n] : Indicates number of taxes stored in the struct taxes_tbl array for this transaction

Parameters

session : Session handle returned when initialized with call to EZTaxInitEx

*trans : Pointer to data structure that contains transaction data. See the private_line_P_Code struct in the header file EZTaxStruct.h.

*err_code : Error status returned

EZTaxPrivateLineAdj

Description

EZTaxPrivateLineAdj accepts transaction data and performs tax adjustments for a private line transaction. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. This program takes a private_line_P _Code struct as input and calculates taxes for the transaction. The private_line_P_Code struct has fields named point_A (origination point), point_Z(termination point), both in PCode, and split which is a number between 0 and 1 to indicate the percentage which applies to the origination point. Any remaining charges are then applied to the termination point.

Format

short int EZTaxPrivateLineAdj (EZTaxSession session, struct private_line_P_Code *trans, int discount_type, int adj_method, int *err_code);

Return Value List

[0] : No taxes calculated or an error was found

[n] : Indicates number of taxes stored in the struct taxes_tbl array for this transaction

Parameters

session : Session handle returned when initialized with call to EZTaxInitEx

*trans : Pointer to data structure that contains transaction data. See the private_line_P_Code struct in the header file EZTaxStruct.h.

discount_type : discount type code

adj_method : adjustment method (DLM)

*err_code : Error status returned

Remarks

Returns tax adjustments identical to method used for returning tax calculations. Interface data structures are also described in detail in the AFC Data Structures section. The section AFC Calculations explains how taxes are returned to the user in detail.

EZTaxProRateJCodeEx

Description

EZTaxProRateJCodeEx accepts transaction data and performs appropriate tax calculations. If the taxing jurisdiction allows a pro-rated reduction of taxes, the tax returned will be appropriately reduced. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. BTN, origination and termination information is passed using JCodes. This program takes a J_Code struct as input and calculates taxes for the transaction. This is the same as EZTaxJCodeEx but with percent as input.

Format

short int EZTaxProRateJCodeEx(EZTaxSession session, struct J_CodeEx *trans, double percent, int *err_code);

Header(s) Required

EZTaxDefine.h

EZTaxProto.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[0] : No taxes calculated or an error was found

[n] : Indicates number of taxes stored in the struct taxes_tbl array for this transaction

Parameters

session : Session handle returned when initialized with call to EZTaxInitEx

*trans : Pointer to data structure that contains transaction data. See the J_CodeEx struct in the header file EZTaxStruct.h.

percent : percentage to pro-rate

*err_code : Error status returned

Remarks

Some taxes can be pro-rated when a customer receives only a partial period of service. The transaction data should be filled in with the data for a complete period, and the percent value calculated as the fraction of a period. When both return and *err_code are 0, no taxes were found, but there is no error.

EZTaxProRateNPANEx

Description

EZTaxProRateNPANEx accepts transaction data and performs appropriate tax calculations. If the taxing jurisdiction allows a pro-rated reduction of taxes, the tax returned will be appropriately reduced. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. BTN, origination and termination information is passed using NPANXX. This program takes an NPANXX_code struct as input and calculates taxes for the transaction. This is the same as EZTaxNPANEx but with input percent.

Format

short int EZTaxProRateNPANEx(EZTaxSession session, struct NPANXX_codeEx *trans, double percent, int *err_code);

Header(s) Required

EZTaxDefine.h

EZTaxProto.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[0]: No taxes calculated or an error was found

[n]: Indicates number of taxes stored in the struct taxes_tbl array for this transaction

Parameters

session : Session handle returned when initialized with call to EZTaxInitEx

*trans : Pointer to data structure that contains transaction data. See the NPANXX_codeEx struct in the header file EZTaxStruct.h.

percent : percentage to pro-rate

*err_code : Error status returned

Remarks

Some taxes can be pro-rated when a customer receives only a partial period of service. The transaction data should be filled in with the data for a complete period, and the percent value calculated as the fraction of a period. When both return and *err_code are 0, no taxes were found, but there is no error.

EZTaxProRatePCodeEx

Description

EZTaxProRatePCodeEx accepts transaction data and performs appropriate tax calculations. If the taxing jurisdiction allows a pro-rated reduction of taxes, the tax returned will be appropriately reduced. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. BTN, origination and termination information is passed using PCode. This program takes a PCode struct as input and calculates taxes for the transaction. This is the same as EZTaxPCodeEx but with percent as input.

Format

short int EZTaxProRatePCodeEx(EZTaxSession session, struct P_CodeEx *trans, double percent, int *err_code);

Header(s) Required

EZTaxDefine.h

EZTaxProto.h

Libraries

EZTax2.lib

Return Value List

[0]: No taxes calculated or an error was found

[n]: Indicates number of taxes stored in the struct taxes_tbl array for this transaction

Parameters

session : Session handle returned when initialized with call to EZTaxInitEx

*trans : Pointer to data structure that contains transaction data. See the P_CodeEx struct in the header file EZTaxStruct.h.

percent : percentage to pro-rate

*err_code : Error status returned

Remarks

Some taxes can be pro-rated when a customer receives only a partial period of service. The transaction data should be filled in with the data for a complete period, and the percent value calculated as the fraction of a period. When both return and *err_code are 0, no taxes were found, but there is no error.

EZTaxProRateThisJCodeEx

Description

EZTaxProRateThisJCodeEx accepts transaction data and performs appropriate tax calculations. If the taxing jurisdiction allows a pro-rated reduction of taxes, the tax returned will be appropriately reduced. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. Jurisdiction information is passed using a JCode. This program takes a specific jurisdiction code as input and calculates taxes for the transaction. It is the same as EZTaxThisJCodeEx but with input percent.

Format

short int EZTaxProRateThisJCodeEx(EZTaxSession session, struct this_J_CodeEx *trans, double percent, int *err_code);

Header(s) Required

EZTaxDefine.h

EZTaxProto.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[0]: No taxes calculated or an error was found

[n]: Indicates number of taxes stored in the struct taxes_tbl array for this transaction

Parameters

session : Session handle returned when initialized with call to EZTaxInitEx

*trans : Pointer to data structure that contains transaction data. See the this_J_CodeEx struct in the header file EZTaxStruct.h.

percent : percentage to pro-rate

*err_code : Error status returned

Remarks

Some taxes can be pro-rated when a customer receives only a partial period of service. The transaction data should be filled in with the data for a complete period, and the percent value calculated as the fraction of a period. When both return and *err_code are 0, no taxes were found, but there is no error.

EZTaxProRateThisPCodeEx

Description

EZTaxProRateThisPCodeEx accepts transaction data and performs appropriate tax calculations. If the taxing jurisdiction allows a pro-rated reduction of taxes, the tax returned will be appropriately reduced. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. Jurisdiction information is passed using a PCode. This program takes a specific jurisdiction code as input and calculates taxes for the transaction. It is the same as EZTaxThisPCodeEx but with input percent.

Format

short int EZTaxProRateThisPCodeEx(EZTaxSession session, struct this_P_CodeEx *trans, double percent, int *err_code);

Header(s) Required

EZTaxDefine.h

EZTaxProto.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[0]: No taxes calculated or an error was found

[n] : Indicates number of taxes stored in the struct taxes_tbl array for this transaction

Parameters

session : Session handle returned when initialized with call to EZTaxInitEx

*trans : Pointer to data structure that contains transaction data. See the this_P_CodeEx struct in the header file EZTaxStruct.h.

percent : percentage to pro-rate

*err_code : Error status returned

Remarks

Some taxes can be pro-rated when a customer receives only a partial period of service. The transaction data should be filled in with the data for a complete period, and the percent value calculated as the fraction of a period. When both return and *err_code are 0, no taxes were found, but there is no error.

EZTaxProRateZipEx

Description

EZTaxProRateZipEx accepts transaction data and performs appropriate tax calculations. If the taxing jurisdiction allows a pro-rated reduction of taxes, the tax returned will be appropriately reduced. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. Jurisdiction information is passed using a Zip Code. This program takes a zip code plus 4 structure as input and calculates taxes for the transaction. This is the same as EZTaxZipEx but with percent as input.

Format

short int EZTaxProRateZipEx(EZTaxSession session, struct zip_codeEx *trans, double percent, int *err_code);

Header(s) Required

EZTaxDefine.h

EZTaxProto.h

Libraries

EZTax2.lib

Return Value List

[0]: No taxes calculated or an error was found

[n]: Indicates number of taxes stored in the struct taxes_tbl array for this transaction

Parameters

session : Session handle returned when initialized with call to EZTaxInitEx

*trans : Pointer to data structure that contains transaction data. See the zip_codeEx struct in the header file EZTaxStruct.h.

percent : percentage to pro-rate

*err_code : Error status returned

Remarks

Some taxes can be pro-rated when a customer receives only a partial period of service. The transaction data should be filled in with the data for a complete period, and the percent value calculated as the fraction of a period. When both return and *err_code are 0, no taxes were found, but there is no error.

EZTaxPtoFipsEx

Description

EZTaxPtoFipsEx returns FIPS Code that is cross-referenced to a PCode. It converts a PCode into a Fips Code. Zero is returned if not found.

Format

char *EZTaxPtoFipsEx(EZTaxSession session, unsigned long int PCode, int *err_code);

Header(s) Required

EZTaxDefine.h

EZTaxProto.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

FALSE : (0) Indicates that the PCode specified was not found or an error has occurred.

FIPS Code : FIPS Jurisdiction code

Parameters

session : Session handle returned when initialized with call to EZTaxInitEx.

PCode : Permanent jurisdiction code.

*err_code : Error codes returned. See the header EZTaxDefine.h for definitions.

Remarks

If the supplied PCode was not found or an error has occurred 0 is returned.

EZTaxPtoJCodeEx

Description

EZTaxPtoJCodeEx converts a PCode into a J-Code. PCODE_NOT_FOUND returned if not found.

Format

unsigned long int EZTaxPtoJCodeEx(EZTaxSession session, unsigned long int PCode, int *err_code);

Header(s) Required

EZTaxDefine.h

EZTaxStruct.h

EZTaxProto.h

Libraries

EZTax2.lib

Return Value List

FALSE (0) : Indicates that the PCode specified was not found or an error has occurred.

JCode : Jurisdiction code

Parameters

session : Session handle returned when initialized with call to EZTaxInitEx

PCode : Permanent jurisdiction code.

*err_code : Error codes returned. See the header EZTaxDefine.h for definitions.

Remarks

If the supplied PCode was not found or an error has occurred 0 is returned, which is a valid U.S. Federal level code.

Please check the error code before using the JCode that is returned.

EZTaxPTTypeEx

Description

Returns transaction type for a given pair of PCodes indicating whether the call is interstate or intrastate. The first JCode is the originating and the second the terminating PCode. Will set error code to INTERSTATE_NOT_VALID_FOR_INTERNATIONAL_CALLS If the originating country and terminating country are not the same.

The returned value can also be used to determine service types. For example for transaction type, 19, 20, 21, 59, the interstate service type is 49, the intrastate service is 50. For transaction type 61, the intersate service is 585, intrastate service is 586. But caller is responsible to map INTERSTATE or INTRASTATE to the right service type.

Format

short int EZTaxPTType(EZTaxSession session, unsigned long int orig_PCode, unsigned long int term_PCode, int* err_code)

Return Value List

INTERSTATE or INTRASTATE : depending on the origination and termination States.

Parameters

session: Session handle returned when session was initialized

orig_PCode: origination p-code

term_PCode: termination p-code

*err_code : error status returned

Remarks

This is the preferred API to be used and replaces usage of EZTaxJTType and EZTaxJTTypeEx.

EZTaxRestoreEx

Description

EZTaxRestoreEx removes all overrides that have been inserted, by the user, into the AFC databases. This action occurs automatically on EZTaxExit. The function provides the user with the ability to remove prior overrides, without terminating an AFC Session.

This program restores the AFC db to its original state (i.e. before overrides). All tables modified, except for the federal tax table, are restored by restoring EZTax.dll and clearing cache. This is so because all tables are modified by appending overrides to the end of the table and changing the references from the old record to the new record. Therefore, when cache is cleared and new data is pulled from the unmodified EZTax.dll, it references the original, unmodified record in the associated tables. As federal taxes do not work in this fashion, federal tax overrides are installed and restored using a unique procedure.

Format

short int EZTaxRestoreEx(EZTaxSession session);

Header(s) Required

EZTaxDefine.h

EZTaxProto.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

TRUE : Restore succeeded

FALSE : Restore failed

Parameters

session : Session object returned for session when initialized with call to EZTaxInitEx.

Remarks

All prior overrides are lost and the system databases are returned to their original configuration.

EZTaxTaxInclusiveJCode (EZTaxRevJCode deprecated)

Description

EZTaxTaxInclusiveJCode accepts transaction data and performs a tax inclusive calculation to arrive at the base sale amount. The desired total (charge plus all taxes) is placed in the ‘charge’ field in the transaction, and base charge necessary to generate that total is returned in the ‘base_sale’ parameter. Taxes for the desired transaction are returned in the same manner as EZTaxJCodeEx does. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. BTN, origination and termination information is passed using JCodes. The base sale amount will also be stored in the ‘optional’ field in the log output, converted to an integer.

Format

short int EZTaxTaxInclusiveJCode(EZTaxSession session, struct J_CodeEx *trans, double *base_sale, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[-1]: A critical error occurred while preparing the tax inclusive calculation session

[0]: No taxes calculated or an error was found

[n]: Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session: session handle returned when initialized with call to EZTaxInitEx

*trans: transaction information

*base_sale: calculated charge returned

*err_code: error status returned

Remarks

When both return and err_code are 0, no taxes were found, but there is no error. The base_sale returned will equal the charge sent in. If the charge sent in is insufficient to cover the taxes generated, then no taxes will be calculated and the err_code will be set to -37. An error will be logged to the status file indicating an insufficient charge error occurred.

**Note**: Non-billable taxes are not included in the calculation of the base sale amount. Adding the base sale amount and all taxes that appear in the log for a transaction may result in a value greater than the target amount, as any non-billable taxes returned by the transaction *will* be included in that total.

EZTaxTaxInclusiveNPAN (EZTaxRevNPAN deprecated)

Description

EZTaxTaxInclusiveNPAN accepts transaction data and performs a tax inclusive calculation to arrive at the base sale amount. The desired total (charge plus all taxes) is placed in the ‘charge’ field in the transaction, and base charge necessary to generate that total is returned in the ‘base_sale’ parameter. Taxes for the desired transaction are returned in the same manner as EZTaxNPANEx does. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. BTN, origination and termination information is passed using NPANXXs. The base sale amount will also be stored in the ‘optional’ field in the log output, converted to an integer.

Format

short int EZTaxTaxInclusiveNPAN(EZTaxSession session, struct NPANXX_CodeEx *trans, double *base_sale, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[-1] : A critical error occurred while preparing the tax inclusive calculation session

[0]: No taxes calculated or an error was found

[n]: Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session: session handle returned when initialized with call to EZTaxInitEx

*trans: transaction information

*base_sale: calculated charge returned

*err_code: error status returned

Remarks

When both return and err_code are 0, no taxes were found, but there is no error. The base_sale returned will equal the charge sent in. If the charge sent in is insufficient to cover the taxes generated, then no taxes will be calculated and the err_code will be set to -37. An error will be logged to the status file indicating an insufficient charge error occurred.

**Note**: Non-billable taxes are not included in the calculation of the base sale amount. Adding the base sale amount and all taxes that appear in the log for a transaction may result in a value greater than the target amount, as any non-billable taxes returned by the transaction *will* be included in that total. 

EZTaxTaxInclusivePCode (EZTaxRevPCode deprecated)

Description

EZTaxTaxInclusivePCode accepts transaction data and performs a tax inclusive calculation to arrive at the base sale amount. The desired total (charge plus all taxes) is placed in the ‘charge’ field in the transaction, and base charge necessary to generate that total is returned in the base_sale’parameter. Taxes for the desired transaction are returned in the same manner as EZTaxPCodeEx does. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. BTN, origination and termination information is passed using PCodes. The base sale amount will also be stored in the ‘optional’ field in the log output, converted to an integer.

Format

short int EZTaxTaxInclusivePCode(EZTaxSession session, struct P_CodeEx *trans, double *base_sale, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[-1] : A critical error occurred while preparing the tax inclusive calculation session

[0]: No taxes calculated or an error was found

[n]: Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session: session handle returned when initialized with call to EZTaxInitEx

*trans: transaction information

*base_sale: calculated charge returned

*err_code: error status returned

Remarks

When both return and err_code are 0, no taxes were found, but there is no error. The base_sale returned will equal the charge sent in. If the charge sent in is insufficient to cover the taxes generated, then no taxes will be calculated and the err_code will be set to -37. An error will be logged to the status file indicating an insufficient charge error occurred.

**Note**: Non-billable taxes are not included in the calculation of the base sale amount. Adding the base sale amount and all taxes that appear in the log for a transaction may result in a value greater than the target amount, as any non-billable taxes returned by the transaction *will* be included in that total.

EZTaxTaxInclusiveZip (EZTaxRevZip deprecated)

Description

EZTaxTaxInclusiveZip accepts transaction data and performs a tax inclusive calculation to arrive at the base sale amount. The desired total (charge plus all taxes) is placed in the ‘charge’ field in the transaction, and base charge necessary to generate that total is returned in the ‘base_sale’parameter. Taxes for the desired transaction are returned in the same manner as EZTaxJCodeEx does. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports. The base sale amount will also be stored in the ‘optional’ field in the log output, converted to an integer.

When the user knows the tax jurisdiction, address information can be supplied to specify it. This function passes tax jurisdiction information to AFC by specifying the appropriate zip code, state identifier, county, and locality. AFC uses this information to determine the JCode used for tax calculations. It is important to supply complete address information as there are many duplicate zip codes and localities contained within the AFC database tables. AFC always returns the first match of the data supplied.

Supplying incomplete information can result in tax calculations for an unexpected jurisdiction. When information regarding the locality is not supplied, AFC may be limited to data based upon the county or parish involved. Likewise, when information about the county is not supplied, the AFC engine may be limited to performance of calculations based upon the state and zip code identifiers.

Format

short int EZTaxTaxInclusiveZip(EZTaxSession session, struct zip_codeEx *trans, double *base_sale, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

[-1]: A critical error occurred while preparing the tax inclusive calculation session

[0]: No taxes calculated or an error was found

[n]: Indicates number of taxes stored in the struct enhanced_taxes_tbl array for this transaction

Parameters

session: session handle returned when initialized with call to EZTaxInitEx

*trans: transaction information

*base_sale: calculated charge returned

*err_code: error status returned

Remarks

When both return and err_code are 0, no taxes were found, but there is no error. The base_sale returned will equal the charge sent in. If the charge sent in is insufficient to cover the taxes generated, then no taxes will be calculated and the err_code will be set to -37. An error will be logged to the status file indicating an insufficient charge error occurred.

**Note**: Non-billable taxes are not included in the calculation of the base sale amount. Adding the base sale amount and all taxes that appear in the log for a transaction may result in a value greater than the target amount, as any non-billable taxes returned by the transaction *will* be included in that total. 

EZTaxSessionDbVersion

Description

Function EZTaxSessionDbVersion reads the database version being used by the specified AFC Session and returns it to the caller.

Format

short int EZTaxDbVersion(EZTaxSession session, char *psz_db_version);

Return Value List

TRUE if database version is returned in psz_db_version

FALSE if database version couldn't be obtained

Parameters

session : session handle

*psz_db_version : address of character array that will receive the database version.

Remarks

The database version will be returned in the form ww.xx.yy.zz, where each piece of the database version number can be 1 or 2 digits.

EZTaxSetInvoiceModeEx

Description

Function EZTaxSetInvoiceModeEx sets Invoice Mode on or off - allocating or freeing memory for tables.

This function sets the Invoice Mode on or off. When the Invoice Mode is off AFC works in the normal fashion, each transaction passed is taxed with caps and limits calculated on a per transaction basis.

When Invoice Mode is on, AFC performs appropriate tax calculations and returns the taxes calculated, AFC also keeps the tax amounts in memory and uses them to adjust rates for bracketet or tiered taxes and apply caps and limits to the taxes generated for each subsequent transaction. When EZTaxNextCustomerEx is called a summarized version of the taxes is returned.

Format

struct enhanced_cust_taxes_tbl *EZTaxSetInvoiceModeEx(EZTaxSession session, short int mode);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

pointer : to the tax table if successful

null : if an error occurred

Parameters

session : session handle returned for session when initialized with call to EZTaxInitEx

mode: flag for turning Invoice Mode on (TRUE) or off (FALSE)

References:

EZTaxNextCustomerEx

Remarks

Interface data structures are also described in detail in the AFC Data Structures section.

Before setting the Invoice Mode to false, EZTaxNextCustomerEx must be called in order to get summarized taxes should be processed prior to turning off the Invoice Mode). Failure to call EZTaxNextCustomerEx will cause the last customer's summarized taxes to be lost.

Note: The summarized taxes returned when calling EZTaxNextCustomerEx are identical to the total of the individual taxes returned from the taxing APIs. Typically one or the other is used but not both.  Combining the individual taxes and the summarized taxes will result in twice as much taxes as should be normal.

EZTaxSetInvoiceModeV98

Description

Function EZTaxSetInvoiceModeV98 sets Invoice Mode on or off – allocating or freeing memory for tables. It differs from EZTaxSetInvoiceModeEx in that the tax table returned contains tax category information.

This function sets the Invoice Mode on or off. When the Invoice Mode is off AFC works in the normal fashion, each transaction passed is taxed with caps and limits calculated on a per transaction basis.

When Invoice Mode is on, AFC performs appropriate tax calculations and returns the taxes calculated, AFC also keeps the tax amounts in memory and uses them to adjust rates for bracketet or tiered taxes and apply caps and limits to the taxes generated for each subsequent transaction. When EZTaxNextCustomerEx is called a summarized version of the taxes is returned.

Format

struct cust_taxes_tbl_v98 *EZTaxSetInvoiceModeV98(EZTaxSession session, short int mode);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

pointer : to the tax table if successful

null : if an error occurred

Parameters

session : session handle returned for session when initialized withcall to EZTaxInitEx

mode: flag for turning Invoice Mode on (TRUE) or off (FALSE)

References:

EZTaxNextCustomerEx

Remarks

Interface data structures are also described in detail in the AFC Data Structures section.

Before setting the Invoice Mode to false, EZTaxNextCustomerEx must be called in order to get summarized taxes should be processed prior to turning off the Invoice Mode). Failure to call EZTaxNextCustomerEx will cause the last customer's summarized taxes to be lost.

Note: The summarized taxes returned when calling EZTaxNextCustomerEx are identical to the total of the individual taxes returned from the taxing APIs. Typically one or the other is used but not both. Combining the individual taxes and the summarized taxes will result in twice as much taxes as should be normal.

EZTaxSetNexus

Description

Function EZTaxSetNexus sets nexus on or off for the specified states.

This function sets the nexus information by jurisdiction on or off. For each nexus point in the nexus_table, the engine will calculate its jurisdiction and either set nexus on or off based on the has_nexus variable of the nexus_table structure.

Format

short int EZTaxSetNexus(EZTaxSession session, struct nexus_table *nexus_tbl, short int nexus_count);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

TRUE if nexus information was changed;

FALSE otherwise

Parameters

session : session handle returned for session when initialized with call to EZTaxInitEx

*nexus_table : Pointer to nexus table structure that contains nexus information. See the nexus_table struct in the header file EZTaxStruct.h.

nexus_count : Number of nexus points in the structure.

Remarks

Interface data structures are also described in detail in the AFC Data Structures section.

Using this API with the nexus=on option in the configuration file is not recommended. This API is to be used as a programmatic option instead of a configuration file option.

EZTaxSetStateExclusion

Description

EZTaxSetStateExclusion uses the country code and, optionally, a state code to set an exclusion. A flag is used to determine if the country/state jurisdiction is to be turned off (enable regular taxation) or on (exclude country and/or state taxation for all jurisdictions within the country or state including county and local taxation). Transactions for an excluded state continue to return federal (country) level taxes for all transactions within the excluded state.

Note: The three-character country code should be used for countries and the two-character code should be used for states, including US territories.

In this context, references to state apply to either a state or province.

For US territories, the USA Federal exclusions have precedence over US Terriotry jurisdictions. As a result, all US Territory exclusions will be set or cleared along with US Federal exclusions when only USA is specified.

Please make note, country codes for US territories have been deprecated.

Format

short int EZTaxSetStateExclusion(EZTaxSession session, char country_ISO[4], char state_abv[3], short int flag);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

Libraries

EZTax2.lib

Return Value List

TRUE : EZTaxSetStateExclusion was successful.

FALSE : EZTaxSetStateExclusion failed.

Parameters

Session : session handle returned when initialized with call to EZTaxInitEx

country_ISO: The country code. These are listed in EZTaxDefine.h.

state_abv: The state abbreviation. These are listed in EZTaxDefine.h.

flag: TRUE - Exclude this state from taxation.

FALSE - Do not exclude this state from taxation.

Remarks

None

EZTaxSetStateNexus

Description

EZTaxSetStateNexus uses a state code to set the nexus. A flag is used to determine if the state has nexus (true) or not (false).

Format

short int EZTaxSetStateNexus(EZTaxSession session, char state_abv[3], short int flag);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

Libraries

EZTax2.lib

Return Value List

TRUE : EZTaxSetStateNexus was successful.

FALSE : EZTaxSetStateNexus failed.

Parameters

Session : session handle returned when initialized with call to EZTaxInitEx

state_abv: The state abbreviation. These are listed in EZTaxDefine.h.

flag: TRUE or FALSE.

Remarks

None

EZTaxSetWorkingDir

Description

Function EZTaxSetWorkingDir is utilized to set the working directory to a know location. This is especially useful when AFC is being called from inside a database application where the default working directory may be different from run to run.

Format

short int EZTaxSetWorkingDir(char *directory);

Header(s) Required

EZTaxProto.h

EZTaxStruct.h

EZTaxDefine.h

Libraries

EZTax2.lib

Return Value List

TRUE if change directory is successful;

FALSE otherwise

Parameters

directory : string containing directory path to change to

Remarks

MUST be called before EZTaxInitEx!

EZTaxStart

Description

EZTaxStart declares and initializes the session variables for the EZTax system. These globals are set when defined but need to be reset when the user restarts system.

This function is utilized to start EZTax and must be the first EZTax API function call. This function allocates and initializes resources necessary for execution of multiple simultaneous sessions.

Format

void EZTaxStart(void);

Header(s) Required

EZTaxProto.h

Libraries

EZTax2.lib

Return Value List

Parameters

Remarks

This function initializes and starts EZTax. EZTax will not function properly if this call is not the initial call made to EZTax.

EZTaxStartEx

Description

EZTaxStartEx declares and initializes the session variables for the EZTax system. These globals are set when defined, but need to be reset when the user restarts system.

This function is utilized to start EZTax and must be the first EZTax API function call. This function allocates and initializes resources necessary for execution of multiple simultaneous sessions.

Format

short int EZTaxStart(char *start_dir);

Header(s) Required

EZTaxProto.h

Libraries

EZTax2.lib

Return Value List

FALSE if the starting directory length exceeds the limit (failure!) or the working directory could not be set;

TRUE otherwise

Parameters

start_dir: string containing the initial working directory

Remarks

This function initializes and starts EZTax. EZTax will not function properly if this call is not the initial call made to EZTax.

EZTaxSetLogName

Description

EZTaxSetLogName allows applications API functionality to set just the log file instead of all the data files. This function is special for new batch executable that separates taxes into two logs. Currently a function for internal use.

Format

short int EZTaxSetLogName(EZTaxSession session, char *fileName) Return Value List

Parameters

session : session handle returned for session when initialized with call to EZTaxInitEx

filename : new filename for the log

Remarks

None

EZTaxThisJCodeEx

Description

EZTaxThisJCodeEx accepts transaction data and performs appropriate tax calculations. The tax jurisdiction to use for tax calculations is specified to AFC with this method. If the AFC Session was started with the tax log open, appropriate taxes are logged and will be reflected in tax reports.  Jurisdiction information is passed using a PCode.

Format

short int EZTaxThisJCodeEx(EZTaxSession session, struct this_J_Code *trans, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

FALSE : Indicates no tax data available for transaction (not taxable) or an error has occurred.

[n] : Indicates number of taxes stored in the struct taxes_tbl array for this transaction

Parameters

session : Session object returned for session when initialized with call to EZTaxInitEx.

*trans : Pointer to data structure that contains transaction data. See the this_J_Code struct in EZTaxStruct.h

*err_code : Error codes returned. See the header EZTaxDefine.h for definitions.

Remarks

This API call is particularly suited for processing local transactions, since there is only one jurisdiction involved

EZTaxThisPCodeEx

Description

EZTaxThisPCodeEx accepts transaction data and performs appropriate tax calculations. The tax jurisdiction to use for tax calculations is specified to AFC with this method. If the AFC Session was started with the tax log open, appropriate taxes are logged and will be reflected in tax reports.  Jurisdiction information is passed using a PCode.

Format

short int EZTaxThisPCodeEx(EZTaxSession session, struct this_P_Code *trans, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

FALSE : Indicates no tax data available for transaction (not taxable) or an error has occurred.

[n]: Indicates number of taxes stored in the struct taxes_tbl array for this transaction.

Parameters

session : Session object returned for session when initialized with call to EZTaxInitEx.

*trans : Pointer to data structure that contains transaction data. See the this_P_Code struct in EZTaxStruct.h

*err_code : Error codes returned. See the header EZTaxDefine.h for definitions.

Remarks

This API call is particularly suited for processing local transactions, since there is only one jurisdiction involved

EZTaxTPPEx

Description

EZTaxTPPEx takes up to three addresses; Ship From, Ship To, and Point-Of-Acceptance. It requires Ship From. If others have NOT NULL values, then they must be valid. Uses rules to determine interstate or intrastate to determine which taxing jurisdiction should be used.

It accepts the optional Nexus Table, which if given will be checked against the jurisdiction determined above. No taxes will be calculated unless the flag is set (by the caller) for the given state. It returns tax_count, having populated the tax_log structure with any taxes found.

Format

short int EZTaxTPPEx(EZTaxSession session, struct TPP_addrEx *tpp_trans, struct nexus_table *nex_tab, short int nexus_count, int *err_code)

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

Parameters

session : Session object returned for session when initialized with call to EZTaxInitEx.

*tpp_trans : Pointer to data structure that contains transaction data.

*nex_tab : list of states where a business nexus exists.

nexus_count : number of entries in nex_tab

*err_code : Error codes returned. See the header EZTaxDefine.h for definitions.

Remarks

None

EZTaxWriteToLogEx

Description

Function EZTaxWriteToLogEx allows customers to create the correctly formatted binary AFC log from scratch by passing in data they have stored from a different database or saved from AFC transactions using EZTaxInitExp.

Format

short int EZTaxWriteToLogEx(EZTaxSession session, int count, struct EZTax_logEx *log);

Header(s) Required

EZTaxProto.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

FALSE : An error occurred

TRUE : Success

Parameters

session : Session handle returned when initialized with call to EZTaxInitEx

count: Number of taxes in the log structure

*log : Log structure to save information from

Remarks

EZTaxWriteToLogEx does not support logging of the transaction type and service type.

EZTaxWriteToLogV914

Description

Function EZTaxWriteToLogV914 allows customers to create the correctly formatted binary AFC log from scratch by passing in data they have stored from a different database or saved from AFC transactions.

Format

short int EZTaxWriteToLogV914(EZTaxSession session, int count, struct eztax_log_v914 *log

Return Value List

FALSE : An error occurred

TRUE : Success

Parameters

session: session handle returned with call to initialize the AFC Session.

count: Number of taxes in the log structure

*log : Log structure containing records to be written to file.

Remarks

EZTaxWriteToLogEx does not support logging of the transaction charge, the tax description, the tax category id or the tax category description.

EZTaxZipEx

Description

EZTaxZipEx accepts transaction data and performs appropriate tax calculations. If the AFC Session was started with the tax log open, tax calculations are logged and will be reflected in tax reports.

When the user knows the tax jurisdiction, address information can be supplied to specify it. This function passes tax jurisdiction information to AFC by specifying the appropriate zip code, state identifier, county, and locality. AFC uses this information to determine the JCode used for tax calculations. It is important to supply complete address information as there are many duplicate zip codes and localities contained within the AFC database tables. AFC always returns the first match of the data supplied.

Supplying incomplete information can result in tax calculations for an unexpected jurisdiction. When information regarding the locality is not supplied, AFC may be limited to data based upon the county or parish involved. Likewise, when information about the county is not supplied, the AFC engine may be limited to performance of calculations based upon the state and zip code identifiers.

Format

short int EZTaxZipEx(EZTaxSession session, struct zip_codeEx *trans, int *err_code);

Header(s) Required

EZTaxDefine.h

EZTaxProto.h

EZTaxStruct.h

Libraries

EZTax2.lib

Return Value List

FALSE : Indicates no tax data available for transaction (not taxable) or an error has occurred.

[n] : Indicates number of taxes stored in the struct taxes_tbl array for this transaction.

Parameters

session : Session object returned for session when initialized with call to EZTaxInitEx.

*trans : Pointer to data structure that contains transaction data. See the zip_codeEx struct in the header file EZTaxStruct.h.

*err_code : Error status returned

Remarks

Interface data structures are also described in detail in the AFC Data Structures section. The section AFC Calculations explains how taxes are returned to the user in detail.

AFC currently has Zip Code information for U.S. and Canadian jurisdictions.

The six character Canadian postal code must be broken up for entry. The first 3 characters go into the zip code field and the last 3 characters go into the plus 4 field.

EZTaxZtoJCodeEx

Description

EZTaxZtoJCodeEx utilizes zip code plus 4 and address information supplied by the user, to obtain a J- Code.

Format

unsigned long int EZTaxZtoJCodeEx(EZTaxSession session, struct zip_address_p4 *address, int *err_code);

Header(s) Required

EZTaxProto.h

EZTaxDefine.h

Libraries

EZTax2.lib

Return Value List

[0]: Error Code has been set. If the supplied address was not found or an error has occurred 0 is returned, which is a valid U.S. Federal level code. Please check the error code before using the JCode that is returned.

JCode : Error Code has not been set.

Parameters

session : Session handle returned when initialized with call to EZTaxInitEx

address : Address information with zip+4

*err_code : Error status returned

Remarks

AFC currently has Zip Code information for U.S. and Canadian jurisdictions. The six character Canadian postal code must be broken up for entry. The first 3 characters go into the zip code field and the last 3 characters go into the plus 4 field.

EZTaxZtoPCodeEx

Description

EZTaxZtoPCodeEx returns PCode cross-referenced to a zip code and address.

Format

unsigned long int EZTaxZtoPCodeEx(EZTaxSession session struct zip_address_p4 *address, int *err_code);

Header(s) Required

EZTaxProto.h

Libraries

EZTax2.lib

Return Value List

PCode : Permanent jurisdiction code. If the supplied address was not found or an error has occurred 0 is returned which is a valid U.S. Federal level code. Please check the error code before using the PCode that is returned.

Parameters

session : Session object returned for session when initialized with call to EZTaxInitEx.

*address : Pointer to zip_address_p4 structure containing valid address data, see struct in EZTaxStruct.h Interface data structures are also described in detail in the AFC Data Structures section.

*err_code : Error codes returned. See the header EZTaxDefine.h for definitions.

Remarks

AFC currently has Zip Code information for U.S. and Canadian jurisdictions. The six character Canadian postal code must be broken up for entry. The first 3 characters go into the zip code field and the last 3 characters go into the plus 4 field.

EZTaxSetSafeHarborTAMOverride

Description

EZTaxSetSafeHarborTAMOverride stores the provided fraction in the session object and sets a flag indicating that the particular session has an override at the federal level. The corresponding state level fraction is calculated and stored. The override is written to the EZTax status file if it changed. The AFC engine then applies the new values instead of the default safe harbor percentages for the chosen TAMTypeID.

Format

EZTaxSetSafeHarborTAMOverride(EZTaxSession session, short TAMTypeID, double originalFederalTAM, double newFederalTAM, int * error_code);

Return Value List

FALSE: 0

TRUE: 1

Parameters

session : Session object returned for session when initialized with call to EZTaxInitEx.

originalFederalTAM

newFederalTAM

*err_code: Error codes returned. See the header EZTaxDefine.h for definitions.

Remarks

None

EZTaxClearSafeHarborTAMOverride

Description

EZTaxClearSafeHarborTAMOverride allows users to clear the safe harbor override at run time.

Format

short int EZTaxClearSafeHarborOverride(EZTaxSession session, short int safe_harbor_type, int *err_code);

Return Value List

TRUE : success

FALSE : failure (check error status code)

Parameters

Session : session handle returned when initialized with call to EZTaxInitEx

safe_harbor_type : valid safe harbor type (1, 2, 4 or 7)

*err_code : error status code

Remarks

None

Public Header and Modules

Communications Headers

Windows installation package location: .\dll\*.h

Unix installation package location: .\hdr\*.h

File name

Description

EZTaxCountryType.h Definitions for country ids by country name and by country ISO
EZTaxDefine.h Definitions for external constants used in by engine
EZTaxProto.h Function prototypes for available API calls into the engine
EZTaxServType.h Definitions for service type ids by service type name
EZTaxStateType.h Definitions for state ids by state name
EZTaxStruct.h Structure declarations for structures used in API calls into the engine
EZTaxTaxType.h Definitions for tax type ids by tax type name
EZTaxTransType.h Definitions for transaction type ids by transaction type name

Java Clients

Windows installation package location: .\Java Interface\eztaxconstants\*.java

Unix installation package location: *_eztax_java.tar\eztax_java\eztaxconstants\*.java

File name Description
CountryType.java Definitions for country ids by country name and by country ISO
ServiceType. java Definitions for service type ids by service type name
StateType. java Definitions for state ids by state name
TaxType. java Definitions for tax type ids by tax type name
TransactionType. java Definitions for transaction type ids by transaction type name

Dot Net Clients

Windows installation package location: .\EZTaxNET\{framework}\EZTaxConstants.cs

Public Class Name

Description

TaxType

Constants for tax type ids by tax type name

TaxCategory

Constants for tax category ids by tax category name

TransactionType

Constants for transaction type ids by transaction type name

ServiceType

Constants for service type ids by service type name

StateType

Constants for state type ids by state type name

CountryType

Constants for country type ids by country type name

Monthly Update Procedure

The AFC monthly update is available at approximately 4:00 PM Central time on the day before the last business day of each month. It contains updated tax information and database files and is available at the Avalara Customer Portal.  The update contains changes resulting from ongoing research and development, providing the most current and efficient tax-rating engine available.

The process of updating your AFC system is similar to the procedure used to install AFC. Use the Installation Wizard to update your files monthly. There is no need to compile your system data because the Avalara database and AFC software functions are independent from your billing system. Simply follow the seven easy steps.

WARNING: AFC MUST be updated each month in order for the program to be current. If the download is not completed within the allotted month, AFC is disabled to prevent incorrect tax calculations.

Download the Monthly Update

The Monthly updates are available from the client download page of the AFC Customer Portal web site: https://communications.avalara.net.

See How can I access my software downloads from Support? for more information.

Important Files in Update

The following files and directories are included in the monthly update:

  • Update.exe - Utility that steps the user through the process of installing the update.
  • Current tax changes and other documents - located in the \support\docs directory are file format keys, guidelines, and the AFC Tax Changes doc
  • filelocs.upd – rename this new file “filelocs.txt”

Monthly Maintenance

Proper monthly maintenance will keep the AFC system operating without interruption. Refer to the following figure for the update procedure flow.

  1. Take an inventory of all file directories and locations.
  2. Create a backup of these either on media such as a diskette or save them to a backup directory.
  3. Once the update is installed, closely review the update file locations.
  4. Run a Test on a small file.
  5. Review the \support\docs directory for tax changes and current update information.

Figure 8-5 EZtax Update Procedure

image

  • Was this article helpful?