Refund Tax Calculation

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 sets the Transaction Type field to Refund in the Tax Detail Report and makes the value of the Tax Amount negative.

Fields Specific to This Use Case

Include this 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 taxInformation.commitIndicator field to true.
To apply the same rate from the day of the original transaction, set the invoiceDetails.invoiceDate field to the original transaction date.

POST /vas/v2/tax

Refund Tax Calculation Scenarios

You can report a refund tax calculation at different moments in a transaction.

Use these scenario examples to determine when you should report a refund tax calculation.

Scenario 1: Full or Partial Refund

You can refund a tax calculation request before requesting an authorization if you have access to the original transaction data. For example:

Refund the full or partial amount of the original transaction.
If the refund is successful, request the tax calculation service for the refunded item(s) and include the refund indicator by using the taxInformation.refundIndicator field set to true.

You can include the commit indicator by setting the taxInformation.commitIndicator field to true to indicate when the refund was successfully processed in the Tax Detail Report.

Scenario 2: Stand-Alone Credit

You can credit a transaction if you do not have access to the original transaction data. For example:

Request the tax service with the taxInformation.refundIndicator field set to true.
Credit the payment.

You can include the commit indicator by setting the taxInformation.commitIndicator field to true 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 (pre-authorization), or in subsequent tax service requests, such as Scenario 2 (post-capture). If the credit fails, void the previously committed tax service request. See Void Tax Calculation.

Example: Processing a Tax Refund Calculation

{  "clientReferenceInformation": {    "code": "TAX_TC001"  },  "taxInformation": {    "nexus": ["CA", "TX", "AL"],    "showTaxPerLineItem": "Yes",    "commitIndicator": "true",    "refundIndicator": "true"  },  "orderInformation": {    "amountDetails": {      "currency": "USD"    },    "billTo": {      "address1": "1 Market St",      "locality": "San Francisco",      "administrativeArea": "CA",      "postalCode": 94105,      "country": "US"    },    "lineItems": [      {        "productSKU": "07-12-00657",        "productCode": "PO000000",        "quantity": 1,        "productName": "Chewing Gum",        "unitPrice": 1200      }    ],    "invoiceDetails": {      "invoiceDate": "20221010"    }  }}

{  "_links": {    "void": {      "method": "PATCH",      "href": "/vas/v2/tax/6679353637266069103955"    }  },  "clientReferenceInformation": {    "code": "TAX_TC001"  },  "id": "6679353637266069103955",  "orderInformation": {    "lineItems": [      {        "taxableAmount": "1200.00",        "taxDetails": [          { "amount": "0.00", "type": "city" },          { "amount": "28.50", "type": "special" },          { "amount": "72.00", "type": "state" },          { "amount": "3.00", "type": "county" },          { "amount": "0.00", "type": "national" }        ],        "jurisdiction": [          {            "country": "US",            "code": "06",            "taxable": "1200.00",            "rate": "0.060000",            "name": "CALIFORNIA",            "type": "State",            "region": "CA",            "taxAmount": "72.00",            "taxName": "CA STATE TAX"          },          {            "country": "US",            "code": "075",            "taxable": "1200.00",            "rate": "0.002500",            "name": "SAN FRANCISCO",            "type": "County",            "region": "CA",            "taxAmount": "3.00",            "taxName": "CA COUNTY TAX"          },          {            "country": "US",            "code": "EMBE0",            "taxable": "1200.00",            "rate": "0.013750",            "name": "SAN FRANCISCO COUNTY DISTRICT TAX SP",            "type": "Special",            "region": "CA",            "taxAmount": "16.50",            "taxName": "CA SPECIAL TAX"          },          {            "country": "US",            "code": "EMTV0",            "taxable": "1200.00",            "rate": "0.010000",            "name": "SAN FRANCISCO CO LOCAL TAX SL",            "type": "Special",            "region": "CA",            "taxAmount": "12.00",            "taxName": "CA SPECIAL TAX"          }        ],        "exemptAmount": "0.00",        "taxAmount": "103.50"      }    ],    "taxableAmount": "1200.00",    "taxDetails": [      { "amount": "28.50", "type": "special" },      { "amount": "72.00", "type": "state" },      { "amount": "0.00", "type": "national" },      { "amount": "3.00", "type": "county" },      { "amount": "0.00", "type": "city" }    ],    "exemptAmount": "0.00",    "taxAmount": "103.50",    "amountDetails": {      "totalAmount": "1303.50",      "currency": "USD"    }  },  "status": "COMPLETED",  "submitTimeUtc": "2022-11-08T19:22:44Z",  "taxInformation": {    "commitIndicator": "true",    "refundIndicator": "true"  }}

Required Fields

Use these fields to perform a tax refund calculation.

clientReferenceInformation.code

Merchant-generated order reference or tracking number.

invoiceDetails.invoiceDate

Set this field to the original transaction date.

orderInformation.lineItems[].unitPrice

Unit price of the line item.

orderInformation.billTo.country

Country of the billing address.

orderInformation.billTo.postalCode

Postal code of the billing address.

orderInformation.billTo.locality

City or locality of the billing address.

orderInformation.billTo.administrativeArea

State or province of the billing address.

taxInformation.refundIndicator

Set the value of this field to true.

taxInformation.showTaxPerLineItem

Indicates whether to return tax amounts per line item in the response.

taxInformation.nexus

Specify the states in which you have nexus. If you include this field, do not include the taxInformation.noNexus field.

taxInformation.noNexus

Specify the states in which you do not have nexus. If you include this field, do not include the taxInformation.nexus field.

Was this page helpful?

Last published: September 29, 2026