Tax Calculation Opcode Workflows

Opcode	Topic
PCM_OP_BILL_CYCLE_TAX	Calculating Taxes During Billing
PCM_OP_BILL_TAX_EVENT	Retrieving Tax Supplier Data
PCM_OP_CUST_POL_TAX_CALC	Using Custom Tax Rates
PCM_OP_CUST_POL_TAX_INIT	Using Custom Tax Rates
PCM_OP_CUST_POL_VALID_NAMEINFO	Using Geocodes to Calculate Taxes
PCM_OP_CUST_POL_VALID_TAXINFO	Validating Tax Information
PCM_OP_CUST_SET_TAXINFO	Adding Tax Information to Accounts
PCM_OP_RATE_EVENT	Calculating Taxes During Billing Retrieving Tax Location Data
PCM_OP_RATE_POL_GET_TAX_SUPPLIER	Retrieving a List of Tax Suppliers
PCM_OP_RATE_POL_GET_TAXCODE	Retrieving a List of Tax Codes
PCM_OP_RATE_POL_MAP_TAX_SUPPLIER	Retrieving Tax Supplier Data
PCM_OP_RATE_POL_POST_TAX	Modifying Tax Data After Calculating Taxes Requesting Additional Data from Vertex Tax Software Retrieving Additional Tax Data Storing Vertex Tax Data in Your Custom Storable Class
PCM_OP_RATE_POL_PRE_TAX	Modifying Tax Data Before Calculating Taxes Modifying Addresses for Non-telephony Events Using Geocodes to Calculate Taxes Requesting Additional Data from Vertex Tax Software
PCM_OP_RATE_POL_TAX_LOC	Calculating Taxes During Billing Retrieving Tax Location Data
PCM_OP_RATE_TAX_CALC	How PCM_OP_RATE_TAX_CALC Calculates Taxes Calculating Taxes During Billing Modifying Tax Data Before Calculating Taxes Validating Tax Information
PCM_OP_TAX_GW_CALCULATE_TAX	Calculating Taxes at Event Time or During Billing
PCM_OP_TAX_GW_VALIDATE_ADDRESS	Validating Tax Jurisdictions Based on Address

Calculating Taxes During Billing

Taxes are calculated during rating and during billing. During rating, taxes are calculated by ECE. You can customize tax calculation in rating by using ECE extensions.

To calculate taxes during billing:

For each rated event, PCM_OP_RATE_EVENT reads the PIN_FLD_RATES_USED array in the input flist to determine what pricing to apply. This pricing information determines how the taxable amount is treated.
PCM_OP_RATE_EVENT calls PCM_OP_RATE_POL_TAX_LOC to determine whether custom processing or default processing is used to determine the tax-related locales.
- If default processing is used, PCM_OP_RATE_EVENT retrieves the locales from the database.
- If custom processing is used, control is handed to PCM_OP_RATE_POL_TAX_LOC, which determines which locales to use.
The locales are used during the tax calculation process to determine jurisdiction. BRM stores up to four tax locales for the current account, session, and event.

See "Retrieving Tax Location Data" for more information on the tax locales and how to customize their retrieval.
PCM_OP_RATE_EVENT also checks the PIN_FLD_EXEMPTIONS array in /account objects to determine whether all or part of the purchase amount is exempt from taxes.
PCM_OP_RATE_EVENT returns a revised set of objects for the event. This can include PIN_FLD_TAXES and PIN_FLD_EXEMPTIONS arrays to indicate tax amounts that were calculated immediately by PCM_OP_RATE_TAX_CALC.
The event is taxable, PCM_OP_RATE_EVENT calls PCM_OP_BILL_CYCLE_TAX. If the event is nontaxable, PCM_OP_RATE_EVENT does nothing.
If a transaction is not already open, PCM_OP_BILL_CYCLE_TAX opens one.

If PCM_OPFLG_CALC_ONLY is set, the transaction is opened with the flag PCM_TRANS_OPEN_READONLY.
PCM_OP_BILL_CYCLE_TAX calls PCM_OP_RATE_TAX_CALC to perform the actual tax calculation. See "How PCM_OP_RATE_TAX_CALC Calculates Taxes" for information.
PCM_OP_BILL_CYCLE_TAX receives the tax data from PCM_OP_RATE_TAX_CALC in the PIN_FLD_TAXES array.
PCM_OP_BILL_CYCLE_TAX does one of the following:
- Creates an /event/billing/cycle/tax object with the taxable amount if there were any deferred taxes.
- If PCM_OP_BILL_CYCLE_TAX was called with the PCM_OPFLG_CALC_ONLY flag set, it still performs the tax calculation but does not create the /event/billing/cycle/tax object.
  
  Instead, the PCM_OP_BILL_CYCLE_TAX output flist contains the PIN_FLD_RESULTS array, an flist with the information that would have been used to create the /event/billing/cycle/tax object.
PCM_OP_BILL_CYCLE_TAX sets the /event/billing/cycle/tax object status to inactive.
PCM_OP_BILL_CYCLE_TAX commits the transaction if one was opened.

How PCM_OP_RATE_TAX_CALC Calculates Taxes

PCM_OP_RATE_TAX_CALC determines the taxation Data Manager (DM) or custom taxation method to be used for an event. It sends the input flist to the DM or the custom tax calculation method for calculation. It receives the information it needs to calculate taxes from the following input fields:

The tax code of the BRM charge offer mapped to a charge offer code that is recognized by the taxation software. The tax code also identifies the taxation DM or the custom tax calculation method to be used.
The purchase amount to be taxed from the PIN_FLD_TAXES array. Each element of the PIN_FLD_TAXES array represents a separate tax calculation method.

Note:

If the tax calculation software or custom policy is not specified in the tax code, taxes are not calculated.
The locations that are involved in the transaction to be taxed. This includes ship-from, ship-to, order origin, and order accept addresses for sales and use taxation.

Note:

