Configuring Taxation Gateway for Vertex O Series

About Implementing Vertex O Series Tax Calculation

Vertex O Series integrates BRM with Vertex’s cloud tax service using the Taxation Gateway. To calculate taxes using Vertex Tax O Series, you install and run the BRM Taxation Gateway.

BRM maps tax data to Vertex REST API requests using the Mapper framework, sends the requests to the configured REST endpoints, and returns jurisdiction-level results for billing. You configure the Taxation Gateway properties in the application.yaml file. You do not install Vertex libraries with BRM; BRM uses REST to communicate with Vertex O Series.

Note:

BRM audits tax calculation data but does not support the Vertex auditing features.

To implement Vertex O Series tax calculation:

Set up the Vertex O Series software. See "Setting Up the Vertex Software" for more information.
Configure your tax codes. See "Creating Tax Codes for Vertex O Series" for more information.
Configure your tax suppliers. See "Providing the Tax Supplier Data for Vertex O Series" for more information.
Configure the Taxation Gateway. See "Configuring the Taxation Gateway" for more information.
Configure your system to validate account addresses. See "Validating Addresses with Vertex O Series" for more information.
Specify the detail level to provide in invoices. See "Itemizing or Summarizing Taxes for Each Jurisdiction Level" for more information.
Test that taxes are calculated correctly. See "Verifying That Taxes Are Being Calculated" for more information.

You can also customize the way you calculate taxes, validate addresses, and the authenticator. See "Customizing the Taxation Gateway" for more information.

Setting Up the Vertex Software

Vertex O Series is a cloud service. You do not install Vertex software or databases on the BRM host. Instead, BRM connects to Vertex over REST using configured provider settings (base URI and OAuth credentials).

To set up Vertex O Series, ensure you have the following:

A Vertex O Series tenant with API access enabled
Network connectivity from BRM to the configured Vertex O Series base URI
OAuth 2.0 credentials for Vertex O Series, stored and managed securely

See BRM Compatibility Matrix for information on supported versions of the Vertex software.

See the Vertex documentation for setting up your tenant and API access in Vertex O Series.

Configuring the Taxation Gateway

To configure the Taxation Gateway for Vertex O Series:

Edit the BRM_home/sys/taxation_gateway/Infranet.properties file, and set the following values:
1. Set the following parameter to the server port:
```
infranet.server.portNr=16025
```
2. Set the following parameter to the path to the Taxation Gateway configuration file:
```
infranet.taxation.gateway.config.path=BRM_HOME/sys/taxation_gateway/application.yaml
```
  where BRM_HOME is the home directory for BRM.

Edit the Taxation Gateway configuration file (BRM_home/sys/taxation_gateway/application.yaml) and set the following values:

Change the following entries to define the Vertex O Series provider and endpoint:

providers:
  - id: 6
    name: "Vertex"
    uri: baseURI
    authentication:
      manager: "com.oracle.communications.brm.taxation.authentication.GatewayTokenAuthenticationManager"
      configuration:
        path: "/oseries-auth/oauth/token"
        method: "POST"
        headers:
          Content-Type : "application/x-www-form-urlencoded"
          Accept : "application/json"
        payload:
          grant_type: "client_credentials"
          client_id: "${vertex.client.id}"
          client_secret: "${vertex.client.secret}"
        token_field_path: "$.access_token"

Set the path to the mapper specifications in mapping.specs.directory to BRM_home/sys/taxation_gateway/mappings.

Stop and restart the Taxation Gateway. Ensure the Taxation Gateway is running on the default port 16025.

Validating Addresses with Vertex O Series

To validate addresses with Vertex O Series, you configure and use the Address Lookup endpoint through the Taxation Gateway.

To configure Vertex O Series address validation:

Open the Taxation Gateway configuration YAML file (BRM_home/sys/taxation_gateway/application.yaml) and verify that the address-lookup endpoint is defined:

Verify the Address Lookup endpoint is defined:

providers:
  - id: 6
    name: "Vertex"
    uri: BaseURI
    endpoints:
      - id: "supplies"
