Getting started with the tax calculation service
A practical introduction when first integrating the Tax Service
This document provides a high level overview of the essential steps to be taken when starting your project to integrate the Tax Service. This document is intended for technical consultants, integrators, business users and project managers involved in the integration project. This document is not a comprehensive implementation guide nor designed to provide tax related guidance for your implementation.
Overview
Steps to get started with the Tax Service:
- Onboard your company onto the Banqup platform
- Determine the appropriate account/space setup
- Subscribe to the Tax Service app
- Access the Banqup API’s
- Understand the structure and fields of our API request and response
- Make your first (simple) tax call
- Perform your tax configurations and fine-tuning
- Tax test all your scenarios
1. Onboard your company onto the Banqup platform
The Tax Service has been created as a service running on the Banqup platform. Therefore, before you can start using the Tax Service, it will be required to onboard your company onto the Banqup platform and create a business space.
If you are not familiar with the onboarding process, refer to the relevant documentation here.
2. Determine the appropriate account/space setup
As part of the initial planning of the project, it is important to investigate what the best account setup can be, for your requirements. Depending on the setup of your organization and the way in which you want to use the Tax Service (for one account or multiple accounts, using configurations stored on the Banqup platform or not) and depending on your other activities on the Banqup platform, you may set up your account through a single business space, or you may set up a business space for each legal entity separately.
If you are not familiar with the entity and space concept, refer to the relevant documentation here.
Key areas to understand:
- Business requirements: are you using the Tax Service for yourself, your clients, one or multiple legal entities?
- Other use of your Banqup account: are you using your Banqup account for electronic invoicing or other secure use?
- Impact on account setup
3. Subscribe to the Tax Service app
Once your business space is created, it is possible to activate the Tax Service app.
Depending on your subscription type, this will be either fully self-service through your space, or the license will be activated through your customer service representative.
4. Access the Banqup API’s
4.1 To start using the Banqup APIs, you'll first need to generate app credentials, by setting up an account on the Banqup Developer Portal and creating a new app. For the Tax Service only the OAuth2 and Tax service needs to be enabled. The relevant documentation on how to manage and setup app credentials can be found here.
4.2 Once the app credential is created, the space admin needs to grant access with the role Accountant responsible. The relevant documentation on how to grant permissions to the app can be found here.
4.3 Now that the app credentials are setup you can get an access token using the client credentials OAuth2 flow. The relevant documentation on getting an access token with the app credentials can be found here.
5. Understand the structure and fields of our API request and response
Before starting your integration work, it is important to review the API documentation to understand what transactional data can and what data must be submitted to the Tax Service to enable the tax calculation.
The relevant documentation on the Tax Service can be found here.
The relevant information on error handling can be found here.
Key areas to understand:
- Authentication method: header-based token, OAuth 2.0, etc..
- Request structure: what is the structure of the JSON request, what are the field types, allowed values and how does the engine handle bad data.
- Required fields: what are the mandatory fields without which the engine cannot perform a calculation.
- Tax drivers: what are the critical fields for tax purposes such as product tax codes, destination addresses, seller information, exemption details.
- Response structure: what is the structure of the JSON response, what are the tax conclusion fields and how are they built up.
- What are the options to perform validations.
- Data mapping: how does your data map to the API request fields.
6. Make your first (simple) tax call
The tax calculation is very complex and can take many data points into consideration. Therefore it is highly recommended to start with a simple tax call, and gradually work your way up to fine-tuning.
As a first step, test the connectivity using only the mandatory fields. Once you have established this works, you can start adding some more data elements and variations in entity establishments to evaluate the expected impact.
7. Perform your tax configurations and fine-tuning
Once step 6 has been completed, you can move on to the tax relevant configurations and fine-tuning of the engine to move on to more complex scenarios.
Depending on your data structure and availability, your business and how you will be using the engine, you can or need to perform the following configurations:
- Product mapping.
- Custom data rules for missing or incorrect inputs.
- Setting up your tax codes for reporting.
- Any custom output rules.
- Any custom tax content for rules deviating from the standard.
- Any custom transaction memos you want to set for certain events.
The engine has been designed to work where possible standard out of the box without configurations, but in reality some configuration is always needed.
Finally it is also important to understand the impacts of missing data and how the engine sometimes sources data, impact of tax IDs on the transaction etc..
Please note that for this step you may need to involve tax specialist knowledge to make this a success.
8. Tax test all your scenarios
The tax conclusion in the response depends on many factors such as tax content in the engine, tax configurations, data sent to the engine, any custom rules set up by the users and more. Therefore it is very important to test all of your business scenarios and validate that the tax call gives your expected tax outcome, before going live with the tax engine. It is best practice to ensure you re-run such a transaction test deck on a regular basis to ensure continued compliance.