This chapter describes how to extend the Oracle Communications Billing and Revenue Management (BRM) tax calculation features, including the Vertex Data Manager.
See "About Calculating Taxes" for information on calculating taxes.
How BRM Calculates Taxes
The PCM_OP_RATE_EVENT opcode is the main tax calculation opcode.
For each rated event, this opcode reads the PIN_FLD_RATES_USED array in the input flist to determine what rates to apply. This rate information determines how the taxable amount is treated.
Based on the information it collects, PCM_OP_RATE_EVENT does the following:
If taxation occurs during rating, it calls the PCM_OP_RATE_TAX_CALC opcode.
If taxation occurs during billing, it calls the PCM_OP_BILL_CYCLE_TAX opcode. PCM_OP_BILL_CYCLE_TAX calls PCM_OP_RATE_TAX_CALC to perform the tax calculation.
If the event is nontaxable, it does nothing.
PCM_OP_RATE_EVENT also calls the PCM_OP_RATE_POL_TAX_LOC policy opcode 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 the PCM_OP_RATE_POL_TAX_LOC policy opcode, 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.
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.
See "Retrieving Tax Location Data" for more information on the tax locales and how to customize their retrieval.
PCM_OP_RATE_TAX_CALC performs tax calculations when taxes are calculated during real-time rating or during billing.
To calculate taxes during real-time rating, PCM_OP_RATE_TAX_CALC is called by PCM_OP_RATE_EVENT.
To calculate taxes during billing, PCM_OP_RATE_TAX_CALC is called by PCM_OP_BILL_CYCLE_TAX.
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 product mapped to a product 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.
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.
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 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.
Tax Calculation Error Handling
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, such as vertex_db in the Connection Manager (CM) configuration file ( pin.conf ).
Tax Calculation Policy Opcodes
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.
PCM_OP_RATE_POL_POST_TAX, to modify any tax data in the output flist that is returned from the taxation DM.
PCM_OP_CUST_POL_TAX_CALC, to use custom tax calculation methods instead of using an external tax calculation software.
See "About Customizing BRM Taxation" for more information about customizing tax calculation.
Calculating Taxes without Recording Them
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.
Performing Address or VAT Certificate Validation
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.
In jurisdiction-check-only mode, PCM_OP_RATE_TAX_CALC returns 1 if the jurisdiction is valid and 0 if it is not.
Calculating Taxes during Billing
To calculate taxes during billing, PCM_OP_RATE_EVENT calls PCM_OP_BILL_CYCLE_TAX.
PCM_OP_BILL_CYCLE_TAX performs these steps:
If a transaction is not already open, opens one.
If PCM_OPFLG_CALC_ONLY is set, the transaction is opened with the flag PCM_TRANS_OPEN_READONLY.
Creates an /event/billing/cycle/tax object with the taxable amount if there were any deferred taxes.
The output flist contains the POID of the created /event/billing/cycle/tax object.
Calls PCM_OP_RATE_TAX_CALC to perform the actual tax calculation.
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, this opcode's 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.
Sets the /event/billing/cycle/tax object status to inactive.
Commits the transaction if one was opened in step 1 .
About Customizing BRM Taxation
You can customize BRM tax calculation in the following ways:
To retrieve tax data such as tax codes and tax suppliers from the database. See "Retrieving Tax Calculation Data" for more information.
To use custom tax rates instead of a taxation package. See "Using Custom Tax Rates" for more information.
To modify tax data before passing it to the taxation DM. For example, you can set up tax exemptions prior to calculating taxes. See "Modifying Tax Data Before Calculating Taxes" for more information.
To modify tax data returned from the taxation DM. For example, you can add a surcharge to the tax amount before adding it to the account balance. See "Modifying Tax Data after Calculating Taxes" for more information.
To use geocodes to identify the taxing jurisdiction for the rated and taxed event. See "Using Geocodes to Calculate Taxes" for more information.
Retrieving Tax Calculation Data