For telecommunications taxation, the address fields contain additional information (NPA-NXX or geocodes) for origin, termination, and charge-to numbers.
The date and time of the transaction from the PIN_FLD_START_T and PIN_FLD_END_T fields. PIN_FLD_START_T is used to compute PIN_FLD_ELAPSED_TIME or duration (that is, the difference between the end time and start time).
Tax exemption information, including exemption information based on tax jurisdiction, from the PIN_FLD_EXEMPTIONS array.
The tax supplier ID from the PIN_FLD_TAX_SUPPLIER field.
Other optional values such as the account's bill object in the PIN_FLD_BILL_OBJ field and telecommunications values such as incorporated, residence, and regulated flags.

PCM_OP_RATE_TAX_CALC checks for the following errors:

Missing or nonvalid PIN_FLD_TAX_CODE field.
Nonvalid PIN_FLD_TAXPKG_TYPE field, which is derived from PIN_FLD_TAX_CODE field and the taxcodes_map file.
Missing or nonvalid tax database entry.

PCM_OP_RATE_TAX_CALC returns an output flist with a revised PIN_FLD_TAXES array containing the tax data that the tax calculation software or the custom tax calculation method returns. The calculated taxes are sorted by jurisdiction.

If the PCM_OPFLG_CALC_ONLY flag is set, PCM_OP_RATE_TAX_CALC performs the tax calculation and returns the tax rate and amount. The tax data is not written to the database, however.

How PCM_OP_RATE_TAX_CALC Validates Addresses and VAT Certificates

You can call PCM_OP_RATE_TAX_CALC in jurisdiction-check-only mode during account creation to perform address or VAT certificate number validation. You specify jurisdiction-check-only mode by using the PIN_FLD_COMMAND input field. The following modes are supported:

If PIN_FLD_COMMAND is set to 1, it sends an address to the taxation DM for verification and additionally returns the geocode and county information in the PIN_FLD_NAMEINFO array if the address was successfully validated.
If PIN_FLD_COMMAND is set to 2, it sends a VAT certificate number to the tax DM for validation.

Note:

The VAT certificate number validation is supported only for a custom tax calculation implementation. It is not supported by the default BRM tax calculation functions.

In jurisdiction-check-only mode, PCM_OP_RATE_TAX_CALC returns 1 if the jurisdiction is valid and 0 if it is not.

Policy Opcodes Called by PCM_OP_RATE_TAX_CALC

PCM_OP_RATE_TAX_CALC calls the following policy opcodes that you can customize to modify the tax data or to use custom tax calculation:

PCM_OP_RATE_POL_PRE_TAX, to modify any tax data in the input flist that is passed to the taxation DM.

See "Modifying Tax Data Before Calculating Taxes" for more information.
PCM_OP_RATE_POL_POST_TAX, to modify any tax data in the output flist that is returned from the taxation DM.

See "Modifying Tax Data After Calculating Taxes" for more information.
PCM_OP_CUST_POL_TAX_CALC, to use custom tax calculation methods instead of using an external tax calculation software.

See "Using Custom Tax Rates" for more information.

Modifying Tax Data Before Calculating Taxes

Use the PCM_OP_RATE_POL_PRE_TAX policy opcode to modify data before you send it to the Vertex DM or Taxation Gateway for calculating taxes.

This opcode is called by PCM_OP_RATE_TAX_CALC before determining the tax package to use for tax calculation.

By default, PCM_OP_RATE_POL_PRE_TAX returns the input flist as the output flist. You can customize the opcode to perform these functions:

Identify the geocode for an address and provide it to the Vertex DM or Taxation Gateway.
Add a tax exemption before sending it to the Vertex DM or Taxation Gateway.
Change the tax exemption from a percentage to a set amount.

Modifying Addresses for Non-telephony Events

You can customize the PCM_OP_RATE_POL_PRE_TAX policy opcode to add telco information to addresses for non-telephony events. This enables:

Vertex DM to calculate taxes on non-telephony events using Vertex Communications Tax Q Series.
Taxation Gateway to calculate taxes on non-telephony events using Vertex O Series.

The policy opcode’s source file includes sample commented code for adding telco information to these fields:

PIN_FLD_ORDER_ORIGIN
PIN_FLD_ORDER_ACCEPT
PIN_FLD_SHIP_TO
PIN_FLD_SHIP_FROM
PIN_FLD_INTERNATIONAL_IND

To customize the policy opcode to add telco information to addresses:

Open the fm_rate_pol_pre_tax.c policy source file in a text editor.
Uncomment the sample code beginning at the line:
```
#ifdef OVERRIDE_BY_ZIP
```
Define the OVERRIDE_BY_ZIP macro.
Save and close the file.
Recompile and deploy the updated policy opcode following your standard build and deployment procedures.

Modifying Tax Data After Calculating Taxes

You can customize the PCM_OP_RATE_POL_POST_TAX policy opcode to modify data in the output flist returned by the external tax calculation software after taxes are calculated. For example, you can use this policy opcode to:

Change how the Connection Manager (CM) logs messages returned by the Vertex DM or Taxation Gateway.

Add a surcharge to the tax amount in the output flist returned from the Vertex DM or Taxation Gateway, as shown in the following example:

void fm_rate_pol_post_tax(...) {

   /* Loop through array of incoming taxes*/
   while ((t_flistp = PIN_FLIST_ELEM_GET_NEXT(in_flistp, PIN_FLD_TAXES,  
   &elemid, 1, &cookie, ebufp)) != (pin_flist_t )NULL) {

      /* Add a surcharge entry to the SUBTOTAL array */
      cnt = PIN_FLIST_ELEM_COUNT(t_flistp, PIN_FLD_SUBTOTAL, ebufp);
      s_flistp = PIN_FLIST_ELEM_ADD(t_flistp, PIN_FLD_SUBTOTAL, cnt++, ebufp);

      /* Add the entries to the SUBTOTAL array */
      PIN_FLIST_FLD_SET(s_flistp, PIN_FLD_TAX, (void *)&tax, ebufp);
      PIN_FLIST_FLD_SET(s_flistp, PIN_FLD_SUBTYPE, (void *)&taxType, ebufp); 
   }
}

By default, PCM_OP_RATE_POL_POST_TAX returns the input flist as the output flist and removes the PIN_FLD_MESSAGES array. It also logs any messages returned from the Vertex DM or Taxation Gateway according to the tax_return_loglevel setting in the CM pin.conf file.

