Title Page Tax Calculation Service Using the SCMP API September 2014 CyberSource Corporation HQ P.O. Box 8999 San Francisco, CA 94128-8999 Phone: 800-530-9095
CyberSource Contact Information For general information about our company, products, and services, go to http://www.cybersource.com. For sales questions about any CyberSource Service, email sales@cybersource.com or call 650-432-7350 or 888-330-2300 (toll free in the United States). For support information about any CyberSource Service, visit the Support Center at http://www.cybersource.com/support. Copyright 2014 CyberSource Corporation. All rights reserved. CyberSource Corporation ("CyberSource") furnishes this document and the software described in this document under the applicable agreement between the reader of this document ("You") and CyberSource ("Agreement"). You may use this document and/or software only in accordance with the terms of the Agreement. Except as expressly set forth in the Agreement, the information contained in this document is subject to change without notice and therefore should not be interpreted in any way as a guarantee or warranty by CyberSource. CyberSource assumes no responsibility or liability for any errors that may appear in this document. The copyrighted software that accompanies this document is licensed to You for use only in strict accordance with the Agreement. You should read the Agreement carefully before using the software. Except as permitted by the Agreement, You may not reproduce any part of this document, store this document in a retrieval system, or transmit this document, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written consent of CyberSource. Restricted Rights Legends For Government or defense agencies. Use, duplication, or disclosure by the Government or defense agencies is subject to restrictions as set forth the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 and in similar clauses in the FAR and NASA FAR Supplement. For civilian agencies. Use, reproduction, or disclosure is subject to restrictions set forth in subparagraphs (a) through (d) of the Commercial Computer Software Restricted Rights clause at 52.227-19 and the limitations set forth in CyberSource Corporation's standard commercial agreement for this software. Unpublished rights reserved under the copyright laws of the United States. Trademarks CyberSource, The Power of Payment, CyberSource Payment Manager, CyberSource Risk Manager, CyberSource Decision Manager, CyberSource Connect, Authorize.Net, and echeck.net are trademarks and/or service marks of CyberSource Corporation. All other brands and product names are trademarks or registered trademarks of their respective owners. 2
Contents CONTENTS Recent Revisions to This Document 5 About This Guide 6 Audience and Purpose 6 Conventions 6 Note and Important Statements 6 Text and Command Conventions 7 Related Documents 7 Customer Support 7 Chapter 1 Introduction to Tax Calculation 8 Overview of Tax Calculation 8 U.S. Sales Tax and Use Tax 10 Canadian Taxes 10 International Taxes and Value Added Tax 10 One VAT Seller Registration Number 11 Multiple VAT Seller Registration Numbers 11 Planning for Tax Calculation 11 International Taxes/VAT 12 Tax Nexus 12 Product Codes 13 U.S. and Canadian Tax 13 International and VAT Tax 13 When to Perform Tax Calculation 13 Multiple Shipping Destinations in a Single Order 14 Tax Information Storage 14 Tax Consultation Services 14 Maximum Line Items 15 Tax Calculation Service Using the SCMP API September 2014 3
Contents Chapter 2 Requesting Services with the SCMP API 16 Requesting the Tax Calculation Service 16 Calculating U.S. and Canadian Tax 17 Calculating International Tax/VAT 18 Override Fields 19 Invalid Address Combination Correction 19 Displaying Separate Tax Amounts 20 Testing 20 Request and Reply Examples 20 Appendix A Fields for the SCMP API 22 Formatting Requirements 22 Data Type Definitions 22 Request-Level Fields 23 Offer-Level Fields 33 Reply Fields 39 Appendix B Reply Flags for the SCMP API 42 Appendix C Supported Countries 43 North America 43 Latin America 43 Europe, Middle East, Africa 44 Asia Pacific 45 Appendix D City Abbreviations 46 Index 47 Tax Calculation Service Using the SCMP API September 2014 4
Recent Revisions to This Document CHANGES Release September 2014 Changes Clarified the valid values you can use for the API offer-level field product_code. Use values listed in the Commodity Code column of the appropriate tax product code guide that is linked to in the field description. See product_code, page 37. April 2012 Added important legal disclaimer. "Overview of Tax Calculation," page 8. Updated the API field: seller_registration. See "Request-Level Fields," page 23, or "Offer- Level Fields," page 33. January 2012 Added the ship_from_country offer-level field. See "Offer-Level Fields," page 33. Updated the descriptions for the following request-level fields. See "Request-Level Fields," page 23. order_acceptance_county order_origin_county ship_from_county ship_to_county Updated the descriptions for the following offer-level fields. See "Offer-Level Fields," page 33. order_acceptance_county order_origin_county ship_from_county April 2011 Multiple VAT seller registration numbers are supported for each country: See "International Taxes and Value Added Tax," page 10. Updated the API field: seller_registration. See "Request-Level Fields," page 23, or "Offer- Level Fields," page 33. Added the API field: seller_registration0...n. See "Request-Level Fields," page 23 or "Offer- Level Fields," page 33. January 2011 Only one VAT seller registration number is currently supported for each country: "International Taxes and Value Added Tax," page 10. Updated the API field: seller_registration. See "Request-Level Fields," page 23, or "Offer- Level Fields," page 33. Tax Calculation Service Using the SCMP API September 2014 5
About This Guide ABOUT GUIDE Audience and Purpose This guide is written for application developers who want to use the CyberSource SCMP API to integrate tax calculation into an order management system. Implementing the CyberSource tax calculation service requires software development skills. You must write code that uses the API request and reply fields to integrate the tax calculation service into an existing order management system. Conventions Note and Important Statements Note A Note contains helpful suggestions or references to material not contained in the document. Important An Important statement contains information essential to successfully completing a task or learning a concept. Tax Calculation Service Using the SCMP API September 2014 6
About This Guide Text and Command Conventions Convention Usage bold Field and service names in text; for example: Include the ics_applications field. Items that you are instructed to act upon; for example: Click Save. monospace XML elements. Code examples and samples. Text that you enter in an API environment; for example: Set the davservice_run field to true. Related Documents The following documents provide information about processing commonly used payment types. For a list of all the documentation related for the CyberSource ICS services, see Services Documentation. Credit Card Services Using the SCMP API (PDF HTML) This guide explains how to use the CyberSource SCMP API to access the CyberSource ICS Credit Card Services. Electronic Check Services Using the SCMP API (PDF HTML) This guide describes how to process electronic check orders. Reporting Developer Guide (PDF HTML) This guide describes how to download several of the reports you will use when managing your transactions. Refer to the Support Center for complete CyberSource technical documentation: http://www.cybersource.com/support_center/support_documentation Customer Support For support information about any CyberSource service, visit the Support Center at: http://www.cybersource.com/support Tax Calculation Service Using the SCMP API September 2014 7
Introduction to Tax Calculation CHAPTER 1 Overview of Tax Calculation The tax calculation service provides real-time tax calculation for worldwide orders placed with your business. The tax calculation service enhances your ability to conduct business globally, while enabling you to avoid the risk and complexity of managing online tax calculation. IMPORTANT NOTICE FOR USERS OF CYBERSOURCE TAX SERVICES Important The tax calculation is based on the location of the customer s taxing jurisdiction, as well as the tax and product code information 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. Tax Calculation Service Using the SCMP API September 2014 8
Chapter 1 Introduction to Tax Calculation The tax calculation service determines the following types of taxes, as appropriate for a customer s order: U.S. Sales and Use taxes Canadian Goods and Services Tax (GST) Canadian Provincial Sales Tax (PST) Canadian Harmonized Sales Tax (HST) Quebec Sales Tax (QST) International (non-u.s./canadian) and Value Added Tax (VAT) Note CyberSource currently supports a maximum of 10 VAT Seller Registration Numbers. See "International Taxes and Value Added Tax," page 10. The tax calculation is based on the location of the customer s taxing jurisdiction. The order price and quantity are included in the calculation to determine the order s total tax amount. Note The tax calculation service is not recommended for merchants conducting business with countries other than the supported countries listed in Appendix C, "Supported Countries," on page 43. The tax calculation service is part of the Internet Commerce Suite SM (ICS), which includes electronic payment, fraud management, and verification services. To use the ICS services, send a request that includes information about your company, the customer, and the services you want to use. You will receive a reply with information appropriate to the services you requested. Use the reply information to interpret the results of your request. You can use the Business Center, which offers a graphical interface for various functions, including: Viewing details about your transactions, including the breakdown of the taxes for the transaction Viewing and downloading reports see Using the Reporting System Processing customers payments and credits After you register your merchant ID with CyberSource, you can use the test version of the Business Center at https://ebctest.cybersource.com. After you go live, you can also use the production version at https://ebc.cybersource.com. The username and password that you use to log in to either site is your merchant ID and the password you established when you registered the merchant ID with CyberSource. After you log in to the production or test version of the Business Center, click the Help button on any page for additional information. Tax Calculation Service Using the SCMP API September 2014 9
Chapter 1 Introduction to Tax Calculation U.S. Sales Tax and Use Tax For U.S. orders, sales tax is imposed on a transfer of property. Some states do not have sales tax. Use tax is imposed on the use of property after sale has taken place. In most states, sales and use tax rates are the same. For U.S. orders, the tax calculation service includes sales and use tax in the total tax value and breaks them down into their state, county, city, and district levels. Canadian Taxes For Canadian orders, GST is administered by the federal government and is equivalent to U.S. sales and use tax. Canadian goods and services can also be subject to certain taxes in the following provinces: PST in British Columbia, Manitoba, Saskatchewan, Ontario, and Prince Edward Island HST in New Brunswick, Nova Scotia, Newfoundland, Labrador, Ontario, and British Columbia QST in Quebec Follow the same procedures to calculate taxes for Canada as you do for the United States, taking into consideration the following points: The federal GST is processed as a state-level tax PST, HST, and QST are each processed as a county-level tax The six-character Canadian Postal Code is used Canadian dollars should be used for entering any amounts International Taxes and Value Added Tax International taxes are calculated for countries other than the U.S. Specifically, some countries have a VAT, which is sales tax chargeable on most goods and services. The VAT seller registration number may be required for some Canadian transactions. CyberSource supports international/vat calculation in the countries listed in Appendix C, "Supported Countries," on page 43. Note CyberSource currently supports a maximum of ten VAT seller registration numbers. Tax Calculation Service Using the SCMP API September 2014 10
Chapter 1 Introduction to Tax Calculation One VAT Seller Registration Number To include one VAT seller registration number in the request as a request-level field, include the seller_registration field in your request. This can be either a request-level field and/or an offer-level field. Example One VAT Seller Registration Number as a Request-Level Field seller_registration=339072747 Example One VAT Seller Registration Number as an Offer-Level Field offer0=amount:100.00^seller_registration:339072747 Multiple VAT Seller Registration Numbers To include multiple VAT seller registration numbers in the request, include the seller_ registration0 field for the first VAT seller registration number, seller_registration1 for the second, seller_registration2 for the third, and so on. These can be request-level fields, offer-level fields, or both. Example Three VAT Seller Registration Numbers as Request-Level Fields seller_registration0=339072747 seller_registration1=339072846 seller_registration2=339072945 Example Three VAT Seller Registration Numbers as Offer-Level Fields offer0=amount:100.00^seller_registration0:339072747^seller_ registration1:339072846^seller_registration2:339072945 Planning for Tax Calculation To use the tax calculation service: Determine when you will provide a tax calculation during a customer transaction. Understand and comply with sales and use tax laws in the U.S. and Canada and international/vat laws in other countries. Determine your tax nexus. See "Tax Nexus," page 12. Determine if any products require special product codes for tax purposes. See "Product Codes," page 13. Important If you want to use a product code that is not listed in the available guides, contact Customer Support for information about how to proceed. Tax Calculation Service Using the SCMP API September 2014 11
Chapter 1 Introduction to Tax Calculation International Taxes/VAT To calculate international taxes/vat: Maintain VAT seller registration for each VAT country in which you conduct business. Note CyberSource currently supports a maximum of ten VAT Seller Registration Numbers. See "International Taxes and Value Added Tax," page 10. Important The seller_registration field can be included in your request as a Request-level field and/or an Offer-level field. The seller_ registration0...n field can also be included in your request as a Requestlevel field, an Offer-level field, or both. Determine the appropriate product codes if required by the countries with which you intend to do business. See "Product Codes," page 13. Comply with any tax registration laws for the countries in which you intend to do business. Decide if you want to apply your own tax calculations for any of the products. Tax Nexus U.S. and Canadian merchants have nexus in states or provinces in which they have some form of physical presence. The physical presence requirement is satisfied if you: Maintain an office, warehouse, or other place of business within the state or province Maintain an inventory within the state or province Solicit orders in the state or province through the use of traveling sales staff Deliver goods in the state or province in your own vehicles If your office and distribution centers are in different states, then you have nexus in at least two different states. Important Products are taxable only if your customer s state matches a state in which your company has nexus. In your tax calculation service request, if you do not specify the states in which you have nexus, the tax system assumes you have nexus in every state. If you are not sure where you have substantial nexus, consult your tax advisor. Tax Calculation Service Using the SCMP API September 2014 12
Chapter 1 Introduction to Tax Calculation 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 if the product is non-taxable, or if the product has a non-standard tax rate in a certain jurisdiction. If you do not include a product code in your request, the tax calculation service assumes the product has no productbased tax exemptions and is fully taxable. U.S. 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 U.S. Tax Product Code Guide, which is available on the Support Center. For example, software that is distributed electronically is exempt from tax in many states. If you are selling electronic software and you have nexus in any of these states and you do not include a product code, the tax calculation service would incorrectly calculate tax for these states. If you want to use a product code that is not listed in the guide, contact CyberSource Customer Support for information about how to proceed. Until the product code is supported, you must submit either rate overrides or the tax amount for the product. International and VAT Tax For a list of available product codes for international taxes/vat, see the European Union Tax Product Code Guide. If you want to use a product code that is not listed in the guide, contact CyberSource Customer Support for information about how to proceed. When to Perform Tax Calculation You can calculate tax at two times during the order process: Whenever the customer prompts for a subtotal or total When the customer performs a final check out If you use only the second option, you minimize the number of transaction charges for using the tax calculation service. Tax Calculation Service Using the SCMP API September 2014 13
Chapter 1 Introduction to Tax Calculation Multiple Shipping Destinations in a Single Order You cannot specify a different shipping address for each item in an order. If the order contains multiple items that are going to different addresses, you must send a separate tax calculation service request for each item/shipping address. Tax Information Storage CyberSource does not provide tax liability reporting. It is your responsibility to determine how you store and retrieve tax liability information for tax reporting purposes. As a general business practice, keep all records of transaction activity for completing tax returns. For your own reference, consider summarizing and cross-checking transaction records by calculated tax, product code, customer ID, invoice number, or jurisdiction location. Important CyberSource does not store any portion of the tax calculation service request. You cannot obtain information from CyberSource regarding previous tax calculation transactions. It is your responsibility to store the results and report to any applicable taxing jurisdiction. Tax Consultation Services CyberSource does not provide tax consultation services. Important Due to the dynamic nature and complex intricacies of tax laws, especially at the local and municipal levels, automated tax calculation systems have inherent limitations that can affect the accuracy of returned tax rates in certain situations. Automated tax calculation systems typically rely on city, state, and postal code to determine the applicable tax rate. However, a small number of local taxing jurisdictions within the United States assess taxes based on less common jurisdictional boundary criteria, especially in unincorporated areas. For example, tax rates can vary by jurisdiction as exercised by a specific police precinct. This occurs in a very small number of cases, but you need to educate your customer service staff so they can address the issue if it arises. CyberSource strongly recommends that you consult your tax professional to make sure you are in compliance with the tax laws. Tax Calculation Service Using the SCMP API September 2014 14
Chapter 1 Introduction to Tax Calculation Maximum Line Items Each tax service request that you send to CyberSource should not include more than 50 line items. If you send a request with more than 50 line items, your service request could time out. Tax Calculation Service Using the SCMP API September 2014 15
Requesting Services with the SCMP API CHAPTER 2 Requesting the Tax Calculation Service Use the ics_tax application to request the tax calculation service. See Appendix A, "Fields for the SCMP API," on page 22 for the list of required and optional fields to include in the request. When requesting ics_tax, do not request any of the following services in the same request: Authorization reversal (ics_auth_reversal) See the Credit Card Services Using the SCMP API for more information. Risk update (ics_risk_update) See the Decision Manager Developer Guide Using the SCMP API for more information. To submit the total tax instead of having the tax calculation service calculate tax for the offer, use the tax_amount offer-level field. The tax_amount value will be returned in the tax_tax_amount0...n reply field. You cannot specify a different shipping address for each item in an order. If the order contains multiple items that are going to different addresses, you must send a separate tax calculation service request for each item/shipping address. Important CyberSource does not store any portion of the tax calculation service request. You cannot obtain information from CyberSource regarding previous tax calculation transactions. It is your responsibility to store the results and report to any applicable taxing jurisdiction. Tax Calculation Service Using the SCMP API September 2014 16
Chapter 2 Requesting Services with the SCMP API Calculating U.S. and Canadian Tax To use ics_tax to calculate tax for the U.S. or Canada: Identify where your company has nexus. Products are only taxable if your customer s ship_to_state value matches a state where your company has nexus. Use the nexus field to list the states or provinces in which your company has nexus. Or, if it is easier, use the no_nexus field to list states that should not be taxed. You cannot combine the nexus and no_nexus fields in the same request. If you do not specify where you have nexus, ics_tax assumes every state is taxable. If you do not specify where you have nexus, or if a value of the nexus field matches the value of ship_to_state, ics_tax calculates the applicable tax for the product. If the ship_to_state value does not match any state where you have nexus, ics_ tax assigns zero tax to the offer and then skips to the next offer. Determine whether the product is exempt from tax or subject to special tax considerations. See "Product Codes," page 13, for more information. If you want to use a product code that is not listed in the available guides, contact CyberSource Customer Support for information about how to proceed. Determine when you will provide tax calculations during the customer transaction. Tax calculation can occur before or after determining the final order total. To receive the most accurate tax calculation possible, include the following information in the request: Ship to address, in fields beginning with ship_to_ This is the location to which you ship the customer s order. Ship from address, in fields beginning with ship_from_ This is the location from which you ship the customer s order. Point of order origin (POO), in fields beginning with order_origin_ This is the place of business where you receive the customer s order. Point of order acceptance (POA), in fields beginning with order_acceptance_ This is the place of business where you accept/approve the customer s order, thereby becoming contractually obligated to make the sale. Product code, in the product_code field Nexus, in the nexus field or if it is easier, you can use the no_nexus field to provide a list of states where you do NOT have nexus. Tax Calculation Service Using the SCMP API September 2014 17
Chapter 2 Requesting Services with the SCMP API The point of order origin and point of order acceptance fields are particularly important for accurate tax calculation. By providing both types of fields, you allow the tax calculation service to use jurisdiction information to determine whether sales or use tax should be calculated. If you do not send the information, only sales tax is calculated. For many companies, the point of order origin and point of order acceptance are the same. Note Consult your tax advisor to determine the point or order origin and the point of order acceptance for your business. If the tax calculation service succeeds, the reply includes tax_tax_amount0...n for each line item and indicates whether CyberSource calculated the tax or you supplied the tax. The reply also includes separate state, county, city, and district tax values for each item. Note The total tax value reported can be slightly higher or lower than the correct amount because the service separately determines state, county, city, and district taxes, rounds off these values to the nearest cent, and then sums these parts to arrive at the total tax value. For example, 8.5% total tax that includes 6% state tax, 1.25% city tax, and 1.25% district tax levied on a $10 item would result in a total tax of $0.86 (not $0.85) based on amounts of $0.60 state tax, $0.13 city tax and $0.13 district tax. Calculating International Tax/VAT Before calculating international tax, make sure the country is on the list of supported countries. See "Supported Countries," page 43. International tax/vat calculation requests use several different API fields compared to U.S. tax calculation requests. Pay attention to the requirements in the Req/Opt for Intl. Tax/VAT column in "Request-Level Fields," page 23, and "Offer-Level Fields," page 33. Be sure that you determine whether the product is exempt from tax or subject to special tax considerations. If it is, provide the appropriate international tax product code in the product_code offer-level field in the request. See "Product Codes," page 13, for more information. If you want to use a product code that is not listed in the available guides, contact CyberSource Customer Support for information about how to proceed. If the tax calculation service succeeds, the reply includes tax_tax_amount0...n for each line item and indicates if CyberSource calculated the tax or you supplied the tax. Tax Calculation Service Using the SCMP API September 2014 18
Chapter 2 Requesting Services with the SCMP API Override Fields The following optional override fields allow you to replace tax rates, by percentage or amount, for transactions at any level. This is particularly helpful for backbilling after a rate change. city_override_amount country_override_amount county_override_amount state_override_amount city_override_rate country_override_rate county_override_rate state_override_rate For Canadian taxes, use the following fields to override the different tax rates: GST: country_override_amount or country_override_rate PST, HST, and QST: state_override_amount or state_override_rate Note If override_amount and override_rate fields are both supplied for the same offer, the override_rate field is ignored. Invalid Address Combination Correction The tax calculation service handles invalid address combinations of state, county, city, and postal code as long as the state and postal code combination is valid. For example, if the state and postal code are CA and 94043, the tax calculation service calculates tax for the city of Mountain View and the county of Santa Clara. If multiple cities are within a postal code area, the optional request-level field ship_to_city value improves the accuracy of the calculated tax. Note 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. Expect replies for all abbreviation possibilities when you code to these values. Tax Calculation Service Using the SCMP API September 2014 19
Chapter 2 Requesting Services with the SCMP API Displaying Separate Tax Amounts If the optional request-level field show_tax_per_offer is set to yes, then separate state, county, city, and district tax values are returned for each offer. The default value is no. Note The total tax value reported can be slightly higher or lower than the correct amount because the service separately determines state, county, city, and district taxes, rounds off these values to the nearest cent, and then sums these parts to arrive at the total tax value. For example, 8.5% total tax that includes 6% state tax, 1.25% city tax, and 1.25% district tax levied on a $10 item would result in a total tax of $0.86 (not $0.85) based on amounts of $0.60 state tax, $0.13 city tax and $0.13 district tax. Testing You can use the CyberSource test server at any time to send test tax calculation service requests. See the documentation for the CyberSource client that you are using for information about how to specify which server to use. Request and Reply Examples Example 1 Request bill_address1=1295 Charleston Rd. bill_city=mountain View bill_country=us bill_state=ca bill_zip=94043 ics_applications=ics_tax merchant_id=infodev merchant_ref_number=1564c362f3c8261a10e255def offer0=amount:100.00^merchant_product_sku:2b1079^product_ code:18902^product_name:test Product^quantity:1 Tax Calculation Service Using the SCMP API September 2014 20
Chapter 2 Requesting Services with the SCMP API Example 2 Reply client_lib_version=perl3.2/mswin324.0/nt4.0/win32/c/3.4.6 currency=usd ics_rcode=1 ics_rflag=sok ics_rmsg=request was processed successfully. merchant_ref_number=1564c362f3c8261a10e255def request_id=0341148600000167905080 tax_city_name=mountain VIEW tax_county_name=santa CLARA tax_rcode=1 tax_rflag=sok tax_rmsg=tax service was successful. tax_state_name=ca tax_zip=94043 tax_tax_amount0=8.25 tax_total_city_tax=0.00 tax_total_county_tax=1.00 tax_total_district_tax=1.00 tax_total_grand=108.25 tax_total_state_tax=6.25 tax_total_tax=8.25 Tax Calculation Service Using the SCMP API September 2014 21
Fields for the SCMP API APPENDIX A Formatting Requirements Unless otherwise noted, all of the fields listed are order and case insensitive, and the fields accept special characters, such as @, #, and %. Request-level and offer-level field names and values must not contain carets (^) or colons (:). However, they can contain embedded spaces and any other printable characters. If you use more than one consecutive space, the extra spaces will be removed. Data Type Definitions Table 1 Data Type Definitions for the SCMP API Data Type Date and time Definition The format is YYYY-MM-DDThhmmssZ. For example, 2007-08-11T224757Z is equal to August 11, 2007, at 10:47:57 P.M. The T separates the date and the time. The Z indicates Coordinated Universal Time (UTC), which is also known as Greenwich Mean Time (GMT). Decimal Number that includes a decimal point. Examples: 23.45, - 0.1, 4.0, 90809.0468. Integer Whole number {..., -3, -2, -1, 0, 1, 2, 3,...}. Non-negative integer Whole number greater than or equal to zero {0, 1, 2, 3,...}. Positive integer Whole number greater than zero {1, 2, 3,...}. String Sequence of letters, numbers, spaces, and special characters, such as @ and #. Tax Calculation Service Using the SCMP API September 2014 22
Appendix A Fields for the SCMP API Request-Level Fields Table 2 Request-Level Fields for the SCMP API Field Description Req/Opt for U.S. & Canadian Tax bill_address1 bill_address2 First line of the billing street address. In the U.S., this information can be helpful in determining the ZIP+4, which the service can use when determining tax. Second line of the billing street address. In the U.S., this information can be helpful in determining the ZIP+4, which the service can use when determining tax. Req/ Opt for Intl. Tax/VAT Data Type & Length Optional N/A String (60) Optional N/A String (60) bill_city Credit card billing city. Required (1) N/A String (50) bill_country bill_state bill_county bill_state Credit card billing country. Use the twocharacter ISO Standard Country Codes. If ship_to_country is not provided, bill_ country is used in its place. If bill_country is set to US or CA, then bill_zip and bill_state are also required. Credit card billing state or province. Use the State, Province, and Territory Codes for the United States and Canada. Billing county if the order is from the United States, or billing province if the order is from Canada. If ship_to_county is not provided, bill_county is used in its place. Credit card billing state or province. Use the State, Province, and Territory Codes for the United States and Canada. Required Required String (2) Required (1) N/A String (2) Optional N/A String (60) Required 1 N/A String (2) (1) For U.S. and Canada only (2) The field has no length limit due to the varying number of states and provinces that can be included in the list. Tax Calculation Service Using the SCMP API September 2014 23
Appendix A Fields for the SCMP API Table 2 Request-Level Fields for the SCMP API (Continued) Field Description Req/Opt for U.S. & Canadian Tax bill_zip Postal code for the billing address. The postal code must consist of 5 to 9 digits. If the billing country is the U.S., the 9-digit postal code must follow this format: [5 digits][dash][4 digits] Example:12345-6789 If the billing country is Canada, the 6-digit postal code must follow this format: [alpha][numeric][alpha] [numeric][alpha][numeric] Example: A1B 2C3 Required 1 N/A String (10) buyer_registration Buyer s VAT registration number. N/A Optional String (25) currency Currency used for the order. Use the standard ISO Standard Currency Codes. The default value is USD. Optional Required String (5) ics_applications ICS services to process for the request. Required Required String (255) invoice_date merchant_id merchant_ref_number Date of the tax calculation. Use format YYYYMMDD. You can provide a date in the past if you are calculating tax for a refund and want to know what the tax was on the date the order was placed. You can provide a date in the future if you are calculating the tax for a future date, such as an upcoming tax holiday. Note The default is the date, in Pacific time, that CyberSource receives the request. Keep this in mind if you are in a different time zone and want the tax calculated with the rates that are applicable on a specific date. Your CyberSource merchant ID. Use the same merchant_id for evaluation, testing, and production. Merchant-generated order reference or tracking number. See Getting Started with CyberSource Advanced for the SCMP API for more information. Req/ Opt for Intl. Tax/VAT Optional Optional String (8) Required Required String (30) Required Required String (50) middleman_registration Middleman s VAT registration number. N/A Optional String (25) (1) For U.S. and Canada only (2) The field has no length limit due to the varying number of states and provinces that can be included in the list. Data Type & Length Tax Calculation Service Using the SCMP API September 2014 24
Appendix A Fields for the SCMP API Table 2 Request-Level Fields for the SCMP API (Continued) Field Description Req/Opt for U.S. & Canadian Tax nexus no_nexus offer0...n order_acceptance_city order_acceptance_country Comma-separated list of states or provinces where merchandise is taxable. Do not use both the nexus and no_ nexus fields together in your request. The default value for nexus is all states. Use the State, Province, and Territory Codes for the United States and Canada. Comma-separated list of states or provinces where merchandise is not taxable. Do not use both the nexus and no_nexus fields together in your request. Use the State, Province, and Territory Codes for the United States and Canada. Offers for the request. An offer is a line item in the order. At a minimum, offer0 must be present. Order acceptance city. This field is not used unless the order_acceptance_ state and order_acceptance_country fields are present. Order acceptance country. This field is not used unless the order_acceptance_ state and order_acceptance_city fields are present. Use the two-character ISO Standard Country Codes. Either this field or no_ nexus is required if you do not have nexus in every state or province Either this field or nexus is required if you do not have nexus in every state or province Req/ Opt for Intl. Tax/VAT N/A N/A String (no limit) (2) String (no limit) (2) Required Required String (50) Optional N/A String (50) Optional N/A String (2) (1) For U.S. and Canada only (2) The field has no length limit due to the varying number of states and provinces that can be included in the list. Data Type & Length Tax Calculation Service Using the SCMP API September 2014 25
Appendix A Fields for the SCMP API Table 2 Request-Level Fields for the SCMP API (Continued) Field Description Req/Opt for U.S. & Canadian Tax order_acceptance_county order_acceptance_state order_acceptance_zip order_origin_city order_origin_country Order acceptance county. This field is forwarded to the third party tax calculation engine only if the following requirements are met: Your CyberSource account is enabled for forwarding county information. The corresponding country is the U.S. or Canada. The order_acceptance_city, order_ acceptance_state, and order_ acceptance_country fields are included in the request. Order acceptance state. This field is not used unless the order_acceptance_city and order_acceptance_country fields are present. Use the State, Province, and Territory Codes for the United States and Canada. Order acceptance postal code. This field is not used unless the order_ acceptance_city, order_acceptance_ state, and order_acceptance_country fields are present. Order origin city. This field is not used unless the order_origin_state and order_origin_country fields are present. Order origin country. This field is not used unless the order_origin_state and order_origin_city fields are present. Use the two-character ISO Standard Country Codes. Req/ Opt for Intl. Tax/VAT Optional N/A String (50) Optional N/A String (2) Optional N/A String (10) Optional N/A String (50) Optional N/A String (2) (1) For U.S. and Canada only (2) The field has no length limit due to the varying number of states and provinces that can be included in the list. Data Type & Length Tax Calculation Service Using the SCMP API September 2014 26
Appendix A Fields for the SCMP API Table 2 Request-Level Fields for the SCMP API (Continued) Field Description Req/Opt for U.S. & Canadian Tax order_origin_county order_origin_state order_origin_zip Order origin county. This field is forwarded to the third party tax calculation engine only if the following requirements are met: Your CyberSource account is enabled for forwarding county information. The corresponding country is the U.S. or Canada. The order_origin_city, order_origin_ state, and order_origin_country fields are included in the request. Order origin state. This field is not used unless the order_origin_city and order_ origin_country fields are present.use the State, Province, and Territory Codes for the United States and Canada. Order origin postal code. This field is not used unless the order_origin_city, order_origin_state, and order_origin_ country fields are present. Req/ Opt for Intl. Tax/VAT Optional N/A String (50) Optional N/A String (2) Optional N/A String (10) (1) For U.S. and Canada only (2) The field has no length limit due to the varying number of states and provinces that can be included in the list. Data Type & Length Tax Calculation Service Using the SCMP API September 2014 27
Appendix A Fields for the SCMP API Table 2 Request-Level Fields for the SCMP API (Continued) Field Description Req/Opt for U.S. & Canadian Tax point_of_title_transfer Point of title transfer. Either use one of these basic values: D: Destination O: Origin I: In transit Or use one of these Incoterms: EXW: Ex Works FCA: Free Carrier FAS: Free Alongside Ship FOB: Free On Board CFR: Cost and Freight CIF: Cost, Insurance, and Freight CPT: Carriage Paid To CIP: Carriage and Insurance Paid to DAF: Delivered At Frontier DES: Delivered Ex Ship DEQ: Delivered Ex Quay DDU: Delivered Duty Unpaid DDP: Delivered Duty Paid Req/ Opt for Intl. Tax/VAT Data Type & Length N/A Optional String (3) seller_registration0...n VAT seller registration number. Only applicable if including multiple VAT seller registration numbers in the request. See "International Taxes and Value Added Tax," page 10. N/A Required for VAT String (25) Note There is also an Offer-level field named seller_registration0...n. See "Offer-Level Fields," page 33. Note The VAT seller registration number may be required for some Canadian transactions. (1) For U.S. and Canada only (2) The field has no length limit due to the varying number of states and provinces that can be included in the list. Tax Calculation Service Using the SCMP API September 2014 28
Appendix A Fields for the SCMP API Table 2 Request-Level Fields for the SCMP API (Continued) Field Description Req/Opt for U.S. & Canadian Tax seller_registration ship_from_city ship_from_country ship_from_county ship_from_state VAT seller registration number. Only applicable if including one VAT seller registration number in the request. See "International Taxes and Value Added Tax," page 10. Note There is also an Offer-level field named seller_registration. See "Offer- Level Fields," page 33. City where the product is shipped from, which is used to determine nexus. This field is only used if ship_from_state and ship_from_country are present. Country where the product is shipped from, which is used to determine nexus. This field is only used if ship_from_city and ship_from_state are present. Use the two-character ISO Standard Country Codes. County from where the product is shipped. This field is forwarded to the third party tax calculation engine only if the following requirements are met: Your CyberSource account is enabled for forwarding county information. The corresponding country is the U.S. or Canada. The ship_from_city, ship_from_ state, and ship_from_country fields are included in the request. State where the product is shipped from, which is used to determine nexus. This field is only used if ship_from_city and ship_from_country are present. Use the State, Province, and Territory Codes for the United States and Canada. N/A Req/ Opt for Intl. Tax/VAT Required for VAT String (25) Optional N/A String (50) Optional Optional String (2) Optional N/A String (50) Optional N/A String (2) (1) For U.S. and Canada only (2) The field has no length limit due to the varying number of states and provinces that can be included in the list. Data Type & Length Tax Calculation Service Using the SCMP API September 2014 29
Appendix A Fields for the SCMP API Table 2 Request-Level Fields for the SCMP API (Continued) Field Description Req/Opt for U.S. & Canadian Tax ship_from_zip ship_to_address1 ship_to_address2 ship_to_address3 ship_to_city ship_to_country Postal code for the merchant shipping address. The postal code must consist of 5 to 9 digits. If the billing country is the U.S., the 9-digit postal code must follow this format: [5 digits][dash][4 digits] Example: 12345-6789 If the billing country is Canada, the 6-digit postal code must follow this format: [alpha][numeric][alpha] [numeric][alpha][numeric] Example: A1B 2C3 First line of the address to ship the product to. Required if any shipping information is included. Also see "Multiple Shipping Destinations in a Single Order," page 14. Second line of the address to ship the product to. Also see "Multiple Shipping Destinations in a Single Order," page 14. Third line of the address to ship the product to. Also see "Multiple Shipping Destinations in a Single Order," page 14. City to ship the product to.this field is only used when the ship_to_state and ship_to_country fields are present. Also see "Multiple Shipping Destinations in a Single Order," page 14. Country to ship the product to. This field is only used when the ship_to_city and ship_to_state fields are present. Use the two-character ISO Standard Country Codes. Also see "Multiple Shipping Destinations in a Single Order," page 14. Req/ Opt for Intl. Tax/VAT Optional N/A String (10) Optional N/A String (60) Optional N/A String (60) Optional N/A String (60) Optional N/A String (50) Optional Optional String (2) (1) For U.S. and Canada only (2) The field has no length limit due to the varying number of states and provinces that can be included in the list. Data Type & Length Tax Calculation Service Using the SCMP API September 2014 30
Appendix A Fields for the SCMP API Table 2 Request-Level Fields for the SCMP API (Continued) Field Description Req/Opt for U.S. & Canadian Tax ship_to_county ship_to_state County to ship the product to. This field is forwarded to the third party tax calculation engine only if the following requirements are met: Your CyberSource account is enabled for forwarding county information. The corresponding country is the U.S. or Canada. The ship_to_city, ship_to_state, and ship_to_country fields are included in the request. Also see "Multiple Shipping Destinations in a Single Order," page 14. State or province to ship the product to. The default value for ship_to_state is bill_state. This field is only used when the ship_to_city and ship_to_country fields are present. Use the State, Province, and Territory Codes for the United States and Canada. Also see "Multiple Shipping Destinations in a Single Order," page 14. Req/ Opt for Intl. Tax/VAT Optional N/A String (50) Optional N/A String (2) (1) For U.S. and Canada only (2) The field has no length limit due to the varying number of states and provinces that can be included in the list. Data Type & Length Tax Calculation Service Using the SCMP API September 2014 31
Appendix A Fields for the SCMP API Table 2 Request-Level Fields for the SCMP API (Continued) Field Description Req/Opt for U.S. & Canadian Tax ship_to_zip show_tax_per_offer timeout Postal code for the shipping address. The postal code must consist of 5 to 9 digits. If the billing country is the U.S., the 9-digit postal code must follow this format: [5 digits][dash][4 digits] Example: 12345-6789 If the billing country is Canada, the 6-digit postal code must follow this format: [alpha][numeric][alpha] [numeric][alpha][numeric] Example: A1B 2C3 If the postal code for the shipping address is not included in the request message, CyberSource will use the postal code for the billing address. If the postal code for the billing address is not included in the request message, the postal code for the shipping address is required. Also see "Multiple Shipping Destinations in a Single Order," page 14. Whether or not to display tax amounts for each offer. This field can contain one of the following values: yes: Display tax amounts for each offer. no: Do not display tax amounts for each offer. Number of seconds the system waits before returning a timeout error. The default is 110 seconds. Req/ Opt for Intl. Tax/VAT Optional N/A String (10) Optional N/A String (3) Optional Optional Positive integer (3) (1) For U.S. and Canada only (2) The field has no length limit due to the varying number of states and provinces that can be included in the list. Data Type & Length Tax Calculation Service Using the SCMP API September 2014 32
Appendix A Fields for the SCMP API Offer-Level Fields Table 3 Offer-Level Fields for the SCMP API Field Description Req/Opt for U.S. & Canada amount Per-item price of the product. You can include a decimal point (.) in this field, but you cannot include any other special characters. The amount will be truncated at the request level to the correct number of decimal places. Req/ Opt for VAT Data Type & Length Required Required Decimal (15) buyer_registration Buyer s VAT registration number. N/A Optional String (25) city_override_amount Overrides the calculated city tax amount. Optional N/A Decimal (15) city_override_rate country_override_amount country_override_rate county_override_amount county_override_rate merchant_product_sku Overrides the calculated city tax rate. This value must be greater than or equal to 0 and less than 1. For example, for a rate of 1.5%, enter the value 0.015. Overrides the calculated country tax amount, or the calculated Canadian GST amount. Overrides the calculated country tax rate, or the calculated Canadian GST rate. This value must be greater than or equal to 0 and less than 1. For example, for a rate of 1.5%, enter the value 0.015. Overrides the calculated district tax amount. Overrides the calculated district tax rate. This value must be greater than or equal to 0 and less than 1. For example, for a rate of 1.5%, enter the value 0.015. Product s identifier code. For ics_auth and ics_bill, required if product_code is not default or one of the values related to shipping and handling. Optional N/A Decimal (15) Optional N/A Decimal (15) Optional N/A Decimal (15) Optional N/A Decimal (15) Optional N/A Decimal (15) Optional N/A String (30) middleman_registration Middleman s VAT registration number. N/A Optional String (25) Tax Calculation Service Using the SCMP API September 2014 33
Appendix A Fields for the SCMP API Table 3 Offer-Level Fields for the SCMP API (Continued) Field Description Req/Opt for U.S. & Canada order_acceptance_city order_acceptance_country order_acceptance_county order_acceptance_state order_acceptance_zip The order_acceptance_city at the offer level overrides the corresponding request-level field. This field is not used unless the order_acceptance_state and order_acceptance_country fields are present. The order_acceptance_country at the offer level overrides the corresponding request-level field. This field is not used unless the order_acceptance_state and order_acceptance_city fields are present. Use the two-character ISO Standard Country Codes. The order_acceptance_county at the offer level overrides the corresponding request-level field. This field is forwarded to the third party tax calculation engine only if the following requirements are met: Your CyberSource account is enabled for forwarding county information. The corresponding country is the U.S. or Canada. The order_acceptance_city, order_ acceptance_state, and order_ acceptance_country fields are included in the request. The order_acceptance_state at the offer level overrides the corresponding request-level field. This field is not used unless the order_acceptance_city and order_acceptance_country fields are present. Use the State, Province, and Territory Codes for the United States and Canada. The order_acceptance_zip at the offer level overrides the corresponding request-level field. This field is not used unless the order_acceptance_city, order_acceptance_state, and order_ acceptance_country fields are present. Req/ Opt for VAT Data Type & Length Optional N/A String (50) Optional N/A String (2) Optional N/A String (50) Optional N/A String (2) Optional N/A String (10) Tax Calculation Service Using the SCMP API September 2014 34
Appendix A Fields for the SCMP API Table 3 Offer-Level Fields for the SCMP API (Continued) Field Description Req/Opt for U.S. & Canada order_origin_city order_origin_country order_origin_county order_origin_state order_origin_zip The order_origin_city at the offer level overrides the corresponding requestlevel field. This field is not used unless the order_origin_state and order_ origin_country fields are present. The order_origin_country at the offer level overrides the corresponding request-level field. This field is not used unless the order_origin_state and order_origin_city fields are present. Use the two-character ISO Standard Country Codes. The order_origin_county at the offer level overrides the corresponding request-level field. This field is forwarded to the third party tax calculation engine only if the following requirements are met: Your CyberSource account is enabled for forwarding county information. The corresponding country is the U.S. or Canada. The order_origin_city, order_origin_ state, and order_origin_country fields are included in the request. The order_origin_state at the offer level overrides the corresponding requestlevel field. This field is not used unless the order_origin_city and order_ origin_country fields are present. Use the State, Province, and Territory Codes for the United States and Canada. The order_origin_zip at the offer level overrides the corresponding requestlevel field. This field is not used unless the order_origin_city, order_origin_ state, and order_origin_country fields are present. Req/ Opt for VAT Data Type & Length Optional N/A String (50) Optional N/A String (2) Optional N/A String (50) Optional N/A String (2) Optional N/A String (10) Tax Calculation Service Using the SCMP API September 2014 35
Appendix A Fields for the SCMP API Table 3 Offer-Level Fields for the SCMP API (Continued) Field Description Req/Opt for U.S. & Canada point_of_title_transfer Point of title transfer for the item. Either use one of these basic values: D: Destination O: Origin I: In transit Or use one of these Incoterms: EXW: Ex Works FCA: Free Carrier FAS: Free Alongside Ship FOB: Free On Board CFR: Cost and Freight CIF: Cost, Insurance, and Freight CPT: Carriage Paid To CIP: Carriage and Insurance Paid to DAF: Delivered At Frontier DES: Delivered Ex Ship DEQ: Delivered Ex Quay DDU: Delivered Duty Unpaid DDP: Delivered Duty Paid Req/ Opt for VAT Data Type & Length N/A Optional String (3) Tax Calculation Service Using the SCMP API September 2014 36
Appendix A Fields for the SCMP API Table 3 Offer-Level Fields for the SCMP API (Continued) Field Description Req/Opt for U.S. & Canada product_code product_name quantity seller_registration0...n Type of product. This value is used to determine the category that the product is in: electronic, handling, physical, service, or shipping. To use the tax calculation service, use values listed in the Commodity Code column from one of the following documents: European Union Tax Product Code Guide (PDF.xls) U.S. Tax Product Code Guide (PDF.xlsx) See "Product Codes," page 13, for more information. The default value is default. For ics_auth, if you set this to a value other than default or any of the other values related to shipping and handling, the quantity, product_name, and merchant_product_sku fields are required. See the information about offers and grand totals in Getting Started with CyberSource Advanced for the SCMP API. Name of the product. For ics_auth and ics_bill, required if product_code is not default or one of the values related to shipping and handling. Quantity of the product being purchased. For ics_auth and ics_bill, required if product_code is not default or one of the values related to shipping and handling. VAT seller registration number. Only applicable if including multiple VAT seller registration numbers in the request. Note There is also an Request-level field named seller_registration0...n. See "Request-Level Fields," page 23. Note The VAT seller registration number may be required for some Canadian transactions. Optional Optional String (20) Optional Optional String (30) Optional Optional Nonnegative integer (10) N/A Req/ Opt for VAT Required for VAT Data Type & Length String (25) Tax Calculation Service Using the SCMP API September 2014 37
Appendix A Fields for the SCMP API Table 3 Offer-Level Fields for the SCMP API (Continued) Field Description Req/Opt for U.S. & Canada seller_registration ship_from_city ship_from_country ship_from_county ship_from_state ship_from_zip state_override_amount VAT seller registration number. Only applicable if including one VAT seller registration number in the request. Note There is also an Request-level field named seller_registration0...n. See "Request-Level Fields," page 23. City where the product is shipped from, which is used to determine nexus. Country where the product is shipped from, which is used to determine nexus. Use the two-character ISO Standard Country Codes. County from where the product is shipped. This field is forwarded to the third party tax calculation engine only if the following requirements are met: Your CyberSource account is enabled for forwarding county information. The corresponding country is the U.S. or Canada. The ship_from_city, ship_from_ state, and ship_from_country fields are included in the request. State where the product is shipped from, which is used to determine nexus. Use the State, Province, and Territory Codes for the United States and Canada. Postal code for the merchant shipping address. The postal code must consist of 5 to 9 digits. If the shipping country is the U.S., the 9- digit postal code must follow this format: [5 digits][dash][4 digits] Example: 12345-6789 If the shipping country is Canada, the 6- digit postal code must follow this format: [alpha][numeric][alpha] [space][numeric][alpha] [numeric] Example: A1B 2C4 Overrides the calculated state tax amount, or the calculated Canadian PST, HST, or QST amount. N/A Req/ Opt for VAT Required for VAT Data Type & Length String (25) Optional N/A String (50) Optional Optional String (2) Optional Optional String (50) Optional N/A String (2) Optional N/A String (10) Optional N/A Decimal (15) Tax Calculation Service Using the SCMP API September 2014 38
Appendix A Fields for the SCMP API Table 3 Offer-Level Fields for the SCMP API (Continued) Field Description Req/Opt for U.S. & Canada state_override_rate tax_amount Overrides the calculated state tax rate, or the calculated Canadian PST, HST, or QST rate. This value must be greater than or equal to 0 and less than 1. For example, for a rate of 1.5%, enter the value 0.015. Total tax to apply to the product. If you include this field, ics_tax does not calculate tax for the offer; instead, it returns the value of tax_amount in the reply field tax_tax_amountn. Req/ Opt for VAT Data Type & Length Optional N/A Decimal (15) Optional Optional Decimal (15) Reply Fields All the reply fields in the following table are returned for U.S. and Canadian orders. The third column in the table indicates whether the field is returned for VAT orders Table 4 Reply Fields for the SCMP API Reply Field Description Returned for VAT orders? Data Type & Length client_lib_version currency ics_rcode Information about the client library used to request the transaction. Currency used for the order. Formatted using the standard ISO Standard Currency Codes. One-digit code that indicates whether the entire request was successful. The field will contain one of the following values: -1: An error occurred 0: The request was declined 1: The request was successful Yes String (50) Yes String (5) Yes Integer (1) ics_rflag One-word description of the result of the entire request. Yes String (50) ics_rmsg Message that explains the reply flag ics_rflag. Do not display this message to your customer, and do not use this field to write an error handler. Yes String (255) Tax Calculation Service Using the SCMP API September 2014 39
Appendix A Fields for the SCMP API Table 4 Reply Fields for the SCMP API (Continued) Reply Field Description Returned for VAT orders? Data Type & Length merchant_ref_number Order reference or tracking number that you provided in the request. If you included multi-byte characters in this field in the request, the returned value might contain corrupted characters. Yes String (50) request_id Identifier for the request generated by the client. Yes String (26) tax_city_name tax_city_tax0...n tax_county_name tax_county_tax0...n tax_district_tax0...n tax_rcode tax_rflag tax_rmsg tax_state_name tax_state_tax0...n Name of the city corresponding with the value returned in the tax_total_city_tax field. City tax for each offer in the request. Returned only if the show_tax_per_offer field is set to yes. Name of the county corresponding with the value returned in tax_total_county_tax. County tax for each offer in the request. Returned only if the show_tax_per_offer field is set to yes. District tax for each offer in the request. Returned only if the show_tax_per_offer field is set to yes. One-digit code that indicates whether the ics_tax request was successful. The field will contain one of the following values: -1: An error occurred 0: The request was declined 1: The request was successful One-word description of the result of the ics_tax request. Message that explains the reply flag tax_rflag. Do not display this message to your customer, and do not use this field to write an error handler. Name of the state, province, or territory corresponding with the value returned in the tax_total_state_tax field. State tax for each offer in the request. Returned only if the show_tax_per_offer field is set to yes. No String (50) No Decimal (15) No String (50) No No Decimal (15) Decimal (15) Yes Integer (1) Yes String (50) Yes String (255) No String (2) No Decimal (15) tax_tax_amount0...n Tax for each offer. Yes Decimal (15) tax_total_city_tax Total amount of city tax. No Decimal (15) tax_total_county_tax Total amount of county tax or Canadian PST, HST, or QST. No Decimal (15) tax_total_district_tax Total amount of district tax. No Decimal (15) tax_total_grand Sum of the offer and tax amounts. Yes Decimal (15) Tax Calculation Service Using the SCMP API September 2014 40
Appendix A Fields for the SCMP API Table 4 Reply Fields for the SCMP API (Continued) Reply Field Description Returned for VAT orders? Data Type & Length tax_total_state_tax Total amount of state tax or Canadian GST. No Decimal (15) tax_total_tax Total tax for all offers. Yes Decimal (15) tax_zip Postal code corresponding to the jurisdiction used to calculate the tax. No String (10) Tax Calculation Service Using the SCMP API September 2014 41
Reply Flags for the SCMP API APPENDIX B The following table lists the tax calculation service reply flags returned by the SCMP API. See Getting Started with CyberSource Advanced for the SCMP API for a discussion of reply codes, reply flags, and reply messages. Important Because CyberSource can add reply fields, reply codes, and reply flags at any time: You need to parse the reply data according to the names of the fields instead of the field order in the reply. For more information about parsing reply fields, see the documentation for your client. Your error handler should be able to process new reply codes and reply flags without problems. Your error handler should use the ics_rcode field to determine the result if it receives a reply flag that it does not recognize. Table 5 Reply Flags for the SCMP API Reply Flags DINVALIDADDRESS DINVALIDDATA DMISSINGFIELD ESYSTEM ETIMEOUT SOK Brief Description Customer entered an invalid city, state, country, or postal code. Data provided is not consistent with the request. The request is missing a required field. System error. See the documentation for your CyberSource client for information about how to handle retries in the case of system errors. The request timed out. Transaction was successful. Tax Calculation Service Using the SCMP API September 2014 42
Supported Countries APPENDIX C This appendix lists the countries supported by the tax calculation service. North America Canada United States Latin America Anguilla Costa Rica Nicaragua Antigua and Barbuda Dominican Republic Panama Argentina Ecuador Peru Aruba El Salvador St. Kitts and Nevis Bahamas French Guiana St. Lucia Bermuda Grenada Trinidad and Tobago Bolivia Guatemala Turks and Caicos Brazil Guyana Uruguay British Virgin Islands Honduras Venezuela Chile Colombia Jamaica Mexico Tax Calculation Service Using the SCMP API September 2014 43
Appendix C Supported Countries Europe, Middle East, Africa Aland Island Georgia Liechtenstein Serbia Albania Germany (EU) Lithuania (EU) Slovakia (EU) Algeria Ghana Luxembourg (EU) Slovenia (EU) Andorra Gibraltar Macedonia South Africa Austria (EU) Greece (EU) Maldives Spain (EU) Azerbaijan Guernsey Malta (EU) Sweden (EU) Bahrain Guinea-Bissau Moldova Switzerland Belarus Hungary (EU) Montenegro Syria Belgium (EU) Iceland Morocco Tunisia Bulgaria Iran The Netherlands (EU) Turkey Chad Iraq Nigeria Turkmenistan Comoros Ireland (EU) Norway Ukraine Cote D'Ivoire Israel Oman United Arab Emirates Croatia Italy (EU) Poland (EU) United Kingdom (EU) Cyprus (EU) Jersey Portugal (EU) Uzbekistan Czech Republic (EU) Jordan Qatar Yemen Denmark (EU) Kazakhstan Romania Zambia Egypt Kuwait Russia Zimbabwe Estonia (EU) Kyrgyzstan Rwanda Finland (EU) Latvia (EU) Saudi Arabia France (EU) Lebanon Senegal Tax Calculation Service Using the SCMP API September 2014 44
Appendix C Supported Countries Asia Pacific Australia Macau Singapore Brunei Darussalam Malaysia South Korea China Marshall Islands Sri Lanka French Polynesia Nauru Taiwan Guam New Zealand Thailand Hong Kong Northern Mariana Islands Vietnam Indonesia Pakistan Wallis and Futuna Japan Philippines Tax Calculation Service Using the SCMP API September 2014 45
City Abbreviations APPENDIX D Several CyberSource ICS applications expand some commonly used city-name abbreviations. This enables the tax calculation service to correctly evaluate city names for tax purposes. The U.S. Postal Service maintains a list of other common abbreviations. If a customer uses other abbreviations, the tax calculation service might not recognize the combination of city, state, and postal code, in which case the request will fail with reply flag DINVALIDADDRESS. The following table provides a list of the abbreviations used by the tax calculation service and the U.S. Postal Service. Table 6 City Abbreviations Expansion 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 saint country code) hgts, hts heights spr spring jct, jctn junction sprs springs la los angeles vly valley mt, mtn mountain w west Tax Calculation Service Using the SCMP API September 2014 46
INDEX Index A B C D E F G H I J K L M N O P Q R S T U V W X Y Z A abbreviations for cities 46 addresses, invalid 19 C Canadian taxes calculating 17 described 10 overriding 19 overview 8 characters, special 22 city abbreviations 46 countries supported 43 D data types 22 date and time formats 22 E example requests and replies 20 G GMT 22 Goods and Services Tax (GST) calculating 17 overriding 19 overview 8 H Harmonized Sales Tax (HST) calculating 17 overriding 19 overview 8 I ics_tax example request and reply 20 reply flags 42 requesting 16 requirements for using details 17 overview 11 when to use details 17 overview 13 international taxes calculating 18 described 10 overview 8 requirements 12 invalid addresses, effect on tax rates 19 M multiple shipping addresses 14 N nexus calculating 17 described 12 Tax Calculation Service Using the SCMP API September 2014 47
Index A B C D E F G H I J K L M N O P Q R S T U V W X Y Z O offer-level fields 33 overriding tax rates 19 P point of order acceptance 17 point of order origin 17 product codes 13 Provincial Sales Tax (PST) calculating 17 overriding 19 overview 8 Q Quebec Sales Tax (QST) calculating 17 overriding 19 overview 8 R replies flags 42 sample code 20 reply fields 39 reply flags 42 request-level fields 23 requests, sample code 20 requirements for tax calculation details 17 overview 11 T tax amount overriding 19 showing per offer 20 when to calculate details 17 overview 13 tax exempt products 13 tax information storage 14 tax liability 14 tax per offer vs. total tax 20 tax rates calculation of 8 invalid addresses 19 non-standard 13 overriding 19 tax records 14 time formats 22 total tax vs. tax per offer 20 U U.S. taxes calculating 17 described 10 overview 8 use tax 10 UTC 22 V value added tax 10 S sales tax 10 shipping addresses, multiple 14 special characters 22 storage of tax information 14 Tax Calculation Service Using the SCMP API September 2014 48