Many PHP developers are working with custom shopping carts or other systems that need to calculate taxes. We have provided some working example code that will allow you to quickly integrate your applications with TaxCloud. The communication between your system and TaxCloud is done through web services. The example code includes all the web service calls, so you can simply call the supplied methods.
The first step is to create a merchant account at TaxCloud.net. After you do that, we will send you a copy of the user guide, which describes how to set up your merchant account and create a test site. Once you have set up your test site, the system will generate your TaxCloud API ID and Key, which identifies you to our system. The guide also describes how to get a USPS ID, which is required for the address verification service.
The next step is to determine where to place the integration in your system. In a shopping cart application, it’s standard to make it part of the checkout process, after the user has entered a shipping address.
The basic process is as follows:
1. Verify the customer’s address using the VerifyAddress service. This will determine the 9-digit zip code for the shipping address, which is necessary to make an accurate tax calculation. If your system already verifies addresses you can skip this step.
2. Look up the taxes for the items in the shopping cart.
3. Once the order has been completed, you call the Authorized and Captured services to complete the transaction in TaxCloud and to record that payment has been made. This follows the standard pattern of a credit card transaction. It is also possible to combine these two calls into one, which is what will be shown in this example. You can determine which method to use based on the design of your system.
That’s it! The TaxCloud system needs to receive a tax identification code (TIC ID) for each product so it can determine the tax rate to use. You will have to store this information along with your product. There is some optional functionality that you may want to include. TaxCloud can also manage exemption certificates for customers and apply them to orders. You can also return part or all of an order. We are just covering the basics in this post.
The example code can be downloaded here. The zip file contains three PHP files. The classes.php file contains standard TaxCloud class objects. The taxCloudConfig.php file is a configuration file. You will need to modify this file to include your TaxCloud merchant account information. You could, of course, store this information some other way in your application, such as in the database. The func.taxcloud.php file contains the methods that your application will call to integrate with TaxCloud. You will have to include these files in your PHP files so they can be referenced.
Example integration code:
The method you will be calling is the func_taxcloud_verify_address() method in func.taxcloud.php. This method requires an Address parameter and an Error parameter.
// Create an Address object. You will of course have to populate the fields below with data from your system. $destination = new Address(); $destination->setAddress1('The customer's street address'); $destination->setAddress2('The customer's street address, line 2 if available'); $destination->setCity('The customer's city'); $destination->setState('The customer's state'); // Two character state abbreviation $destination->setZip5('The customer's 5 digit zip code'); $destination->setZip4(''); // Create an error Array $err = Array(); // Call TaxCloud. You will receive a verified address in return. // Note that this method will populate the error array with messages if there is a problem. // You will have to write code to handle error conditions. $verifiedAddress = func_taxcloud_verify_address($destination, $err);
Once you have a verified address you can look up taxes for the products in the shopping cart.
// Create your product Array (example) $products = Array(); $product = Array(); $product['productid'] = 1; //Your system's product ID $product['price'] = '19.99'. //product price $product['qty'] = 1; //product quantity $products = $product; //repeat this for each item in the shopping cart // Create the 'origin' address - your company's business address $origin = new Address(); $origin->setAddress1('Your company's street address'); $origin->setAddress2('Your company's street address, line 2 if available'); $origin->setCity('Your company's city'); $origin->setState('Your company's state'); // Two character state abbreviation $origin->setZip5('Your company's 5 digit zip code'); $origin->setZip4(''); // We also need to pass in the shipping charges $shipping = 5; // Create an array to contain any error messages that may be returned $errMsg = Array(); // Now call TaxCloud - $taxes will contain the total tax amount for the order $taxes = func_taxcloud_lookup_tax($products, $origin, $destination, $shipping, errMsg);
At this point you can add the taxes to your cart’s total and proceed with the checkout. The above code assumes that you have a TaxCloud TIC ID configured for each product in your catalog. There is an example method called “func_taxcloud_get_tic()” in the example code. This method will have to be modified to retrieve the TIC ID for each product in your system. Another way to do this is to pass the TIC ID in with each product.
It also assumes that you already have a cart ID stored in the user’s session ($_SESSION['cartID']). This will be needed later on in the process. TaxCloud can generate a cart ID for you if needed. It also assumes that there is a customerID stored in the session ($_SESSION['customerID']).
Once the customer has entered payment information and is ready to complete the order, it is time to inform TaxCloud that the order has been completed. In this example we are assuming that payment has been made.
// Call TaxCloud Authorized() and Captured() $orderID = 12345; // The order ID $errMsg = Array(); // Container for any error messages $result = func_taxcloud_authorized_with_capture($orderID, $errMsg); // The result will be 0 if the call is successful or -1 if there is a problem
That is it! The transaction is complete.