Creating Tax Codes

About Creating Tax Codes

Tax codes define which tax to apply to a charge. For example, a telephone handset uses a different tax code than an online service subscription. The tax code identifies the tax amount or percentage to apply for each jurisdiction.

You can configure tax codes in the following ways:

Using the PDC UI. See "Creating Tax Codes" in PDC Online Help.
Using the ImportExportPricing utility. See "Creating Tax Codes Using ImportExportPricing".

After you finish creating tax codes, you can associate them with your charges, discounts, and chargeshares.

You can also assign tax codes to charges, discounts, and chargeshares using tax selectors. Tax selectors decide the tax code to apply based on account, service, event, and profile attributes. You can create tax selectors in the following ways:

Using the PDC UI. For information, see "Creating a Tax Selector" in PDC Online Help.
Using the ImportExportPricing utility. For information, see "Creating Tax Selectors Using ImportExportPricing".

Creating Tax Codes Using ImportExportPricing

You create tax codes in PDC and publish them to BRM and Elastic Charging Engine (ECE) using the ImportExportPricing utility.

To implement tax codes:

Define your tax codes in an XML file. You can base your tax codes on those provided in the Sample_Tax_Code.xml file available in the PDC_home/apps/Samples/Examples directory, where PDC_home is the directory in which the PDC software is installed.
The sample file contains examples of tax codes for calculating taxes based on a custom implementation or Vertex. For more information about XML elements specific to Vertex or custom tax codes, see:
- Creating Tax Codes for Vertex
- Creating Tax Codes for a Flat Tax or Custom Implementation
Import the XML file into PDC using the ImportExportPricing utility:
```
ImportExportPricing -import -config MyTaxCodes.xml
```
where MyTaxCodes is the name of the XML file where you defined the tax codes.

You can also modify existing tax codes using the -ow parameter.

See "Importing Pricing and Setup Components" and "ImportExportPricing" in PDC Creating Product Offerings for more information about the utility's syntax and parameters.

The ImportExportPricing utility also publishes the tax codes to the real-time rating engine (RRE) and ECE.

Note:
You cannot publish tax codes to the batch rating engine (BRE).
Map your tax codes to G/L IDs in ECE. Do the following for each tax code you configured in MyTaxCodes.xml:
1. Access the ECE configuration MBeans in a JMX editor, such as JConsole. See "Accessing ECE Configuration MBeans" in ECE Implementing Charging for more information.
2. Expand the ECE Configuration node.
3. Expand charging.taxation.
4. Expand Operations.
5. Click addTaxDetails.
6. Specify values for the following attributes:
  - taxCode: Enter a tax code. The tax code must match a value in the <code> element of your MyTaxCodes.xml file.
  - taxGlId: Enter the General Ledger ID to use for the tax impact.

Creating Tax Codes for a Flat Tax or Custom Implementation

You implement simple flat taxes by defining them in an XML file that you import into PDC. In the file, you enter a tax code and assign it to one or more tax rates, which are differentiated by criteria such as validity date and jurisdiction.

The following XML example shows custom tax codes:

<taxCodes>
      <name>CustomTaxCode</name>
      <priceListName>Default</priceListName>
      <obsolete>false</obsolete>
      <code>CustomTaxCode</code>
      <taxPackageType>CUSTOM</taxPackageType>
      <taxCodeValidityPeriods>
         <validFrom>20220101</validFrom>
         <validTo>20230120</validTo>
         <taxCodeMaps>
            <description>TRS1</description>
            <percent>4.0</percent>
            <taxJurisdictionLevel>FEDERAL</taxJurisdictionLevel>
            <taxJurisdictions>US</taxJurisdictions>
            <taxRuleType>TAX</taxRuleType>
         </taxCodeMaps>
      </taxCodeValidityPeriods>
      <taxCodeValidityPeriods>
         <validFrom>20240101</validFrom>
         <validTo>20300120</validTo>
         <taxCodeMaps>
            <description>TRS2</description>
            <percent>8.0</percent>
            <taxJurisdictionLevel>LOCATION</taxJurisdictionLevel>
            <taxJurisdictions>EU</taxJurisdictions>
            <taxRuleType>INCLUSIVE</taxRuleType>
         </taxCodeMaps>
         <taxCodeMaps>
            <description>TRS3</description>
            <percent>8.0</percent>
            <taxJurisdictionLevel>LOCATION</taxJurisdictionLevel>
            <taxJurisdictions>ASIA</taxJurisdictions>
            <taxRuleType>NCS</taxRuleType>
         </taxCodeMaps>
      </taxCodeValidityPeriods>
   </taxCodes>

When the value of the <taxPackageType> element is CUSTOM, one of the following is required under the <taxCodeMaps> element:

<percent>: If you include this element, the elements described in Table 3-1 are also required.
<transType_CategoryCode_Rate>: If you include this element, no other elements are supported in the tax code map.