...
        path: "/vertex-ws/v2/address-lookup"
        method: "POST"
        headers:
          Content-Type: "application/json"
          Accept: "application/json"
        mapper:
          request:
            - "request.validate-address"
          response:
            - "response.validate-address"

In your account creation or address-capture flow, enable address validation by calling the Vertex Address Lookup operation to validate the city, state, postal code, and country.
Stop and restart the Taxation Gateway if you changed the application configuration.

Note:

BRM uses the PCM_OP_TAX_GW_VALIDATE_ADDRESS opcode to validate addresses. For more information, see "Validating Tax Jurisdictions Based On Address" in BRM Opcode Guide.

Itemizing or Summarizing Taxes for Each Jurisdiction Level

Vertex returns jurisdiction details (for example, STATE, COUNTY, CITY, DISTRICT) in the tax response, and BRM can display them itemized or summarized on invoices. To configure whether BRM itemizes or summarizes jurisdiction-level taxes returned by Vertex O Series, set the invoice presentation in the CM configuration file.

To configure the jurisdiction presentation:

Specify the entry in the BRM_home/sys/cm/pin.conf file:
- To itemize taxes by jurisdiction level:
```
fm_rate tax_return_juris itemize 
```
- To summarize taxes into a single amount:
```
fm_rate tax_return_juris summarize 
```

3. Save and close the file.

4. Stop and restart the CM.

Verifying That Taxes Are Being Calculated

After you have installed and configured the Vertex software, you can run the following test to verify that the Vertex software is calculating taxes.

Create a text file named T502_O with the following contents:

0 PIN_FLD_POID POID [0] 0.0.0.1 /_tax_db -1 0
0 PIN_FLD_FLAGS INT [0] 0
0 PIN_FLD_END_T TSTAMP [0] (1763032566)
0 PIN_FLD_BILL_OBJ POID [0] 0.0.0.1 /bill 1 0
0 PIN_FLD_ACCOUNT_NO STR [0] "0.0.0.1-1"
0 PIN_FLD_CURRENCY INT [0] 840
0 PIN_FLD_CURRENCY_NAME STR [0] "USD"
0 PIN_FLD_TAXPKG_TYPE ENUM [0] 6
0 PIN_FLD_TAXES ARRAY [0] allocated 1, used 1
1 PIN_FLD_ELEMENT_ID INT [0] 0
1 PIN_FLD_TAX_CODE STR [0] "internet"
1 PIN_FLD_AMOUNT_TAXED DECIMAL [0] 100
1 PIN_FLD_LOCATION_MODE ENUM [0] 0
1 PIN_FLD_SHIP_TO_ADDRESS SUBSTRUCT [0]
2 PIN_FLD_COUNTRY STR [0] "US"
2 PIN_FLD_ZIP STR [0] "94086"
2 PIN_FLD_STATE STR [0] "CA"
2 PIN_FLD_CITY STR [0] "SUNNYVALE"
1 PIN_FLD_SHIP_FROM_ADDRESS SUBSTRUCT [0]
2 PIN_FLD_COUNTRY STR [0] "US"
2 PIN_FLD_ZIP STR [0] "94086"
2 PIN_FLD_STATE STR [0] "CA"
2 PIN_FLD_CITY STR [0] "SUNNYVALE"

Note:

Use the TAX_CODE that you mapped with TAXPKG_TAX_CODE in config_taxcodes_map.xml. For Vertex O Series, the Tax Code is O.

Save the text file to the BRM_home/setup/scripts directory.
Start Taxation Gateway.
Open the BRM_home/sys/cm.pinlog file and verify that there are no errors.
Run testnap in the BRM_home/setup/scripts directory to verify that the taxes are being calculated:
```
testnap
r T502_O 1
xop 9441 - 0 1
```
Note:

9441 is the opcode reference number for PCM_OP_TAX_GW_CALCULATE_TAX.

Customizing the Taxation Gateway

You can customize the taxation gateway to change the way it calculates taxes and validates addresses. Additionally, you can use a custom authenticator instead of OAuth 2.0. To customize the taxation gateway, you extend the default Vertex O Series configurations using the application.yaml file and optional custom classes.

