Find Answers

Find Answers

Specified Languages
British English
English

How do I transition to CyberSource's upgraded Global Tax Calculation in 2017?


Doc ID:    C1712
Version:    13.0
Status:    Published
Published date:    09/28/2017
Updated:    09/28/2017
 

Answer


Title: Global Tax Calculation Upgrade Reference Guide
 
Overview

CyberSource upgraded its Global Tax Calculation solution during the first quarter of 2017. These upgrades help us to continue to provide accurate tax information for every transaction, and enhance the data you receive in response to each tax call. We are currently transitioning CyberSource customers upon request to the upgraded service through September 2017. The final and mandatory cut over date is September 26, 2017. At that time, all customers will be switched over to the upgraded service.  New CyberSource customers will automatically be configured for the upgraded service, but existing customers must transition to the upgraded service.

We recommend that you review this article to learn about the implications of the transition and decide if any changes should be made to your implementation. The existing tax service should continue to function even if you do not make any changes, but the data you receive in the response message may change. This step will help make sure you receive the correct tax amounts after you transition to the upgraded service. This reference article contains sections on new features, transition timeline, technical changes, and recommended actions.

If you have questions or concerns not addressed here, please contact CyberSource Customer Support.

The following section contains recommended actions to support your transition to the upgraded service. Additional detail will be provided in subsequent sections of this article.



Recommended Actions
We recommend you take the following actions during this transition:
  1. Continue to send all request fields at least until September 2017, but be aware that once you are transitioned some fields will no longer affect the tax calculation.
  2. Review the product mapping to ensure the new product descriptions and exemptions are accurate for your products.
  3. After you have been switched to the upgraded service, implement the newer product codes by September 2017, when product-based rules and exemptions will no longer be applied to the previously mapped product codes.
Let your sales or technical account manager know between January 2017 and September 2017 when you are ready to transition to the upgraded service.
  
New Features
The upgraded service will include the features and benefits outlined below.
 
Feature Description Benefit
New Product Codes Multi-regional codes. Approximately 2,000 product codes supported across 138 countries Improved support for international, product-based tax rules and exemptions
Geolocation Tax engine uses the full address to identify taxable jurisdictions Increases accuracy of tax calculation
Relative Shipping Tax Shipping tax depends on taxability of other line items Ensures business is not over-collecting on shipping tax
Data Enhancements Additional data returned in tax response (tax rates, exempt/taxable amounts, jurisdiction names/codes) Gives businesses more visibility into how tax was calculated, and additional data to use for tracking and auditing purposes
 
 
Transition Timeline
CyberSource customers can begin transitioning to the upgraded service on January 1st 2017. The API specification for the upgraded service is currently available upon request and also at http://www.cybersource.com/developers/documentation/tax_services/

Customers will be migrated to the upgraded service upon request from January through September 2017. The final and mandatory cut over date is September 26, 2017. At that time, all customers will be switched over to the upgraded service.
 
 
Technical Changes
Transitioning to the upgraded service will involve changes to the request fields, changes to reply fields, changes to product codes, and changes to country support.

Changes to request fields
A subset of the existing request fields will no longer be supported. You may continue to send the fields in the call and the tax service will ignore them. A list of unsupported fields for the Simple Order and SCMP APIs is located in Appendix A of this document. 

We recommend that you continue to send your existing fields in your requests at least until September 2017, but want you to be aware that once you are transitioned these fields will no longer affect the tax calculation.
 
The service features that will no longer be supported are:
 
Feature Purpose Notes
County-level request fields Identify county tax jurisdiction Upgraded service uses geolocation for more accurate jurisdiction assignment so county-level request fields are no longer necessary
Point of title transfer fields Send incoterm rules for international transactions Incoterm rules are not supported in the upgraded service
Jurisdiction-level tax rate and tax amount overrides Override the amount for a specific jurisdictional tax Tax amount overrides at the offer level (i.e. for specific items in the order) will continue to be supported
Middleman registration fields Trigger tax triangulation rules on international transactions Triangulation is not supported in the upgraded service
Multiple seller registration ID fields Send multiple seller registration numbers in a request Multiple seller registration ID fields are no longer supported: 
 