Table 3-1 describes the critical XML elements specific to custom tax codes.

Table 3-1 XML Elements in the Tax Code File for Custom Tax Codes

Element	Description
code	The tax code. A unique alphanumeric value that defines categories with different tax treatments.
taxPackageType	The package type. For flat taxes and custom implementations, this is always CUSTOM.
validFrom	The start date of the validity period for the tax rate in yyyymmdd format. Note: You can use multiple validity periods to create different rates for a single tax code, as shown in the example, but the validity periods must not overlap.
validTo	The end date of the validity period for the tax rate in yyyymmdd format.
description	A brief description of the tax code.
percent	The tax rate in percent. For example, 4.25 means 4.25%. For prepaid purchase events that grant negative currency balances, the corresponding tax associated with it should also be negative. For example, -4.25.
taxJurisdictionLevel	The jurisdiction level for which this rate is applicable. Values are FEDERAL, STATE, COUNTY, CITY, and LOCATION.
taxJurisdictions	The jurisdiction where the rate applies. Similar to a nexus for the corresponding jurisdiction level. For example, if the taxJurisdictionLevel value is STATE, the taxJurisdictions values must be state-level jurisdictions.
taxRuleType	Determines how taxes will be computed. Values are: STANDARD: Standard tax computation. Taxes are computed based on the taxable amount and are then added to the total. TAX: "Tax on tax" computation. Taxes are computed based on previous taxable amounts and taxes, and are then added to the total. For example, if tax1 = 10%, tax2 = 20%, and charge = 100.00, taxes are computed as follows: tax1 = 10% @ 100.00 = 10.00 tax2 = 20% @ (100.00 + 10.00) = 22.00 INCLUSIVE: Inclusive tax computation. Taxes are already included in the total. For example, if the total is $110 and the tax is 10%, the tax amount is $10 and the charge is $100. This option can only be configured for event-time taxation, not billing-time taxation or dynamic taxation. Note: Inclusive taxes are not supported by Oracle Communications Elastic Charging Engine (ECE). NCS: Noncumulative standard tax computation. Taxes are computed based on the taxable amount but are not added to the total. NCT: Noncumulative "tax on tax" computation. Taxes are computed based on the taxable amount but are not added to the total. For example, if tax1 = 10%, tax2 = 20%, and charge = 100.00, taxes are computed as follows: tax1 = 10% @ 100.00 = 10.00 tax2 = 20% @ 100.00 = 20.00

Creating Tax Codes for Vertex

You specify to calculate taxes using Vertex by mapping tax codes to Vertex product codes in an XML file that you import into PDC. The Vertex product codes are used to apply the tax rate.

The following XML example shows the two types of Vertex tax codes. The three elements under the taxCodeMaps element are the only ones supported for Vertex tax codes.

<taxCodes>
      <name>VQTaxCode</name>
      <priceListName>Default</priceListName>
      <obsolete>false</obsolete>
      <code>VQTaxCode</code>
      <taxPackageType>VERTEX_QUANTUM</taxPackageType>
      <taxCodeValidityPeriods>
         <taxCodeMaps>
            <transType_CategoryCode_Rate>01</transType_CategoryCode_Rate>
            <transSubType_ServiceCode>01</transSubType_ServiceCode>
            <salesIndicator>SALE</salesIndicator>
         </taxCodeMaps>
      </taxCodeValidityPeriods>
   </taxCodes>
   <taxCodes>
      <name>VCTaxCode</name>
      <priceListName>Default</priceListName>
      <obsolete>false</obsolete>
      <code>VCTaxCode</code>
      <taxPackageType>VERTEX_COMMTAX_21</taxPackageType>
      <taxCodeValidityPeriods>
         <taxCodeMaps>
            <transType_CategoryCode_Rate>4</transType_CategoryCode_Rate>
            <transSubType_ServiceCode>2</transSubType_ServiceCode>
            <salesIndicator>SALE</salesIndicator>
         </taxCodeMaps>
      </taxCodeValidityPeriods>
   </taxCodes>

Table 3-2 describes the important XML elements specific to Vertex tax codes.

Table 3-2 XML Elements in the Tax Code File for Vertex

Element	Explanation
code	The tax code. A unique alphanumeric value that defines categories with different tax treatments.
taxPackageType	The tax package you use: VERTEX_QUANTUM: Vertex Communications Tax Q Series (telecommunications). VERTEX_COMMTAX_21: Vertex Sales Tax Q Series (sales and use).
transType_CategoryCode_Rate	The field value is determined by the tax package you use. For Vertex Communications Tax Q Series, this field is the category code. See the Communications Tax Q Series documentation for more information about its category codes. For Vertex Sales Tax Q Series, this field is the transaction type. See the Sales Tax Q Series documentation for more information on transaction types.
transSubType_ServiceCode	The field value is determined by the tax package you use. For Vertex Communications Tax Q Series, this field is the service code. Refer to the Communications Tax Q Series documentation for more information on service codes. For Vertex Sales Tax Q Series, this field is the transaction subtype. Refer to the Sales Tax Q Series documentation for more information on transaction subtypes.
salesIndicator	For Vertex Communications Tax Q Series and Vertex Sales Tax Q Series, this is the resale flag field, which indicates if the charge offer is for sale (SALE) or resale (RESALE). The default is SALE.