To customize the taxation gateway:

Decide what to customize: Authentication, Validating Addresses or Calculating Taxes.
Implement a custom policy class by using the GatewayPolicyInterface. Extend the policy class of the item that you want to customize:
- For validating addresses, extend VertexValidateAddressGatewayPolicy, applied to the Tax Area lookup endpoint.
- For calculating taxes, extend VertexSuppliesCalculateTaxGatewayPolicy, applied to the Supplies Tax Calculate endpoint.
- For authentication, implement GatewayAuthenticationManagerInterface for custom authorization.

Override the following GatewayPolicyInterface methods to perform request validation before the call and response handling after the call:

Before Request Convert Hook using the method beforeRequestConvert():

FList beforeRequestConvert(
GatewayContext context, 
FList requestFlist) 
throws GatewayException, EBufException 
{
// ... custom business logic ...
return requestFlist;
}

Before Request Hook using the method beforeRequest():

Flist beforeRequest(
GatewayContext context, 
FList requestFlist, 
JsonNode requestJson) 
throws GatewayException, EBufException 
{
// ... custom business logic ...
return requestJson;
}

Before Response Convert Hook using the method beforeResponseConvert():

Flist beforeResponseConvert(
GatewayContext context, 
FList requestFlist, 
JsonNode requestJson, 
JsonNode responseJson) 
throws GatewayException, EBufException 
{
// ... custom business logic ...        
return responseJson;
}

Before Response Hook using the method beforeResponse():

FList beforeResponse(
GatewayContext context, 
FList requestFlist, 
JsonNode requestJson, 
JsonNode responseJson, 
FList responseFlist) 
throws GatewayException, 
EBufException 
{
// ... custom business logic ...		
return responseFlist;
}

When customizing authentication, override GatewayAuthenticationManagerInterface using the method authenticate():

 authenticate(
int id, 
HttpRequest.Builder builder) 
throws GatewayException 
{
// ... custom business logic ... 
}

In the application.yaml file, set providers[].endpoints[].hook to your customized policy hook class for each customized endpoint.
Package your classes in a .jar file and add them to the runtime classpath using the TAXATION_GATEWAY_CLASSPATH_EXT environment variable.
Verify that the infranet.taxation.gateway.config.path in the infranet.properties file points to the application.yaml file, and ensure that the mapping.specs.directory path is set. Ensure the service port is set to 16025.
Define your provider and endpoints in the application.yaml file by setting the provider ID, name, base URI, each endpoint’s ID, path, method, headers, and the hook class name for custom policy hooks.
Configure authentication in the application.yaml file through the OAuth 2.0 GatewayTokenAuthenticationManager with its token endpoint, headers, payload, and token_field_path.
Create custom request and response mapping specifications for FLIST to JSON and JSON to FLIST, add the YAML files in the mapping.specs.directory, and reference them under each endpoint’s mapper.request and mapper.response entries in the application.yaml file.
For more information on creating custom mapper files, see "Configuring and Deploying Custom Mapper Files" in BRM Cloud Native System Administrator's Guide.
Configure routing in the application.yaml file with taxcode_groups so your tax codes map to the correct provider and endpoint at runtime, and add taxcode_mappings if you need static enrichments in the outgoing request payload.
Update the configuration property providers[].endpoints[].hook for the customized endpoints in the application.yaml file.
Review the HTTP client behavior and precision settings in the application.yaml file to meet your performance requirements.
Restart the Taxation Gateway. Verify that the configuration and custom .jar files load without errors by checking the taxation gateway logs in the PCM log path.
Validate the customization by calling the PCM_OP_TAX_GW_VALIDATE_ADDRESS and PCM_OP_TAX_GW_CALCULATE_TAX opcodes.

8 Configuring Taxation Gateway for Vertex O Series

About Implementing Vertex O Series Tax Calculation

Setting Up the Vertex Software

Configuring the Taxation Gateway

Validating Addresses with Vertex O Series

Itemizing or Summarizing Taxes for Each Jurisdiction Level

Verifying That Taxes Are Being Calculated

Customizing the Taxation Gateway