ONESOURCE Indirect Tax Determination App V2

Prerequisites

• To use the OneSource Indirect Tax Determination V2 app, you must purchase Configurable tax apps. Contact your Zuora account team for assistance.
• To enable the Connect Tax Engines feature in your Zuora production environment, submit a request through Zuora Global Support . You can activate the Connect Tax Engine feature in your Zuora sandbox tenant with the self-serve interface. For more information, see Enable billing features by yourself.
• Ensure that your billing user role includes the Admin permission.

Difference between legacy OneSource App and OneSource Indirect Tax Determination V2 app

The existing ONESOURCE Indirect Tax Determination app is built on OneSource legacy SOAP API. The new App V2 is built on a new tax platform and integrates with the latest REST API. Following are the differences between the existing OneSource App and the new App V2:

• Authentication
  The legacy ONESOURCE App supports various authentication methods including Basic-Auth, BearedId, OAuth 2.0, whereas REST exclusively uses OAuth2 for enhanced security.
• Void Functionality
  ONESOURCE App V2 includes a straightforward built-in void/reverse feature. The legacy ONESOURCE App’s void function involves sending a negative total amount of the previous transaction, though this method is not recommended.
• API Version
  OneSource recommends using the REST API version moving forward, as updates to their legacy SOAP API are no longer supported.

Configure Tax Engine

1. Navigate to Settings > Billing > Setup Tax Engine and Tax Date.
2. Select Global Tax Hub from the drop-down list.
3. Click Setup New Tax Engine.
4. Configure the necessary data as shown in the following image:
   
5. Specify the URL for performing tax calculations in the Tax Calculation URL field. The URL may vary depending on the region or customer. If you are using ONESOURCE Indirect Tax Determination Cloud, use one of the following URLs:
   • Sandbox: https://api-uat.onesourcetax.com/ind...axes/v1/commit
   • Production: https://api.onesourcetax.com/indirec...axes/v1/commit

6. Select the required authentication type from the drop-down list.
7. Enter the Access Token URL as specified, if you are using ONESOURCE Indirect Tax Determination Cloud:
   • Sandbox - https://api-uat.onesourcetax.com/oauth2/v1/token
   • Production - https://api.onesourcetax.com/oauth2/v1/token

8. Request for the following credentials from your tax vendor:
   • Scope
   • User ID (Client ID)
   • Private Key (Client Secret)
9. Click Save.
10. Enter the following in the Standard section of Request Templates:

Default Standard Template

{
    "callingSystemNumber": "SAP1000",
    "hostSystem": "VGD",
    "companyRole": "S",
    "externalCompanyId": "DPPZUORADEV_1000",
    "processingOptions":
    {
        "chargeIncludedInAmounts": false,
        "chargeResponse": "SeparateAuthority",
        "responseSummary": "FullDetails",
        "documentAmountType": "GrossAmount"
    },
    "documents":
    [
        {
            "documentType": "Sales Invoice",
            "documentNumber": "{{document["invoiceNumber"]}}",
            "currencyCode": "{{document["currency"]}}",
            "addresses":
            [
                {
                    "type": "shipFrom",
                    "country": "{{seller["country"]}}",
                    "region": "{{seller["state"]}}",
                    "city": "{{seller["city"]}}",
                    "postcode": "{{seller["zipCode"]}}"
                },
                {
                    "type": "shipTo",
                    "country": "{{customer["country"]}}",
                    "region": "{{customer["state"]}}",
                    "city": "{{customer["city"]}}",
                    "postcode": "{{customer["zipCode"]}}"
                }
            ],
            "documentDate": "{{document["invoiceDate"]}}",
            "lines":
            [
                {% for document_item in document_items %}
                    {% if forloop.first != true %},{% endif %}
                {
                    "lineNumber": "{{document_item["id"]}}",
                    "amount": "{{document_item["totalAmount"]}}",
                    "productCode": "{{document_item["productName"]}}"
                }
                {% endfor %}
            ]
        }
    ]
}

9. Customize the fields in the template. You can refer to ONESOURCE Indirect Tax Calculation REST API to understand the request payload fields for tax calculation API.
   • externalCompanyId: The unique identifier used by your business application to indicate which company to use in Determination. This element may be passed at the header level, or with each document, and is passed through to the Determination response. 
   • callingSystemNumber: A brief description of the source system, and the origin of the transaction.
   • hostSystem: The name of the ERP instance sending the transaction.
   • companyRole: The role the company plays in a given transaction: Buyer (B), Middleman (M) or Seller (S). Each role results in different transaction tax and reporting requirements.
   • processingOption: Several options are available, ensure that the responseSummary is set to Full Details. 
10. Enter the following to void the default template:

{
"callingSystemNumber": "SAP1000",
"companyRole": "S",
"documentNumber": "{{document["invoiceNumber"]}}",
"externalCompanyId": "DPPZUORADEV_2000",
"hostSystem": "VGD",
"documentDate": "{{document["documentDate"]}}"
}

11. Click Save.

Migration Guidelines

• Migrating existing ONESOURCE Indirect Tax Determination app customers to App V2 may require template redesign.
• Certain fields like companyId/externalCompanyId and companyRole remain similar between the two apps.