1. General Overview
This document is intended for developers of SureTax customers who want to consume one or more SureTax Services directly.
SureTax services allow the users to communicate with the calculation engine to perform a particular task within the SureTax application (e.g., calculation of tax liability). In order to perform these tasks, you need to consume the services.
This Application Programming Interface (API) document defines the structures and methods that are used in the CCH SureTax tax rating and calculation system. The CCH SureTax system can be used for tax calculation of product and services on a "real-time" basis by submitting web request/response messages via Internet services using REST or SOAP.
With the API, the request interface is an object in your application's native programming language. Clients are available in different programming languages. Most modern software languages have SOAP/REST toolkits to generate native programming code for the API consumption. Your application can process these generated object properties, and it can send and receive the data by calling the object methods.
Please note that the current implementation is synchronous, where a response is provided for each request submitted. Each request can contain one-to-many items (transaction records) which can correlate multiple customers and/or invoices.
1.1 Connecting to the API
In order to communicate with the SureTax API you'll need an active SureTax Account. With your account you'll be provided a SureTax Client Number and Validation Key.
1.2 Environments
SureTax provides two different environments for every new account: CERT and PRODUCTION. They are completely separate environments, and each is provisioned its own credentials. We keep CERT and PRODUCTION credentials separate to help you test your software in without the risk of accidentally affecting production data.
CERT - URL: https://testapi.taxrating.net/
This is your SureTax Sandbox/Certification environment. All new customers will begin their development, setup and tax calculation configuration in this environment. After you have performed your user acceptance testing in the SureTax CERT environment and provided written sign off to our SureTax implementation team, you will be allowed access to migrate to PRODUCTION.
Note
SureTax's CERT environment architecture is not as robust and load balanced as our PRODUCTION environment. As you are testing your integration, we ask that do you do not perform any stress or load testing against our CERT environment. It will not be a true representation of PRODUCTION and CERT will be unable to withstand the load.
PRODUCTION - URL: https://api.taxrating.net/
This is your live SureTax account. This account will not be initially active when your accounts are created. All initial configuration and setup is performed in your CERT account. After you have performed your user acceptance testing in the SureTax CERT environment and provided written sign off to our SureTax implementation team, you will be allowed access to migrate to PRODUCTION. Your implementation team will assist in copying any configuration over from CERT into your PRODUCTION account prior to account activation.
1.3 Method Definitions
Calculation Request - SoapRequest (SOAP) / PostRequest (REST) - This method is used for calculation of taxes for the specified transaction. Transactions are defined in SureTax by their status. There are three transaction statuses available in SureTax:
- Quote - (ReturnFileCode = Q) This status is used for tax calculation lookup only.
- In Progress - (ReturnFileCode = T) This status is used to create an In Progress/Non-Finalized transaction
- Finalized - (ReturnFileCode = 0) This status reflects a Finalized/Posted transaction.
Cancel Request - CancelSoapRequest (SOAP) / CancelPostRequest (REST) - This method is used to cancel an In-Progress or Finalized transaction. You cannot call the Cancel Request method until you have successfully created an In-Progress transaction or Finalized the transaction in SureTax.
Finalize Request - FinalizeSoapRequest (SOAP) / FinalizePostRequest (REST) - This method is used to finalize a In-Progress transaction. You cannot call the Finalize Request method until you have successfully called the Calculation Request method at least once creating an In-Progress transaction (ReturnFileCode = T). This method must be called when a user's order is committed/finalized. Utilizing a finalize request will not incur a new tax calculation, it will only change the status of your transaction from In-Progress to Final.
Tax Adjustment Request - SoapTaxAdjustmentRequest (SOAP) / PostTaxAdjustmentRequest (REST) - This method is used for sending tax adjustment amounts for a transaction. The total tax amount is required to return the correct tax details.
1.4 REST
For web requests submitted via REST, the data should be formatted using either JSON or XML format. The response format type is the same as the request format.
When supplying the request as a POST variable, the request value would be supplied as: request={<JSON or XML>} The Headers Content-Type value would be provided as: "Content-Type: application/x-www-form-urlencoded".
If you want the JSON request to be serialized, the request value would be supplied as: {"request":'<JSON>'} The Headers Content-Type value would be provided as: "Content-Type: application/json". This response will be returned wrapped in a "d" object. The object response will contain additional backslashes to escape double quotes around field names and values.
1.5 SOAP
For requests submitted via SOAP, responses are provided in same XML format as the request. The SOAP API schema defines the SOAP messages that you can use to access the SureTax API. SOAP clients can handle the generation of the SOAP request, send the data to the SureTax application, and then convert the data back to the programming interface so that you can use the objects in your application.
The SureTax API has a WSDL that describes its web service. The SureTax General API WSDL can be located at:
For example environment URL for CERT and PROD would be:
CERT: https://testapi.taxrating.net/Services/V07/SureTax.asmx?wsdl
PROD: https://api.taxrating.net/Services/V07/SureTax.asmx?wsdl
1.6 Response Type Code
For every SureTax tax calculation the Response Type Code determines the processing option, granularity of taxes, and the decimal precision for the tax amounts in the response.
A Response Type is comprised of three components:
Processing Option - optional
- 1 - Return non-taxable and exempt items in the response.
- 2 - Fail entire response if one or more items fail.
Tax level grouping flag - Grouping of taxes at line item level (C or D recommended).
Groups response by various configurations of TaxType(TT), TaxCat (TC), TaxAuthType (TAType), TaxAuthId (TAId), Location (Loc), PassFlag (PF), PassType (PT).
- A - TAType + TT + TC | TAId
- B - PF+PT+TAType+TT+TC+TAId
- C - TAType + TT + TC
- D - TAType + TT
- E - TAType + TT + TC | TAId | Loc
- F - PF + TAType + TT
- G - PF + TAType + TT
- P - P + TAType + TT
- Z - TAType + TT + TC | TAId | Loc | Taxability Value
- Note: Taxability Value can be any of the following:
- TX : Taxable
- NT : Non-Taxable
- EX : Exempt
- Note: Taxability Value can be any of the following:
Precision Flag (0-9) - optional (Default 5) The decimal precision of tax response.
Some examples of a response type code are:
2D5 - Using this ResponseType code what we've asked by using the processing option of 2, is that if a single line item within the entire request has an error, SureTax will fail the entire transaction and not calculate taxes or finalize the transaction. Using the precision flag of 5, if all lines are valid, tax amounts will be returned 5 places past the decimal point.
12C2 - Using this ResponseType code similar the one above, this code will fail if any single line contains an error. With the additional processing option of 1, SureTax will try to return jurisdictional information for non-taxable line items. Using the precision flag of 2, if all lines are valid, tax amounts will be rounded to 2 places past the decimal point.
D6 - Using this ResponseType code there is no processing options, each line item on the API call will be allowed to fail but the entire call will still process and only successful lines will be processed and finalized in SureTax. Using the precision flag of 6, tax amounts will be returned 6 places past the decimal point.
C - Tax level grouping flag is the only required component required, thus this ResponseType Code is acceptable. The precision flag will default to 2 places past the decimal point.
1.7 Tax Situs Options
The SureTax V07 API has several address fields to populate: BillingAddress, P2PAddress, ShipToAddress, ShipFromAddress, OrderPlacementAddress, OrderApprovalAddress. The Tax Situs Option will direct the SureTax Calculation which of these addresses to consider for tax calculation.
1.7.1 Telecommunications Tax Situs Options
Telecomm situs in the U.S. is predominantly a choice between the following 2 options:
- Tax Situs rule "04" for 5-digit Zip Code
- Tax Situs rule "05" for 5-digit Zip Code with Plus 4
Zip Plus 4 is the preferred option, as it is more accurate. When using Tax Situs rule "04" or "05" SureTax will look at the BillingAddress and P2PAddress (Secondary) for tax consideration.
Both monthly recurring charges (MRCs), and non-recurring charges (NRCs) such as connection/disconnection, are treated the same for this purpose.
However, MRCs are not necessarily treated the same as NRCs such as Usage.
When it comes to VoIP Usage, for example, if you want to determine the intrastate vs. interstate nature of the call, you will need to use Situs Rule "09", 2-out-of-3 Rule Using Billed To Zip+4. On the other hand, if you are not doing call rating of the VoIP Usage on a call by call basis, rather leaving the Usage as Undetermined, Situs Rules "05" or "04" are used, as mentioned above.
Point to Point (P2P) transactions are a whole new ballgame, as follows:
- Tax Situs rule "07" - Point to Point zip codes (Private Line transactions).
- Tax Situs rule "17" - Point to Point zip codes (Private Line transactions). Both Points Evaluated
Unlike most telecommunications services, the tracking of which entails mapping charges to a single sourcing location or service address, a sale of private-line service is unique in that, in most cases, two destinations are involved. Thus, for point-to-point private-line service, both endpoints have to be provided in order to determine the collective tax liability of a given private line. As such, the default calculation of Private Line services (Line Charge, Connection/Disconnection and Service Charges) is a 50% percent taxable factor on all taxes and surcharges for each point of the private line.
Hence, the user's billing system must be programmed, first to calculate the tax liability for Point A of the private line, followed by running an identical tax calculation for Point Z of the same private line. This requires two sets of transactions to be provided to CCH SureTax; one for Point A to Point Z, and a second for Point Z to Point A using the Zip Code and P2P Zip Code fields.
Unlike Tax Situs rule "07", Tax Situs rule "17" computes both endpoints of the private line with one input request. As such, one request generates two response lines with different taxing jurisdictions.
For the need to calculate Value Added Tax ("VAT") and VAT related Situs rules please consult your professional services team.
1.7.2 General Sales and Use Tax Situs Options
For General Sales and Use the most common Tax Situs Rule used is 22, which will tell the SureTax calculation engine to consider all general sales and use addresses that are provided. Those addresses are ShipToAddress, ShipFromAddress, OrderPlacementAddress and OrderApprovalAddress.
It is common for all addresses to be considered as some states have specific modified origination rules that require taxes to consider both the Ship From and Ship to location rather than the just Ship To. The SureTax calculation engine has built in logic to know which states have these modified rules and will apply them as long as Situs Rule 22 is used.
Using Situs Rules 23, 24, 25, 26 will force the SureTax to consider only specific addresses.
For the need to calculate Value Added Tax ("VAT") and VAT related Situs rules please consult your professional services team.