Skip to main content

Instant Tax Rate Export (ITE)

Instant Tax Rate Export (ITE)

Last updated: 03-Jun-2025
Rate this article:

Overview

Instant Tax Rate Export allows you to extract the tax rate information for your products as a JSON. The resulting file will contain the tax rates for each country & state (where applicable) for the product tax category provided, including zip codes* if requested (where applicable).

 
*US tax rates by zip code are informative only, final tax rate is calculated at checkout. 

Availability

ITE is available to all 2Checkout accounts.

Rate limit: this service is rate limited and can only be accessed by an account 20 times each day. Tax Rates exported at the beginning of the day should be stored by you for the rest of the day, do not call this service for each customer.

Method and URL

POST: https://secure.2checkout.com/action/taxes.php

Request parameters

2Checkout captures the parameters you send and exports the data to the client.

Field Description Required Used in HASH validation
MERCHANT Your 2Checkout merchant code. The merchant code and secret key for your account are available here. Required, cannot be empty YES
REQ_DATE The time of request (UTC), in format Y-m-d H:i:s:
Y = year, 4 digits
m = month, 2 digits
d = day, 2 digits
H = hour, 2 digits
i = minute, 2 digits
s = seconds, 2 digits
Required, cannot be empty YES
PRODUCT_TAX_CATEGORY Unique, system-generated 2Checkout product tax category identifier in the form of a UUID. Use getProductTaxCategories API method to retrieve the list of product tax categories available for your account. Required, cannot be empty YES
SHOPPER_TYPE

Indicates the type of customer (individual or company) you would like to export tax rates for. 

Possible values:
EMPTY – Exports tax rates for all possible combinations of shopper type.
B2B – Exports tax rates exclusively applicable to company type shoppers.
B2C – Exports tax rates exclusively applicable to individual type shoppers.
Both – exports tax rates exclusively applicable to both B2B and B2C customers at the same time.

Required, can be empty YES
INCLUDE_ZIP_CODES Indicates whether the export should include the zip code level tax rates where applicable.
*Note US tax rates by zip code are informative only, final tax rate is calculated at checkout.
Possible values:
0 – Do not include zip code level tax rates
1 – Include zip code level tax rates
Required, cannot be empty YES
HASH The SHA2/SHA3 HMAC key for the request. Required N/A
SIGNATURE_ALG

The hashing algorithm used to authenticate the request. 

Supported algorithms:
sha256
sha3-256

Required NO

Requirements

HASH validation

  • To validate the SHA2/SHA3 hash signature, you're required to include all mandatory parameters. 2Checkout throws an error if one of these parameters is missing.
  • Use UTC for the time zone of REQ_DATE. The difference between the value of REQ_DATE and the moment when you send the request to 2Checkout must be smaller than 5 minutes, or 2Checkout will respond with the 'Request expired' error message.

Authentication

Authenticate requests using:

  • HASH. This ia a SHA2/SHA3 Hash-based message authentication code (HMAC) that you create using your account's secret key and the parameters marked as mandatory for HASH validation. To build the source string, prepend each value with its own length in bytes. Use 0 for null or empty values without prepending their length. However, when the value is 0 (zero), you do need to prepend its length (1). Note that for UTF-8 characters the length in bytes can be longer that the string length.
  • REQ_DATE. Use UTC time zone.

Optional: The authentication can be restricted by IP or range of IPs from firewall (Accounts settings > User access > Firewall) for the special service user. If the IP from where you make the request is not configured in 2Checkout, the authentication fails.

Response

Provided that your request is valid, you will receive the information in line, in JSON format with HTTP code 200.

Code sample

<?php
// init
$host = 'https://secure.2checkout.com/action/taxes.php';

$merchantCode = 'YOUR_MERCHANT_CODE';
$key = 'YOUR_SECRET_KEY';
$signatureAlgo = 'sha256';

$jsonRpcRequest = array (
    'MERCHANT' => $merchantCode,
    'REQ_DATE' => (new DateTime("now", new DateTimeZone("UTC")))->format('Y-m-d H:i:s'),
    'PRODUCT_TAX_CATEGORY' => '997391d5-48d2-48d4-8914-6d48307b1307', // uuidProductTaxCategory received from API method getProductTaxCategories 
    'SHOPPER_TYPE' => '',// B2B, B2C, Both or empty
    'INCLUDE_ZIP_CODES' => '0'
);

$string = '';
foreach ($jsonRpcRequest as $value) {
    $string .= strlen($value) . $value;
}

$hash = hash_hmac($signatureAlgo, $string, $key);

$jsonRpcRequest['HASH'] = $hash;
$jsonRpcRequest['SIGNATURE_ALG'] = $signatureAlgo;

header('Content-Type: application/json');
echo call($jsonRpcRequest, $host, false);


function call($Request, $hostUrl, $Debug = true) {
    $curl = curl_init($hostUrl);
    curl_setopt($curl, CURLOPT_POST, 1);
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
    curl_setopt($curl, CURLOPT_SSLVERSION, 0);
    curl_setopt($curl, CURLOPT_VERBOSE, 1);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($curl, CURLOPT_PROXY, '');

    curl_setopt($curl, CURLOPT_POSTFIELDS, $Request);

    if ($Debug) {
        var_dump($Request);
    }

    $ResponseString = curl_exec($curl);
    if ($Debug) {
        var_dump($ResponseString);
    }

    if (!empty($ResponseString)) {
        return $ResponseString;
    } else {
        return null;
    }
}
Rate this article:

Need help?

Do you have a question? If you didn’t find the answer you are looking for in our documentation, you can contact our Support teams for more information. If you have a technical issue or question, please contact us. We are happy to help.

Not yet a Verifone customer?

We’ll help you choose the right payment solution for your business, wherever you want to sell, in-person or online. Our team of experts will happily discuss your needs.

Verifone logo