Tax Calculation Developer Guide {#tax-about-guide} ================================================== This section describes the audience and purpose of this guide as well as conventions and related documentation. Audience and Purpose -------------------- This guide is written for application developers who want to use the `Simple Order API` to integrate tax calculation into an order management system. Implementing the tax calculation service requires software development skills. You must write code that uses the API request and response fields to integrate the tax calculation service into an existing order management system. Conventions ----------- The following special statements are used in this document: > An *Important* statement contains information essential to successfully completing a task or learning a concept. > A *Warning* contains information or instructions, which, if not heeded, can result in a security risk, irreversible loss of data, or significant cost in time or revenue or both. Testing ------- We recommend you test all use uses to ensure the tax engine is calculating taxes as expected before going live. Contact `Cybersource` Customer Support to have your test account set up to return production-level tax rates for short-term testing needs. You will be required to use a production merchant for testing if you have long-term testing needs that require production-level data for ongoing validation. Use the Developer Center to test Value Added Services: [https://developer.cybersource.com/api-reference-assets/index.html#value-added-service_taxes_value-added-service](https://developer.cybersource.com/api-reference-assets/index.md#value-added-service_taxes_value-added-service "") Related Documentation --------------------- Refer to the Support Center for complete technical documentation: [https://docs.cybersource.com/en/index.html](https://developer.cybersource.com/docs.md "") Customer Support ---------------- For support information about any service, visit the Support Center: Recent Revisions to This Document {#tax-recent-revisions} ========================================================= 26.03.01 -------- This revision contains only editorial changes and no technical updates. 24.02 ----- This revision contains only editorial changes and no technical updates. 24.01 ----- Removed references to `Business Center`. 23.02 ----- This revision contains only editorial changes and no technical updates. 23.01 ----- This revision contains only editorial changes and no technical updates. 21.02 ----- Updated Invalid Tax Calculation. VISA Platform Connect: Specifications and Conditions for Resellers/Partners {#vpc-partner-reseller-disclaimer} ============================================================================================================== The following are specifications and conditions that apply to a Reseller/Partner enabling its merchants through Cybersource for Visa Platform Connect ("VPC") processing. Failure to meet any of the specifications and conditions below is subject to the liability provisions and indemnification obligations under Reseller/Partner's contract with Visa/Cybersource. 1. Before boarding merchants for payment processing on a VPC acquirer's connection, Reseller/Partner and the VPC acquirer must have a contract or other legal agreement that permits Reseller/Partner to enable its merchants to process payments with the acquirer through the dedicated VPC connection and/or traditional connection with such VPC acquirer. 2. Reseller/Partner is responsible for boarding and enabling its merchants in accordance with the terms of the contract or other legal agreement with the relevant VPC acquirer. 3. Reseller/Partner acknowledges and agrees that all considerations and fees associated with chargebacks, interchange downgrades, settlement issues, funding delays, and other processing related activities are strictly between Reseller and the relevant VPC acquirer. 4. Reseller/Partner acknowledges and agrees that the relevant VPC acquirer is responsible for payment processing issues, including but not limited to, transaction declines by network/issuer, decline rates, and interchange qualification, as may be agreed to or outlined in the contract or other legal agreement between Reseller/Partner and such VPC acquirer. DISCLAIMER: NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR ANY ERRORS OR OMISSIONS BY THE Visa Platform Connect ACQUIRER IN PROCESSING TRANSACTIONS. NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR RESELLER/PARTNER BOARDING MERCHANTS OR ENABLING MERCHANT PROCESSING IN VIOLATION OF THE TERMS AND CONDITIONS IMPOSED BY THE RELEVANT Visa Platform Connect ACQUIRER. Overview of Tax Calculation {#tax-overview} =========================================== The tax calculation service provides real-time tax calculation for worldwide orders placed with your business. It also enables you to avoid the risk and complexity of managing online tax calculation. The key services provided allow you to: * [Calculate Taxes](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-request-calculating-overview.md "") * [Tax Reporting](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-reporting-intro.md "") > {#tax-overview_ul_vy3_4ml_z5b} **IMPORTANT NOTICE FOR USERS OF CYBERSOURCE TAX SERVICES** > The tax calculation is based on the location of the customer's taxing jurisdiction, your nexus locations, and the tax and product codes that you provide to Cybersource. The order price and quantity are included in the calculation to determine the order's total tax amount. You are solely responsible for selecting the appropriate tax and product codes for your business and its goods and services, including with respect to shipping and handling, and providing those codes to Cybersource. > CYBERSOURCE DOES NOT PROVIDE TAX CONSULTATION SERVICES, ACCOUNTING OR LEGAL ADVICE AND ASSUMES NO OBLIGATION, LIABILITY OR RESPONSIBILITY FOR ANY INCORRECT, INACCURATE, OR INCOMPLETE INFORMATION PROVIDED TO CYBERSOURCE, OR FOR ANY INCORRECT TAX CALCULATIONS RESULTING FROM SUCH INFORMATION. CYBERSOURCE STRONGLY RECOMMENDS THAT YOU CONSULT WITH A TAX PROFESSIONAL IN CONNECTION WITH YOUR SELECTION OF TAX-RELATED DATA FOR INPUT INTO THE CYBERSOURCE TAX CALCULATION SYSTEM. TO THE EXTENT CUSTOMER USES CYBERSOURCE'S TAX CALCULATION SERVICE, CUSTOMER UNDERSTANDS AND AGREES THAT NEITHER CYBERSOURCE NOR ITS THIRD-PARTY LICENSORS CAN GUARANTEE THE ACCURACY OF TAX OR VAT RATES OBTAINED FROM TAXING AUTHORITIES, AND, (ii) THAT CUSTOMER BEARS THE ULTIMATE RESPONSIBILITY FOR THE PROPER PAYMENT AND REPORTING OF TAXES APPLICABLE TO CUSTOMER'S SALE OF ITS PRODUCTS OR SERVICES. Additional Information ---------------------- In the `Business Center`, you can view transaction details, process customers' transactions, and manage the Tax Detail Report. For more information about tax calculation using the `Business Center`, see [`https://businesscenter.cybersource.com`](https://businesscenter.cybersource.com ""). Prerequisites for Tax Calculation {#tax-plan-planning-for-tax-calculation} ========================================================================== Before implementing the tax calculation service, you must know the following: 1. Where your business is required to pay tax, and register there. See [Tax Nexus](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-overview/tax-plan-planning-for-tax-calculation/tax-plan-nexus.md ""). 2. Whether any products require special product codes for tax purposes. See [Product Codes](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-overview/tax-plan-planning-for-tax-calculation/tax-plan-product-codes.md ""). 3. The correct address information. See [Address Requirements](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-overview/tax-plan-planning-for-tax-calculation/tax-plan-address-intro.md ""). 4. When to calculate tax in your check out flow. See [When to Calculate Taxes](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-overview/tax-plan-planning-for-tax-calculation/tax-plan-when-to-calculate-taxes.md ""). {#tax-plan-planning-for-tax-calculation_ol_gkn_4cb_mvb} Tax Nexus {#tax-plan-nexus} =========================== When your company has *nexus* in the US or Canada, you might be required to collect sales tax or sellers use tax in those countries. You can establish nexus in a state or province in various ways. For example: * Your company has a physical presence in the US or Canada such as office space, warehouse space, paid staff, or inventory. * Your company sells a sufficiently large volume of goods in the US or Canada to have *economic* nexus. Each state and province has its own rules for determining nexus. Consult your tax advisor to determine where you have nexus. In your tax calculation service request, specify the states in which you have nexus by populating the taxService_nexus and taxService_noNexus API fields. When you do not include one of these fields in a tax calculation service request, the tax system makes its calculations as if you have nexus in every state. For more information, see [Step 1: Nexus](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-request-calculating-overview/tax-overview-us-sales-tax-descr/tax-request-calculating-us-and-canadian-tax.md#tax-request-calculating-us-and-canadian-tax_step-one-nexus ""). Product Codes {#tax-plan-product-codes} ======================================= When you request the tax calculation service, you can provide a separate product code for each item in the order. A product code is required in order to trigger product-based rules and exemptions. When you do not include a product code in your request, or when you include an invalid product code, the tax calculation service assumes that the product has no product-based tax exemptions and is fully taxable. > To use a product code that is not listed in the available guides, contact customer support for information about how to proceed. US and Canadian Tax ------------------- Products that are fully taxable in all states do not need a product code because they do not have tax exemption in any state. For tax-exempt products or those with non-standard tax rates, use the product codes in the `Cybersource` tax codes guide, which can be requested each month from customer support. To use a product code that is not listed in the guide, contact customer support for information about how to proceed. Until the product code is supported, you can override the tax amount for the product by sending the amount of tax to apply to the item in the purchaseTotals_taxAmount field. For more information, see [Step 2: Product Codes](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-request-calculating-overview/tax-overview-us-sales-tax-descr/tax-request-calculating-us-and-canadian-tax.md#tax-request-calculating-us-and-canadian-tax_step-two-codes ""). International Tax and VAT ------------------------- For a list of available product codes for international taxes or VAT, see the `Cybersource` tax codes guide. For information about these codes, contact customer support. Address Requirements {#tax-plan-address-intro} ============================================== The tax calculation service requires specific address information be provided in order to properly calculate tax. This section goes over how the tax calculation service uses address information to calculate tax. > There is additional address related information in the US and Canada section that explains specific request fields. See [US and Canadian Addresses](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-request-calculating-overview/tax-overview-us-sales-tax-descr/tax-request-calculating-us-and-canadian-tax.md#tax-request-calculating-us-and-canadian-tax_address ""). Multiple Shipping Destinations in a Single Order ------------------------------------------------ You cannot specify a different shipping address for each item in an order. When the order contains multiple items that are going to different addresses, you must send a separate tax calculation service request for each shipping address. Missing Origin Addresses ------------------------ The destination address is substituted for the origin address when no origin address or a partial origin address is specified. For the best results, use fully validated origin and destination addresses. Invalid Address Combination Correction -------------------------------------- The tax calculation service performs an implicit address validation; if successful, the entire address is used for tax calculation In case the full address validation failed, engine looks for "Zip + 4" -- if it has been provided. If provided, tax is calculated with the "Zip + 4". If "Zip + 4" is not provided or is incorrect, engine looks for "City \& State" or Zip; if either are provided and are accurate, tax is calculated based on these details. If the zip code does NOT lie within the state, then the city and state are used to determine the region for the tax calculation. Note: In certain cases, Zip alone is not enough to accurately determine the jurisdictions; in such cases, engine looks for additional information -- such as Address Lines or City and State. If either is provided and enables identification of the jurisdictions, the successful tax calculation is returned. As Jurisdiction data is in a regular state of change, partial addresses can produce different results over time as the jurisdictions and tax authorities change. Abbreviations used for some city and county names are acceptable in more than one form. For example, St. Louis is acceptable as *Saint Louis* , *St Louis* , and *St. Louis* . See [City Abbreviations](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-info-city-abbrevs.md ""). When to Calculate Taxes {#tax-plan-when-to-calculate-taxes} =========================================================== You can calculate tax at these times during the order process: * When the customer prompts for a subtotal or total. * When the customer performs a final check out. * When the order ships, which ensures that the current tax rate is applied to the order. As you determine how and where to implement the Tax Calculation Service on your website, consider that the Global Tax Calculation Service is billable for each request. To offset your costs and optimize your pricing, consider waiting to request a tax calculation until after your customer has entered their shipping or billing address on the checkout page. This minimizes the number of tax calculation requests for a single transaction. To ensure that your business complies with tax laws, work with a tax advisor to determine when to calculate tax. For more information on when to calculate US and Canadian taxes, see [Step 4: When to Calculate Tax](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-request-calculating-overview/tax-overview-us-sales-tax-descr/tax-request-calculating-us-and-canadian-tax.md#tax-request-calculating-us-and-canadian-tax_step-four-when ""). Tax Calculation {#concept_xxx_tqb_mvb} ====================================== The service can calculate the following types of taxes: * US sales and sellers use tax * Canadian sales tax (GST, PST, HST, QST) * International (non-US/Canadian) and Value-Added Tax (VAT) {#concept_xxx_tqb_mvb_ul_gbt_sxd_bwb} The calculation is based on the location of the customer's taxing jurisdiction, your nexus locations, and the product codes that you provide. The order price and quantity are included in the calculation. The tax calculation service is not recommended for merchants conducting business with unsupported countries. See [Supported Countries and Regions](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-info-supported-country-regions.md ""). US and Canadian Tax Calculation {#tax-overview-us-sales-tax-descr} ================================================================== The tax calculation service uses the same request to calculate US and Canadian sales tax due to their similarities, but there are some distinguishing factors that should be known. US Sales Tax ------------ Sales tax is imposed on a transfer of property. Some states do not have sales tax. For US orders, the tax calculation service includes the total tax value for the transaction and tax values and rates per jurisdiction, divided into national, state, county, city, and special taxes. Some states do not have sales tax. Canadian Taxes -------------- The same procedures apply to calculating taxes for Canada as for the United States. Use only Canadian dollars for all Canadian taxes. The tax calculation service returns: * GST as a country-level tax * PST and QST as state-level taxes * HST as the sum of GST and PST If you want the tax calculation service to return HST as one field, contact customer support to configure your account accordingly. Calculating US and Canadian Tax {#tax-request-calculating-us-and-canadian-tax} ============================================================================== To receive the most accurate tax calculation, you will need specific information for the field values. Follow these steps to determine the values for the fields. One tax service request should not include more than 50 line items. When you send a request with more than 50 line items, the request could time out. The Tax Calculation Service uses line-level rounding. Tax amounts for each jurisdictional detail will be rounded and then aggregated to the line. For example, 8.5% total tax that includes 1.25% city tax, 1.25% county tax, and 6% state tax, levied on a 10.00 item would result in a total tax of 0.86 based on amounts of 0.13 city tax, 0.13 county tax, and 0.60 state tax. Step 1: Nexus {#tax-request-calculating-us-and-canadian-tax_step-one-nexus} --------------------------------------------------------------------------- Identify the location of your company's nexus. Products are taxable only when the customer's shipTo_state field value matches a state or province in which your company has nexus. If the ship to fields are not included in the request, the service will use the bill to fields to determine the tax amount. Use the taxService_nexus field to list the states or provinces in which your company has nexus. Alternatively, you can use the taxService_noNexus field to list states that should not be taxed. You cannot combine the taxService_nexus and taxService_noNexus fields in the same request. When you do not specify your nexus locations, the tax calculation service processes your request as if every state or province is taxable. * When you do not specify your nexus locations, or when a value of the nexus field matches the value for the shipTo_state field, the service calculates the applicable tax for the product. * When the value for the shipTo_state field does not match any state or province where you have nexus, the service assigns zero tax. For more information, see [Tax Nexus](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-overview/tax-plan-planning-for-tax-calculation/tax-plan-nexus.md ""). Step 2: Product Codes {#tax-request-calculating-us-and-canadian-tax_step-two-codes} ----------------------------------------------------------------------------------- If the product has special tax considerations, you can provide the appropriate tax product code in the item_#_productCode field in the request. For more information, see [Product Codes](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-overview/tax-plan-planning-for-tax-calculation/tax-plan-product-codes.md ""). Step 3: Addresses {#tax-request-calculating-us-and-canadian-tax_address} ------------------------------------------------------------------------ To receive the most accurate tax calculation possible, include the following address information in the request: * Ship-to address, in fields in the shipTo fields group. When multiple cities are within a postal code area, the optional request field shipTo_city value improves the accuracy of the calculated tax. * Product code, in the item_#_productCode field. * Nexus, in the taxService_nexus field---or if it is easier, you can use the taxService_noNexus field to provide a list of states in which you do not have nexus. When the tax calculation service succeeds, the response includes the taxReply_grandTotalAmount field. For more address-related information, see [Address Requirement](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-overview/tax-plan-planning-for-tax-calculation/tax-plan-address-intro.md ""). Step 4: When to Calculate Tax {#tax-request-calculating-us-and-canadian-tax_step-four-when} ------------------------------------------------------------------------------------------- Determine when you will provide tax calculations during the customer transaction. Tax calculation can occur before or after determining the final order total. See Tax Reporting to know how this service can impact when you would want to request the tax service. For more information, see [When to Calculate Taxes](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-overview/tax-plan-planning-for-tax-calculation/tax-plan-when-to-calculate-taxes.md ""). Endpoint {#tax-request-calculating-us-and-canadian-tax_tax-endpoint} -------------------------------------------------------------------- Set the `taxService` field to `true`. Send the request to `https://ics2ws.ic3.com/commerce/1.x/transactionProcessor`. Required Fields for a Tax Calculation Using the `Simple Order API` {#tax-calc-req-required-fields} ================================================================================================== Use these fields to perform a tax calculation. billTo_city : billTo_country : billTo_postalCode : billTo_state : item_#_unitPrice : merchantReferenceCode : taxService_nexus : If you include this field, do not include the taxInformation.noNexus field. taxService_noNexus : If you include this field, do not include the taxInformation.Nexus field. taxService : Set to `true`. {#tax-calc-req-required-fields_dl_oss_2kh_vwb} Optional Fields for a Tax Calculation Using the SO API {#tax-calc-req-opt-fields} ================================================================================= Use these optional fields to perform a tax calculation. item_#_taxAmount : Example: Processing a Tax Calculation Using the SO API {#tax-calc-req-ex-so} ============================================================================ Request ``` taxService_run=true billTo_street1=123 Main Street billTo_city=Small Town billTo_country=US billTo_state=CA billTo_postalCode=98765 purchaseTotals_currency=USD merchantID=infodev merchantReferenceCode=482046C3A7E94F5 item_0_unitPrice=1200 item_0_quantity=1 item_0_productCode=50161815 item_0_productName=Chewing Gum item_0_productSKU=07-12-00657 item_1_unitPrice=1240 item_1_quantity=1 item_1_productCode=50181905 item_1_productName=Sugar Cookies item_1_productSKU=07-12-00659 ``` Response ``` merchantReferenceCode=482046C3A7E94F5 requestID=4817605701820004775333 decision=ACCEPT reasonCode=100 purchaseTotals_currency=USD taxReply_totalCountryTaxAmount=0.00 taxReply_reasonCode=100 taxReply_totalSpecialTaxAmount=73.20 taxReply_totalTaxableAmount=2440.00 taxReply_totalStateTaxAmount=152.50 taxReply_totalExemptAmount=0.00 taxReply_grandTotalAmount=2671.80 taxReply_totalCityTaxAmount=0.00 taxReply_totalTaxAmount=231.80 taxReply_item_0_taxableAmount=1200.00 taxReply_item_0_exemptAmount=0.00 taxReply_item_0_specialTaxAmount=36.00 taxReply_item_0_cityTaxAmount=0.00 taxReply_item_0_countyTaxAmount=3.00 taxReply_item_0_stateTaxAmount=75.00 taxReply_item_0_countryTaxAmount=0.00 taxReply_item_0_totalTaxAmount=114.00 taxReply_item_0_jurisdiction_0_country=US taxReply_item_0_jurisdiction_0_region=CA taxReply_item_0_jurisdiction_0_type=State taxReply_item_0_jurisdiction_0_code=06 taxReply_item_0_jurisdiction_0_taxable=1200.00 taxReply_item_0_jurisdiction_0_rate=0.062500 taxReply_item_0_jurisdiction_0_taxAmount=75.00 taxReply_item_0_jurisdiction_0_name=CALIFORNIA taxReply_item_0_jurisdiction_0_taxName=CA STATE TAX taxReply_item_0_jurisdiction_1_country=US taxReply_item_0_jurisdiction_1_region=CA taxReply_item_0_jurisdiction_1_type=County taxReply_item_0_jurisdiction_1_code=001 taxReply_item_0_jurisdiction_1_taxable=1200.00 taxReply_item_0_jurisdiction_1_rate=0.002500 taxReply_item_0_jurisdiction_1_taxAmount=3.00 taxReply_item_0_jurisdiction_1_name=ALAMEDA taxReply_item_0_jurisdiction_1_taxName=CA COUNTY TAX taxReply_item_0_jurisdiction_2_country=US taxReply_item_0_jurisdiction_2_region=CA taxReply_item_0_jurisdiction_2_type=Special taxReply_item_0_jurisdiction_2_code=EMAK0 taxReply_item_0_jurisdiction_2_taxable=1200.00 taxReply_item_0_jurisdiction_2_rate=0.020000 taxReply_item_0_jurisdiction_2_taxAmount=24.00 taxReply_item_0_jurisdiction_2_name=ALAMEDA COUNTY DISTRICT TAX SP taxReply_item_0_jurisdiction_2_taxName=CA SPECIAL TAX taxReply_item_0_jurisdiction_3_country=US taxReply_item_0_jurisdiction_3_region=CA taxReply_item_0_jurisdiction_3_type=Special taxReply_item_0_jurisdiction_3_code=EMSJ0 taxReply_item_0_jurisdiction_3_taxable=1200.00 taxReply_item_0_jurisdiction_3_rate=0.010000 taxReply_item_0_jurisdiction_3_taxAmount=12.00 taxReply_item_0_jurisdiction_3_name=ALAMEDA CO LOCAL TAX SL taxReply_item_0_jurisdiction_3_taxName=CA SPECIAL TAX taxReply_item_1_taxableAmount=1240.00 taxReply_item_1_exemptAmount=0.00 taxReply_item_1_specialTaxAmount=37.20 taxReply_item_1_cityTaxAmount=0.00 taxReply_item_1_countyTaxAmount=3.10 taxReply_item_1_stateTaxAmount=77.50 taxReply_item_1_countryTaxAmount=0.00 taxReply_item_1_totalTaxAmount=117.80 taxReply_item_1_jurisdiction_0_country=US taxReply_item_1_jurisdiction_0_region=CA taxReply_item_1_jurisdiction_0_type=State taxReply_item_1_jurisdiction_0_code=06 taxReply_item_1_jurisdiction_0_taxable=1240.00 taxReply_item_1_jurisdiction_0_rate=0.062500 taxReply_item_1_jurisdiction_0_taxAmount=77.50 taxReply_item_1_jurisdiction_0_name=CALIFORNIA taxReply_item_1_jurisdiction_0_taxName=CA STATE TAX taxReply_item_1_jurisdiction_1_country=US taxReply_item_1_jurisdiction_1_region=CA taxReply_item_1_jurisdiction_1_type=County taxReply_item_1_jurisdiction_1_code=001 taxReply_item_1_jurisdiction_1_taxable=1240.00 taxReply_item_1_jurisdiction_1_rate=0.002500 taxReply_item_1_jurisdiction_1_taxAmount=3.10 taxReply_item_1_jurisdiction_1_name=ALAMEDA taxReply_item_1_jurisdiction_1_taxName=CA COUNTY TAX taxReply_item_1_jurisdiction_2_country=US taxReply_item_1_jurisdiction_2_region=CA taxReply_item_1_jurisdiction_2_type=Special taxReply_item_1_jurisdiction_2_code=EMAK0 taxReply_item_1_jurisdiction_2_taxable=1240.00 taxReply_item_1_jurisdiction_2_rate=0.020000 taxReply_item_1_jurisdiction_2_taxAmount=24.80 taxReply_item_1_jurisdiction_2_name=ALAMEDA COUNTY DISTRICT TAX SP taxReply_item_1_jurisdiction_2_taxName=CA SPECIAL TAX taxReply_item_1_jurisdiction_3_country=US taxReply_item_1_jurisdiction_3_region=CA taxReply_item_1_jurisdiction_3_type=Special taxReply_item_1_jurisdiction_3_code=EMSJ0 taxReply_item_1_jurisdiction_3_taxable=1240.00 taxReply_item_1_jurisdiction_3_rate=0.010000 taxReply_item_1_jurisdiction_3_taxAmount=12.40 taxReply_item_1_jurisdiction_3_name=ALAMEDA CO LOCAL TAX SL taxReply_item_1_jurisdiction_3_taxName=CA SPECIAL TAX ``` International Taxes and Value-Added Tax (VAT) Calculation {#tax-overview-intl-vat-descr} ======================================================================================== International taxes are calculated for countries other than the US Specifically, some countries have a VAT, which is sales tax chargeable on most goods and services. A VAT seller registration number is assigned to sellers and required to calculate international taxes in most countries. International and VAT calculation is supported in specific countries. See [Supported Countries and Regions](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-info-supported-country-regions.md ""). When you request the tax service and the product is being shipped to or consumed in one of the following countries, tax is calculated by default. The seller registration number is not required in order to calculate tax in these locations: * Canada * China * Congo, Republic of the * Congo, the Democratic Republic of the * Lake Lugano, Territorial Waters of * Lao People's Democratic Republic * Macedonia, Republic of North * South Georgia and the South Sandwich Islands * United Kingdom * United States Calculating International Tax and VAT {#tax-request-calculating-international-tax-vat} ====================================================================================== Before calculating international tax, make sure that the country is on the list of [Supported Countries and Regions](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-info-supported-country-regions.md ""). > One tax service request should not include more than 50 line items. When you send a request with more than 50 line items, the request could time out. VAT Number ---------- When you include the or field and VAT rules and rates are applicable, the service calculates a VAT tax, and the relevant tax amounts are returned in the response. There are some countries where VAT registration is not required. More details are mentioned in [Supported Countries and Regions](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-info-supported-country-regions.md ""). Product Codes ------------- If a product is subject to special tax considerations, provide the appropriate tax product code in the field in the request. To use a product code that is not listed in the available guides, contact customer support for information about how to proceed. Tax Per Item ------------ When the tax calculation service succeeds, the response includes a tax amount for each item and indicates whether the tax amount was calculated by the tax calculation service or provided by you. Endpoint {#tax-request-calculating-international-tax-vat_tax-endpoint} ---------------------------------------------------------------------- Set the `taxService` field to `true`. Send the request to `https://ics2ws.ic3.com/commerce/1.x/transactionProcessor`. Required Fields for an International Tax and VAT Calculation Using the `Simple Order API` {#tax-calc-req-int-required-fields} ============================================================================================================================= Use these fields to perform a tax calculation. billTo_country : invoiceHeader_merchantVATRegistrationNumber : item_#_unitPrice : purchaseTotals_currency : taxService : Set to `true`. {#tax-calc-req-int-required-fields_dl_hnl_pkh_vwb} Optional Fields for an International Tax and VAT Calculation Using the `Simple Order API` {#tax-calc-req-int-optional-fields} ============================================================================================================================= Select from these optional fields to perform a tax calculation. merchantReferenceCode : ccAuthReply_requestAmount : Example: Processing an International Tax Calculation Using the SO API {#tax-calc-req-int-ex-so} =============================================================================================== Request ``` billTo_country=FR invoiceHeader_merchantVATRegistrationNumber=123456789 item_#_unitPrice=1200 purchaseTotals_currency=EUR taxService=true ``` Response ``` merchantReferenceCode=482046C3A7E94F5 requestID=4817605701820004775333 decision=ACCEPT reasonCode=100 purchaseTotals_currency=EUR taxReply_totalCountryTaxAmount=0.00 taxReply_reasonCode=100 taxReply_totalSpecialTaxAmount=73.20 taxReply_totalTaxableAmount=2440.00 taxReply_totalStateTaxAmount=152.50 taxReply_totalExemptAmount=0.00 taxReply_grandTotalAmount=2671.80 taxReply_totalCityTaxAmount=0.00 taxReply_totalTaxAmount=231.80 taxReply_item_0_taxableAmount=1200.00 taxReply_item_0_exemptAmount=0.00 taxReply_item_0_specialTaxAmount=36.00 taxReply_item_0_cityTaxAmount=0.00 taxReply_item_0_countyTaxAmount=3.00 taxReply_item_0_stateTaxAmount=75.00 taxReply_item_0_countryTaxAmount=0.00 taxReply_item_0_totalTaxAmount=114.00 taxReply_item_0_jurisdiction_0_country=FR taxReply_item_0_jurisdiction_0_region=FR taxReply_item_0_jurisdiction_0_type=Country taxReply_item_0_jurisdiction_0_code=06 taxReply_item_0_jurisdiction_0_taxable=1200.00 taxReply_item_0_jurisdiction_0_rate=0.062500 taxReply_item_0_jurisdiction_0_taxAmount=75.00 taxReply_item_0_jurisdiction_0_name=FR taxReply_item_0_jurisdiction_0_taxName=FR STATE TAX taxReply_item_0_jurisdiction_1_country=FR taxReply_item_0_jurisdiction_1_region=FR taxReply_item_0_jurisdiction_1_type=Country taxReply_item_0_jurisdiction_1_code=001 taxReply_item_0_jurisdiction_1_taxable=1200.00 taxReply_item_0_jurisdiction_1_rate=0.002500 taxReply_item_0_jurisdiction_1_taxAmount=3.00 taxReply_item_0_jurisdiction_1_name=ALAMEDA taxReply_item_0_jurisdiction_1_taxName=FR COUNTY TAX taxReply_item_0_jurisdiction_2_country=FR taxReply_item_0_jurisdiction_2_region=FR taxReply_item_0_jurisdiction_2_type=Special taxReply_item_0_jurisdiction_2_code=EMAK0 taxReply_item_0_jurisdiction_2_taxable=1200.00 taxReply_item_0_jurisdiction_2_rate=0.020000 taxReply_item_0_jurisdiction_2_taxAmount=24.00 taxReply_item_0_jurisdiction_2_name=ALAMEDA COUNTY DISTRICT TAX SP taxReply_item_0_jurisdiction_2_taxName=FR SPECIAL TAX taxReply_item_0_jurisdiction_3_country=FR taxReply_item_0_jurisdiction_3_region=FR taxReply_item_0_jurisdiction_3_type=Special taxReply_item_0_jurisdiction_3_code=EMSJ0 taxReply_item_0_jurisdiction_3_taxable=1200.00 taxReply_item_0_jurisdiction_3_rate=0.010000 taxReply_item_0_jurisdiction_3_taxAmount=12.00 taxReply_item_0_jurisdiction_3_name=ALAMEDA CO LOCAL TAX SL taxReply_item_0_jurisdiction_3_taxName=FR SPECIAL TAX ``` Tax Reporting {#concept_grm_2ks_lvb} ==================================== The tax reporting features are available for businesses who use the `Cybersource` Tax Calculation service. These features are used to populate the Tax Detail Report for tax reporting and reconciliation. They have no impact on the payment transactions. Tax Reporting features include these services: * [Commit Tax Calculation](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-reporting-intro/tax-com-call-intro.md "") * [Refund Tax Calculation](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-reporting-intro/tax-calc-refund-intro.md "") * [Void Tax Calculation](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-reporting-intro/tax-void-intro.md "") {#concept_grm_2ks_lvb_ul_ksx_k31_mvb} One tax service request should not include more than 50 line items. When you send a request with more than 50 line items, the request could time out. Commit Tax Calculation {#tax-com-call-intro} ============================================ Commit a tax calculation to indicate in the Tax Detail Report that the calculated tax amount in the tax request was added to a successful capture or refund transaction. Tax Detail Report ----------------- The commit request will set the Status field in the Tax Detail Report to Committed. Commit Tax Calculation Scenarios {#tax-scenario-com-intro} ========================================================== You can commit tax calculation requests at different moments in a transaction. Use these scenario examples to determine when it would be best for you to commit a tax calculation. Possible scenarios: * [Scenario 1: Pre-authorization](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-reporting-intro/tax-com-call-intro/tax-scenario-com-intro/tax-scenario-com-one.md "") * [Scenario 2: Post-capture](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-reporting-intro/tax-com-call-intro/tax-scenario-com-intro/tax-scenario-com-two.md "") * [Scenario 3: Partial Captures](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-reporting-intro/tax-com-call-intro/tax-scenario-com-intro/tax-scenario-com-three.md "") {#tax-scenario-com-intro_ul_tvk_gn3_vwb} Scenario 1: Pre-authorization {#tax-scenario-com-one} ===================================================== You can commit a tax calculation request before requesting an authorization. For example: 1. Request the tax calculation service with the taxService_commitIndicator field set to `true`.{#tax-scenario-com-one_step1} {#tax-scenario-com-one_step1} 2. Authorize and capture payment.{#tax-scenario-com-one_step2} {#tax-scenario-com-one_step2} 3. If the authorization or capture fails, void the previously committed tax calculation request. See [Void Tax Calculation](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-reporting-intro/tax-void-intro.md "").{#tax-scenario-com-one_step3} {#tax-scenario-com-one_step3} {#tax-scenario-com-one_steps-commit} Scenario 2: Post-capture {#tax-scenario-com-two} ================================================ You can commit a tax request after a capture. If you implement the tax service in this way, you will have to request the tax calculation service at least twice per request. For example: 1. Request the tax calculation service with the commit indicator field set to taxService_commitIndicator set to `false`. 2. Authorize and capture the payment. 3. If the authorization and capture are successful, request the tax calculation service with the taxService_commitIndicator set to `true`. Scenario 3: Partial Captures {#tax-scenario-com-three} ====================================================== You can commit a tax request for partial captures. For example: 1. Request the tax calculation service with the commit indicator field set to taxService_commitIndicator set to `false`. 2. Authorize the payment for $0 or wait to authorize partial payments as items are transferred to the customer. 3. Implement [Scenario 1](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-reporting-intro/tax-com-call-intro/tax-scenario-com-intro/tax-scenario-com-one.md "") or [Scenario 2](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-reporting-intro/tax-com-call-intro/tax-scenario-com-intro/tax-scenario-com-two.md "") as you make authorizations and captures. US and Canada Tax Commit {#tax-request-calculating-uscan} ========================================================= This section shows the fields necessary to commit US and Canadian tax calculation. To commit a tax calculation, include the taxService_commitIndicator field set to `true` in a tax calculation request. Endpoint {#tax-request-calculating-uscan_tax-endpoint} ------------------------------------------------------ Set the `taxService` field to `true`. Send the request to `https://ics2ws.ic3.com/commerce/1.x/transactionProcessor`. Required Fields for a Committed Tax Request Using the SO API {#tax-com-call-required-fields} ============================================================================================ Use these fields to perform a committed tax request. billTo_country : billTo_city : billTo_postalCode : billTo_state : item_#_unitPrice : merchantReferenceCode : taxService_commitIndicator : Set to `true`. taxService_nexus : If you include this field, do not include the taxService.noNexus field. taxService_noNexus : If you include this field, do not include the taxService.Nexus field. Optional Fields for a Committed Tax Request Using the SO API {#tax-com-call-optional-fields} ============================================================================================ Select from these optional fields to commit a tax request. item_#_unitPrice : merchantReferenceCode : taxService_commitIndicator : Set field to `true` to commit tax calculation. Example: Processing a Committed Tax Request Using the SO API {#tax-com-call-ex-so} ================================================================================== Request ``` taxService_run=true billTo_street1=123 Main St. billTo_city=Small Town billTo_country=us billTo_state=ca billTo_postalCode=98765 purchaseTotals_currency=usd merchantID=infodev merchantReferenceCode=TAX_TC097 item_0_unitPrice=1200 item_0_quantity=1 item_0_productCode=50161815 item_0_productName=Chewing Gum item_0_productSKU=07-12-00657 item_1_unitPrice=1240 item_1_quantity=1 item_1_productCode=50181905 item_1_productName=Sugar Cookies item_1_productSKU=07-12-00657 taxService_commitIndicator=true ``` Response ``` taxReply_totalCountryTaxAmount=0.00 taxReply_reasonCode=100 taxReply_totalSpecialTaxAmount=0.00 taxReply_totalTaxableAmount=0.00 purchaseTotals_currency=usd taxReply_totalStateTaxAmount=0.00 taxReply_totalExemptAmount=2440.00 taxReply_commitIndicator=true taxReply_grandTotalAmount=2440.00 taxReply_totalCityTaxAmount=0.00 taxReply_totalTaxAmount=0.00 decision=ACCEPT taxReply_totalCountyTaxAmount=0.00 merchantReferenceCode=TAX_TC097 reasonCode=100 requestID=5244716855106000201086 taxReply_item_0_taxableAmount=0.00 taxReply_item_0_exemptAmount=1200.00 taxReply_item_0_specialTaxAmount=0.00 taxReply_item_0_cityTaxAmount=0.00 taxReply_item_0_countyTaxAmount=0.00 taxReply_item_0_stateTaxAmount=0.00 taxReply_item_0_countryTaxAmount=0.00 taxReply_item_0_totalTaxAmount=0.00 taxReply_item_0_jurisdiction_0_country=US taxReply_item_0_jurisdiction_0_region=CA taxReply_item_0_jurisdiction_0_type=State taxReply_item_0_jurisdiction_0_code=06 taxReply_item_0_jurisdiction_0_taxable=0.00 taxReply_item_0_jurisdiction_0_rate=0.060000 taxReply_item_0_jurisdiction_0_taxAmount=0.00 taxReply_item_0_jurisdiction_0_name=CALIFORNIA taxReply_item_0_jurisdiction_0_taxName=CA STATE TAX taxReply_item_0_jurisdiction_1_country=US taxReply_item_0_jurisdiction_1_region=CA taxReply_item_0_jurisdiction_1_type=County taxReply_item_0_jurisdiction_1_code=001 taxReply_item_0_jurisdiction_1_taxable=0.00 taxReply_item_0_jurisdiction_1_rate=0.002500 taxReply_item_0_jurisdiction_1_taxAmount=0.00 taxReply_item_0_jurisdiction_1_name=ALAMEDA taxReply_item_0_jurisdiction_1_taxName=CA COUNTY TAX taxReply_item_0_jurisdiction_2_country=US taxReply_item_0_jurisdiction_2_region=CA taxReply_item_0_jurisdiction_2_type=Special taxReply_item_0_jurisdiction_2_code=EMAK0 taxReply_item_0_jurisdiction_2_taxable=0.00 taxReply_item_0_jurisdiction_2_rate=0.020000 taxReply_item_0_jurisdiction_2_taxAmount=0.00 taxReply_item_0_jurisdiction_2_name=ALAMEDA COUNTY DISTRICT TAX SP taxReply_item_0_jurisdiction_2_taxName=CA SPECIAL TAX taxReply_item_0_jurisdiction_3_country=US taxReply_item_0_jurisdiction_3_region=CA taxReply_item_0_jurisdiction_3_type=Special taxReply_item_0_jurisdiction_3_code=EMSJ0 taxReply_item_0_jurisdiction_3_taxable=0.00 taxReply_item_0_jurisdiction_3_rate=0.010000 taxReply_item_0_jurisdiction_3_taxAmount=0.00 taxReply_item_0_jurisdiction_3_name=ALAMEDA CO LOCAL TAX SL taxReply_item_0_jurisdiction_3_taxName=CA SPECIAL TAX taxReply_item_1_taxableAmount=0.00 taxReply_item_1_exemptAmount=1240.00 taxReply_item_1_specialTaxAmount=0.00 taxReply_item_1_cityTaxAmount=0.00 taxReply_item_1_countyTaxAmount=0.00 taxReply_item_1_stateTaxAmount=0.00 taxReply_item_1_countryTaxAmount=0.00 taxReply_item_1_totalTaxAmount=0.00 taxReply_item_1_jurisdiction_0_country=US taxReply_item_1_jurisdiction_0_region=CA taxReply_item_1_jurisdiction_0_type=State taxReply_item_1_jurisdiction_0_code=06 taxReply_item_1_jurisdiction_0_taxable=0.00 taxReply_item_1_jurisdiction_0_rate=0.060000 taxReply_item_1_jurisdiction_0_taxAmount=0.00 taxReply_item_1_jurisdiction_0_name=CALIFORNIA taxReply_item_1_jurisdiction_0_taxName=CA STATE TAX taxReply_item_1_jurisdiction_1_country=US taxReply_item_1_jurisdiction_1_region=CA taxReply_item_1_jurisdiction_1_type=County taxReply_item_1_jurisdiction_1_code=001 taxReply_item_1_jurisdiction_1_taxable=0.00 taxReply_item_1_jurisdiction_1_rate=0.002500 taxReply_item_1_jurisdiction_1_taxAmount=0.00 taxReply_item_1_jurisdiction_1_name=ALAMEDA taxReply_item_1_jurisdiction_1_taxName=CA COUNTY TAX taxReply_item_1_jurisdiction_2_country=US taxReply_item_1_jurisdiction_2_region=CA taxReply_item_1_jurisdiction_2_type=Special taxReply_item_1_jurisdiction_2_code=EMAK0 taxReply_item_1_jurisdiction_2_taxable=0.00 taxReply_item_1_jurisdiction_2_rate=0.020000 taxReply_item_1_jurisdiction_2_taxAmount=0.00 taxReply_item_1_jurisdiction_2_name=ALAMEDA COUNTY DISTRICT TAX SP taxReply_item_1_jurisdiction_2_taxName=CA SPECIAL TAX taxReply_item_1_jurisdiction_3_country=US taxReply_item_1_jurisdiction_3_region=CA taxReply_item_1_jurisdiction_3_type=Special taxReply_item_1_jurisdiction_3_code=EMSJ0 taxReply_item_1_jurisdiction_3_taxable=0.00 taxReply_item_1_jurisdiction_3_rate=0.010000 taxReply_item_1_jurisdiction_3_taxAmount=0.00 taxReply_item_1_jurisdiction_3_name=ALAMEDA CO LOCAL TAX SL taxReply_item_1_jurisdiction_3_taxName=CA SPECIAL TAX ``` International Tax and VAT Committed Tax Calculation {#tax-com-call-int-intro} ============================================================================= Use a committed tax calculation to include the owed tax amount with a capture. To commit a tax calculation, include the taxService_commitIndicator field set to `true` in a tax calculation request. Endpoint {#tax-com-call-int-intro_tax-endpoint} ----------------------------------------------- Set the `taxService` field to `true`. Send the request to `https://ics2ws.ic3.com/commerce/1.x/transactionProcessor`. Required Fields for an International Tax and VAT Committed Tax Calculation Using the SO API {#tax-com-call-int-required-fields} =============================================================================================================================== Use these fields to perform a committed tax request. billTo_country : ccAuthReply_requestAmount : invoiceHeader_merchantVATRegistrationNumber : merchantReferenceCode : taxService_commitIndicator : Set to `true`. taxService : Set to `true`. {#tax-com-call-int-required-fields_dl_j4z_clh_vwb} Optional Fields for an International Tax and VAT Committed Tax Calculation Using the SO API {#tax-com-call-int-optional-fields} =============================================================================================================================== Use these fields to perform a committed tax request. billTo_country : ccAuthReply_requestAmount : invoiceHeader_merchantVATRegistrationNumber : merchantReferenceCode : taxService_commitIndicator : Example: Processing an International Tax and VAT Committed Tax Calculation Using the SO API {#tax-com-call-int-ex-so} ===================================================================================================================== Request ``` billTo_country=FR invoiceHeader_merchantVATRegistrationNumber=123456789 item_#_unitPrice=1200 purchaseTotals_currency=EUR taxService=true taxService_commitIndicator=true ``` Response ``` merchantReferenceCode=482046C3A7E94F5 requestID=4817605701820004775333 decision=ACCEPT reasonCode=100 purchaseTotals_currency=EUR taxReply_totalCountryTaxAmount=0.00 taxReply_reasonCode=100 taxReply_totalSpecialTaxAmount=73.20 taxReply_totalTaxableAmount=2440.00 taxReply_totalStateTaxAmount=152.50 taxReply_totalExemptAmount=0.00 taxReply_grandTotalAmount=2671.80 taxReply_totalCityTaxAmount=0.00 taxReply_totalTaxAmount=231.80 taxReply_item_0_taxableAmount=1200.00 taxReply_item_0_exemptAmount=0.00 taxReply_item_0_specialTaxAmount=36.00 taxReply_item_0_cityTaxAmount=0.00 taxReply_item_0_countyTaxAmount=3.00 taxReply_item_0_stateTaxAmount=75.00 taxReply_item_0_countryTaxAmount=0.00 taxReply_item_0_totalTaxAmount=114.00 taxReply_item_0_jurisdiction_0_country=FR taxReply_item_0_jurisdiction_0_region=FR taxReply_item_0_jurisdiction_0_type=Country taxReply_item_0_jurisdiction_0_code=06 taxReply_item_0_jurisdiction_0_taxable=1200.00 taxReply_item_0_jurisdiction_0_rate=0.062500 taxReply_item_0_jurisdiction_0_taxAmount=75.00 taxReply_item_0_jurisdiction_0_name=FR taxReply_item_0_jurisdiction_0_taxName=FR STATE TAX taxReply_item_0_jurisdiction_1_country=FR taxReply_item_0_jurisdiction_1_region=FR taxReply_item_0_jurisdiction_1_type=Country taxReply_item_0_jurisdiction_1_code=001 taxReply_item_0_jurisdiction_1_taxable=1200.00 taxReply_item_0_jurisdiction_1_rate=0.002500 taxReply_item_0_jurisdiction_1_taxAmount=3.00 taxReply_item_0_jurisdiction_1_name=ALAMEDA taxReply_item_0_jurisdiction_1_taxName=FR COUNTY TAX taxReply_item_0_jurisdiction_2_country=FR taxReply_item_0_jurisdiction_2_region=FR taxReply_item_0_jurisdiction_2_type=Special taxReply_item_0_jurisdiction_2_code=EMAK0 taxReply_item_0_jurisdiction_2_taxable=1200.00 taxReply_item_0_jurisdiction_2_rate=0.020000 taxReply_item_0_jurisdiction_2_taxAmount=24.00 taxReply_item_0_jurisdiction_2_name=ALAMEDA COUNTY DISTRICT TAX SP taxReply_item_0_jurisdiction_2_taxName=FR SPECIAL TAX taxReply_item_0_jurisdiction_3_country=FR taxReply_item_0_jurisdiction_3_region=FR taxReply_item_0_jurisdiction_3_type=Special taxReply_item_0_jurisdiction_3_code=EMSJ0 taxReply_item_0_jurisdiction_3_taxable=1200.00 taxReply_item_0_jurisdiction_3_rate=0.010000 taxReply_item_0_jurisdiction_3_taxAmount=12.00 taxReply_item_0_jurisdiction_3_name=ALAMEDA CO LOCAL TAX SL taxReply_item_0_jurisdiction_3_taxName=FR SPECIAL TAX ``` Refund Tax Calculation {#tax-calc-refund-intro} =============================================== A refund tax calculation is a request that sets the transaction type field in the Tax Detail Report to refunded and makes the reported amount negative. Tax amounts are returned as positive amounts in response messages, but they are saved in reports as negative amounts. The tax software enables you to accurately calculate the aggregate amounts. You can also commit a refund tax calculation to include the refunded tax amount with a payment refund. Tax Detail Report ----------------- The refund request will set the Transaction Type field to Refund in the Tax Detail Report and will make the value of the Tax Amount negative. Fields specific to this Use Case -------------------------------- Include the following information with a standard refund tax calculation request when you want to include the refund request to your Tax Detail Report: * To commit a tax calculation refund request, set the taxService_refundIndicator field to `true`. * To apply the same rate from the day of the original transaction, set the invoiceHeader_invoiceDate field to the original transaction date. {#tax-calc-refund-intro_ul_sxk_l4t_lvb} Endpoint {#tax-calc-refund-intro_tax-endpoint} ---------------------------------------------- Set the `taxService_refundIndicator` field to `true`. Send the request to `https://ics2ws.ic3.com/commerce/1.x/transactionProcessor`. Refund Tax Calculation Scenarios {#tax-scenario-refund-intro} ============================================================= You can report a refund tax calculation at different moments in a transaction. Use these scenario examples to determine when you should report refund a tax calculation. Possible scenarios: * [Scenario 1: Full or Partial Refund](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-reporting-intro/tax-calc-refund-intro/tax-scenario-refund-intro/tax-scenario-com-refund-one.md "") * [Scenario 2: Stand-alone Credit](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-reporting-intro/tax-calc-refund-intro/tax-scenario-refund-intro/tax-scenario-com-refund-two.md "") {#tax-scenario-refund-intro_ul_xxh_ph3_vwb} Scenario 1: Full or Partial Refund {#tax-scenario-com-refund-one} ================================================================= You can refund a tax calculation request before requesting an authorization if you have access to the original transaction data. For example: 1. Refund the full or partial amount of the original transaction. 2. If the refund is successful, request the tax calculation service for the refunded item(s) and include the refund indicator by using the taxService_refundIndicator field set to `true`. Scenario 2: Stand-alone Credit {#tax-scenario-com-refund-two} ============================================================= You can credit a transaction if you do not have access to the original transaction data. For example: 1. Request the tax service with the taxService_refundIndicator field set to `true`.{#tax-scenario-com-refund-two_step1} {#tax-scenario-com-refund-two_step1} 2. Credit the payment.{#tax-scenario-com-refund-two_step2} {#tax-scenario-com-refund-two_step2} {#tax-scenario-com-refund-two_steps-refund} You can include the commit indicator by setting the field to to indicate the credit was successfully processed in the Tax Detail Report. The commit indicator can also be sent during the first tax service request, such as [Scenario 1](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-reporting-intro/tax-com-call-intro/tax-scenario-com-intro/tax-scenario-com-one.md ""), or in subsequent tax service requests, such as [Scenario 2](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-reporting-intro/tax-com-call-intro/tax-scenario-com-intro/tax-scenario-com-two.md ""). If the credit fails, void the previously committed tax service request. See [Void Tax Calculation](/docs/cybs/en-us/tax-calculation/developer/all/so/tax-calculation/tax-reporting-intro/tax-void-intro.md ""). Required Fields for a Tax Refund Calculation Using the SO API {#tax-calc-refund-required-fields} ================================================================================================ Use these fields to perform a tax refund calculation. billTo_city : billTo_country : billTo_postalCode : billTo_state : invoiceHeader_invoiceDate : Set this field to original transaction date. item_#_unitPrice : merchantReferenceCode : taxService_nexus : If you include this field, do not include the taxService_noNexus field. taxService_noNexus : If you include this field, do not include the taxService_nexus field. taxService_refundIndicator : Set the value of this field to `true`. {#tax-calc-refund-required-fields_dl_l4x_2qh_vwb} Example: Processing a Tax Refund Calculation Using the SO API {#tax-calc-refund-ex-so} ====================================================================================== Request ``` purchaseTotals_currency=usd merchantID=infodev merchantReferenceCode=TAX_TC097 item_0_unitPrice=1200 item_0_quantity=1 item_0_productCode=50161815 item_0_productName=Chewing Gum item_0_productSKU=07-12-00657 item_1_unitPrice=1240 item_1_quantity=1 item_1_productCode=50181905 item_1_productName=Sugar Cookies item_1_productSKU=07-12-00657 taxService_refundIndicator=true ``` Response ``` taxReply_totalCountryTaxAmount=0.00 taxReply_reasonCode=100 taxReply_totalSpecialTaxAmount=0.00 taxReply_totalTaxableAmount=0.00 purchaseTotals_currency=usd taxReply_totalStateTaxAmount=0.00 taxReply_totalExemptAmount=2440.00 taxReply_refundIndicator=true taxReply_grandTotalAmount=2440.00 taxReply_totalCityTaxAmount=0.00 taxReply_totalTaxAmount=0.00 decision=ACCEPT taxReply_totalCountyTaxAmount=0.00 merchantReferenceCode=TAX_TC097 reasonCode=100 requestID=5244716855106000201086 taxReply_item_0_taxableAmount=0.00 taxReply_item_0_exemptAmount=1200.00 taxReply_item_0_specialTaxAmount=0.00 taxReply_item_0_cityTaxAmount=0.00 taxReply_item_0_countyTaxAmount=0.00 taxReply_item_0_stateTaxAmount=0.00 taxReply_item_0_countryTaxAmount=0.00 taxReply_item_0_totalTaxAmount=0.00 taxReply_item_0_jurisdiction_0_country=US taxReply_item_0_jurisdiction_0_region=CA taxReply_item_0_jurisdiction_0_type=State taxReply_item_0_jurisdiction_0_code=06 taxReply_item_0_jurisdiction_0_taxable=0.00 taxReply_item_0_jurisdiction_0_rate=0.060000 taxReply_item_0_jurisdiction_0_taxAmount=0.00 taxReply_item_0_jurisdiction_0_name=CALIFORNIA taxReply_item_0_jurisdiction_0_taxName=CA STATE TAX taxReply_item_0_jurisdiction_1_country=US taxReply_item_0_jurisdiction_1_region=CA taxReply_item_0_jurisdiction_1_type=County taxReply_item_0_jurisdiction_1_code=001 taxReply_item_0_jurisdiction_1_taxable=0.00 taxReply_item_0_jurisdiction_1_rate=0.002500 taxReply_item_0_jurisdiction_1_taxAmount=0.00 taxReply_item_0_jurisdiction_1_name=ALAMEDA taxReply_item_0_jurisdiction_1_taxName=CA COUNTY TAX taxReply_item_0_jurisdiction_2_country=US taxReply_item_0_jurisdiction_2_region=CA taxReply_item_0_jurisdiction_2_type=Special taxReply_item_0_jurisdiction_2_code=EMAK0 taxReply_item_0_jurisdiction_2_taxable=0.00 taxReply_item_0_jurisdiction_2_rate=0.020000 taxReply_item_0_jurisdiction_2_taxAmount=0.00 taxReply_item_0_jurisdiction_2_name=ALAMEDA COUNTY DISTRICT TAX SP taxReply_item_0_jurisdiction_2_taxName=CA SPECIAL TAX taxReply_item_0_jurisdiction_3_country=US taxReply_item_0_jurisdiction_3_region=CA taxReply_item_0_jurisdiction_3_type=Special taxReply_item_0_jurisdiction_3_code=EMSJ0 taxReply_item_0_jurisdiction_3_taxable=0.00 taxReply_item_0_jurisdiction_3_rate=0.010000 taxReply_item_0_jurisdiction_3_taxAmount=0.00 taxReply_item_0_jurisdiction_3_name=ALAMEDA CO LOCAL TAX SL taxReply_item_0_jurisdiction_3_taxName=CA SPECIAL TAX taxReply_item_1_taxableAmount=0.00 taxReply_item_1_exemptAmount=1240.00 taxReply_item_1_specialTaxAmount=0.00 taxReply_item_1_cityTaxAmount=0.00 taxReply_item_1_countyTaxAmount=0.00 taxReply_item_1_stateTaxAmount=0.00 taxReply_item_1_countryTaxAmount=0.00 taxReply_item_1_totalTaxAmount=0.00 taxReply_item_1_jurisdiction_0_country=US taxReply_item_1_jurisdiction_0_region=CA taxReply_item_1_jurisdiction_0_type=State taxReply_item_1_jurisdiction_0_code=06 taxReply_item_1_jurisdiction_0_taxable=0.00 taxReply_item_1_jurisdiction_0_rate=0.060000 taxReply_item_1_jurisdiction_0_taxAmount=0.00 taxReply_item_1_jurisdiction_0_name=CALIFORNIA taxReply_item_1_jurisdiction_0_taxName=CA STATE TAX taxReply_item_1_jurisdiction_1_country=US taxReply_item_1_jurisdiction_1_region=CA taxReply_item_1_jurisdiction_1_type=County taxReply_item_1_jurisdiction_1_code=001 taxReply_item_1_jurisdiction_1_taxable=0.00 taxReply_item_1_jurisdiction_1_rate=0.002500 taxReply_item_1_jurisdiction_1_taxAmount=0.00 taxReply_item_1_jurisdiction_1_name=ALAMEDA taxReply_item_1_jurisdiction_1_taxName=CA COUNTY TAX taxReply_item_1_jurisdiction_2_country=US taxReply_item_1_jurisdiction_2_region=CA taxReply_item_1_jurisdiction_2_type=Special taxReply_item_1_jurisdiction_2_code=EMAK0 taxReply_item_1_jurisdiction_2_taxable=0.00 taxReply_item_1_jurisdiction_2_rate=0.020000 taxReply_item_1_jurisdiction_2_taxAmount=0.00 taxReply_item_1_jurisdiction_2_name=ALAMEDA COUNTY DISTRICT TAX SP taxReply_item_1_jurisdiction_2_taxName=CA SPECIAL TAX taxReply_item_1_jurisdiction_3_country=US taxReply_item_1_jurisdiction_3_region=CA taxReply_item_1_jurisdiction_3_type=Special taxReply_item_1_jurisdiction_3_code=EMSJ0 taxReply_item_1_jurisdiction_3_taxable=0.00 taxReply_item_1_jurisdiction_3_rate=0.010000 taxReply_item_1_jurisdiction_3_taxAmount=0.00 taxReply_item_1_jurisdiction_3_name=ALAMEDA CO LOCAL TAX SL taxReply_item_1_jurisdiction_3_taxName=CA SPECIAL TAX ``` Void Tax Calculation {#tax-void-intro} ====================================== Use the void tax calculation request to indicate when a previously committed tax transaction either: * Was not successfully captured or refunded * Was successfully voided {#tax-void-intro_ul_jzv_fj5_lvb} This feature can only be used to void the full original tax service request. It cannot be used to void a single line item. Contact customer support to have your account enabled to test this feature in the `Cybersource` Developer Center. Tax Detail Report ----------------- When you void a tax calculation request, a line item is added to the Tax Detail Report with a `Cancelled` value in the Status field. The cancelled line item will have a request ID of the original committed transaction in the LinkToRequestID field. Use the value of the LinkToRequestID to identify the original tax amounts that were not successfully debited or credited from a cardholder bank account. Endpoint {#tax-void-intro_tax-endpoint} --------------------------------------- Set the `voidService_run` field to `true`. Send the request to `https://ics2ws.ic3.com/commerce/1.x/transactionProcessor`. Required Field for a Tax Void Using the SO API {#tax-void-required-fields} ========================================================================== Use these fields to perform a tax void. merchantID : merchantReferenceCode : voidService_run : Set to `true`. voidService_voidRequestID : Example: Processing a Tax Void Using the SO API {#tax-void-ex-so} ================================================================= Request ``` merchant_id=my_store_123 merchant_ref_number=ABC123 voidService_run=true void_request_id=5805137656106112903096 ``` Response ``` merchantReferenceCode=ABC123 requestID=5805137922226113003096 decision=ACCEPT reasonCode=100 voidReply_reasonCode=100 voidReply_requestDateTime=2020-01-31T23:36:32Z voidReply_amount=100.00 voidReply_currency=usd ``` Supported Countries and Regions {#tax-info-supported-country-regions} ===================================================================== |-----------------------------------------------------------------------------------------------------|----------------------------------------------| | Afghanistan | Lebanon | | Albania | Lesotho | | Algeria | Liberia | | Andorra | Libyan Arab Jamahiriya | | Angola | Liechtenstein | | Anguilla | Lithuania | | Antigua and Barbuda | Livigno | | Argentina | Luxembourg | | Armenia | Macau | | Aruba | Macedonia, the Former Yogoslav Republic of | | Australia | Madagascar | | Austria | Malawi | | Azerbaijan | Malaysia | | Bahamas | Maldives | | Bahrain | Mali | | Bangladesh | Malta | | Barbados | Marshall Islands | | Belarus | Mauritania | | Belgium | Mauritius | | Belize | Mayotte | | Benin | Mexico | | Bermuda | Micronesia | | Bhutan | Moldova | | Bolivia | Monaco | | Bosnia and Herzegovina | Mongolia | | Botswana | Montenegro | | British Indian Ocean Territory | Montserrat | | Brunei Darussalam | Morocco | | Bulgaria | Mozambique | | Burkina Faso | Myanmar | | Burundi | Namibia | | Cambodia | Nauru | | Cameroon | Nepal | | Campione D'Italia | Netherlands | | Canada | New Caledonia | | Canary Islands | New Zealand | | Cape Verde | Nicaragua | | Caribbean Netherlands (Bonaire) | Niger | | Caribbean Netherlands (Sint Eustatius and Saba) | Nigeria | | Cayman Islands | Niue | | Central African Republic | Norway | | Chad | Oman | | Chile | Pakistan | | China > Regional tax is not supported in China. Tax determination defaults to the federal tax rate. | Palau | | Christmas Island | Palestine Occupied Territory | | Cocos (Keeling) Islands | Panama | | Colombia | Papua New Guinea | | Comoros | Paraguay | | Congo, Republic of the | Peru | | Congo, The Democratic Republic of the | Philippines | | Coral Sea Islands | Pitcairn Islands | | Costa Rica | Poland | | Cote D'Ivoire | Portugal | | Croatia | Puerto Rico | | Curacao | Qatar | | Cyprus | Republic of Korea (South Korea) | | Czech Republic | Romania | | Denmark | Russian Federation | | Djibouti | Rwanda | | Dominica | Saint Helena | | Dominican Republic | Saint Kitts and Nevis | | Ecuador | Saint Lucia | | El Salvador | Saint Martin | | Equatorial Guinea | Saint Pierre and Miquelon | | Eritrea | Saint Vincent and the Grenadines | | Estonia | Samoa | | Ethiopia | San Marino | | Falkland Islands (Malvinas) | Sao Tome and Principe | | Faroe Islands | Saudi Arabia | | Fiji | Senegal | | Finland (includes Aland Island) | Serbia | | France | Seychelles | | French Guiana | Sierra Leone | | French Polynesia | Singapore | | French Southern Territories | Sint Maarten | | Gabon | Slovakia | | Gambia | Slovenia | | Georgia | Somalia | | Germany | South Africa | | Ghana | South Georgia and the South Sandwich Islands | | Gibraltar | Spain | | Greece | Sri Lanka | | Greenland | Suriname | | Grenada | Svalbard and Jan Mayen | | Guadeloupe | Swaziland | | Guam | Sweden | | Guatemala | Switzerland | | Guernsey | Taiwan | | Guinea | Tajikistan | | Guinea-Bissau | Tanzania | | Guyana | Thailand | | Haiti | Timor-Leste | | Heligoland | Togo | | Holy See | Tokelau | | Honduras | Tonga | | Hong Kong | Trinidad and Tobago | | Hungary | Tunisia | | Iceland | Turkey | | Indonesia | Turkmenistan | | Iraq | Turks and Caicos Islands | | Ireland | Tuvalu | | Israel | Uganda | | Italy | Ukraine | | Jamaica | United Arab Emirates | | Japan | United Kingdom | | Jersey | United States | | Jordan | Uruguay | | Kazakhstan | Uzbekistan | | Kenya | Vanuatu | | Kiribati | Venezuela | | Kosovo | Vietnam | | Kuwait | Virgin Islands, British | | Kyrgyzstan | Wallis and Futuna | | Lake Lugano, Territorial Waters of | Yemen | | Lao People's Democratic Republic | Zambia | | Latvia | Zimbabwe | [Supported Countries and Regions] City Abbreviations {#tax-info-city-abbrevs} =========================================== Several applications expand some commonly used city-name abbreviations, which enables the tax calculation service to correctly evaluate city names for tax purposes. The US Postal Service also maintains a list of common abbreviations. When a customer uses abbreviations not accepted by either entity, the tax calculation service might not recognize the combination of city, state, and postal code, in which case the request fails and returns a reason code of `600`. The following table provides a list of the abbreviations used by the tax calculation service and the US Postal Service. | Abbreviation | Expansion | Abbreviation | Expansion | |--------------|-------------|-----------------------------------|---------------| | bch | beach | n | north | | crk | creek | ny | new york | | cty | city | pk | park | | cyn | canyon | pkwy | parkway | | e | east | pt | point | | ft | fort | s | south | | grdn | garden | sf | san francisco | | hbr | harbor | st (only for the US country code) | saint | | hgts, hts | heights | spr | spring | | jct, jctn | junction | sprs | springs | | la | los angeles | vly | valley | | mt, mtn | mountain | w | west | [Expanded City Abbreviations]