The default implementation of PCM_OP_RATE_POL_POST_TAX handles errors as follows:

Logs messages according to tax_return_loglevel in the CM pin.conf file. The default is to log warnings only.
If an error occurs while reading the tax_return_loglevel entry, the opcode sets the error buffer to INVALID_CONF.

Overriding Customer Tax Locale for Purchases

By default, BRM calculates the taxes your customers owe for purchases using their shipped-to address (stored in an /account object's PIN_FLD_NAMEINFO array). You can instead configure BRM to calculate the tax amount using a customer's real-time location when purchasing a bundle (or deal), buying a charge offer (or product), or topping up a prepaid account.

To do so, configure your custom client application to call the following opcodes:

PCM_OP_SUBSCRIPTION_PURCHASE_DEAL
PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT
PCM_OP_PYMT_TOPUP

You pass in the customer's real-time location to the opcode using the PIN_FLD_LOCALE input flist field or using zone maps.

Real-Time Location Using PIN_FLD_LOCALE

Set the PIN_FLD_LOCALE input flist field to the customer's current location in the following format:

"City;State;Zipcode;Country"

For example:

"Austin;TX;78741;US"

The following example shows a PCM_OP_PYMT_TOPUP input flist that sets the customer's real-time location to Chicago using PIN_FLD_LOCALE:

0 PIN_FLD_PROGRAM_NAME                   STR [0] "testnap"
0 PIN_FLD_POID                          POID [0] 0.0.0.1 /account 91058 8
0 PIN_FLD_LOCALE                         STR [0] "Chicago;IL;60634;US"
0 PIN_FLD_INHERITED_INFO           SUBSTRUCT [0] allocated 1, used 1
1 PIN_FLD_TOPUP_INFO                   ARRAY [0] allocated 4, used 4
2       PIN_FLD_BILLINFO_OBJ            POID [0] 0.0.0.1 /billinfo 94130 0
2       PIN_FLD_BAL_GRP_OBJ             POID [0] 0.0.0.1 /balance_group 93298 0
2       PIN_FLD_TOPUP_AMT            DECIMAL [0] 19
2         PIN_FLD_PAYINFO              ARRAY [0] allocated 4, used 4
3             PIN_FLD_ACCOUNT_OBJ       POID [0] 0.0.0.1 /account 91058 8
3             PIN_FLD_POID              POID [0] 0.0.0.1 /payinfo/cc -1 0
3             PIN_FLD_PAY_TYPE          ENUM [0] 10003
3             PIN_FLD_CC_INFO          ARRAY [0] allocated 9, used 9
4                 PIN_FLD_SECURITY_ID    STR [0] "ID"
4                 PIN_FLD_NAME           STR [0] "John Evans"
4                 PIN_FLD_DEBIT_EXP      STR [0] "Expiration"
4                 PIN_FLD_DEBIT_NUM      STR [0] "DebitNumber"
4                 PIN_FLD_COUNTRY        STR [0] "US"
4                 PIN_FLD_ZIP            STR [0] "94065"
4                 PIN_FLD_STATE          STR [0] "CA"
4                 PIN_FLD_CITY           STR [0] "Redwood City"
4                 PIN_FLD_ADDRESS        STR [0] "100 Oracle Pkwy"

Real-Time Location Using Zone Maps

Set the following opcode input flist fields to supply the customer's real-time location using a zone map:

PIN_FLD_ZONEMAP_NAME: The name of the zone map to use.
PIN_FLD_ZONEMAP_TARGET: The name of the end-leaf node in the zone map.

The following example shows a PCM_OP_SUBSCRIPTION_PURCHASE_DEAL input flist that sets the customer's real-time location using a zone map:

0 PIN_FLD_POID              POID [0] 0.0.0.1 /account 101267 7 
0 PIN_FLD_SERVICE_OBJ       POID [0] 0.0.0.1 /service/ip 98643 6 
0 PIN_FLD_PROGRAM_NAME       STR [0] "testnap" 
0 PIN_FLD_ZONEMAP_TARGET     STR [0] "3"
0 PIN_FLD_ZONEMAP_NAME       STR [0] "TestZoneMap2"
0 PIN_FLD_DEAL_INFO    SUBSTRUCT [0] allocated 20, used 7 
1    PIN_FLD_PRODUCTS      ARRAY [0] allocated 35, used 35 
2       PIN_FLD_FLAGS        INT [0] 1

Note:

To use this method, ensure that a zone map with the specified name and target node exists and is active in the environment.

Using Custom Tax Rates

If your business uses a simple tax method, you may not need a third-party tax calculation package. Instead, you can use custom tax rates. In simple scenarios, you can implement taxation with built-in features that do not require programming.

If your business needs a more complex tax structure but not the full capabilities of a tax calculation package, you can implement custom tax rates by modifying two taxation policy opcodes:

PCM_OP_CUST_POL_TAX_INIT: Caches tax rate information from the /config/taxcodes_map object, then calls either the PCM_OP_CUST_POL_TAX_CALC policy opcode (if no tax calculation software is configured), the Vertex DM (if the Vertex Q tax calculation software is configured), or Taxation Gateway (if the Vertex O Series tax calculation software is configured).
PCM_OP_CUST_POL_TAX_CALC: Performs the tax calculation for all tax codes with package code “U” (user-defined). By default, it reads the custom tax rate from cache and calculates tax as:

tax = amount * rate

To use custom tax rates, complete the following steps:

Define your tax rates as required for your BRM release. See "Creating Tax Codes" in BRM Calculating Taxes.
Modify the source file for PCM_OP_CUST_POL_TAX_INIT (BRM_SDK_home/source/sys/fm_cust_pol/fm_cust_pol_tax_init.c) to implement your customizations.

To load tax code data in a different format, define a data structure in fm_cust_pol_tax_init.c for your custom tax rates, and perform any additional customizations required in that file.
If required for your customizations, modify the source file for PCM_OP_CUST_POL_TAX_CALC (BRM_SDK_home/source/sys/fm_cust_pol_tax_calc.c).
Compile fm_cust_pol_tax_init.c and fm_cust_pol_tax_calc.c using the makefile in BRM_SDK_home/source/sys/fm_cust_pol.
Copy the compiled shared libraries to BRM_home/lib, replacing the existing versions.
Open the CM configuration file (pin.conf) and ensure the following entries in the fm_module section are enabled (not commented out):
```
- cm fm_module BRM_home/lib/fm_cust.so fm_cust_config - pin
- cm fm_module BRM_home/lib/fm_cust_pol.so fm_cust_pol_config fm_cust_pol_tax_init pin
```
Stop and restart the CM.

Using Geocodes to Calculate Taxes

A geocode is a geographic identifier used to determine a tax jurisdiction. Different tax calculation packages use their own geocode systems and update them frequently. To use geocodes to calculate taxes, modify PCM_OP_RATE_POL_PRE_TAX to query the geocoder and obtain the account’s geocode. The geocoder maps the account’s address or postal code to a unique geocode.

If a geocode is available during tax calculation, the tax package uses it to compute taxes. If a geocode is not available, the tax calculation software selects a geocode from those it finds for the account address; selection behavior depends on the package configuration.

Note:

The tax calculation software does not map an address to a unique geocode.

To use geocodes to calculate taxes, complete the following steps:

In Storable Class Editor, ensure a /profile storable class exists and add the PIN_FLD_GEOCODE field to it.

If more than one tax calculation package is configured, create an array with separate PIN_FLD_GEOCODE fields per package. Use array index values to represent packages as follows:
- 0 specifies a custom tax package.
- 2 specifies the WorldTax package.
- 3 specifies the Sales Tax Q Series package.
- 4 specifies the Communications Tax Q Series package.
- 6 specifies the Vertex O Series package.
Modify PCM_OP_CUST_POL_VALID_NAMEINFO to store the geocode in the PIN_FLD_GEOCODE field of the /profile object when the address is validated successfully.
Implement PCM_OP_RATE_POL_PRE_TAX to:
- Read the geocode from the /profile object.
- Set the geocode in the PIN_FLD_SHIP_TO or PIN_FLD_SHIP_FROM field in the PIN_FLD_TAXES array of the input flist sent to the Vertex DM (for Vertex Q Series) or Taxation Gateway (for Vertex O Series).
  
  For example, update this value:
```
PIN_FLD_SHIP_TO STR [0] "Cupertino; CA; 95012; US; []"
```
  so that it includes the geocode in square brackets:
```
PIN_FLD_SHIP_TO STR [0] "Cupertino; CA; 95012; US; [050850860]"
```
Set the location mode to geocode by setting PIN_FLD_LOCATION_MODE to 1 in the PIN_FLD_TAXES array of the input flist.

When location mode is set to geocode, the Vertex DM or Taxation Gateway passes the geocode instead of the address to the tax calculation module.

For example:
```
PIN_FLD_LOCATION_MODE  ENUM [0] 1
```

After tax calculation, the Vertex DM or Taxation Gateway returns the jurisdiction (address and geocode) where rates were applied in the PIN_FLD_TAXES array of the output flist. For example:

PIN_FLD_NAME STR[0] "US: CA: Santa Clara: Cupertino: 95012 : [050850860]"

Adding Tax Information to Accounts

Use PCM_OP_CUST_SET_TAXINFO to add or update tax information for an account.

This opcode manages the following account-level tax attributes:

VAT certificate
Tax exemptions
Tax incorporation status
Tax residency status

PCM_OP_CUST_SET_TAXINFO adds or updates the following fields in the PIN_FLD_TAXINFO array of the /account object:

PIN_FLD_VAT_CERT
PIN_FLD_EXEMPTIONS
PIN_FLD_INCORPORATED_FLAG
PIN_FLD_RESIDENCE_FLAG

For example, when an account is created and a VAT certificate number or exemption information is provided, call PCM_OP_CUST_SET_TAXINFO. PCM_OP_CUST_SET_TAXINFO performs these functions:

Modifies existing data or adds information to the PIN_FLD_TAXINFO array of the /account object using the field values in the input flist.
If no VAT certificate number is provided, replaces the value of PIN_FLD_VAT_CERT in the account object with an empty string ("").
If no exemption information is provided, deletes the PIN_FLD_EXEMPTIONS array.
If the input flist includes PIN_FLD_INCORPORATED_FLAG or PIN_FLD_RESIDENCE_FLAG, adds or updates these values in the account object.

Validating Tax Information

To customize tax information validation, use PCM_OP_CUST_POL_VALID_TAXINFO. This opcode validates the VAT certificate number to prevent invalid entries, which can cause tax calculation failures.

By default, PCM_OP_CUST_POL_VALID_TAXINFO checks VAT certificate data and performs the following:

If the VAT certificate number is an empty string, returns validation result PASS.

If the tax_valid entry in the CM pin.conf file is not set or is set to 0, returns validation result FAIL.

#Enables or disables validation of the VAT certificate number. 
#1 means Enable; 0, which is the default, means Disable.
- fm_cust_pol  tax_valid 0

You can customize PCM_OP_CUST_POL_VALID_TAXINFO to use a custom validation service to validate the VAT certificate number. For example, instead of calling PCM_OP_RATE_TAX_CALC, you can call a custom VAT validation function by rewriting do_vat_cert_validation in the PCM_OP_CUST_POL_VALID_TAXINFO source file.

Retrieving Tax Calculation Data

See the following topics:

Retrieving a List of Tax Codes

Use PCM_OP_RATE_POL_GET_TAXCODE to retrieve the list of tax codes. This opcode returns all tax codes loaded from the config_taxcodes_map.xml file and cached by the CM during initialization. For example, Billing Care uses this opcode to display the list of tax codes used to configure rate plans for taxation. You can customize this opcode to return additional cached tax code information (for example, descriptions or effective dates).

This opcode is not called by any opcode.

PCM_OP_RATE_POL_GET_TAXCODE takes an account POID as input and performs these functions:

Obtains the database number from the POID.
Searches the CM in-memory cache for tax codes.
Returns an array of tax code names in the output flist.

It returns the tax code names cached from the config_taxcodes_map.xml file by the CM during initialization.

Retrieving a List of Tax Suppliers

Use PCM_OP_RATE_POL_GET_TAX_SUPPLIER to retrieve the list of tax suppliers. You can customize this opcode by modifying fields in the output flist. You can also control which fields are validated by adding or removing them from the input flist.

PCM_OP_RATE_POL_GET_TAX_SUPPLIER takes an account POID as input and performs these functions:

Obtains the database number from the POID.
Performs a global search for tax suppliers.
Returns a list of tax suppliers with relevant fields in the output flist.

This opcode is not called by any opcode.

Retrieving Tax Supplier Data

Use PCM_OP_RATE_POL_MAP_TAX_SUPPLIER to retrieve tax supplier data. You can customize this opcode to change how a tax supplier is derived for a specific BRM event.

This opcode is called by PCM_OP_BILL_TAX_EVENT.

This opcode supports two modes:

If a pin_tax_supplier.xml file is used and specified in the CM pin.conf file, the opcode searches the file by company ID based on the charge offer name and ship-to categories. If a match is found, it returns that entry. If no match exists, it returns NULL for the flist pointer.
If the pin_tax_supplier.xml file does not exist or is not enabled in the pin.conf file, the opcode attempts to find the tax_supplier object POID in the PIN_FLD_PRODUCTS array of the /account object.

The opcode also retrieves the utility flag used for telecommunications taxation from PIN_FLD_REGULATED_FLAG in the /config/tax_supplier object and returns it in the output flist.

Retrieving Tax Location Data

Use PCM_OP_RATE_POL_TAX_LOC to customize how PCM_OP_RATE_EVENT obtains locations for tax jurisdictions. This opcode returns event locations used to establish jurisdictions for tax calculation.

Note:

For telephony events, the locations include additional information enclosed in square brackets ([]).

For example, you can retrieve the PIN_FLD_ORDER_ACCEPT value from a different system or provide a geocode instead of an NPA/NXX for telephony events.

PCM_OP_RATE_POL_TAX_LOC takes an account POID as input and returns these fields:

PIN_FLD_SHIP_TO: The ship-to address; for telephony events, the call termination number.
PIN_FLD_SHIP_FROM: The ship-from address; for telephony events, the call origination number.
PIN_FLD_ORDER_ACCEPT: The order-accept address; for telephony events, the charge-to number.
PIN_FLD_ORDER_ORIGIN: The order-origin address.

It returns four strings with the following syntax:

city; state_abbreviation;zipcode; country;[code,location,international_indicator]

where:

code is the geocode or NPA/NXX.
location specifies the type of code:
- 0: Address
- 1: Geocode
- 2: NPA/NXX
international_indicator specifies the type of call:
- 1: North America numbering plan
- 2: North America originated, overseas terminated
- 3: North America originated, overseas terminated and billed
- 4: IOC North America originated, overseas terminated
- 5: Overseas originated, North America terminated
- 6: IOC North America originated, overseas terminated and billed
- 7: Overseas originated, overseas terminated

For example:

1  PIN_FLD_SHIP_TO            STR [0] "Cupertino; CA; 95014; USA;[408572,2,1]"
1  PIN_FLD_SHIP_FROM          STR [0] "Englewood; CO; 80112; USA;[060050006000,1,1]"
1  PIN_FLD_ORDER_ORIGIN       STR [0] "Englewood; CO; 80112; USA;[060050006000,1,1]"
1  PIN_FLD_ORDER_ACCEPT       STR [0] "Englewood; CO; 80112; USA;[060050006000,1,1]"
1  PIN_FLD_LOCATION_MODE     ENUM [0] 1
1  PIN_FLD_INTERNATIONAL_IND  INT [0] 1

By default, PCM_OP_RATE_POL_TAX_LOC uses the sources for locations described in Table 23-2:

Table 23-2 PCM_OP_RATE_POL_TAX_LOC Source Locations

Location	Default Source
PIN_FLD_SHIP_TO	The account billing address, obtained from the PIN_FLD_NAMEINFO array of the /account object.
PIN_FLD_SHIP_FROM	Same as PIN_FLD_ORDER_ACCEPT.
PIN_FLD_ORDER_ACCEPT	The value of the provider_loc entry in the CM pin.conf file.
PIN_FLD_ORDER_ORIGIN	Same as PIN_FLD_ORDER_ACCEPT.

Using Vertex O Series to Calculate Taxes

The Taxation Gateway uses the following opcodes to send tax requests to the Vertex O Series tax calculation software:

PCM_OP_TAX_GW_CALCULATE_TAX. See "Calculating Taxes at Event Time or During Billing".
PCM_OP_TAX_GW_VALIDATE_ADDRESS. See "Validating Tax Jurisdictions Based on Address".

Calculating Taxes at Event Time or During Billing

Use PCM_OP_TAX_GW_CALCULATE_TAX to calculate taxes at purchase time, during usage, or during billing. This opcode is called by PCM_OP_RATE_TAX_CALC.

The opcode takes the account POID, tax currency, tax package type, and other tax details as input and performs the following functions:

Uses the tax package type to locate the taxation provider’s endpoint.
Converts the input flist to a JSON payload using mappings defined in the vertex_supplies_calculate_tax_mappings.yaml file.
Enriches the JSON payload based on the configured tax code mappings.
Sends the JSON payload through an HTTP POST request to the Vertex O Series /v2/supplies endpoint.
Converts the REST API endpoint's response payload to an output flist using the vertex_supplies_calculate_tax_mappings.yaml file.
Rounds calculated tax values according to BRM rounding configuration.
Returns the calculated taxes for the event in the opcode output flist.

Validating Tax Jurisdictions Based on Address

Use the PCM_OP_TAX_GW_VALIDATE_ADDRESS opcode to validate tax jurisdictions based on the address passed in during account creation. This opcode is called by PCM_OP_RATE_TAX_CALC.

The opcode requires the following input flist fields:

PIN_FLD_POID set to the account's POID.
PIN_FLD_TAXPKG_TYPE set to PIN_RATE_TAXPKG_VERTEX_OSERIES (6), the taxation provider that performs the jurisdiction check.

PCM_OP_TAX_GW_VALIDATE_ADDRESS performs these functions:

Uses the tax package type to locate the taxation provider's endpoint.
Converts the input flist to a JSON payload using mappings defined in the vertex_validate_address_mappings.yaml file.
Sends the JSON payload through an HTTP POST to the Vertex O Series /v2/address-lookup endpoint.
Converts the REST API response payload to an output flist using the vertex_validate_address_mappings.yaml file.
Sets PIN_FLD_RESULT in the output flist to 1 if the address is valid or 0 if invalid, and includes the validated address and geocode information.

Retrieving Additional Tax Data from Vertex Tax Q Series

When you perform tax calculation using the Vertex Tax Q Series software, it returns tax data in an input flist to the BRM opcodes. The tax data is then processed and stored in the BRM database. For a list of data that Vertex returns to the opcodes by default, see "Default Tax Data Returned by Vertex Communications Tax Q Series" for more information.

You can also customize BRM to request and store additional data from the Vertex Tax Q Series software. See the following:

Default Tax Data Returned by Vertex Communications Tax Q Series

Vertex Communications Tax Q Series makes its attributes available to other applications through data handles. BRM uses tax data from the following two data handles only:

The Register Transaction data handle, which defines tax transaction attributes.
The Register Transaction Tax Detail data handle, which defines tax jurisdiction attributes.

Vertex Communications Tax Q Series sends tax attributes to the BRM API in the following input flist structures:

PIN_FLD_TAXES input flist array: Contains the result of a tax calculation at the transaction level.
PIN_FLD_TAXES.PIN_FLD_SUBTOTAL input flist array: Contains the result of a tax calculation at the jurisdiction level, such as at the Federal level or at the State level. In each jurisdiction, the taxes are broken into subtypes, such as 911 and DEAF.

Table 23-3 shows the tax attributes that are sent to the BRM API by default and the flist structure in which the attribute is passed:

Table 23-3 Default BRM Tax Attributes and flist Structure

Vertex Communications Tax Q Series Data Handle	Vertex Communications Tax Q Series Attributes	BRM Input Flist Structure
Register Transaction data handle	eCtqAttribChargeToLocationMode eCtqAttribChargeToPostalCode eCtqAttribTaxedGeoCodeOverrideCode eCtqAttribInvoiceDate eCtqAttribBilledLines eCtqAttribInvoiceNumber eCtqAttribServiceCode eCtqAttribCategoryCode eCtqAttribCreditCode eCtqAttribDescriptionFlag eCtqAttribTaxedGeoCodeIncorporatedCode eCtqAttribFederalExemptFlag eCtqAttribStateExemptFlag eCtqAttribCountyExemptFlag eCtqAttribCityExemptFlag eCtqAttribWriteJournal Note: The eCtqAttribWriteJournal attribute is retrieved from the Register Subsystem data handle.	PIN_FLD_TAXES array
Register Transaction Tax Detail data handle	eCtqAttribTrunksTaxed eCtqAttribTaxCode eCtqAttribLinkTaxAmount eCtqAttribRowCount	PIN_FLD_TAXES.PIN_FLD_SUBTOTAL array

Vertex Communications Tax Q Series Data Handle

Vertex Communications Tax Q Series Attributes

BRM Input Flist Structure

Register Transaction data handle

eCtqAttribChargeToLocationMode
eCtqAttribChargeToPostalCode
eCtqAttribTaxedGeoCodeOverrideCode
eCtqAttribInvoiceDate
eCtqAttribBilledLines
eCtqAttribInvoiceNumber
eCtqAttribServiceCode
eCtqAttribCategoryCode
eCtqAttribCreditCode
eCtqAttribDescriptionFlag
eCtqAttribTaxedGeoCodeIncorporatedCode
eCtqAttribFederalExemptFlag
eCtqAttribStateExemptFlag
eCtqAttribCountyExemptFlag
eCtqAttribCityExemptFlag
eCtqAttribWriteJournal

Note: The eCtqAttribWriteJournal attribute is retrieved from the Register Subsystem data handle.

PIN_FLD_TAXES array

Register Transaction Tax Detail data handle

eCtqAttribTrunksTaxed
eCtqAttribTaxCode
eCtqAttribLinkTaxAmount
eCtqAttribRowCount

PIN_FLD_TAXES.PIN_FLD_SUBTOTAL array

Requesting Additional Data from Vertex Tax Software

You can request additional tax data from the Vertex tax calculation software by customizing the PCM_OP_RATE_POL_PRE_TAX policy opcode. Vertex returns the requested tax data in the input flist to PCM_OP_RATE_POL_POST_TAX.

To request additional tax data:

Customize PCM_OP_RATE_POL_PRE_TAX to request data from the following two Vertex data handles: Register Transaction data handle and Register Transaction Tax Detail data handle.
Add custom output flist fields to PCM_OP_RATE_POL_PRE_TAX. To request additional tax data, add the flist fields shown in bold below to the PIN_FLD_RESULTS output flist array:
```
0 PIN_FLD_RESULTS           ARRAY [0] allocated 20, used 1
1   PIN_FLD_TAXES                 [0] allocated 20, used 1
2     PIN_FLD_FIELD_NAMES   ARRAY [ArrayIndexValue] allocated 20, used 2
3       PIN_FLD_TYPE         ENUM [0] VertexDataType
1   PIN_FLD_SUBTOTAL              [0] allocated 20, used 1
2     PIN_FLD_FIELD_NAMES   ARRAY [ArrayIndexValue] allocated 20, used 2
3       PIN_FLD_TYPE         ENUM [0] VertexDataType
```
where:
- The PIN_FLD_TAXES structure specifies that you are requesting data from the Vertex Register Transaction data handle. All elements under this array must reference attributes from the Register Transaction data handle only.
- The PIN_FLD_SUBTOTAL structure specifies that you are requesting data from the Vertex Register Transaction Tax Detail data handle. All elements under this array must reference attributes from the Register Transaction Tax Detail data handle only.
- ArrayIndexValue specifies the the Vertex tax calculation software attribute ID that you are requesting. For example, set the PIN_FLD_FIELD_NAMES array index to 304 to request the eCtqAttribTrunksTaxed attribute.
- VertexDataType specifies the Vertex data type ID for the the Vertex tax calculation software attribute you are requesting. Supported Vertex data types include the following:
  - eCtqInt
  - eCtqString
  - eCtqBool
  - eCtqFloat
  - eCtqDouble
  - eCtqLong
  - eCtqDate

For example, the following shows custom output flist fields for requesting additional tax data:

0 PIN_FLD_RESULTS                ARRAY [0] allocated 20, used 1 
1   PIN_FLD_TAXES                      [0] allocated 20, used 1 
2     PIN_FLD_FIELD_NAMES        ARRAY [271] allocated 20, used 2 
3       PIN_FLD_TYPE              ENUM [0] 3 
1   PIN_FLD_SUBTOTAL                   [0] allocated 20, used 1 
2     PIN_FLD_FIELD_NAMES        ARRAY [285] allocated 20, used 2 
3       PIN_FLD_TYPE              ENUM [0] 10

Retrieving Additional Tax Data

The additional data you request from the Vertex tax calculation software is returned in the PCM_OP_RATE_POL_POST_TAX input flist. You can customize the BRM opcodes to retrieve the tax data from the input flist fields and process it according to your business needs.

Vertex returns the additional data in the following PCM_OP_RATE_POL_POST_TAX input flist structure under the PIN_FLD_TAXES array or the PIN_FLD_TAXES.PIN_FLD_SUBTOTAL array:

If passed in the PIN_FLD_TAXES array, the data is for one tax transaction. This information is from the Register Transaction data handle.

If passed in the PIN_FLD_TAXES.PIN_FLD_SUBTOTAL array, the tax data is for one jurisdiction. This information is from the Register Transaction Tax Detail data handle.

1  PIN_FLD_FIELD_NAMES               ARRAY [ArrayIndexValue] allocated 20, used 3
2    PIN_FLD_TYPE                     ENUM [0] VertexDataType
2    PIN_FLD_VERTEX_CTQ_BRMDataType    INT [0] BRMTaxData

where:

ArrayIndexValue specifies the Vertex tax calculation software attribute ID. For example, enter 295 to request data from the eCtqAttribTaxedGeoCode attribute.
VertexDataType specifies the data type ID of the Vertex attribute. For example, enter 3 for the eCtqInt data type.
BRMTaxData is the tax data from the specified the Vertex attribute.

PIN_FLD_VERTEX_CTQ_BRMDataType is the name of the input flist field that contains the tax data. Table 23-4 specifies the name of the BRM input flist field that corresponds to each Vertex data type.

Table 23-4 BRM Input flist for Vertex Data Type

BRM Data Type	Vertex Data Type
INT	eCtqInt
STR	eCtqString
BOOL	eCtqBool
FLOAT	eCtqFloat
DOUBLE	eCtqDouble
LONG	eCtqLong
STR Important: This field will contain the date in the Vertex tax calculation software format (CCYYMMDD). This is different from the mapping for custom input fields, in which eCtqDate is mapped to PIN_FLD_VERTEX_CTQ_TIMESTAMP.	eCtqDate

For example, the following shows a simple PCM_OP_RATE_POL_POST_TAX input flist. The flist fields for the additional tax data are shown in bold.

# number of field entries allocated 20, used 2
0 PIN_FLD_POID                  POID [0] 0.0.0.1 /account 27225 0
0 PIN_FLD_EVENT_OBJ             POID [0] 0.0.0.1 /event/billing/cycle/tax 11111 0
0 PIN_FLD_TAXES                ARRAY [0] allocated 20, used 3
1   PIN_FLD_TAXPKG_TYPE         ENUM [0] 0
1   PIN_FLD_TAX              DECIMAL [0] 0.70
1   PIN_FLD_FIELD_NAMES         ARRAY [295] allocated 20, used 3  // Array index = eCtqAttribTaxedGeoCode
2     PIN_FLD_TYPE              ENUM [0] 10
2     PIN_FLD_VERTEX_CTQ_STR     STR [0] "123456789"
1   PIN_FLD_SUBTOTAL           ARRAY [0] allocated 20, used 10
2     PIN_FLD_TAX            DECIMAL [0] 0.70
2     PIN_FLD_TYPE              ENUM [0] 0
2     PIN_FLD_NAME               STR [0] "US; CA; Sunnyvale; ; 94086"
2     PIN_FLD_AMOUNT_GROSS   DECIMAL [0] 19.88
2     PIN_FLD_PERCENT        DECIMAL [0] 0.035000
2     PIN_FLD_AMOUNT_TAXED   DECIMAL [0] 19.88
2     PIN_FLD_AMOUNT_EXEMPT  DECIMAL [0] 0.00
2     PIN_FLD_SUBTYPE           ENUM [0] 0
2     PIN_FLD_DESCR              STR [0] "Excise"
2     PIN_FLD_LOCATION_MODE     ENUM [0] 0
2     PIN_FLD_FIELD_NAMES       ARRAY [304] allocated 20, used 3  // Array index = eCtqAttribTrunksTaxed
3       PIN_FLD_TYPE            ENUM [0] 3
3       PIN_FLD_VERTEX_CTQ_INT   INT [0] 1

Each PIN_FLD_TAXES array element results in a single balance impact. All tax data from the PIN_FLD_TAXES array element is stored in the BRM /event object in the PIN_FLD_BAL_IMPACTS array.

Each PIN_FLD_TAXES.PIN_FLD_SUBTOTAL array element results in a single balance impact for a jurisdiction. All tax data for that jurisdiction is stored in the BRM /event object in the PIN_FLD_TAX_JURISDICTIONS array.

Note:

Sometimes, a Vertex attribute may be missing from the PCM_OP_RATE_POL_POST_TAX input flist. This could be due to an exception condition. For example:

If taxes do not apply because of an undefined service code. In this case, the PIN_FLD_SUBTOTAL array will have a zero tax amount but none of the additional output fields.
If BRM requested a nonapplicable attribute. For example, if BRM requested the eCtqAttribOriginGeoCode attribute when calculating taxes for a wireless service based on the PPU location passed in as a ZIP code.

Storing the Requested Vertex Q Series Data in the BRM Database

All additional Vertex Tax Q Series data that you request is returned in the PCM_OP_RATE_POL_POST_TAX input flist.

To customize the opcode to store the additional data in the BRM database:

Create a custom tax storable class.

See "Creating a Custom Storable Class for Vertex Tax Data" for more information.
Customize PCM_OP_RATE_POL_POST_TAX to store the additional tax data in your custom tax storable class.

See "Storing Vertex Tax Data in Your Custom Storable Class" for more information.
Configure BRM to itemize taxes by jurisdiction.

Creating a Custom Storable Class for Vertex Tax Data

To store the additional data from Vertex, create a custom tax storable class, such as /custom/tax/v_output. The structure of the custom tax storable class should be similar to the following flist:

Note:

Make sure you define all fields in the custom tax storable class.

PIN_FLD_POID
PIN_FLD_ACCOUNT_OBJ
PIN_FLD_EVENT_OBJ
   PIN_FLD_CUSTOM_TAX_BAL_IMPACTS           ARRAY
      PIN_FLD_CUSTOM_TAX_TAXED_GEO_CODE     STR
...
   PIN_FLD_CUSTOM_TAX_TAX_JURISDICTIONS     ARRAY
      PIN_FLD_ELEMENT_ID                    INT
      PIN_FLD_CUSTOM_TAX_TRUNKS_TAXED       INT

Storing Vertex Tax Data in Your Custom Storable Class

To store the additional Vertex tax data in your custom tax storable class, customize PCM_OP_RATE_POL_POST_TAX as follows:

Add the following compiler directives to include Vertex compiler definitions. Copy these files from the Vertex installation directory to the directory in which the policy source code resides.
```
#include "stda.h"
#include "ctqa.h"
```
In the policy source code directory, modify Makefile to add the -DPORT_UNIXANSI Compiler option.

For example, you can use the CFLAGS variable as follows:
```
CFLAGS += -DPORT_UNIXANSI
```
Create a new flist instance of your custom tax storable class and set PIN_FLD_EVENT_OBJ of this instance in the /event object.
In your custom tax storable class:
- Add a PIN_FLD_CUSTOM_TAX_BAL_IMPACTS array element for each PIN_FLD_TAXES element passed in the PCM_OP_RATE_POL_POST_TAX input flist.
- In the PIN_FLD_CUSTOM_TAX_BAL_IMPACTS element, set each custom tax storable class field to its corresponding value from the PIN_FLD_TAXES input flist array. For example, set the PIN_FLD_CUSTOM_TAX_TAXED_GEO_CODE storable class field to the value in the PIN_FLD_VERTEX_CTQ_STR input flist field.
- Add a PIN_FLD_CUSTOM_TAX_TAX_JURISDICTIONS array element for each PIN_FLD_TAXES.PIN_FLD_SUBTOTAL element passed in the PCM_OP_RATE_POL_POST_TAX input flist.
- In the PIN_FLD_CUSTOM_TAX_TAX_JURISDICTIONS element, set each custom tax storable class field to its corresponding value from the PIN_FLD_SUBTOTAL input flist array. For example, set the PIN_FLD_CUSTOM_TAX_TRUNKS_TAXED storable class field to the value in the PIN_FLD_VERTEX_CTQ_INT input flist field.
- Link each PIN_FLD_CUSTOM_TAX_TAX_JURISDICTIONS element to its corresponding parent PIN_FLD_CUSTOM_TAX_BAL_IMPACTS element by using the PIN_FLD_ELEMENT_ID field.
  
  Note:
  
  BRM uses this same method to link PIN_FLD_TAX_JURISDICTIONS elements to corresponding parent PIN_FLD_BAL_IMPACTS elements in the /event object.
Create an instance of your custom tax storable class in the BRM database by calling PCM_OP_CREATE_OBJ.
Drop the PIN_FLD_FIELD_NAMES arrays from PCM_OP_RATE_POL_POST_TAX output flist, because they are no longer needed.
Note:
- In the rare case that no taxes are computed, the policy input flist will include a single PIN_FLD_TAXES element set to 0 and no PIN_FLD_SUBTOTAL elements. Likewise, when a jurisdiction check is performed to validate the account address, the policy input flist will not include a PIN_FLD_TAXES element. In both cases, you do not need to create a new instance of your custom tax storable class.
- For event-time taxation, the PCM_OP_RATE_POL_POST_TAX input flist does not include the PIN_FLD_EVENT_OBJ field.
- For reporting purposes, you can relate a taxed event's default tax fields with the additional tax fields by using the /event POID as the join criterion between the /event object and your custom tax object.

23 Tax Calculation Opcode Workflows

Opcodes Described in This Chapter

Calculating Taxes During Billing

How PCM_OP_RATE_TAX_CALC Calculates Taxes

How PCM_OP_RATE_TAX_CALC Validates Addresses and VAT Certificates

Policy Opcodes Called by PCM_OP_RATE_TAX_CALC

Modifying Tax Data Before Calculating Taxes

Modifying Addresses for Non-telephony Events

Modifying Tax Data After Calculating Taxes

Overriding Customer Tax Locale for Purchases

Using Custom Tax Rates

Using Geocodes to Calculate Taxes

Adding Tax Information to Accounts

Validating Tax Information

Retrieving Tax Calculation Data

Retrieving a List of Tax Codes

Retrieving a List of Tax Suppliers

Retrieving Tax Supplier Data

Retrieving Tax Location Data

Using Vertex O Series to Calculate Taxes

Calculating Taxes at Event Time or During Billing

Validating Tax Jurisdictions Based on Address

Retrieving Additional Tax Data from Vertex Tax Q Series

Default Tax Data Returned by Vertex Communications Tax Q Series

Requesting Additional Data from Vertex Tax Software

Retrieving Additional Tax Data

Storing the Requested Vertex Q Series Data in the BRM Database

Creating a Custom Storable Class for Vertex Tax Data

Storing Vertex Tax Data in Your Custom Storable Class