See your tax package documentation for information about product codes, service codes, and service indicators.

When configuring Vertex tax calculation, you also need to configure tax suppliers. See "Creating Tax Suppliers".

Creating Tax Selectors Using ImportExportPricing

You can create tax selectors in an XML file and publish them to PDC, BRM, and ECE using the ImportExportPricing utility.

To implement tax selectors using ImportExportPricing:

Define your tax selectors in an XML file. You can base them on the sample tax selectors provided in the PDC_home/apps/Samples/Examples/SampleTaxSelector.xml file.

See "Creating an XML File for Tax Selectors" for more information about the XML elements in the file.
Import the XML file into PDC using the ImportExportPricing utility:
```
ImportExportPricing -import -pricing MyTaxSelectors.xml
```
where MyTaxSelectors is the name of the XML file where you defined the tax selectors.

The ImportExportPricing utility publishes the tax selectors to the PDC database, real-time rating engine (RRE), and ECE.

Note:

You cannot publish tax selectors to the batch rating engine (BRE).

Creating an XML File for Tax Selectors

You can implement tax selectors by defining them in an XML file that you import into PDC. In the file, you enter a tax selector and then define the rules for assigning tax codes to charges, discounts, and chargeshares.

The following sample XML shows how to create tax selectors:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><pdc:PricingObjectsJXB xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing">
<taxSelector xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing">
   <name>Sample_TAX_SELECTOR</name>
   <description>Sample TAX_SELECTOR</description>
   <pricingProfileName>Convergent Usage</pricingProfileName>
   <priceListName>Default</priceListName>
   <obsolete>false</obsolete>
   <stereoType>TAX_SELECTOR</stereoType>
   <productSpecName>TelcoGsmSms</productSpecName>
   <eventSpecName>EventDelayedSessionTelcoGsm</eventSpecName>
   <validityPeriod>
      <validFrom>0</validFrom>
      <rule>
         <name>Rule1</name>
         <result>
            <resultName>VAT</resultName>
         </result>
         <fieldToValueExpression>
            <operation>REGEX</operation>
            <seperator>;</seperator>
            <fieldName>EventDelayedSessionTelcoGsm.CALLED_ID</fieldName>
            <fieldValue>1800.*</fieldValue>
            <fieldKind>EVENT_SPEC_FIELD</fieldKind>
         </fieldToValueExpression>
      </rule>
      <rule>
         <name>Rule2</name>
         <result>
            <resultName>toll</resultName>
         </result>
         <fieldToValueExpression>
            <operation>REGEX</operation>
            <seperator>;</seperator>
            <fieldName>EventDelayedSessionTelcoGsm.CALLED_ID</fieldName>
            <fieldValue>.*</fieldValue>
            <fieldKind>EVENT_SPEC_FIELD</fieldKind>
         </fieldToValueExpression>
      </rule>
   </validityPeriod>
   </taxSelector></pdc:PricingObjectsJXB>

Table 3-3 describes the important XML elements specific to tax selectors.

Table 3-3 XML Elements in the Tax Selector File

Element	Description
name	The name of the tax selector.
description	A description of the tax selector.
pricingProfileName	The pricing profile to associate with the tax selector.
priceListName	The name of the price list to which the selector applies.
stereoType	The type of pricing object: TAX_SELECTOR.
productSpecName	The service type to which the tax selector applies.
eventSpecName	The event type to which the tax selector applies.
validityPeriod	Indicates when the rules in the tax selector are valid. The default effective period starts immediately and never ends.
name	The name of a rule.
resultName	The name of the tax code to apply when all criteria in the rule are met.
operation	The operator to apply, which is dependent on the field. The valid values are: REGEX, EQUAL_TO, NOT_EQUAL_TO, GREATER_THAN, GREATER_THAN_EQUAL, LESS_THAN, LESS_THAN_EQUAL, IN_LIST, and MAPS_TO.
seperator	The character that is used to separate the field values, such as a semicolon (;).
fieldName	The name of the field to evaluate.
fieldValue	The required value of the field.
fieldKind	The type of attributes to be selected for assigning the tax code. The valid values are: EVENT_SPEC_FIELD, PRODUCT_SPEC_FIELD, CUSTOMER_SPEC_FIELD, and PROFILE_SPEC_FIELD.