Skip to main content
Vindicia Knowledge Center

Transaction.calculateSalesTax

Transaction.calculateSalesTax

Transaction.calculateSalesTax

The calculateSalesTax method calculates the sales tax of a Transaction object.

Transactions may be taxable by several local and state governments. For example, in the United States, depending on the address, a transaction might be taxable by the city, county, and state. For each applicable tax, this method adds a line item to your Transaction (see the Transaction object’sitems data member).

The CashBox sales-tax engine works as follows:

  1. Taxes are collected according to the buyer’s address. If the shipping address is specified on the Transaction, CashBox considers that address for tax calculation first. If not, CashBox uses the billing address on the payment method. In the absence of those two addresses, CashBox cannot calculate the taxes. For U.S. and Canadian addresses, be sure to provide full address information since taxes vary from state to state and, in many cases, from city to city.
  2. CashBox “cleans up” the address chosen to apply taxes. For example, CashBox converts Saint Fort, Sainte Fort, or Ste Fort to St Fort, discards punctuation marks, and converts dashes to spaces.
  3. CashBox “fixes up” the address in question, by correcting misspelled street or city names, and by applying the correct postal code according to the street address. CashBox does not change the actual address in the Transaction object; instead, CashBox stores the corrected address in the Transaction object’s salesTaxAddress data member when returning the object to you. This step enables the CashBox sales-tax engine to pinpoint the correct final jurisdiction (country, district, county, city, and postal code) to calculate taxes.
  4. CashBox looks in a database for the applicable tax rates for the jurisdiction. That database is continually updated with the latest information.

Customize the applicable tax rates as follows:

  • Upload overriding tax rules to the Vindicia database. In those rules, you may define a specific tax rate for CashBox to apply to your transactions if the customer address is in a specific city, county, state, or other location. You may also specify a date range for applying those tax rules. For more information, contact your Vindicia Client Services representative.
  • Specify your tax nexus. In the United States, your tax nexus is the set of local and state governments that may collect sales tax on your transactions. This nexus depends on the physical location of your business registration. For example, if your company is registered only in California, only the State of California may collect sales tax on your transactions, and CashBox applies sales tax only if your customer’s address is also in California. Contact your Vindicia Client Services representative for more information.
  • Define the tax exemptions on your customer accounts. See the taxExemptions attribute in The Account Object.
  • Define the tax classification on your Product and TransactionItem objects. The tax classification enables you to specify the categories, such as physical goods and electronic data, to which your sales items belong. If your nexus specifies that an item is taxable, CashBox applies sales tax accordingly. See the taxClassification attribute in The Product Object, and in the TransactionItem Subobject.

CashBox includes sales tax items added to your Transaction as new items in the returned Transaction object. The names of those transaction items begin with the prefix VIN, for example,VIN_SALES_TAX_STATE. CashBox also adds a line item that contains the total amount of all the tax items with the name VIN_SALES_TAX.

Note that the calculateSalesTax method does not save the transaction sent for tax calculation in the CashBox database. When a customer makes a one-time purchase on your site, create a Transaction object and call calculateSalesTax on it to calculate the applicable taxes. CashBox will return the total amount of the purchase after adding the applicable taxes. Then present the amount to your customer. Once the customer has finalized the purchase, capture the transaction by calling authCapture on the original Transaction.

The calculateSalesTax call will handle a tax-based timeout, returning a 503 error if the tax calculation has timed out. Given this error, you may choose to abandon or cancel the Transaction. If you ignore this error, sales tax is not calculated.

The authCapture() and auth() methods automatically calculate and add taxes to a transaction before processing it with the payment processor. CashBox also adds applicable sales tax to recurring billing transactions generated for AutoBill objects.

Input

srd: sparse response description, a SOAP string (which must be a JSON object), in which you specify the elements you want returned.This parameter enables the calling system to constrain a method call to return only components you specify. This gives you greater control over returned content, and improves response time within the Vindicia platform by reducing the processing needed for the call.

Some fields are required, either practically or in the WSDL, and will be returned regardless of the srd. A null srd returns the complete response.

transaction: the Transaction object for which to calculate sales tax. This object must have an address and a line item that describes the product sold, as well as a price. Identify this object with either its VID or your merchantTransactionId.

Output

return: an object of type Return that indicates the success or failure of the call.

transaction: the Transaction object that contains the added tax line items, the total amount with the total sales tax added, and the salesTaxAddress attribute filled in with the (corrected) address used to compute taxes.

addressType: the address CashBox chose to calculate sales tax. This parameter has a value of either Shipping or Billing.

originalAddress: the original value of the address chosen by CashBox for tax calculation.

correctedAddress: the final value of the selected address, after CashBox has corrected inconsistencies.

taxItems: an array of SalesTax objects, each of which contains a description attribute, which describes a specific type of tax added (for example, city tax); and a tax attribute, which contains the amount of the tax calculated by CashBox.

totalTax: the total sales tax calculated by CashBox.

Returns

In addition to those listed in Standard Return Codes, this call returns:

Return Code

Return String

404

One of the following:

  • Address not specified on transaction, and unable to load it from customer accounts - unable to calculate sales tax!
  • Must specify line items in transaction to calculate sales tax!

503

Tax service temporarily unavailable.

Example

$tx = new Transaction();
$tx->setAmount('29.90');
$tx->setCurrency('USD');
$tx->setMerchantTransactionId('txid-123456');

$tx->setSourceIp('35.45.123.158');

$account = new Account();
$account->setMerchantAccountId('9876-5432');
$account->setEmailAddress('jdoe@mail.com');
$account->setName('J Doe');
$tx->setAccount($account);

$shippingAddress = new Address();
$shippingAddress->setName('Jane Doe');
$shippingAddress->setAddr1('44 Elm St.');
$shippingAddress->setCity('San Mateo');
$shippingAddress->setDistrict('CA');
$shippingAddress->setPostalCode('94403');
$shippingAddress->setCountry('US');

$tx->setShippingAddress($shippingAddress);

// The line items of the transaction

$tx_item = new TransactionItem();
$tx_item->setSku('sku-1234');
$tx_item->setName('Widget');
$tx_item->setPrice('3.30');
$tx_item->setQuantity('3');
$tx->setTransactionItems(array($tx_item));

$paymentMethod = new PaymentMethod();
$ccCard = new CreditCard();
$ccCard->setAccount('4111111111111111');
$ccCard->setExpirationDate('201109');
$paymentMethod->setType('CreditCard');
$paymentMethod->setCreditCard($ccCard);
$paymentMethod->setBillingAddress($shippingAddress);

$tx->setSourcePaymentMethod($paymentMethod);

$response = $tx->calculateSalesTax();
if ($response['returnCode'] == 200) {

print "Address type used for computing tax: ";
print $response['addressType'] . "\n";
print "Taxes added: \n";
$taxes = $response['taxItems'];
foreach($taxes as $tax) {

print $tax->getDescription() . " : " ;
print $tax->getTax() . "\n";

}

print "Total tax: " . $response['totalTax'];
print "Total transaction amount: " ;
print $response['transaction']->getAmount() . "\n";

}

For Users

Learn More
For Users

Cashbox Features

Learn More
Cashbox Features
Back to Top