Simple Order API
taxService_sellerRegistration0...N
item_#_sellerRegistration0...N
 
SCMP API
seller_registration0...N
 
Note: If you send a value in the single seller registration ID field(s) and VAT rules and rates are applicable, then VAT tax will be calculated and the relevant tax amounts will be returned in the response. The single seller registration ID fields are:
 
Simple Order API
taxService_sellerRegistration
item_#_sellerRegistration
 
SCMP API
seller_registration
 
 
Changes to reply fields
There are 17 new reply fields. Refer to the API guide for field names and descriptions.  In order to have these new fields returned in the tax replies, customers performing tax calls using the CyberSource Simple Order API and/or the SOAP Toolkit API will need to configure their APIs to point to a newer version of the CyberSource WSDL (version 1.139 or greater). Note that the upgraded tax service will continue to function normally when the API is pointed at earlier versions of the CyberSource WSDL (i.e. before 1.133), but since not all fields will be returned in the transaction reply, some jurisidictional sub-amounts will be missing (although these sub-amounts will still be accounted for in the total tax amounts sent in the reply). Customers using the SCMP API will not need to make any configuration changes in order to see these new fields returned in their tax replies.

An issue has been identified with the interoperability of Axis 1.4* and CyberSource's upgraded tax service. In isolated cases, Axis 1.4 deserialization of the arrays in the reply XML to parse the new response fields is not working.  Transaction requests are sent/processed successfully, but replies are failing on the client side, returning a NULL POINTER EXCEPTION when the Axis 1.4 library is used to parse the result.  CyberSource has resolved this Axis 1.4 limitation on the server side beginning with WSDL version 1.139. If your client integration is using Axis 1.4 and you experience this issue with the upgraded tax service (and your client is pointed at WSDL version 1.133 through 1.138), CyberSource recommends you configure your client to point to WSDL version 1.139 or greater. If the issue persists, please reach out to
CyberSource Customer Support before the auto-cutover date in September 2017.

*Axis is an open source Java library which can be used to connect to any SOAP endpoint.


The reply fields that will no longer be supported are:
Simple Order API
taxReply_city
taxReply_postalCode
taxReply_state
taxReply_county
taxReply_item_#_districtTaxAmount
taxReply_totalDistrictTaxAmount
 

SCMP API
tax_city_name
tax_zip
tax_state_name
tax_county_name
tax_district_tax#
tax_total_district_tax
 
 
For Canada, the following reply fields and associated values are changing:
Canada Tax Type Changing FROM Changing TO
GST Simple Order API
taxReply_item_#_stateTaxAmount
taxReply_totalStateTaxAmount
 
SCMP API
tax_state_tax#
tax_total_state_tax
New Simple Order API Field
taxReply_item_#_countryTaxAmount
taxReply_totalCountryTaxAmount
 
New SCMP API Field
tax_country_tax#
tax_total_country_tax
PST, QST Simple Order API
taxReply_item_#_countyTaxAmount
taxReply_totalCountyTaxAmount
 
SCMP API
tax_county_tax#
tax_total_county_tax
Existing Simple Order API Field
taxReply_item_#_stateTaxAmount
taxReply_totalStateTaxAmount
 
Existing SCMP API Field
tax_state_tax#
tax_total_state_tax
 
 
Canada Tax Type Changing FROM Changing TO
HST Simple Order API
taxReply_item_#_countyTaxAmount
taxReply_totalCountyTaxAmount
 
SCMP API
tax_county_tax#
tax_total_county_tax
*Split into GST and PST:

GST portion:
New Simple Order API Field
taxReply_item_#_countryTaxAmount
taxReply_totalCountryTaxAmount
 
New SCMP API Field
tax_country_tax#
tax_total_country_tax

PST portion:
​New Simple Order API Field
taxReply_item_#_stateTaxAmount
taxReply_totalStateTaxAmount
 
New SCMP API Field
tax_state_tax#
tax_total_state_tax
*The HST tax type is, by default, returned as a GST portion and a PST portion (as shown in the above table).  CyberSource offers an alternative option whereby the HST is aggregated into a single amount and returned in the state tax field.  Please contact CyberSource Customer Support if you would like to have your merchant ID configured for this option.

