ONESOURCE Indirect Tax Integrator PlaybookDocument Version 1Table of Contents About This Playbook Introduction Business Processes Architectural Overview Main Components of a Tax Call System Access SoapUI Design Concepts Organizational Structure Company Role Currencies Integration Configuration Screens Configuration Screen TEST process Addresses POO, POA, and Bill To Addresses Logging Charges INCOTERMS/Point of Title Transfer Tax Liability Tracking (Audit) Uniqueness in Audit Reversals Processing Transactions without ONESOURCE Amounts Document Types Dates Use Tax UserAttributeContainer Taxability Product Taxability Commodity Code Other Standard ERP Field Add New Field Product Tax Code Product Tax Code Import Non-Inventory Items Exempt Management Registrations Sales Tax Code Integration Level Methods Quantity and Unit of Measure
Miscellaneous US to Canada Purchasing Cross Border Transactions Related Lines Coding Standards Security Considerations WSS-Header-Requirements SimpleTaxService Web Service Request Informational Fields Determining Postal Code and Geo Code Web Service Response Status of a Response Tax Results Mapping TaxCalculationService Address Validation Service ERP Testing Test Cases Test Data Tips & Tricks Log Formatting and Comparing References Document History Glossary© 2016 Thomson Reuters/ONESOURCE. All Rights Reserved. Proprietary and confidential information of Thomson Reuters. Disclosure,use, or reproduction without the written authorization of Thomson Reuters is prohibited.
About This PlaybookPurposeThis guide assists clients and partners who want to integrate with the Thomson Reuters ONESOURCE Indirect Tax on our cloud platform with afinancial system, such as an enterprise resource planning (ERP) or e-commerce system. This guide documents common questions and recurringissues with the goal of supporting customers and partners while they build sound solutions.AudienceThis guide supports customers and partners who integrate Thomson Reuters ONESCOURCE Indirect Tax Cloud via our web services with theirfinancials system. Customers and partners using standard prepackaged integrations should refer to the respective product installation guides. DependenciesThe Integration Playbook is based on the latest supported versions of the SimpleTaxService, TaxCalculationService, and Address ValidationService as outlined in the respective chapters of this guide. To use this guide successfully, you need to: Have previous knowledge of Thomson Reuters ONESOURCE Indirect Tax Cloud, as well as knowledge of coding and business processes. Treat this guide as a living document that should be adjusted to reflect your actual implementation approach. Validate the design and implementation directions presented here during your implementation. Have Internet connectivity from your workstation to Thomson Reuters ONESOURCE Indirect Tax Cloud.
IntroductionThomson Reuters ONESOURCE™ Indirect Tax offers a comprehensive, cloud-based transaction tax management solution that seamlesslyintegrates for accurate sales tax calculation, easy document management and effortless filing and remittance.SimpleONESOURCE Indirect Tax works behind the scenes of your existing system to instantly and intelligently deliver billions of real-time tax decisionsat the point of transaction. Better manage your tax requirements and gain a complete view of your sales tax liability from a single, unified platform.FlexibleONESOURCE Indirect Tax is a scalable solution offering enterprise-grade configurability to meet the specific tax needs of your company. Not onlydoes it connect to your ERP you can pair ONESOURCE with your other business systems, enabling company-wide automation.ReliableONESOURCE Indirect Tax is built on APIs, which eliminates the need to modify your ERP code, guaranteeing top-notch performance, forwardcompatibility, and a flawless user experience. You’ll benefit from the industry’s broadest and deepest tax research supporting rates and rules formore than 16,000 tax authorities in over 180 countries.Cloud-basedThomson Reuters ONESOURCE™ Indirect Tax provides a cloud-based tax automation solution that connects with your ERP system to helpcompanies simplify the entire sales tax life cycle and eliminate the complexities of calculating, collecting, reporting, and remitting sales and usetax. ONESOURCE Indirect Tax is used by more than 1,000 companies worldwide to complete billions of transactions every day.Patented Rate DeterminationUnparalleled versatility of the only patented global tax determination engine ensures every tax scenario is handled with ease and accuracy. Enjoybuilt-in automatic tax rate updates for more than 16,000 tax authorities in over 180 countries. With ONESOURCE Indirect Tax taxability andsourcing rules are automatically applied behind the scenes at the time of transaction.Solution OverviewThe diagram below describes the tax process flow from the originating transaction in the business application through sales tax filing. The taxprocess includes adding your company's specific tax policy requirements into Determination.
ONESOURCE Indirect Tax Suite of products is made up of the following components to support the tax process flow:IntegrationONESOURCE Indirect Tax Integration seamlessly connects your ERP system to Determination for tax calculations and appropriate return of taxresults to the ERP for invoice printing and posting to the General Ledger. Integrations are developed and maintained in-house by a team ofThomson Reuters Business Systems Analysts, Developers, and Quality Assurance employees providing the most advanced tax enginedetermination capability and compliance returns processing globally. Our solution can be fully assimilated into any of your existing businesses,e-commerce, or financial systems using our open integration architecture. Tax calculation calls can be easily inserted into existing systemworkflows and processes to deliver real-time or batch solutions with accurate tax results.DeterminationONESOURCE Indirect Tax Determination enables companies to consolidate their global tax policy in one central location. All enterprise-wideapplications can use a single scalable instance of Determination and still deliver business-specific tax policy across multiple-business systems.Fully integrated to all your financial applications, Determination enables the passing of transaction data from the financial system to the taxengine, and returns transaction taxes in real time for fast, reliable, and accurate indirect tax determination. We offer fully supported standardOracle and SAP integrations, as well as custom integrations via our tax calculation web service.Tax Certificate ManagerONESOURCE Indirect Tax Certificate Manager is a solution for the precise tracking, validating, and governing of exemption certificates. As part ofONESOURCE, it provides integration to our ONESOURCE Indirect Tax Determination software that allows for the export of customers andexemption certificates. ONESOURCE Indirect Tax Certificate Manager improves efficiency in all aspects of the burdensome exemption certificatelifecycle by reducing operating costs, mitigating risk, and increasing accuracy. ONESOURCE Indirect Tax Certificate Manager reduces auditexposure and assessments while empowering you with full control of the exemption certificate process to maintain Sarbanes-Oxley compliance.ReportingONESOURCE Indirect Tax Reporting software provides fast, accurate, and flexible reporting that’s fully integrated with our ONESOURCE IndirectTax global software suite to support your global compliance, reconciliation, and data analysis processes. An easy-to-use interface provides alibrary of over 40 production-ready reports that can deliver the most relevant data in a few simple clicks. Drill-down capabilities provide a way foryou to quickly explore the underlying data details, all the way down to the lowest level individual authority taxes. Our summary-level or detail-levelreports allow you to choose the type of report data that best meets your immediate tax data needs in the most efficient way possible.Compliance for USRegardless of location or industry, Sales & Use Tax Compliance has the forms required to meet your needs. It provides over 600 signature-readystate and local returns that are facsimiles of the official forms. Returns and schedules include sales, seller’s use, consumer’s use, and rental taxforms for all applicable states, as well as the District of Columbia. Industry-specific food and beverage returns are also included. In addition, morethan 70 electronic returns are available and accepted in over 25 states. Sales & Use Tax Compliance is one of the market leaders in e-filingsupport. Thomson Reuters continues to work directly with state taxing authorities to ensure full compliance for each state’s unique electronic filingrequirements. The software also goes beyond borders to include the returns required for tax compliance in both Canada and Puerto Rico.Compliance for VATONESOURCE Indirect Tax’s flexibility accommodates your distinct VAT compliance requirements, while maintaining a robust risk managementframework. It enables automated data collection and entry in a number of ways to ensure data integrity from numerous data sources. We maintainand update the latest tax rules, which enable you to focus on your indirect tax compliance rather than the implications of changing regulationsusing our solution maps and your company’s unique in-house knowledge into the compliance process. We can reduce risk and assist withsuccession planning. Our VAT compliance solution has in-built and maintained VAT logic, automated VAT returns from data taken directly fromfinancial systems and has detailed exception reporting embedded in the ONESOURCE software. It has a full audit trail of data from the returnback to the source, and HMRC-approved XML e-filing capability.
Business ProcessesBusiness Process ConsiderationsThe examples in this section illustrate the basic process flow of an order and it's interaction with ONESOURCE Indirect Tax. Consider when thetax liability (audit) should be recorded for each of these examples. See Tax Liability Tracking (Audit) for more information.Quote to Cash ProcessThe sales process in a financials system typically starts with a quote. The quote will call ONESOURCE Indirect Tax for tax calculation, but will notrecord the tax liability (audit the transaction). Once the quote is turned into an order, ONESOURCE Indirect Tax will again be called to update thetax amount as it might change due to different dates, pricing, quantities, etc. Shipping is a non-taxable event and ONESOURCE IndirectTax should not be called. After shipping, an invoice is generated and ONESOURCE Indirect Tax is again called for a final update of the taxes.Once the final invoice is created, ONESOURCE Indirect Tax audit is updated by a final tax call with the tax liability for future reporting and returnsprocessing.Common business processes to consider are: Quotes Orders Invoicing Credit Memos Debit Memos Invoice Cancellationse-Commerce Sales ProcessAn e-Commerce sales process typically starts when an item is selected and placed into a shopping cart. Once the checkout process starts,ONESOURCE Indirect Tax is called to calculate tax on the sale. The results are displayed to the customer and also used for authorization. Thesecalls are not audited. Typically, the next step is to capture credit card information. During the credit card payment process, ONESOURCE IndirectTax is called one last time to update the ONESOURCE Indirect Tax Audit Database with the tax liability for future reporting and returnsprocessing.
When building an integration to an e-Commerce application consider other financial applications that are a part of the order to cash process,noting when and in which system the audit call will be made. In the event that the e-Commerce platform feeds transactions into the ERP system,the calls from the e-Commerce system may not be audited at all as the transactions may be audited in the ERP system. Here are someexamples: The feed to the ERP creates sales orders that will be invoiced from the ERP. The audit call to ONESOURCE Indirect Tax will occur from the ERP. Since the audit call occurs from the ERP, there is no need to audit from the e-Commerce applications. Completed invoices created in the ERP from the e-Commence application will likely already have been audited, as those transactions would make that call from your e-Commerce application. If the backend system or ERP is not connected to ONESOURCE Indirect Tax, then audit should occur from the e-Commerce application.Common business processes to consider are: Purchase Carts Credit Card AuthorizationsPurchase to Pay ProcessA purchasing process starts with a requisition or a purchase order. ONESOURCE Indirect Tax is called for tax results that will not be audited.Goods receipt is a non-taxable event, and ONESOURCE Indirect Tax will not be called. After the receipt, a vendor invoice is received and enteredand ONESOURCE Indirect Tax is again called for a final update of the taxes.There are options for handling the vendor charged tax and use taxaccruals. See Use Tax for more information. ONESOURCE Indirect Tax audit is updated with the tax liability for future reporting and returnsprocessing when the vendor invoice is posted.
Common business processes to consider are: Requisitions Purchase Orders Blanket Purchase Orders Invoice Receipt Returns
Architectural OverviewThomson Reuters Indirect Tax Cloud services provides robust API's for integrations to a variety of financials systems. Partners can build theirintegration utilizing these API: Tax Calculation API Address Validation APIThe specific implementation varies based upon both financials system technology and the business processes you choose to support.ARCHITECTURE DIAGRAMOur cloud based hosting allows for simple implementation of our solution:
Main Components of a Tax CallTwo versions of web services available for tax calculations: the SimpleTaxService and TaxCalculationService (also referred to as EnterpriseWeb Service). Unless advised by your Thomson Reuters implementation contact, it is expected that you use the Simple Tax Service. In general,both services have similar structures, but with slightly different naming conventions. Also, the simple service has fewer fields that are in a moreconsumer-friendly format. This service should be sufficient for most if not all United States of America or Canadian implementations. For theexact fields available in the data model, refer to the SimpleTaxService or TaxCalculationService.RequestThe request represents the data being sent from the source system to the tax engine. It has three main levels: Request Model REQUEST: The top level request object that is sent to ONESOURCE Indirect Tax Determination for tax calculation. DOCUMENT: Multiple invoices, or other documents such as sales quotes, can be present in a request. LINE: Item level data for each input invoice. Multiple lines can be present in each document.Note that some identical elements appear at both the document and line levels in the data structure. Depending on your tax calculationrequirements, both can be used by following guidelines: If a data element value appears at the document level, it does not need to be repeated at the line level. If an element value appears at the document level, and is populated differently at the line level, the line level value overrides the value at the document level for that given line only. If an element value is only present for a given line, then that value applies for that line only.ResponseThe response is returned to the calling system and contains the tax results from the tax engine. The response model is as follows: Request Model RESPONSE: Returns information about the request's success or failure and, in the event of an error, contains messages that indicate the source of the failure. OUTPUT DOCUMENT: Contains a summary about the entire document. Multiple documents can be present in a response. OUTPUT LINE: Item-level data for each document. Multiple lines can be present in each document. TAX SUMMARY: Summarized tax data that applies to a line. This will provide one summarized amount for all jurisdictions–one tax amount for the entire line. TAX ZONE SUMMARY: Summarized tax data that applies to a line. Each individual applicable tax authority will have a summarized tax block. TAX DETAIL: Tax detail that applies to a line. Multiple tax blocks can be present in each line.
System AccessDescriptionSuccessful tax calls require several pieces of information that are provided by either the Thomson Reuters product development or onboardingteam. This information is used when formulating the tax request to Thomson Reuters Indirect Tax and includes: Tax service URL: The URL of the Tax Calculation server. External Company ID: The External Company ID provided uniquely identifies the tax request within the Thomson Reuters solution for audit, reporting, and return purposes. User Name: The user set up for you in the system allowed to send tax calculation requests. Password: The password set up for the user above. Other optional fields.Web Service AccessThe current version of the Integrator Playbook focuses on the SimpleTaxService only. Partners who develop against the TaxCalculationService will be provided with unique credentials during the sign-up process.Service URL WSDL/XSDSimple https://partnerdev2-uat.hostedtax.thomsonreuters.com/sabrix/services/taxservice/2009-12-20/taxservice https://partnerdev2-uat.hostedtax.thomTaxServiceAddress https://partnerdev2-uat.hostedtax.thomsonreuters.com/avs https://partnerdev2-uat.hostedtax.thomValidationGeneric Developer Community AccountA generic account has been setup for Community-level members of the Developer Community to use for development and testing. For Endorsedand Premier-level members unique accounts will be setup during the sign-up process.Service Country ExternalCompanyId Username PasswordSimple Tax Service US DevCom_US DevCom 4TaxCalcSimple Tax Service CA DevCom_CA DevCom 4TaxCalcAddress Validation US DevCom DevCom 4TaxCalc The users listed above are system users for use with the interfaces only. They do not provide access to Determination. Community-leve l members do not receive system access.SoapUIFor a quick test of system access and to gain an understanding of how the API's work see the SoapUI page.
SoapUIDescriptionWe recommend using SoapUI, a free tool available at http://sourceforge.net/projects/soapui/files/, to test basic communication with our services.Once communication is confirmed, then the system integration can take place. A pre-configured project, that can be imported into SoapUI,containing sample tax calculation and address validation requests is attached to this page.Using the Sample XMLThe attached sample XML contains examples of the Simple Tax Service and the Address Validation Service. To use them in SoapUI, import theproject by navigating to File > Import Project on the SOAPUI menu bar. Select the downloaded file and then select Open. 1. After the project is imported, expand the project and its sub-folders. You should see something like this: 2. Double click on 01_DevUS. This opens the request in the right-hand panel of SoapUI:
3. Replace the following three fields, highlighted in yellow in the example above, with the values provided to you by your Thomson Reuters Indirect Tax implementation contact: a. UserName b. Password c. ExternalCompanyId 4. Verify that the URL in the top part of the screen is the one provided by your implementation contact. Once these values have been verified you are ready to reset the timestamp.Reset the SoapUI Timestamp 1. Before using any of above sample scenarios for testing, delete the timestamp collection in the security header. The following code block is an example of the section to delete.
<wsu:Timestamp wsu:Id=\"TS-BBA63BA92C84F21DE6142368467153413\"> <wsu:Created>2015-02-11T19:57:51.534Z</wsu:Created> <wsu:Expires>2015-02-11T19:58:51.534Z</wsu:Expires> </wsu:Timestamp> 2. Next, add a new timestamp to the request by placing your mouse at the line where you just deleted the code block in the previous step, then right click and select Add WS-Timestamp. 3. Confirm the second pop-up. You can set the timestamp value to a higher number, like 3600 (1 hour) so that your request can be reused for a longer duration. Once expired reset the timestamp again.Performing a Tax CallYou are now ready to test your tax call. To do so, click on the green arrow in the upper left-hand corner of the request window:If your request is successful you should see the results XML in the right-hand window.
TroubleshootingMost issues are with either the timestamp setting, incorrect credentials, or an incorrect URL. Please make sure you have reviewed these fieldvalues before contacting Thomson Reuters for assistance. If none of these steps resolved your error check the message in the <RequestStatus>block of the response. For example: <RequestStatus> <Success>Failure</Success> <Code>INVALID_CURRENCY_CODE</Code> <Description>The Currency Code passed was invalid.</Description> <ErrorLocationPath>/TaxRequest/Documents/Document[DocumentNumber='1']</ErrorLocationPath> </RequestStatus>Now check in the request what the value is for the <CurrencyCode> field, the value must be a valid 3-digit ISO currency code like USD. Byevaluating the error message, you should get a good idea what data element isn't properly formatted or contains a wrong value. For more detailson interpreting a response, see the Status of a Response page.SoapUI sampleThe Attached SoapUI sample uses the generic Developer Community access information from the System Access page as an example.
Design ConceptsDescriptionThere are several key concepts to be understood when designing and developing an integration to Determination. Using the Simple Tax Service request format, the following linked pages describe the concept and highlight the business and tax usage of each concept.PrerequisiteOne guiding principle of tax automation with ONESOURCE should be to make sure all tax decisions are made by the tax engine. To support thisyou must: Set up all Customers and Items/Materials as tax relevant,or taxable, so that all tax decisions can be properly made within Determination. Send all relevant information about the transaction to Determination, where the actual taxability of the transaction is determined, and the tax calculated and audited as appropriate. Organizational Structure Integration Configuration Screens Addresses Logging Charges INCOTERMS/Point of Title Transfer Tax Liability Tracking (Audit) Amounts Document Types Dates Use Tax UserAttributeContainer Taxability Registrations Sales Tax Code Integration Level Methods Quantity and Unit of Measure Miscellaneous US to Canada Purchasing Cross Border Transactions Related Lines
Organizational StructureDescriptionA company's legal entity structure, defined in the ERP or financial system, is mapped to a defined company in Determination.Business UsageSet up Companies to organize transaction and audit data, create B2B relationships, and share tax configurations and other data. Separate companies based on corporate divisions, geographies, or for any other reason. Separate custom data can be maintained for each, and each company's audit data can be reported on individually. A parent company whose purpose is to maintain master data that is shared among child transacting companies. For example, a parent company can be an organizational convention that is not a real company but is used to define child companies (legal entities).To share data across companies, it is usually a good practice to have a parent company at the top of the structure as an organizationalconvention. Using this practice, each child company inherits the data set up in the parent company.Tax UsageThe external company ID is the name that this company is referred to in the calling business applications. The external company ID uniquelyidentifies the tax request within Determination for audit, reporting, and return purposes.This is communicated in the simple request via thecompany_id element.
Company RoleDescriptionThe company role is the role the transacting company plays in a given transaction: buyer or seller. Each role results with different transactiontaxes and reporting requirements.Note: the transacting company referred to is from the ONESOURCE company, TR customer, perspective when identifying the role.Business UsageThe company role is the function the transacting company plays in an O2C or P2P transaction.For an O2C transaction, the CompanyRole is seller because the company is selling a good or service.For a P2P transaction, the CompanyRole is buyer because the company is buying a good or service.Enter the partner name and number in the tax request to provide additional reporting information about the transaction for the Determination audit.The partner in a transaction represents the customer in the sales transaction and the vendor in the purchase transaction.For a CompanyRole of seller, the partner name/number in the ShipTo field should represent the buyer (the customer) and the ShipFrom fieldshould represent the seller (the company).For a CompanyRole of buyer, the partner name/number in the ShipTo field should represent the seller (the company), and the ShipFrom fieldshould represent the buyer (the vendor).Tax UsageThe company role indicates to Determination which tax to calculate on the transaction. For O2C or seller transactions, Determination calculatessales tax or seller's use tax. These are tax types collected and reported by the seller. For P2P or buyer transactions, Determination calculatesconsumer's use tax. This is a self-accrued tax and reported by the consumer (buyer).There are some exceptions, however, and the company role is very important in determining the appropriate tax to apply. For example, forinterstate buyer transactions (the ship from and ship to are different states) consumer's use tax is usually applied. For intrastate buyertransactions (the ship from and ship to states are the same), the seller's use tax could apply depending on the state. In Arizona, for example, anintrastate buyer transaction will return a NL (not liable) result since in Arizona, the the seller is liable to pay the tax on the transaction. If the buyertransaction is from out of state shipping to Arizona, then the consumer's use tax will be calculated.
CurrenciesDescriptionThere are two basic currencies, the currency in audit and the document currency. Determination stores its audit data in the defined company'saudit currency. Currently the scope of new markets includes US dollars or Canadian dollars. Determination does not perform currencyconversions, so all transactions from the financials system must be sent in the audit currency, US dollars, or Canadian dollars.Business UsageThe audit currency should be the filing currency (set of books currency, functional currency). The document (transaction) currency can be thesame or a different currency from the audit currency. If the document currency is different from the audit currency (set of books currency,functional currency), the best approach is to send the transaction data to Determination in the audit currency. The ERP then performs thenecessary currency conversion. Any rounding differences in reconciliation can easily be explained with this approach.Tax UsageCurrency is used for tax reporting and filing. Currency also plays a role in the tiered rate calculation, where a different rate applies at differenttransaction levels. If the correct currency is not used, the tax amount calculated could be incorrect. For example, the document currency ofCanadian dollars may calculate a tax at one tier level, yet the audit currency of US dollars could calculate a different tiered level, and therefore, adifferent tax amount.
Integration Configuration Screens Description It is preferred that Integrations are configured using configuration setup screens. Using this method enhances the user experience and allows for quick installation and configuration of the solution. Standard Method All configuration screens must permit add/change/delete functions of the stored data. Screens should follow the same basic paradigm as the transaction system's design principles. For the data section, Thomson Reuters prefers that like data configurations are grouped logically by a header row, followed by the specific data fields. The attached document shows the basic outline of a screen design in the GenericTemplate tab and provides a comprehensive view of a sample setup screen on the TaxConfigScreen tab (also shown below). Screen access should be tied to the transaction system's authorizations and be restricted to a configuration role if possible. Our preference is that a new role of \"Tax Configuration\" be created and assigned to any setup screens used with ONESOURCE Alternate Method When a transaction system doesn't allow for the creation of screens, it is permissible to create file based configurations using simple text or XML-based formats. Logo Branding Each screen should be branded with your company's logo as outlined in the Generic Template tab of the screen mock-up sample showing the Thomson Reuters logo. The Thomson Reuters name, logo, or brand, as well as ONESOURCE cannot be used by Developer Partners in their product name or branding. They can be used to refer to our product offerings. Sample Tax Configuration Setup Screen Below is the sample screen described in the attached document referenced in the Standard Method section above.
Configuration Screen TEST processDescriptionIt is desired to have the ability to test the configuration settings of an ERP Integration directly from the setup screen to ensure that the credentialsare configured correctly. To do so, a “dummy” request has to be sent to the ONESOURCE Indirect Tax service in question to validate thesettings. There are two different processes to be implemented; one for the Simple Tax Calculation Service, the other for the Address ValidationService. This section outlines in general terms how to set this up.Generic SetupTo make the web service calls, perform the following steps: 1. Store the two \"driver\" files (i.e. as xml or txt files) within the implementation of the integration, one each for the tax service and the address validation service, containing the dummy call information. It is recommended to not hard coded the information into the implementation, but rather have them stored in some form within the implementation so that one could access them and make changes to the driver data. 2. Implement a process that uses the TEST button outlined in the configuration screen design. 3. Upon clicking the TEST button a web service call has to be initiated using the URL provided in the configuration screen. 4. Format a SOAP Request with the SOAP Authentication portion using the Username and Password from the configuration screen, as well as the XML information pertaining to the service called with the ExternalCompanyId from the configuration screen. 5. At time of the SOAP Response the results have to be parsed and analyzed to either return a Success or Failure status, and in the case of a failure some information of the cause.SOAP AuthenticationSample of the SOAP header security block containing the Username and Password, the two values (indicted with \"From Configuration\") in thesample below have to be inserted based on the setup value in the configuration screen: <wsse:UsernameToken wsu:Id=\"UsernameToken-FD63C9E1F61FE1E26214073477114572\"> <wsse:Username>From Configuration</wsse:Username> <wsse:Password Type=\"http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0# PasswordText\">From Configuration</wsse:Password> </wsse:UsernameToken>Simple Tax Calculation ServiceCopy BETWEEN the two tags for the SOAP body <soap:Body> and </soap:Body> the following XML data, while replacing the value for <ExternalCompanyId> (indicted with \"From Configuration\") with the value setup in the configuration screen.
<TaxRequest xmlns=\"http://www.sabrix.com/services/taxservice/2009-12-20/\"> <HostRequestInfo> <CallingClient>test</CallingClient> <CallingSource>config test</CallingSource> <CallingSystemNumber>1</CallingSystemNumber> <CallingUser>test</CallingUser> <DbVersion>None</DbVersion> <ErpVersion>Custom</ErpVersion> <HostRequestId>1</HostRequestId> <HostRequestLoggingId>1</HostRequestLoggingId> <HostSystemNumber>1</HostSystemNumber> <IntegrationVersion>test</IntegrationVersion> <SdkVersion>na</SdkVersion> </HostRequestInfo> <ExternalCompanyId>From Configuration</ExternalCompanyId> <Documents> <Document> <DocumentNumber>1</DocumentNumber> <Addresses> <ShipFromAddress> <Country>US</Country> <PostalCode>63111</PostalCode> </ShipFromAddress> <ShipToAddress> <Country>US</Country> <PostalCode>63111</PostalCode> </ShipToAddress> </Addresses> <Attributes> <IsAuditResult>false</IsAuditResult> <AmountType>GrossAmountBased</AmountType> <CompanyRole>Seller</CompanyRole> <CurrencyCode>USD</CurrencyCode> <DocumentType>SalesInvoice</DocumentType> </Attributes> <Dates> <DocumentDate>2014-07-14</DocumentDate> <FiscalDate>2014-07-14</FiscalDate> </Dates> <Lines> <Line Id=\"1\"> <LineNumber>1</LineNumber> <Addresses/> <Amounts> <GrossAmount>10.00</GrossAmount> </Amounts> <Quantity> <Amount>1</Amount> <UOM>EACH</UOM> </Quantity> </Line> </Lines> </Document> </Documents> </TaxRequest>Response Processing
Success: A successful tax calculation is indicated in the SOAP Response by the value Success in the <RequestStatus> block of the responseas shown below. In this case a user message should be displayed stating that the configurations are correct and a successful tax calculation wasmade. <RequestStatus> <Success>Success</Success> <Description>SUCCESS</Description> </RequestStatus>Failure: There are three failure scenarios to consider, an unsuccessful authentication or not being able to calculate tax. Each returns a slightlydifferent form of response message.Invalid URL: This happens if the service URL isn't configured correctly, the response would be similar to this sample: <html> <body>No service was found.</body> </html>In this case a user message should be displayed stating that the URL configuration is incorrect.Authentication Error: Due to either the wrong username and/or password will return a SOAP Response similar to this sample: <soap:Envelope xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\"> <soap:Body> <soap:Fault> <faultcode xmlns:ns1=\"http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0. xsd\">ns1:FailedAuthentication</faultcode> <faultstring>The security token could not be authenticated or authorized; nested exception is: org.apache.ws.security.WSSecurityException: The security token could not be authenticated or authorized</faultstring> </soap:Fault> </soap:Body> </soap:Envelope>In this case a user message should be displayed stating that the configurations are incorrect due to either the Username and/or Password notmatching what is setup in Determination. Please review and update accordingly.External Company ID Error: If the ExternalCompanyId isn't set correctly in the configuration screen the SOAP Response error will look like thissample: <RequestStatus> <Success>Failure</Success> <Code>COMPANY_NOT_FOUND</Code> <Description>Unknown Company.</Description> <ErrorLocationPath>/TaxRequest/ExternalCompanyId/text()</ErrorLocationPath> </RequestStatus>A failed tax calculation is indicated in the SOAP Response by the value Failure in the <RequestStatus> block of the response, followed with adescription of the error in the <Description> tag. In this case a user message should be displayed stating that the configurations are incorrect dueto a wrong ExternalCompanyId. Please review and update accordingly.Address Validation ServiceCopy BETWEEN the two tags for the SOAP body <soap:Body> and </soap:Body> the following XML data, while replacing the value for <ExternalCompanyId> (indicted with \"From Configuration\") with the value setup in the configuration screen.
<ValidateAddressRequest xmlns=\"http://www.sabrix.com/services/address-validation/2008/04\"> <RequestId>f0bb4e62-6471-4ed0-afef-dff00a509fd0</RequestId> <ExternalCompanyId>From Configuration</ExternalCompanyId> <ReturnInputData>false</ReturnInputData> <LogLevel>DEBUG</LogLevel> <AddressRequest> <Address> <Address1>1 Microsoft three</Address1> <Address2/> <Address3/> <City>Redmond</City> <Region>WA</Region> <PostalCode>98052</PostalCode> <Country>USA</Country> </Address> </AddressRequest> </ValidateAddressRequest>Response ProcessingSuccess: A successful address validation is indicated in the SOAP Response by the value SUCCESS in the <ns2:RequestStatus> block of theresponse as shown below. In this case a user message should be displayed stating that the configurations are correct and a successful addressvalidation was made. <ns2:RequestStatus> <ns2:Status>SUCCESS</ns2:Status> <ns2:Description>All addresses validated successfully</ns2:Description> </ns2:RequestStatus>Failure: Their are three failure scenarios to consider, an unsuccessful authentication or not being able to validate an address. Each returns aslightly different form of response message.Invalid URL: This happens if the service URL isn't configured correctly, the response would be similar to this sample: <!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML 2.0//EN\"> <html><head> <title>404 Not Found</title> </head> <body> <h1>Not Found</h1> <p>The requested URL /av was not found on this server.</p> </body></html>In this case a user message should be displayed stating that the URL configuration is incorrect.Authentication Error: Due to either the wrong username and/or password will return a SOAP Response similar to this sample:
<SOAP-ENV:Envelope xmlns:SOAP-ENV=\"http://schemas.xmlsoap.org/soap/envelope/\"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <SOAP-ENV:Fault> <faultcode>SOAP-ENV:Client</faultcode> <faultstring xml:lang=\"en\">com.sun.xml.wss.impl.WssSoapFaultException: Authentication of Username Password Token Failed; nested exception is com.sun.xml.wss.XWSSecurityException: com.sun.xml.wss.impl.WssSoapFaultException: Authentication of Username Password Token Failed</faultstring> </SOAP-ENV:Fault> </SOAP-ENV:Body> </SOAP-ENV:Envelope>In this case a user message should be displayed stating that the configurations are incorrect due to either the Username and/or Password notmatching what is setup in Determination. Please review and update accordingly.External Company ID Error: If the ExternalCompanyId isn't set correctly in the configuration screen the SOAP Response error will look like thissample: <SOAP-ENV:Envelope xmlns:SOAP-ENV=\"http://schemas.xmlsoap.org/soap/envelope/\"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <SOAP-ENV:Fault> <faultcode>SOAP-ENV:Server</faultcode> <faultstring xml:lang=\"en\">Invalid company ID: xxx</faultstring> </SOAP-ENV:Fault> </SOAP-ENV:Body> </SOAP-ENV:Envelope>A failed address validation is indicated in the SOAP Response by the value Failure in the <SOAP-ENV:Fault> block of the response, followedwith a description of the error in the <faultstring xml:lang=\"en\"> tag. In this case a user message should be displayed stating that theconfigurations are incorrect due to a wrong ExternalCompanyId. Please review and update accordingly.
AddressesDescriptionAddresses are one of the primary pieces of data used by Determination for accurate tax calculation. The key addresses used are: ship from ship to bill to point of order origin point of order acceptanceBusiness UsageAddresses are used for tax determination and for tax reporting. Precise addresses result in more precise tax calculations. For example, providing the ZIP Code (first five digits) along with the geocode (last four digits) provides the most granular geographic identification for an address. Whilethe GeoCode is not a required field, using both of these address elements provides the most accurate tax determination for a transactionbecause the exact taxing authorities can be identified.Address accuracy is also critical for accurate tax calculation. The Thomson Reuters Address Validation tool can be used to cleanse masteraddress data prior to using Determination and also as a method to continually validate addresses after going into production. Consider using theaddress validation service as a way to increase tax accuracy when integrating Determination with your application. See Address ValidationService for more information.Tax UsageThe addresses listed below are used to calculate the most accurate tax. The addresses are used to determine the tax jurisdictions involved in thetransaction, which Determination uses to apply the appropriate jurisdiction.Source and Purpose of Address DataAddress T Source and PurposeypeShip To The purpose is to determine the destination taxing authorities. The location where the customer is receiving the merchandise (for example, the customer's address). For sales documents, this is the ship-to address for the customer. For purchase documents, this is the ship-to address for your company. This is typically a receiving warehouse location.Ship From The purpose is to determine the origin-based taxing authorities. Where the goods came from prior to receipt by the customer (for example, a warehouse or store). For sales documents, this is the ship-from address for your company. This is typically a shipping warehouse location. The purpose is to determine the taxing authority. For purchase documents, this is the ship-from address for the vendor. The purpose is to determine the taxing authority. The ship-from location is important for some states, as different tax results could be returned based on the ship-from address. For example, in Arizona, if the ship-from for a buyer transaction is from out-of-state, the consumer use tax rate will return. However, if the ship-from is in Arizona, No Liability rate will return since it is the seller's responsibility to collect the tax. The ship-from and ship-to locations are both important for some states, as some taxes are origin based, others are destination based. For example, California is a “modified origin” sourcing state, which means that state, county, city taxes are calculated at the origin of the sale (ship-from) and the district taxes calculated at the destination of the sale (ship-to). Therefore, both locations are required as the transaction tax will be calculated at the ship-from and ship-to locations.Bill To The transaction's bill to address. This address is used for certain transaction types to determine tax and reporting requirements.Point of The transaction's order-origin address. Where the order for the merchandise was placed (for example, a store or a trade show).Order This address is used for certain taxing authorities to determine tax and reporting requirements.OriginPoint of The transaction's order-acceptance address. The location where the order was accepted (for example, a call center where anOrder order was taken).Acceptance This address is used for certain taxing authorities to determine tax and reporting requirements.Address ExampleLet's use the entry of a sales order in a financial system as an example. The basic tax request includes a ShipToAddress for the customer and a
ShipFromAddress for the shipping warehouse. This information is passed with the tax request to Determination for tax calculation. The followingis an example of the ship to in the XML request:<ShipToAddress><Country>US</Country><Region>TN</Region><County>Knox</County><City>Knoxville</City><Address1>1017 Francis Street</Address1><PostalCode>37996</PostalCode><GeoCode>3601</GeoCode><PartnerNumber>332667</PartnerNumber><PartnerName>Columbia Manufacturing</PartnerName></ShipToAddress>Taxing AddressAddress types are important to tax calculation. Some states do not only tax based on the Ship To address. The table below lists the order that anaddress type is used (by state) to calculate tax for intrastate sales of goods (seller transactions).Jurisdiction Taxing Address Preference OrderAlabama Ship ToAlaska Locals Ship ToArizona Order Origin, Order Acceptance, Ship From, Ship ToArizona (Tribal) Ship ToArkansas Ship ToCalifornia Order Origin if Ship From is within California or POTT (Point of Title Transfer) equals destination, Order Acceptance if Ship From is within California or POTT equals destination, Ship From, Ship ToCalifornia Districts Ship ToColorado Ship ToConnecticut Ship ToDC Ship ToFlorida Ship ToGeorgia Ship ToHawaii Ship ToIdaho Ship ToIllinois Order Acceptance, Ship From, Ship ToIndiana Ship ToIowa Ship ToKansas Ship ToKentucky Ship To
Louisiana Ship ToMaine Ship ToMaryland Ship ToMassachusetts Ship ToMichigan Ship ToMinnesota Ship ToMississippi Ship ToMissouri Order Origin, Ship From, Order Acceptance, Ship ToNebraska Ship ToNevada Ship ToNew Jersey Ship ToNew Mexico Order Origin, Order Acceptance, Ship From, Ship ToNew York Ship ToNorth Carolina Ship ToNorth Dakota Ship ToOhio Ship From, Ship ToOklahoma Ship ToPennsylvania Order Origin, Order Acceptance, Ship From, Ship ToRhode Island Ship ToSouth Carolina Ship ToSouth Dakota Ship ToTennessee Order Origin, Order Acceptance, Ship From, Ship ToTexas Ship From, Ship ToUtah Ship From, Order Origin, Order Acceptance, Ship ToUtah (Tribal) Ship ToVermont Ship ToVirginia Order Origin, Order Acceptance, Ship From, Ship ToWashington Ship ToWest Virginia Ship ToWisconsin Ship ToWyoming Ship ToGuam Ship ToU.S. Virgin Islands Ship To
POO, POA, and Bill To AddressesDescriptionAddresses are one of the primary pieces of data used by Determination for accurate tax calculation. Although Ship To and Ship From areprimarily used as the taxing address, some taxing jurisdictions use the Bill To, Point of Order Origin (POO) or Point of Order Acceptance (POA).Business UsageTax calculations use various addresses to determine the proper tax for a transaction. The more accurate the address (including Zip+4) andaddress usage the more accurate the tax will be. Since some jurisdictions use the BillTo, POO, or POA, it is important to send this data toDetermination if it is known. Below are the definitions of these addresses.Bill To The transaction's bill to address. This address is used for certain transaction types to determine tax and reporting requirements.Point of Order Origin The transaction's order-origin address. Where the order for the merchandise was placed (for example, a store or a trade show). This address is used for certain taxing authorities to determine tax and reporting requirements.Point of Order The transaction's order-acceptance address. The location where the order was accepted (for example, a call centerAcceptance where an order was taken). This address is used for certain taxing authorities to determine tax and reporting requirements.Tax UsageThe combination of addresses, Point of Title Transfer, and Delivery Method determine the tax authority and the tax type. Some taxing authorities,California and Iowa for example, utilize the POO and POA addresses in the tax calculation. The appropriate address elements are sent in thefields for BillToAddress, OrderAcceptanceAddress, or OrderOriginAddress.CaliforniaCalifornia is a modified-origin state. The state, county, and city taxes are based on the origin of the sale, but district taxes are based on thedestination.For shipments of goods within the state of California, the order of preference for taxing addresses is as follows: 1. Point of Order Origin is used if Ship From is within California (POTT = Destination) 2. Point of Order Acceptance is used if Ship From is within California (POTT = Destination) 3. Ship From 4. Ship ToFor interstate transactions into California (non-districts authorities), the tax type Sales Tax (ST) or Seller’s Use Tax (SU) is dependent on themethod of delivery and POTT into the state. Sales Tax (ST) applies when the delivery mode is vendor's vehicle (POTT = Destination) or commoncarrier with FOB or FAS destination (POTT = Destination). Seller’s Use Tax (SU) applies when the delivery mode is common carrier with no FOBor FAS (POTT = null) or common carrier and FOB or FAS is origin (POTT = Origin). Point of Title Transfer In Transit/Null Origin Destination SU Method of Delivery Null SU SU ST Common Carrier ST Seller's Vehicle SU SU ST STIowa
Iowa is a destination-based state.For shipments of goods within the state of Iowa, the order of preference for taxing addresses is as follows: 1. Order Origin if Ship From is within Iowa (POTT = Destination) 2. Order Acceptance if Ship From is within Iowa (POTT = Destination) 3. Ship From 4. Ship ToFor interstate transactions into Iowa, the tax type Sales Tax (ST) applies when the delivery mode is vendor's vehicle (POTT = Destination)or common carrier with FOB or FAS destination (POTT = Destination). Seller's Use Tax (SU) (there is no local SU in IA, only state SU isreturned) applies when the delivery mode is common carrier with no FOB or FAS (POTT = null) or common carrier and FOB or FAS is origin(POTT = Origin) Point of Title Transfer In Transit/Null Origin Destination SUMethod of Delivery Null SU SU ST Common Carrier ST Seller's Vehicle SU SU ST ST
LoggingDescriptionWhen two systems exchange data it is imperative to provide a means to review the exchanged data fortroubleshooting and issue resolution. To assist with this process, each integration needs a minimum standardof logging on the calling application side.Feature RequirementThe integration must have the ability to collect information on the process of sending data from the source system to Determination; either in a flatfile or in a table within the source system. It is best practice to write the logs to a central location. In a client-server architecture, the logs should bestored on the server when possible. If needed, the logs can be written on the client. Preferably, logs should be written to a system table or, insome exceptions, to a log file.Logging ConfigurationLogging configuration should include the following requirements: Logging Configurations should be managed by user. Logging should be enabled (turn on/off) by the user name/ID of the person transactioning the event leading to the tax call. The purpose of this feature is to eliminate system-wide logging which has severe performance implications. Limiting logging by user also makes finding the right log easier by limiting the size of the log. It is helpful if Logs are searchable by user. Logging should immediately activate once enabled and not require a system reset. Logging configurations should not cause system interruptions. Logging configuration should be managed in a system screen. The configuration screen should include: Setting the log level per user Location where logs will be written to if file based Retention Policy; days to retain, size limitations, number of logs Access to the configurations screen is required If a system location is not available for logging configuration, it may be done through a properties fileLog LevelsMake the following three log levels available: ERROR: Lowest level of logging. An entry is only made to the log if a program error occurs in the integration code. Such entries should describe the program errors, i.e., a Java stack trace log or similar. Request XMLs are also written to the log in case the tax engine returned a hard error. ERROR should be the default level value. INFO: ERROR log level, plus the request and response XML of the web service call. DEBUG: INFO log level, plus pertinent information from the source system regarding how the XML was constructed, i.e., the source table-field value from where the data source was assigned to a specific XML value in the request or where the value was returned in the response. The DEBUG level also should include time stamp information on the process. At minimum, the times stamp should include when the integration was called, when the request started to sending data to the tax engine, when the response started receiving data, and when the integration process was closed.NOTE: The logon username and password information sent in the web service request must be removed from the log. The content of the XML taghas to be replaced with, “Removed for security.\"Log Search and ReviewWhen using a system table to record logging, a user interface (UI) to view the logs must be provided. A search feature for users, dates, andpotentially other attributes is optional, but can greatly improve the user experience. Access control to view the logs is suggested.ScopeLogging applies to all forms of web service calls, which include tax calculations as well as address verifications.ExamplesFor logging examples, review the following: How to parse the response for successes or errors, see Configuration Screen TEST process
View a GP logging file with a log level set to ERROR and an incorrect user ID, see GP_Log_Error_Example.log.View a log for a successful sales tax call for a sales order, with a log level set to INFO, see GP_Log_Info_Example.log.View a GP logging file for a successful sales tax call for a sales order, with a log level set to DEBUG, see GP_Log_Debug_Example.log.
ChargesHANDLING, FREIGHT, DELIVERY, OR SIMILAR CHARGESCharges such as freight, insurance, and handling charges can be processed by ONESOURCE. How the charge is sent to Determination in the taxrequest determines how the tax results will be returned in the tax response.ERP systems handle charges in different ways: A charge can be a separate line item; clearly identified as a separate charge with its own amount. A charge can be associated with the line and the charge amount is included in the line amount. A charge can be associated with the line and the charge amount is not included in the line amount. A charge can be header charge with no associated lines or line amounts.Tax results for charges can be returned as separate authorities (one tax block per authority per charge and per line), or as separate tax detailssummarizing the line total tax and the charge total amount.The field name ProcessingOption indicates how the tax results will be returned. The values of this field are ChargeAsSeparateAuthority, ChargeNotIncludedInAmounts, and ChargeIncludedInAmounts.
INCOTERMS/Point of Title TransferDescriptionTwo components, Incoterms and Point of Title Transfer, have an impact on when the transfer of ownership (liability) occurs and when and wheretax applies.Business UsageIt is important to identify where the transfer of ownership occurs. The Delivery Terms (Incoterms) and the Point of Title Transfer provide thisinformation. Some financial systems have fields for both Delivery Terms and Point of Title Transfer, others only have a field for Delivery Terms. Ifonly Delivery Terms are available, they can be used to derive the Point of Title Transfer.INCOTERMSA commonly used international set of delivery terms is Incoterms. Incoterms rules or International Commercial Terms are a series of pre-definedcommercial terms published by the International Chamber of Commerce (ICC). They are widely used in International commercial transactions orprocurement processes. A series of three-letter trade terms related to common contractual sales practices, the Incoterms rules are intendedprimarily to clearly communicate the tasks, costs, and risks associated with the transportation and delivery of goods. Further, Incoterms define therespective roles of the buyer and seller in the arrangement of transportation and other responsibilities and clarify when the ownership of themerchandise takes place. They are used in conjunction with a sales agreement or other method of transacting the sale.Examples: EXW - Ex Works (named place of delivery) DDP - Delivered Duty Paid (named place of destination) FOB - Free on Board (named port of shipment) CIF - Cost, Insurance & Freight (named port of destination)The attached chart, Incoterms_2010_chart.pdf, details the responsibility (buyer or seller) for charges and fees by transportation mode.Point of Title Transfer (POTT)Whereas, Incoterms only deal with shipping responsibilities, payments of costs and duties and when the risk of loss transfers, the Point of TitleTransfer (POTT) describes the point where liability is passed from the seller to the purchaser/consumer. This point can be a completely differentlocation than where the delivery responsibility and the risk of loss occur. It is the point at which title transfers that creates the sale. The sale is thensubject to taxes and fees. The POTT indicates where the title transfers, destination, origin or in-transit. POTT greatly affects specific taxability byimpacting which authorities and which type of tax are calculated for each unique transaction.Tax UsageSales and Use tax laws may define a sale as any transfer of title, transfer of possession, or transfer of title and possession, depending on thestate. Title transfer and possession transfer may take place at different times and in different jurisdictions. This makes it difficult to determinewhen and where a sale has occurred in two situations; Interstate Commerce Transactions, and Intrastate Commerce with Local Option Taxes (insome cases).The taxing authorities of either the originating or destination jurisdiction may look to the sales contract, method of payment, terms of payment,method of delivery, terms of delivery, or other factors to assess the point of sale, and thus determine the jurisdiction that will be allowed to tax thetransaction. State and local law will generally assign tax rights to the state or locality of origination or destination.Incoterms are important for cross-border transactions, as either the US tax is applicable, or the US Export depending on terms. Incoterms are alsoimportant for International transactions.The POTT is used to clarify when and where the ownership of the merchandise takes place and hence where the tax liability occurred. It indicateswhether the destination (ship-to) jurisdiction applies, or if the origin (ship-from) jurisdiction applies. It is also important to send the POTT on UStransactions, especially for states such as California, Iowa, and Oklahoma, the POTT affects the Tax Type that the tax calculation returns.California, for example, is a modified-origin state. The state, county, and city taxes are based on the origin of the sale, but district taxes are basedon the destination. For interstate transactions into California (non-districts authorities), the method of delivery and POTT into the statedetermine whether to charge Sales Tax (ST) or Seller’s Use Tax (SU): Point of Title Transfer In Transit/Null Origin Destination SUMethod of Delivery Null SU SU ST Common Carrier ST Seller's Vehicle SU SU ST ST
Integration UsageFor the Simple Web Service request, the POTT value of 'Destination', 'Origin', or null is sent in the PointOfTitleTransfer XML element at theDocument or Line level. In the case of a null value, Determination assumes the transaction is in-transit and treats the value as in-transit ('I').(Note: the tax calculation service allows for the values of 'D', 'O', 'I'; whereas, the simple service values are 'Destination', 'Origin', or null).If the ERP system only uses delivery terms or Incoterms, the POTT can be derived as follows: If EXW = Origin Elseif DDP = Destination Else not setThe Delivery Terms (Incoterms) are not passed in the Simple Web Service. The element is available in the Tax Calculation Service.
Tax Liability Tracking (Audit)DescriptionLegal documents with tax liabilities, like invoices and credit memos, need to be recorded in the ONESOURCE Indirect Tax Determination auditdatabase for future reporting and return preparation.It is imperative that once transactions are audited they are not changed in the source ERP system; therefore, it is best to follow GAAP rules oncetransactions are committed in the general ledger and posted to Determination audit.Business UsageAs outlined in the Business Processes section, there is a distinction made between a call to calculate taxes and a call to audit taxes. In both casestaxes are calculated, but if the IsAuditResults field in the XML request is set to TRUE, the transaction needs to be stored in the ThomsonReuters Indirect Tax audit database for reporting and compliance purposes. The transaction will then appear on audit reports, tax returns, andother Thomson Reuters Indirect Tax reports.However, not all transactions are audited. For example, sales quotes for customers do not have actual tax liabilities. The tax still needs to becalculated because the customer will want an estimate for the tax that will need to be paid. However, no records of this tax calculation will bestored in the Thomson Reuters Indirect Tax audit database.Some transactions with multiple tax calls are not audited with the first call, but are with the second. For example, e-commerce typically have twotax touch points. The first call is unaudited and occurs when the cart is updated to calculate tax. The second call is audited and occurs after thecredit card authorization.Once a transaction has been audited, it cannot be changed, which is similar to how an entry to the general ledger cannot be modified once it hasbeen posted. To correct an incorrectly-audited tax transaction, enter a reversal into the financial system as a credit or debit memo, or as acancellation, followed by a new entry of the corrected transaction in the Thomson Reuters Indirect Tax audit database. The audited tax touchpoint should immediately follow the recognition of tax liability within the confines of the financial system.When a transaction with the same transaction number is sent, an entry occurs in the Thomson Reuters Indirect Tax audit database reversing theoriginal and entering the new values for that transaction number.Tax UsageOnce there is a tax liability for a transaction, the tax calculation results must be audited. For example, part of the payment due from a customer foran accounts receivable (AR) invoice is for sales tax. The sales tax liability must be recorded and remitted to the appropriate tax authorities. Sincethere is a tax liability on this transaction, it must be audited in ONESOURCE Indirect Tax audit database for inclusion on tax returns.Transactions are stored in audit using a unique invoice number, matching it to a record in the ERP system. For more information on this uniquekey, see Uniqueness in Audit.The IsAuditResults field in the tax request instructs the tax engine whether to persist a transaction in the tax liability database. If the field is setto false or the XML tag is not present, no tax liability is recorded. The IsAuditResults field must be set to true to record a tax liability in the auditdatabase.
Uniqueness in AuditDescriptionAs outlined in the Main Components of a Tax Call section, tax liabilities have to be written to the Determinationdatabase, commonly referred to as \"Audit\" or \"Audit Database.\" When adding records to the audit databaseeach invoice is stored in the Audit Database using a unique key. For more information on the Determinationaudit, see the Tax Liability Tracking (Audit) section.Business UsageIt is important that the client general ledger record of sales tax liability and the Determination audit record remain reconciled. To accomplish this, itis recommended that audited web service calls to Determination are performed during or right after a general ledger post. The reason for this isbecause a document posted to the general ledger usually cannot be changed after posting without doing a reversal, cancellation, or somethingsimilar. That ensures data integrity between the source system and the tax audit. E-commerce applications that will be auditing, the audit callshould occur after the credit card authorization.Always perform the audit function with a unique key. This key uniquely identifies a transaction in audit and canbe traced to the ERP system for reconciliation. The unique key is defined in more detail, below.Reversals (cancellations or credits) of an already-audited document should be sent with a unique document ID(audit key) and must have a negative amount. If the ERP can't support a unique new document for suchtransactions make sure you use the exact unique key combination as used for the original document. Thistriggers a reversal of the original document in the Determination audit database and adds the new documentwith its new values to show the net end result only.Tax UsageTax liabilities have to be recorded in audit for filing and reporting purposes. The transaction is uniquely identified in audit as described in thefollowing section.Unique KeyThe unique key value is stored in the UNIQUE_INVOICE_NUMBER field in audit. The UNIQUE_INVOICE_NUMBER field is a key field inensuring the transaction is unique not only within the ERP system, but also with all other data stored in the audit database. The key used to referto invoices depends on the capabilities of the specific ERP system and which elements have been set during the tax calculation.Simple Web ServiceFor the simple web service, the unique key is a computed field. A value is automatically built in the tax calculation request by concatenating thefollowing three fields into a string value separated by a pipe (|): ExternalCompanyID DocumentNumber CompanyRoleNote: All three XML fields above must have a value set during a tax calculation request event that writes data tothe audit database (SOAP XML field IsAuditResult = true).For example, for the company ACMECo with invoice 14329 and a seller role, the UNIQUE_INVOICE_NUMBER in audit would be: ACMECo|14329|SELLER ExternalCompanyID|DocumentNumber|CompanyRoleTax Calculation ServiceFor the tax calculation service, the UNIQUE_INVOICE_NUMBER value is directly passed from the ERP system in the XML request.Manage Uniqueness ExceptionsIf the above standard behavior isn't unique enough for the integrated ERP system, send a value in the DocumentNumber field. In these cases, a
custom string value can be built, but it is highly recommended to use the same first three fields as part of the custom key.The document number is the unique reference number for a document created in the source system. This number is used by ERP users to trackindividual transactions as they go through their ERP system. The number is also used by customers to identify individual transactions.If the ERP system does not provide a unique document number at the time of audit, an alternate number (row ID) can be used. This will be areconciliation issue/task and could make documentation lookup more difficult. A report can be created in the ERP to display the row ID and thetransaction number (later known) to aid in the reconciliation between audit (row ID) and the ERP system (transaction number).Some ERP systems display both the internal number (row ID) and the transaction number on the transaction form. For example, assume that atthe time of audit, the document number is not known. Instead, the document number sent is the field the ERP calls \"internal ID,\" which is thedatabase row ID.Another example is if an ERP system reuses invoice numbers each year, a transaction from a prior year could be overridden by the next year'stransaction with the same invoice number. To prevent this, add the fiscal year to the DocumentNumber key as follows: ExternalCompanyID|DocumentNumber|CompanyRole|FiscalYear MyCompany_1000|123456|Seller|2015
ReversalsDescriptionA reversal is a negative transaction. Reversals must be sent to Determination to account for credits or reversing original transactions.Business UsageReversals identified by the ERP system need to be sent to Determination. A reversal can be a transaction type such as a credit memo, a debitmemo (typically in accounts payable), or a return material authorization (RMA). A reversal transaction can be a new independent credittransaction with a new document number, a new credit transaction reversing a previously posted transaction with a new document number, ora new credit transaction reversing a previously posted transaction using the same document number.The reversal amount on a reversal transaction must be sent to Determination as a negative amount to indicate a credit for auditing and reportingpurposes. If the ERP system identifies credits by document types and positive amounts, a calculation must be performed. The calculation fornegative document types (e.g. credit memos) should be the amount times negative one (not just changing the sign to negative).There are also situations where positive document types (e.g. invoices) are negative amounts (e.g. over discounted items). These are not credits,but rather negative invoices and should not be identified as reversals.Tax UsageA reversal identified by the ERP system must be sent to Determination for auditing and reporting purposes. These credit amounts can then beassessed by the tax authority for refunds or adjustments.The document number sent to Determination drives the audit activity. If the document number sent to Determination has previously been sent (i.e.exists in Audit), Determination maintains the original document, creates a reversal of that document, and then creates a new version of thatdocument representing the latest document information passed. In the case of a true reversal/cancellation, the reversal is sent as zero. ThenAudit for that document will be reflected as: Original document 1234, line 1 = 100 Determination Reversal document 1234, line 1 = -100 Resubmitted reversal document 1234, line 1 = 0 Net Result in Audit = 0Alternatively, if the reversing transaction is sent with the same document number and a negative amount, then Audit for that document will bereflected as: Original document 1234, line 1 = 100 Determination Reversal document 1234, line 1 = -100 Resubmitted reversal document 1234, line 1 = -100 Net Result in Audit = -100If the ERP creates a reversal/cancellation document or record with a separate Document Number then the value is passed as a negative. NoDetermination reversal will occur and both transactions will be independently stated in Determination and net to zero.Originally, the Is_Credit flag indicated the transaction line was a credit. However, Determination currently has no functionality associated with thisflag. Therefore, the Is_Credit flag is an optional field and should only be used for custom reporting.
Processing Transactions without ONESOURCEOverviewWhile our failover design and other solutions limit downtime on the ONESOURCE, there are still situations where transactions cannot call the taxengine. This could be caused by a local network issue, an inability to connect to the WAN, service provider or a World Wide Web issue. In thesecases, the integration should be designed to minimize business disruption caused by missing tax. The following business processes should beconsidered when designing your solution:Business Process ImpactOrder-like transactions (Quote, Order, The document can be issued without tax included. Consider including a message indicating that taxetc.) was not calculated but will be added at invoice time.Sales Invoice-like transactions (Invoice, The document must include tax. If tax is not included, the transaction cannot proceed. Missing taxCredit, Debit, RMT, etc.) can impact a company's revenue and profit margin.Purchase Order-like transactions The document can be issued without tax included. Consider including a message indicating tax(Requisition, PO, etc.) was not calculated.Vendor Invoice (Purchase Invoice, The document can be put on hold for a time. Vendor invoices are not critical to a business's bottomAdjustments, etc.) line.Posting Documents without TaxDepending on your design choice, build your integration to allow posting of at least the Sales Invoice-like transactions when, due to an inability tocommunicate with ONESOURCE, no tax was calculated by ONESOURCE. We have found that our customers prefer a configurable design. Twoconfiguration options could be provided:System Down Process ActionThis indicator would instruct the integration and transaction systems how to behave when tax was not calculated because the system was down.Based on the table above, for example, for the noncritical transactions, we could allow processing with no tax or zero tax. For the criticalprocesses, the indicator could instruct the system to either put the transaction in error, on hold or continue processing it. When proceeding toprocess the transaction, a second configuration parameter could be introduced to allow an override of the tax rate. This parameter is outlinedbelow.Override Tax Rate for Posting Transactions in ErrorThis parameter would set an override tax rate to be used for tax calculation when ONESOURCE is not available. Since a ONESOURCEdetermined tax rate is not available for transactions in error, the override rate would take precedence. The rate could be any value theimplementing company chooses. It could be set to zero to have no tax calculated and the business would be responsible for paying the tax liabilityto the authorities. Alternatively, a default rate the company would like to collect could be entered; and at least a partial tax liability would becollected from the buyer. If the option to use an override tax rate is selected, we recommend you consider to linking this function with a special taxcode to identify these transactions for later review and correction, and possibly to allow a client to configure a separate account to post these taxliabilities into to make compliance adjustments easier later.Subsequent ProcessingWhen tax is not calculated by the tax service due to a system outage a subsequent process needs to be taken into consideration for reprocessingthese transactions to calculate the proper tax and/or to audit the relevant tax liability in the ONESOURCE database. The Success Status of aResponse chapter of this playbook might be of assistance for this.
AmountsDescriptionTransactions in a financial system can contain several amounts. It is critical to identify the correct amount from the transaction to send toDetermination for tax calculation. This section describes the transaction amounts and related data needed for a tax calculation.Business UsageTax calculation methods are used to enable proper tax calculation, depending on the type of amount that is included in thetransaction. ONESOURCE Indirect Tax Determination allows for three tax calculation methods: Forward, Reverse from Total, or Reverse fromTax. Business requirements, practices, and product pricing dictate which calculation method applies.When dealing with amounts it is important to also take the systems currencies into account, see Currency page.Tax UsageAmounts in the Simple Tax Service are comprised of two elements; AmountType and Amounts. Together they determine how taxes arecalculated and are included in the TaxRequest.Based on the AmountType and Amounts information provided in the TaxRequest, Determination calculates various amounts that are included inthe TaxResponse.TaxRequestThe following list outlines the type of amount fields on the TaxRequest and their definitions.Amount TypeAmountType is a field at the XML document level field that determines the way tax is calculated. Business requirements, practices, and productpricing dictate which AmountType is required.The mutually exclusive tax calculation methods are: GrossAmountBased: The tax amount is calculated based on the gross amount of the invoice. This is considered a Forward calculation where the gross amount is supplied and Determination calculates the tax. GrossPlusTax: The tax amount is calculated from the gross amount of the invoice that includes tax. This is considered a Reverse from Total calculation where one amount is supplied that contains the combined tax and gross amount. Determination calculates the separate amounts for gross and tax. TaxAmount: The gross amount of the invoice is calculated from a tax amount. This is considered a Reverse for Tax calculation where the tax amount (and optionally the gross amount) is supplied and Determination calculates the tax and gross amounts. The results are most accurate if you supply a gross amount.AmountsAmounts is a field at the XML line level field corresponding to the tax calculation method above: GrossAmount: Used with the GrossAmountBased method. The amount (without tax) of a single line in a document. This uses the AmountType of GrossAmountBased. The amount charged for a product, excluding taxes, in the functional currency of the transacting entity. If you only supply this amount, this becomes the starting point for the tax calculation logic. GrossPlusTaxAmount: Used with GrossPlusTax method. This is the invoice amount where tax has not been stated separately. Determination decides the tax liability and gross amount. This is used in cases where a transaction is invoiced without stating the taxes separately. Determination applies tax rules to this single amount and calculates the individual amounts for tax and gross. TaxAmount: Used with the TaxAmountBased method. The amount of tax on a sales order (the amount does NOT include the gross). The tax amount charged on the item line. If you only know the tax, this is the amount you provide as the starting point for tax calculation. Determination uses this amount to determine the gross amount.The following is an example of the use of the AmountType and Amounts fields:If a TaxRequest for a transaction that needs the tax amount calculated from a gross amount of an invoice (not including tax) and needs to havethe tax calculated, the calculation method of GrossAmountBased will calculate the tax from the gross amount of the transaction.TaxResponseThe TaxResponse contains three levels of tax information, TaxSummary, ZoneTaxSummary, and TaxDetails; each containing different taxes.See Tax Results Mapping. The following list outlines the type of Amount fields on the TaxResponse and their definitions.
TotalTaxAmount (Line): The total tax amount for an invoice. This is used in reports and returns.ChargeAmount (Line): The amount applicable for the charge (required). The amount of a charge for additional goods/servicesassociated with the product sold. This could be a positive or negative number.The amount used as the starting point for the taxdetermination, depending on the type of ProcessingOption. See Charges.ChargeTaxAmount: The tax amount calculated on a charge by Determination. This can be stored in the financial system and printed onthe invoice. This is shown on reports and returns. See Charges.CalculatedTaxAmount: The tax amount calculated by Determination for a transaction. This always represents the tax as calculated byDetermination. Depending on the accrual method selected, this can be posted to the general ledger. This amount is shown on reportsand returns.AccrualTaxAmount (Reserved for future use.): The intended use will be for the amount of tax accrued to handle either a tax over orundercharge by a vendor (partner). This is will be used in ERPs to create a tax liability when posting to the general ledger account. Thiswill be dependent on AccrualMethod. This will be shown on reports and returns.PartnerTaxAmount (Reserved for future use.): The intended use will be for the amount of tax a seller included in a purchase order orinvoice (also known as the Vendor Charged Tax). The vendor-charged tax from the TaxRequest. This will be shown on reports andreturns.ExemptAmount: This contains the maximum exempt amount from the tax results. If no tax, the value is zero. In some cases, thisinformation can be used in the ERP or on the invoice. This is shown on reports and returns.
Document TypesDescriptionThe DocumentType field in the XML can provide more granular information about the type of document being sent in the tax request.Business UsageThe document type is used primarily for troubleshooting to aid in identifying the transaction in question. It provides additional data to tie back towhere the document originated in the business source system (financial system). It facilitates reconciliation between Determination Audit and thefinancial system general ledger. Determination does not have a list of values for this data, rather clients set this field at their own discretion basedon supported business processes. See Business Processes.Sample document types:Document Type DescriptionSalesOrder unaudited sales transactionSalesInvoice audited sales transactionsCreditMemo audited sales reversal transactionsPurchaseOrder unaudited purchase transactionPurchaseInvoice audited purchase transactionsReturn unaudited purchase return transactionsDebitMemo audited purchase return transactionsTax UsageThe DocumentType value is not a factor in tax calculation. It is merely informational as a way to further identify the transaction from the sourcesystem (financial system). In the simple tax service request, DocumentType is required. The value is sent in the XML requestas <DocumentType>. Clients can set this field at their own discretion, but more detail is helpful when troubleshooting. An example XML is asfollows:<Document><DocumentNumber>200021</DocumentNumber><Addresses/><Attributes><IsAuditResult>true</IsAuditResult><IsCredit>false</IsCredit><CalculationMethod>GrossAmountBased</CalculationMethod><CompanyRole>Buyer</CompanyRole><CurrencyCode>USD</CurrencyCode><DocumentType>SalesOrder</DocumentType></Attributes><Dates><DocumentDate>2010-05-31</DocumentDate><FiscalDate>2010-05-31</FiscalDate></Dates>
DatesDescriptionMultiple dates are used in the tax request for a variety of reporting and tax calculation purposes. Available dates are: document date, fiscal date,and original document date. In addition, the Determination audit database contains a transaction date, which is a derived date of when thetransaction was written to the Determination audit database. This date is visible on some reports but not used for any taxability determination. Note: ETL Timing Reminder There may be a delay in viewing a posted transaction in audit for verification through Reporting. This is purely timing of running the ETL process.Business UsageThe business usage for each date is as follows:Document DateThe relevant date for document tax calculation. This date has to be set according to the source system rules.For the O2C process, this date is usually one of the following: The document date (order/customer invoice) The goods issue date (invoice of physical goods) The service rendered date for services providedFor the P2P process, this date is usually one of the following: The document date (purchase/vendor invoice) The goods receipt date for physical goods The service rendered date for services provided.Fiscal DateThe fiscal date is the date a tax liability from the transaction is to be posted in the general ledger (G/L), when revenue and expenses arerecognized. Used primarily for reporting and general ledger reconciliation.Original Document DateThe date used when reversing a document previously posted to the general ledger, e.g., a credit invoice, debit invoice, cancellation, or deletion.Tax UsageThe tax usage for each date is as follows:Document DateSent in the XML field DocumentDate. It is the primary date that drives the tax calculation in Determination unless an OriginalDocumentDate issupplied. For example: If a new rate becomes valid on November 1, 2015, Determination will use the old rate up to the document date ofOctober 31, 2015. When implementing an integration, determine the correct date source in the transaction system, i.e., invoice date, pricing date,or similar.Fiscal DateSent in the XML field FiscalDate. Fiscal date has no implications for tax determination (or rate determination), but it affects the period in which anitem is reported. In most cases, it is used for reporting and filling the tax liability to the authorities. For systems without a fiscal date, the date canbe derived from the fiscal period start date.Original Document DateSent in the XML field OriginalDocumentDate. It is for reference and to ensure that the original tax rates and rules are applied to the reversaldocument. It is the document-level date of the original invoice. If sent on a tax request, this date will be used for tax determination instead of the
document date.
Use Tax This section is only relevant for addresses located in the US.DescriptionOn an accounts payable transaction, the vendor charged tax amount may not agree with the Determination calculated amount. To accommodatethis difference, the Integration should have an accrual functionality. Currently there are two levels of functionality, Essential or Advanced,described below.The <VendorTax> is the amount of tax charged by the Vendor on an Accounts Payable invoice. The invoice level field is informational only. It isnot used by either Determination or Reporting. However, customers can use this field for custom reporting (i.e. Transaction Extract forreconciliation). The Integration uses the value in this field to calculate the accrual.Essential Use Tax Accrual FeaturesThe essential use tax accrual functionality is the act of comparing the sales tax the vendor charged on the invoice to the seller tax amountDetermination calculates. The net difference between the vendor charged amount and the Determination seller tax amount is then accrued.Determination will evaluate the transaction using the Company Role of Seller to calculate the seller's use tax amount to use in the comparison.An accrual journal entry is created for return preparation.Following are some examples: If vendor did not charge tax, the Determination calculated amount is accrued to Tax Expense and Tax Accrual general ledger accounts. If the vendor charged tax is the same amount as Determination calculated, no accrual journal entry is created. If there is a difference between the vendor charged tax and the Determination calculated amount (either over-charged or under-charged), the difference is accrued to Tax Expense and Tax Accrual general ledger accounts.The tax code used for these transactions will be IDT_USE_P. The amount accrued is a total not by jurisdiction.Advanced Vendor Charge Tax Accrual FeaturesThe advanced vendor charged tax accrual functionality is the act of comparing the sales tax the vendor charged on the invoice to the seller taxamount Determination calculates. The net difference between the vendor charged amount and the Determination seller tax amount is thenaccrued based on the Handling Option setting. Determination will evaluate the transaction using the Company Role of Seller to calculate theseller's use tax amount to use in the comparison.Handling Options: Total: Accrue full tax liability, pay invoice without any tax Partial: Accrue difference, pay invoice with Determination calculated tax Accrue: Accrue difference, pay invoice with vendor charged tax Hold: No accrual, return indicator to ERP to place invoice on hold status Off: No accrualThe advanced vendor charged tax accrual functionality is complex and is not supported with the Simple Tax Service. Please contact yourdeveloper community partner for more information.
UserAttributeContainerDescriptionIn the SimpleTaxService, ONESOURCE Indirect Tax allows 5 additional fields at the line level to be appended for tax calculation. These additionalfields are mapped to Determination as Input XML Custom Attributes. The TransEditor functionality in Determination is then used to allow theseattributes to be used in the tax calculation.Business UsageWhile our web services account for many of the complex tax scenarios and their need of transaction data to make the proper tax decision, insome cases the list isn't comprehensive enough. For example, in a specific industry, a tax decision is dependent on a specific field which thetransaction system has, but our XML doesn't contain. In these cases, the UserAttributeContainer container can be used. Let's say you sellsoftware and it can be either downloaded from your website or shipped on a CD, but you use an inventory item for this purpose. Your transactionsystem will have a field or indicator that tells if the product was downloaded or shipped on a CD. You would map that value toa UserAttributeContainer.Tax UsageIn above example you would send an attribute to Determination in one of the UserAttributeContainer fields, then create a custom mapping via aTransEditor to change the product taxability to either \"physical software\" or \"software download\" triggering different taxability depending on thetaxing authority.Technical ImplementationThe UserAttributeContainer is made up of two fields; Key and Value. There can be multiple instances of the UserAttributeContainer indicated bythe collection UserAttributes. At this time, the SimpleTaxService limits the number of attributes to 5. The sample code below shows what acollection of two user attributes would look like: <Attributes> <UserAttributeContainer> <UserAttributes> <Key>1</Key> <Value>One</Value> </UserAttributes> <UserAttributes> <Key>2</Key> <Value>Two</Value> </UserAttributes> </UserAttributeContainer> </Attributes>
Search
Read the Text Version
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23
- 24
- 25
- 26
- 27
- 28
- 29
- 30
- 31
- 32
- 33
- 34
- 35
- 36
- 37
- 38
- 39
- 40
- 41
- 42
- 43
- 44
- 45
- 46
- 47
- 48
- 49
- 50
- 51
- 52
- 53
- 54
- 55
- 56
- 57
- 58
- 59
- 60
- 61
- 62
- 63
- 64
- 65
- 66
- 67
- 68
- 69
- 70
- 71
- 72
- 73
- 74
- 75
- 76
- 77
- 78
- 79
- 80
- 81
- 82
- 83
- 84
- 85
- 86
- 87
- 88
- 89
- 90
- 91
- 92
- 93
- 94
- 95
- 96
- 97
- 98
- 99
- 100
- 101
- 102
- 103
- 104
- 105
- 106
- 107
- 108
- 109
- 110
- 111
- 112
- 113