For Value-Added Tax (VAT), amounts are now returned in a NEW reply field as follows:
Simple Order API
taxReply_item_#_countryTaxAmount
taxReply_totalCountryTaxAmount
 
SCMP API
tax_country_tax#
tax_total_country_tax
 
Changes to product codes
A new set of multi-regional product codes is available to help ensure accurate tax rules and product exemptions are applied. A list of these new product codes and descriptions are available upon request and can be used in your tax calls once you are switched over to the new version of the service. When making your request, please refer to this document as the new CyberSource Tax Codes.

In order to make your transition to the upgraded service as seamless as possible, we have mapped a subset of the existing product codes (those which are commonly used) to the corresponding product codes in the new set. These codes have been programmatically mapped in the upgraded service. This means you can continue to send a subset of the older product code in your tax request and similar product-based rules and exemptions will be applied. The product description and associated exemptions may be slightly different for the new codes. Therefore, we recommend you review the mapping to ensure the new product descriptions and exemptions are accurate for your products.

The mapping between the old and new product codes is available upon request. When making your request, please refer to this as the CyberSource Product Code Mapping document. This mapping will continue to be supported through March 2018, after which the older product codes will no longer be recognized. We recommend you implement the newer product codes by this date. You can continue to send the older, unsupported codes in the request messages, but there will be no tax rules or product exemptions applied; the product will be considered fully taxable.

IMPORTANT While CyberSource has provided a suggested mapping of old to new product codes, these are high-level suggestions and it is critical that these are tested by your business for applicability to your products' tax liability. Some items may be taxed at the full rate instead of exempted. Please review the list of new product codes (replacing some of your existing product codes) and make adjustments to your systems as soon as possible in order to avoid over-taxing or under-taxing some items.


Changes to country support
The following countries will no longer be supported:
  • Brazil
 
Recommended Actions
To summarize, we recommend you take the following actions during this transition:
  1. Continue to send all request fields at least until September 2017, but be aware that once you are transitioned some fields will no longer affect the tax calculation.
  2. Review the product mapping to ensure the new product descriptions and exemptions are accurate for your products.
  3. After you have been switched to the upgraded service, implement the newer product codes by September 2017, when product-based rules and exemptions will no longer be applied to the previously mapped product codes.
Let your Sales or Technical Account Manager (TAM) know between January 2017 and September 2017 when you are ready to transition to the upgraded service.  You will have an opportunity to transition first in the Test Environment and, once your testing of the upgraded service is complete, you can then transition to the upgraded service in the Production Environment.
 

 

Appendix A - Unsupported Fields

 
County-level request fields:
Simple Order API
billTo_county
shipFrom_county
shipTo_county
taxService_orderAcceptanceCounty
taxService_orderOriginCounty
item_#_orderAcceptanceCounty
item_#_orderOriginCounty
item_#_shipFromCounty 

SCMP API
bill_county
ship_from_county
ship_to_county
order_acceptance_county
order_origin_county
 

Point of title transfer fields: 
Simple Order API
taxService_pointOfTitleTransfer
item_#_pointOfTitleTransfer

SCMP API
point_of_title_transfer
 
 
 
Jurisdiction-level tax rate and tax amount overrides:
Simple Order API
item_#_countryOverrideRate
item_#_stateOverrideRate
item_#_countyOverrideRate
item_#_cityOverrideRate
item_#_countryOverrideAmount
item_#_ stateOverrideAmount
item_#_countyOverrideAmount
item_#_cityOverrideAmount
 
SCMP API
country_override_rate
state_override_rate
county_override_rate
city_override_rate
country_override_amount
state_override_amount
county_override_amount
city_override_amount
 
 
 
Middleman registration fields:
Simple Order API
taxService_middlemanRegistration
item_#_middlemanRegistration

SCMP API
middleman_registration
 
 
 
Multiple seller registration ID fields: 
Simple Order API
taxService_sellerRegistration0...N
item_#_sellerRegistration0...N

SCMP API
seller_registration0...N
 

Rate This Item